108 lines
3.3 KiB
Markdown
108 lines
3.3 KiB
Markdown
# NODE.DC AI Workspace Assistant
|
|
|
|
Platform-owned shared state service for the cross-surface AI Workspace assistant.
|
|
|
|
It owns:
|
|
|
|
- user AI Workspace executors/devices and selected executor;
|
|
- assistant conversation/thread metadata;
|
|
- surface context and enabled tool packs;
|
|
- linked artifacts between Engine, Ops and future platform surfaces.
|
|
|
|
It does not replace the AI Workspace Hub. The Hub remains the thin transport/rendezvous layer for remote Codex workers.
|
|
|
|
It does not replace the legacy Ops MCP config flow:
|
|
|
|
```text
|
|
external Codex client -> ~/.codex/config.toml -> nodedc-ops-agent MCP -> Ops Agent Gateway
|
|
```
|
|
|
|
That flow remains a separate product path.
|
|
|
|
## API
|
|
|
|
All endpoints require the shared internal token. App BFFs pass the resolved platform subject through:
|
|
|
|
```text
|
|
X-NODEDC-User-Id
|
|
X-NODEDC-User-Email
|
|
X-NODEDC-User-Role
|
|
X-NODEDC-User-Groups
|
|
```
|
|
|
|
`Role` and `Groups` are identity inputs for entitlement adapters. App backends still own object-level ACL enforcement.
|
|
|
|
Executor registry:
|
|
|
|
```text
|
|
GET /api/ai-workspace/assistant/v1/executors
|
|
POST /api/ai-workspace/assistant/v1/executors
|
|
PATCH /api/ai-workspace/assistant/v1/executors/:executorId
|
|
DELETE /api/ai-workspace/assistant/v1/executors/:executorId
|
|
POST /api/ai-workspace/assistant/v1/executors/:executorId/select
|
|
```
|
|
|
|
Conversations:
|
|
|
|
```text
|
|
GET /api/ai-workspace/assistant/v1/threads
|
|
POST /api/ai-workspace/assistant/v1/threads
|
|
GET /api/ai-workspace/assistant/v1/threads/:threadId
|
|
PATCH /api/ai-workspace/assistant/v1/threads/:threadId
|
|
POST /api/ai-workspace/assistant/v1/threads/:threadId/messages
|
|
GET /api/ai-workspace/assistant/v1/threads/:threadId/messages
|
|
```
|
|
|
|
Supported initial surfaces:
|
|
|
|
- `engine`
|
|
- `ops`
|
|
- `global`
|
|
|
|
Supported initial tool packs:
|
|
|
|
- `engine`
|
|
- `ops`
|
|
- `ndc-agent-core`
|
|
- `deploy`
|
|
- `docs`
|
|
|
|
## Run Profile
|
|
|
|
Every dispatch builds an `ai-workspace.run-profile.v1` payload. The raw profile is sent only to the bridge worker; public API responses and run metadata keep MCP headers redacted.
|
|
|
|
The worker uses `runProfile.toolProfile.mcpServers` to create an isolated per-run `CODEX_HOME/config.toml`. Install-time MCP config remains only as a legacy fallback when no dynamic profile is available.
|
|
|
|
Runtime deploy readiness is tracked in [TEST_MATRIX.md](./TEST_MATRIX.md). The `smoke:run-profile` script covers the entitlement adapter to run profile contract and public secret redaction.
|
|
|
|
## Entitlement Adapters
|
|
|
|
App grants can be resolved dynamically before dispatch through adapter endpoints. Configure adapters with:
|
|
|
|
```text
|
|
AI_WORKSPACE_ENTITLEMENT_ADAPTERS_JSON='{"ops":{"url":"https://ops.example/api/ai-workspace/entitlements","tokenEnv":"NODEDC_INTERNAL_ACCESS_TOKEN","required":false}}'
|
|
```
|
|
|
|
or app-specific variables:
|
|
|
|
```text
|
|
AI_WORKSPACE_OPS_ENTITLEMENT_URL=https://ops.example/api/ai-workspace/entitlements
|
|
AI_WORKSPACE_OPS_ENTITLEMENT_TOKEN=...
|
|
AI_WORKSPACE_OPS_ENTITLEMENT_REQUIRED=false
|
|
```
|
|
|
|
Adapter request body:
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": "ai-workspace.entitlement-request.v1",
|
|
"appId": "ops",
|
|
"owner": {},
|
|
"activeContext": {},
|
|
"runContext": {},
|
|
"requestedAt": "2026-06-13T00:00:00.000Z"
|
|
}
|
|
```
|
|
|
|
Adapter response can return `appGrants`, `grants`, `grant`, `appGrant`, or a top-level grant with `mcpServers` and `scopes`. Adapter grants override matching settings grants for the current run only.
|