# AI Workspace Protocol v1

Status: draft canonical contract.
Date: 2026-06-19
Owner: NODE.DC AI Workspace Assistant.

This document fixes the platform contract for cross-application assistant
execution. It exists to prevent assistant capabilities from spreading through
prompt-only rules, app-specific shortcuts, worker code, or transport glue.

## Goal

AI Workspace Protocol v1 defines how a user request from any NODE.DC surface
is converted into a safe, auditable capability call across HUB, OPS, ENGINE,
and future platform applications.

The protocol must support hundreds of functional blocks without changing the
worker for every new feature.

## Layer Ownership

### Client Surface

Examples: ENGINE UI, OPS UI, HUB UI, future platform apps.

Owns:

- visible UI state;
- current surface context;
- active selected objects;
- user-facing preview and confirmation UI.

Must not own:

- final permission enforcement;
- platform action registry;
- backend actor identity;
- raw internal tokens.

### AI Workspace Assistant

Owns:

- assistant thread/session metadata;
- selected executor;
- run profile construction;
- tool manifest construction;
- action routing entrypoint;
- policy prompts derived from structured contracts;
- run-scoped entitlement resolution;
- public redaction of run diagnostics.

Must be the only platform layer that decides which assistant tools are exposed
to a run.

### Ontology Core

Owns:

- canonical entities and relations;
- aliases and resolver rules;
- assistant access policy;
- assistant action registry;
- risk policy;
- confirmation policy;
- app-owned adapter descriptors.

Must not own:

- HUB user source data;
- OPS card source data;
- ENGINE workflow source data;
- transport routing;
- worker execution.

### AI Hub

Owns:

- remote worker rendezvous;
- pairing;
- dispatch relay;
- message delivery;
- proxying to trusted internal services when configured.

Must not own:

- assistant action catalog;
- business permissions;
- prompt policy;
- domain-specific decisions.

### Worker

Owns:

- local/remote executor runtime;
- Codex/model process launch;
- per-run isolated config;
- tool relay based on the received manifest;
- event/result streaming.

Must not own:

- HUB/OPS/ENGINE action IDs as hardcoded product knowledge;
- role rules;
- app-level permission decisions;
- long-lived platform tokens;
- app-owned adapters.

### App API / MCP

Examples: Launcher/HUB API, OPS Gateway, ENGINE API.

Owns:

- source-of-truth data;
- object-level ACL;
- final enforcement;
- app-native audit;
- app-owned adapter routes.

Must reject invalid or forged requests even when AI Workspace allowed the plan.

## Canonical Flow

```mermaid
flowchart LR
  U["User request"] --> C["Client surface context"]
  C --> A["AI Workspace Assistant"]
  A --> O["Ontology Core: resolve capability and policy"]
  O --> A
  A --> P["Run profile + tool manifest"]
  P --> W["Worker or in-process executor"]
  W --> R["Tool relay"]
  R --> API["App API / MCP"]
  API --> AUD["Audit + result"]
  AUD --> A
  A --> C
```

Read actions may execute after the assistant selects a structured action.
Write or privileged actions must use preview first, then explicit confirmation,
then execute. Destructive actions are not exposed as assistant capabilities.

## Run Profile

Schema version:

```text
ai-workspace.run-profile.v1
```

Required top-level fields:

```json
{
  "schemaVersion": "ai-workspace.run-profile.v1",
  "runId": "uuid",
  "createdAt": "2026-06-19T00:00:00.000Z",
  "expiresAt": "2026-06-19T00:10:00.000Z",
  "audience": "ai-workspace-worker",
  "requestId": "uuid-or-nonce",
  "owner": {},
  "sourceSurface": "engine",
  "activeContext": {},
  "toolProfile": {},
  "policyPrompt": "derived text",
  "integrity": {}
}
```

Required rules:

- `expiresAt` must be short-lived.
- `requestId` must be unique enough for replay protection.
- `audience` must name the intended recipient class.
- `integrity` must contain a server-side hash/signature before production use.
- public diagnostics must redact tokens, headers, secrets, and raw internal URLs.

## Actor Claims

Actor claims are backend facts, not user text.

Canonical owner shape:

```json
{
  "ownerKey": "email:dcctouch@gmail.com",
  "userId": "platform-user-id",
  "email": "dcctouch@gmail.com",
  "role": "root-admin",
  "groups": ["nodedc:superadmin"]
}
```

Rules:

- client-supplied actor headers are not trusted directly;
- trusted App BFF or AI Workspace must resolve actor claims;
- target App API must verify the actor again against app-native state;
- app adapters may receive claims, but never treat them as the only authority.

## Tool Profile

Schema version:

```text
ai-workspace.tool-profile.v1
```

Shape:

```json
{
  "schemaVersion": "ai-workspace.tool-profile.v1",
  "enabledToolPacks": ["engine", "ops", "ndc-agent-core"],
  "mcpServers": [],
  "assistantActions": {
    "schemaVersion": "ai-workspace.assistant-actions.v1",
    "endpoint": "/api/ai-workspace/assistant/v1/actions",
    "actionIds": ["hub.user.read_admin_summary"],
    "phases": ["preview", "execute"],
    "tokenRef": "run-token:assistant-actions"
  }
}
```

Rules:

- action IDs come from AI Workspace Assistant + Ontology Core, not from ENGINE
  local routes or worker source code;
- worker may read and expose a generic tool based on this manifest;
- worker must not hardcode the product meaning of an action ID;
- `tokenRef` or server-side relay is preferred over embedding raw bearer tokens;
- if a bearer token is unavoidable during a scaffold phase, it must be
  short-lived, run-scoped, redacted from public output, and removed before
  production.

## Assistant Action Call

Endpoint:

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

Preview request:

```json
{
  "phase": "preview",
  "input": {
    "actionId": "hub.user.block",
    "targetUserId": "user_123",
    "idempotencyKey": "hub.user.block:actor:target"
  }
}
```

Execute request:

```json
{
  "phase": "execute",
  "input": {
    "actionId": "hub.user.block",
    "targetUserId": "user_123",
    "confirmationToken": "preview-token",
    "idempotencyKey": "hub.user.block:actor:target"
  }
}
```

Rules:

- the assistant selects `actionId` after understanding natural language;
- preview must return a human-readable expected effect;
- write execution must require a matching confirmation token;
- write execution must include an idempotency key;
- app-owned adapter must re-check permissions;
- delete/hard destructive requests resolve to forbidden with safe alternatives.

## Worker Protocol

The worker receives a run payload and starts the configured executor.

Worker responsibilities:

- create isolated per-run config;
- expose only tools described by the run profile;
- relay tool calls to AI Workspace or app MCP endpoints;
- stream model/tool events back to AI Workspace;
- redact runtime secrets from logs.

Worker non-responsibilities:

- it does not decide whether a HUB admin can block a user;
- it does not know all HUB/OPS/ENGINE action IDs in source code;
- it does not store internal platform tokens after a run;
- it does not bypass AI Workspace with raw app API calls.

## Hub Protocol

AI Hub may proxy:

- worker dispatch;
- worker events;
- assistant action requests to AI Workspace Assistant.

AI Hub must not:

- build action catalogs;
- evaluate assistant access policy;
- mutate app data directly;
- accept public actor claims as final truth.

## App Adapter Rules

Every app adapter must define:

- owning app: `hub`, `ops`, `engine`, or another platform app;
- allowed method/path list;
- read/write/destructive classification;
- required native scope or role;
- idempotency behavior for writes;
- audit event output;
- confirmation mode;
- safe alternatives for forbidden actions.

HUB examples:

- read admin summary;
- list pending invites;
- list pending access requests;
- block/unblock user;
- disable membership;
- change NDC Core Assistant role.

OPS examples:

- create/update card;
- append report/comment;
- read project/card context;
- update structured card blocks.

ENGINE examples:

- read workflow graph;
- select workflow/agent node;
- inspect workflow errors;
- change workflow ACL only through ENGINE-owned adapter.

## Security Requirements

Production requirements:

- all cross-service traffic uses TLS or an equivalent private secure channel;
- no long-lived internal token in worker, prompt, UI, or public diagnostics;
- run tokens are scoped by run, audience, capability, and expiry;
- run profile integrity is hash/signed by AI Workspace;
- writes require idempotency keys;
- privileged writes require preview and confirmation token;
- target App API performs final authorization;
- all writes produce audit events;
- app APIs reject forged actor headers from public clients;
- secret redaction is covered by smoke tests.

## Localhost vs Production

Localhost and production must use the same logical protocol:

```text
client -> AI Workspace Assistant -> Ontology Core -> AI Hub/Worker -> App API
```

Allowed differences:

- URLs;
- network transport;
- token issuer;
- deployment topology.

Not allowed:

- separate local-only business rules;
- Engine-only action catalog;
- worker-only permission model;
- production-only policy path that contradicts local behavior.

## Migration From Current Scaffold

Current scaffold deviations to remove:

1. ENGINE local bridge owns fallback `ASSISTANT_ACTION_TOOL_PROFILE`.
2. Worker prompt includes concrete HUB action IDs.
3. Worker receives or stores assistant action gateway bearer token.
4. Engine MCP server knows gateway URL/token and owner header rules.
5. AI Hub forwards owner headers without signed actor context.

Migration steps:

1. Move assistant action profile source of truth to AI Workspace Assistant.
2. Generate action IDs from Ontology Core action registry.
3. Replace raw token passthrough with run-scoped token or server-side relay.
4. Convert worker action support to generic manifest-driven relay.
5. Add protocol tests for boundary violations.
6. Mark current scaffold paths as legacy/fallback until removed.

## Boundary Tests

Minimum tests before production rollout:

- public run profile never exposes bearer tokens or internal secrets;
- worker source does not contain product action ID allowlists;
- ENGINE local routes do not contain HUB action registry;
- AI Hub does not evaluate business policy;
- forged public actor headers are rejected by app API;
- write execution without confirmation token is blocked;
- write replay with same idempotency key is safe;
- delete actions are unavailable and resolve to safe alternatives;
- local and production profiles share the same schema.

## Acceptance Criteria

The protocol is ready for product slices when:

- adding a new assistant function changes Ontology Core and the target app
  adapter, not the worker;
- AI Workspace Assistant remains the only run profile source of truth;
- Hub remains transport-only;
- worker can be installed once and keep working as capabilities grow;
- target apps remain final enforcement owners;
- no prompt-only rule is required for safety-critical behavior.