11 KiB

Raw Permalink Blame History

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

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:

ai-workspace.run-profile.v1

Required top-level fields:

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

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

ai-workspace.tool-profile.v1

Shape:

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

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

Preview request:

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

Execute request:

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

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:

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

Migration steps:

Move assistant action profile source of truth to AI Workspace Assistant.
Generate action IDs from Ontology Core action registry.
Replace raw token passthrough with run-scoped token or server-side relay.
Convert worker action support to generic manifest-driven relay.
Add protocol tests for boundary violations.
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.

11 KiB Raw Permalink Blame History

AI Workspace Protocol v1

Goal

Layer Ownership

Client Surface

AI Workspace Assistant

Ontology Core

AI Hub

Worker

App API / MCP

Canonical Flow

Run Profile

Actor Claims

Tool Profile

Assistant Action Call

Worker Protocol

Hub Protocol

App Adapter Rules

Security Requirements

Localhost vs Production

Migration From Current Scaffold

Boundary Tests

Acceptance Criteria

11 KiB

Raw Permalink Blame History