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 data tools are not fully reintroduced yet; missing business data must be reported honestly by the Agent.

Main API

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:

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

Optional request headers can override the local context during experiments:

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

UIEnvelope

The registry is exposed at:

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

Visual opencode tools are mapped by the service:

show_chart -> chart
locate_features, zoom_to_map, render_junctions, apply_layer_style -> map_action
view_history, view_scada -> registered_component

See docs/agent-ui-protocol.md.

Development

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

bun run check typechecks the service and .opencode tools.