# TJWaterAgentExperimental

Experimental opencode-based Agent service for TJWater UI orchestration.

This repository is intentionally separate from the production `TJWaterAgent`
history. It does not include user authentication or the old `tjwater-cli`
bridge. Runtime requests use a local default context and can later be wired to a
real auth provider through `src/context/`.

## Current Boundaries

- No Keycloak / metadata auth context.
- No required `Authorization` or `X-Project-Id` headers.
- No `cli/`, no `tjwater_cli` opencode tool, no free-form CLI command bridge.
- Agent visual output is expressed through `agent-ui@1` UIEnvelope events.
- Tools that depend on the TJWater Server are disabled. Arbitrary URLs, SQL,
  shell commands, and filesystem paths remain unavailable.

## Main API

```text
GET  /health
GET  /api/v1/agent/chat/models
GET  /api/v1/agent/chat/ui-registry
POST /api/v1/agent/chat/session
GET  /api/v1/agent/chat/sessions
GET  /api/v1/agent/chat/session/:session_id
GET  /api/v1/agent/chat/session/:session_id/stream
POST /api/v1/agent/chat/stream
POST /api/v1/agent/chat/abort
```

`POST /api/v1/agent/chat/stream` returns SSE. Important events:

| event | Purpose |
| --- | --- |
| `progress` | Agent planning/tool progress |
| `token` | Assistant text delta |
| `ui_envelope` | Structured UI description for trusted frontend rendering |
| `tool_call` | Deprecated compatibility/debug event |
| `permission_request` | Runtime permission request |
| `question_request` | Runtime/user clarification request |
| `done` | Run completed |
| `error` | Run failed or aborted |

## Local Context

The service uses `src/context/localContext.ts`.

Defaults:

```text
AGENT_LOCAL_USER_ID=local-user
AGENT_LOCAL_PROJECT_ID=local-project
AGENT_LOCAL_NETWORK=local-network
```

Monitoring time-series data is read from the agent project's `source/`
directory and analyzed through validated local skills. `get_project_context`,
`list_scada_assets`, `query_scada_readings`, `web_search`, and `geocode` are not
exposed because they depend on the TJWater Server.

Optional request headers can override the local context during experiments:

```text
X-Agent-Local-User
X-Agent-Local-Project
X-Agent-Local-Network
X-Trace-Id
```

## UIEnvelope

The registry is exposed at:

```text
GET /api/v1/agent/chat/ui-registry
```

No visual or frontend-action tools are currently exposed to the Agent. The
registry endpoints remain available for protocol compatibility and return no
registered charts, components, or actions.

See [docs/agent-ui-protocol.md](docs/agent-ui-protocol.md).

## Development

```bash
bun install
bun run dev
bun run check
bun test tests/**/*.test.ts
```

`bun run check` typechecks the service and `.opencode` tools.