# 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.
- Backend business data is available through typed, allowlisted domain tools.
  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=<UUID returned as project_id by /api/v1/projects>
AGENT_LOCAL_NETWORK=local-network
```

Local domain tools are enabled by default. Set `TJWATER_API_BASE_URL` to the
Server address and `AGENT_LOCAL_PROJECT_ID` to an enabled project UUID. Setting
`TJWATER_API_ENABLED=false` disables all Server calls. Production startup rejects
enabled Server tools while `TJWATER_AUTH_MODE=disabled`.

Available domain tools:

- `get_project_context`
- `list_scada_assets`
- `query_scada_readings` with required `observed_from` and `observed_to`
  ISO8601 timestamps. The server rejects reversed or unbounded historical
  queries.

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
```

Visual opencode tools are mapped by the service:

- `show_chart` -> `chart`
- `zoom_to_map` -> `map_action`
- `view_scada` -> `registered_component`

Use `query_scada_readings` first when the answer needs actual SCADA values.
Use `view_scada` only to ask the frontend to display the selected SCADA asset
panel.

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.