# 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.