110 lines
3.1 KiB
Markdown
110 lines
3.1 KiB
Markdown
# 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.
|