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

5.9 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

Assistant actions:

POST /api/ai-workspace/assistant/v1/actions

This is the platform entrypoint for ontology-backed assistant tool calls. Natural-language chat dispatch still goes through the selected assistant model/executor first; ontology-core is the deterministic policy/action layer the assistant calls after it has interpreted the user's intent.

Request shape:

{
  "phase": "preview",
  "input": {
    "actionId": "hub.user.block",
    "targetUserId": "user_123",
    "confirmed": true,
    "idempotencyKey": "hub.user.block:user_admin:user_123"
  }
}

For write execution, first call phase=preview, show the returned action.confirmation to the user, then call phase=execute with confirmationToken. The final mutation still goes through the app-owned Launcher admin API guards; this service only routes the registered action.

Launcher action gateway configuration:

NDC_ONTOLOGY_LAUNCHER_BASE_URL=http://launcher.local.nodedc
NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN=...

If NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN is not set, the service falls back to NODEDC_INTERNAL_ACCESS_TOKEN.

Launcher entitlement adapter configuration:

AI_WORKSPACE_LAUNCHER_ENTITLEMENT_URL=http://launcher:5173/api/ai-workspace/internal/v1/entitlements
AI_WORKSPACE_LAUNCHER_ENTITLEMENT_TOKEN=...
AI_WORKSPACE_LAUNCHER_ENTITLEMENT_REQUIRED=true

The Launcher adapter is evaluated after app-owned adapters and may return launcher, ops, and engine app grants. A Launcher denial is the top-level service-access decision and clears MCP servers for that app in the run profile; app-owned adapters still own app-local scopes and runtime tokens.

The first HUB action ids exposed to assistants are:

  • hub.user.read_admin_summary
  • hub.invite.list_pending
  • hub.access_request.list_pending

Read actions can be executed without user confirmation after the assistant has selected the structured action. Privileged/write actions still require explicit preview, user confirmation, and execute.

App BFFs should pass active scope facts in action input (clientId, coreAssistantRole, membershipRole, membershipStatus) so policy stays data-driven instead of prompt-driven.

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 canonical cross-surface execution contract is AI Workspace Protocol v1. It defines layer ownership, run profile shape, tool manifests, worker boundaries, Hub boundaries, app adapter rules, and the migration path from the current scaffold.

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
AI_WORKSPACE_ENGINE_ENTITLEMENT_URL=https://engine.example/api/ai-workspace/internal/v1/entitlements
AI_WORKSPACE_ENGINE_ENTITLEMENT_TOKEN=...
AI_WORKSPACE_ENGINE_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.