96 lines
2.7 KiB
Markdown
96 lines
2.7 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.
|
|
- Tools that depend on the TJWater Server are disabled. 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=local-project
|
|
AGENT_LOCAL_NETWORK=local-network
|
|
```
|
|
|
|
Monitoring time-series data is read from the agent project's `source/`
|
|
directory and analyzed through validated local skills. `get_project_context`,
|
|
`list_scada_assets`, `query_scada_readings`, `web_search`, and `geocode` are not
|
|
exposed because they depend on the TJWater Server.
|
|
|
|
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
|
|
```
|
|
|
|
No visual or frontend-action tools are currently exposed to the Agent. The
|
|
registry endpoints remain available for protocol compatibility and return no
|
|
registered charts, components, or actions.
|
|
|
|
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.
|