SILVER/NODEDC_PLATFORM
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat(ai-workspace): add local relay profiles

Browse Source
This commit is contained in:
Codex
2026-06-20 12:54:19 +03:00
parent 2d5fef3948
commit 3526351b1b
28 changed files with 2959 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
services/ai-workspace-assistant/docs/AI_WORKSPACE_PROTOCOL_V1.md
+434
View File
@@ -0,0 +1,434 @@
# 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.