feat: initialize experimental agent repo

2026-06-30 14:03:49 +08:00
commit e83ac54a9e
75 changed files with 11690 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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 data tools are not fully reintroduced yet; missing business data must
+  be reported honestly by the Agent.
+
+## 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
+```
+
+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`
+- `locate_features`, `zoom_to_map`, `render_junctions`, `apply_layer_style` -> `map_action`
+- `view_history`, `view_scada` -> `registered_component`
+
+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.