SILVER
/
NODEDC_PLATFORM
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NODEDC_PLATFORM/services/ai-workspace-assistant/README.md

3.3 KiB
Raw Blame History

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:

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:

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:

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:

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

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:

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:

{
  "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.