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

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=<UUID returned as project_id by /api/v1/meta/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_monitoring_assets
query_monitoring_readings with required observed_from and observed_to ISO8601 timestamps. The server rejects reversed or unbounded historical queries.
start_data_quality_analysis (requires approval)
start_simulation (requires approval)
get_job_status

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

view_history opens the historical data/result panel and must include start_time and end_time ISO8601 timestamps. Use query_monitoring_readings first when the answer needs actual monitoring values; use view_history only to ask the frontend to display the selected feature history panel.

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.

3.4 KiB Raw Blame History