@axiom-lattice/protocols 4.2.0 → 4.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/A2AApiKeyStoreProtocol.ts

@@ -6,6 +6,7 @@
  */
 
 import type { A2AApiKeyEntry } from "./A2AProtocol";
+import type { OpenGrant } from "./OpenProtocol";
 
 export interface A2AApiKeyRecord {
   id: string;
@@ -15,6 +16,11 @@ export interface A2AApiKeyRecord {
   projectId: string;
   /** Assistant whitelist; empty/undefined = all exposed agents in the tenant */
   assistantIds?: string[];
+  /**
+   * Open-door authorization grants (A2A door keeps reading assistantIds).
+   * Absent/empty → derived via effectiveGrants() legacy semantics.
+   */
+  grants?: OpenGrant[];
   label?: string;
   enabled: boolean;
   createdAt: Date;
@@ -27,9 +33,18 @@ export interface CreateA2AApiKeyInput {
   projectId: string;
   /** Assistant whitelist; empty/undefined = all exposed agents in the tenant */
   assistantIds?: string[];
+  /** Open-door grants (see OpenProtocol); absent → legacy derivation */
+  grants?: OpenGrant[];
   label?: string;
 }
 
+export interface UpdateA2AApiKeyInput {
+  label?: string;
+  projectId?: string;
+  assistantIds?: string[];
+  grants?: OpenGrant[];
+}
+
 export interface A2AApiKeyStore {
   /** Look up a key record by its bearer token value (for auth). */
   findByKey(key: string): Promise<A2AApiKeyRecord | null>;
@@ -55,6 +70,9 @@ export interface A2AApiKeyStore {
   /** Delete a key permanently. */
   delete(id: string): Promise<void>;
 
+    /** Update mutable fields of an existing key (label, grants, projectId, assistantIds). */
+  update(id: string, input: UpdateA2AApiKeyInput): Promise<A2AApiKeyRecord>;
+
   /** Bulk load all active keys into a lookup Map (used at startup). */
   loadIntoMap(): Promise<Map<string, A2AApiKeyEntry>>;
 }

package/src/A2AProtocol.ts

@@ -1,3 +1,4 @@
+import type { OpenGrant } from "./OpenProtocol";
 /**
  * A2AProtocol - re-exports standard A2A 0.3 types from @a2a-js/sdk
  * plus Axiom-specific auth/exposure types.
@@ -15,17 +16,6 @@ export type {
  * Per-agent A2A exposure configuration — controls whether an agent is
  * reachable over A2A and which skills are advertised on its AgentCard.
  */
-export interface A2AExposure {
-  /** Whether this agent is exposed over the A2A protocol */
-  enabled: boolean;
-  /** Skills advertised on the AgentCard; defaults to a single generic skill when omitted */
-  skills?: Array<{ id: string; name: string; description: string; tags?: string[]; examples?: string[] }>;
-  /** Supported input modes (MIME types); defaults to text modes when omitted */
-  inputModes?: string[];
-  /** Supported output modes (MIME types); defaults to text modes when omitted */
-  outputModes?: string[];
-}
-
 /**
  * In-memory API key entry used for request authentication.
  * Empty/undefined assistantIds means all exposed agents in the tenant.
@@ -35,6 +25,8 @@ export interface A2AApiKeyEntry {
   tenantId: string;
   projectId: string;
   assistantIds?: string[];
+  /** Open-door grants; the agent whitelist derives from the agent-domain items. */
+  grants?: OpenGrant[];
 }
 
 /**

package/src/AgentWebAppStreamProjection.ts

@@ -62,6 +62,27 @@ export function projectAgentWebAppChunk(
       { type: "stream.completed" },
     ];
   }
+  if (chunk.type === MessageChunkTypes.ERROR) {
+    const code = typeof chunk.data.code === "string" ? chunk.data.code : "stream_error";
+    if (code === "aborted" || code === "superseded") {
+      return [{ type: "stream.completed" }];
+    }
+    // Expose the real reason to the client for debugging.
+    return [
+      {
+        type: "error",
+        error: {
+          code: "STREAM_FAILED",
+          message:
+            typeof chunk.data.content === "string" && chunk.data.content
+              ? chunk.data.content
+              : "Stream failed",
+          retryable: false,
+        },
+      },
+      { type: "stream.completed" },
+    ];
+  }
   if (chunk.type === MessageChunkTypes.MESSAGE_FAILED) {
     return [
       { type: "error", error: { code: "STREAM_FAILED", message: "Stream failed", retryable: true } },

package/src/ChannelAdapterProtocol.ts

@@ -76,6 +76,18 @@ export interface ChannelAdapter<TConfig = unknown> {
     message: OutboundMessage,
     installation: ChannelInstallation,
   ): Promise<void>;
+  /**
+   * 可选：把 Agent 暂停等待人工输入时的问题/提示投影到会话中。
+   *
+   * 与 `sendReply` 不同，这不是对某条入站消息的最终回复，而是运行中途
+   * 产生的一条独立 bot 消息（例如 Project Room 的 clarify 卡片）。
+   * `message.metadata.inputMessageId` 关联触发该运行的入站队列消息。
+   */
+  sendInterrupt?(
+    replyTarget: ReplyTarget,
+    message: OutboundMessage,
+    installation: ChannelInstallation,
+  ): Promise<void>;
   /**
    * 可选：Channel 自定义 thread ID 生成策略。
    * 如果提供，MessageRouter 会优先使用此方法决定 thread ID，

package/src/MessageProtocol.ts

@@ -82,6 +82,7 @@ export const MessageChunkTypes = {
   AI: 'ai',
   TOOL: 'tool',
   INTERRUPT: 'interrupt',
+  ERROR: 'error',
   MESSAGE_COMPLETED: 'message_completed',
   MESSAGE_FAILED: 'message_failed',
   THREAD_IDLE: 'thread_idle',
@@ -94,6 +95,11 @@ export interface MessageChunk {
   data: {
     id: string;
     content?: string;
+    /**
+     * Machine-readable end reason for {@link MessageChunkTypes.ERROR} chunks.
+     * Known values: `aborted`, `superseded`, `stream_error`.
+     */
+    code?: string;
     tool_call_chunks?: Array<{
       name?: string;
       args?: string;

package/src/OpenProtocol.ts

@@ -0,0 +1,125 @@
+/**
+ * OpenProtocol — contracts for the Open API surface (unified external
+ * capability invocation). See docs/superpowers/specs/2026-09-07-open-platform-api-design.md.
+ */
+
+/** Authorization grant: default-deny; a grant covers one capability domain. */
+export interface OpenGrant {
+  domain: string;
+  /**
+   * Action names (kb: ["search"]) or instance ids (agent: [assistantId]).
+   * Absent/empty = every action in the domain.
+   */
+  items?: string[];
+  selector?: { sandbox?: "self" };
+}
+
+/** Execution context synthesized from a verified credential — never from the caller. */
+export interface OpenExecutionContext {
+  tenantId: string;
+  projectId: string;
+  /** Addressing only, not an authorization dimension (see design §6.2). */
+  workspaceId?: string;
+  /** Synthesized runConfig (mirrors the Agent path, incl. _resolvedConnections). */
+  runConfig: Record<string, unknown>;
+}
+
+export interface OpenExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+}
+
+/**
+ * Effective grants for the Open door, derived from a key record.
+ *
+ * Backward compatibility with pre-grants A2A keys:
+ * - explicit grants win;
+ * - otherwise assistantIds become an agent-domain grant;
+ * - legacy "empty assistantIds = all exposed agents" maps to a bare agent grant.
+ *
+ * The A2A door keeps reading assistantIds directly and never consults this —
+ * existing A2A behavior is unchanged by construction.
+ */
+export function effectiveGrants(record: {
+  grants?: OpenGrant[];
+  assistantIds?: string[];
+}): OpenGrant[] {
+  if (record.grants && record.grants.length > 0) return record.grants;
+  if (record.assistantIds && record.assistantIds.length > 0) {
+    return [{ domain: "agent", items: record.assistantIds }];
+  }
+  return [{ domain: "agent" }];
+}
+
+// ─── Capability catalog (for the key-management picker) ───────────────────
+
+/** Where an exposed capability comes from. */
+export type OpenCapabilitySource = "builtin" | "plugin" | "agent";
+
+/** A selectable grant item: an action name or an instance id. */
+export interface OpenCatalogItem {
+  /** Grant item value: action name (kb → "search") or instance id (agent → assistantId). */
+  id: string;
+  /** Full MCP tool name when this item is exclusively exposed (informational). */
+  toolName: string;
+  label: string;
+  description?: string;
+  annotations?: { readOnlyHint: boolean; destructiveHint: boolean };
+}
+
+export interface OpenCatalogDomain {
+  domain: string;
+  label: string;
+  source: OpenCapabilitySource;
+  /** Display-only scope hint (defaults to tenant-wide). */
+  scopeKind?: "tenant" | "workspace" | "project";
+  /** How grant items are chosen: per-action or per-instance. */
+  itemKind: "action" | "instance";
+  items: OpenCatalogItem[];
+}
+
+/** Full grantable capability catalog for a tenant (drives the key picker). */
+export interface OpenCatalog {
+  domains: OpenCatalogDomain[];
+}
+
+// ─── Audit ────────────────────────────────────────────────────────────────
+
+export type OpenCredentialKind = "api_key" | "sandbox_token" | "browser_token";
+
+/** Append-only audit input; the writer is responsible for redacting args. */
+export interface OpenAuditAppendInput {
+  tenantId: string;
+  credentialId: string;
+  credentialKind: OpenCredentialKind;
+  projectId: string;
+  domain: string;
+  action: string;
+  args: unknown;
+  status: "ok" | "error";
+  errorCode?: string;
+  durationMs: number;
+}
+
+export interface OpenAuditRecord extends OpenAuditAppendInput {
+  id: string;
+  createdAt: Date;
+}
+
+export interface OpenAuditQuery {
+  tenantId: string;
+  credentialId?: string;
+  domain?: string;
+  status?: "ok" | "error";
+  /** ISO timestamps; inclusive from / exclusive to. */
+  from?: string;
+  to?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface OpenAuditStore {
+  append(record: OpenAuditAppendInput): Promise<void>;
+  /** Tenant-scoped, newest-first. */
+  query(params: OpenAuditQuery): Promise<OpenAuditRecord[]>;
+}

package/src/PluginProtocol.ts

@@ -73,6 +73,17 @@ export interface PluginConnection {
 export interface PluginToolMeta {
   name: string;
   description: string;
+  /** When true, this tool surfaces on the Open API (MCP) surface. */
+  expose?: boolean;
+}
+
+/** Open-surface exposure entry with MCP annotation hints. */
+export interface PluginOpenExposeTool {
+  name: string;
+  /** MCP readOnlyHint — pure query, no side effects. */
+  readOnly?: boolean;
+  /** MCP destructiveHint — may cause irreversible changes. */
+  destructive?: boolean;
 }
 
 /**
@@ -135,6 +146,14 @@ export interface PluginMeta {
   icon?: string;
   /** 工具清单（可选，middleware 能自动提取时不需要写） */
   tools?: PluginToolMeta[];
+  /**
+   * Open 面（MCP）暴露的工具名清单——独立于 tools 声明，一行即生长。
+   * 声明后 OpenCredentialService 的 grants 匹配 domain=<meta.type>。
+   *
+   * 条目可为字符串（默认 readOnly=false, destructive=false）或带注解对象，
+   * 注解映射到 MCP annotations（readOnlyHint / destructiveHint）。
+   */
+  openExpose?: Array<string | PluginOpenExposeTool>;
   /**
    * 中间件配置 schema（用于 agent 配置面板）。新的 connection-backed
    * plugins use `connections: string[]` and optional `connectAll?: boolean`.

package/src/ProjectRoomMessageStoreProtocol.ts

@@ -13,7 +13,10 @@ export interface ProjectRoomMessageStore {
     input: Omit<ProjectRoomMessage, "createdAt"> & { idempotencyKey: string },
   ): Promise<ProjectRoomMessage>;
 
-  /** Lists messages strictly before an optional cursor, up to the requested limit. */
+  /**
+   * Lists messages strictly before an optional cursor, up to the requested limit.
+   * Individually invalid persisted rows are skipped (and logged) instead of failing the whole read.
+   */
   list(input: {
     tenantId: string;
     roomId: string;

package/src/ProjectRoomProtocol.ts

@@ -18,6 +18,17 @@ export type ProjectRoomMessageSource =
   | "routine"
   | "system";
 
+/**
+ * Canonical label prefix for the one-time room event that announces agent-to-agent task delegation.
+ *
+ * The projection text is `${PROJECT_ROOM_TASK_DELEGATED_LABEL} · <creator> → <owner>`; the UI maps
+ * the exact label or this prefix to the "delegated" task-event kind and never parses arbitrary prose.
+ */
+export const PROJECT_ROOM_TASK_DELEGATED_LABEL = "Task delegated";
+
+/** Separator between the delegation label and its resolved actor labels. */
+export const PROJECT_ROOM_TASK_DELEGATED_SEPARATOR = " · ";
+
 /** The main room associated with a project. */
 export interface ProjectRoom {
   id: string;

package/src/ProjectRoomRealtimeProtocol.ts

@@ -21,6 +21,8 @@ export interface ProjectRoomPublicMessage {
   mentions: ProjectRoomMention[];
   replyToMessageId?: string;
   source: ProjectRoomMessageSource;
+  /** Canonical source identity (e.g. the Task id for source "task"). */
+  sourceId?: string;
   createdAt: string;
 }
 
@@ -264,6 +266,10 @@ function mapPublicMessageRecord(record: Record<string, unknown>): ProjectRoomPub
     if (typeof record.replyToMessageId !== "string") return undefined;
     result.replyToMessageId = record.replyToMessageId;
   }
+  if (record.sourceId !== undefined) {
+    if (typeof record.sourceId !== "string") return undefined;
+    result.sourceId = record.sourceId;
+  }
   return result;
 }
 

package/src/SandboxPluginProtocol.ts

@@ -0,0 +1,62 @@
+import type { AgentConfig } from "./AgentLatticeProtocol";
+import type { PluginConnectionFieldSchema, PluginSkillDefinition } from "./PluginProtocol";
+
+/**
+ * A single tool contributed by a sandbox-authored tenant plugin.
+ *
+ * @property name - Tool name exposed to the LLM (validated `^[a-zA-Z0-9_-]{1,64}$`).
+ * @property description - Tool description.
+ * @property schema - Restricted JSON Schema subset describing the tool input.
+ * @property handler - Safe relative path (within the plugin directory) to a JS file.
+ */
+export interface SandboxPluginToolDef {
+  name: string;
+  description: string;
+  schema: Record<string, unknown>;
+  handler: string;
+  expose?: boolean;
+  readOnly?: boolean;
+  destructive?: boolean;
+  timeoutMs?: number;
+  maxResultBytes?: number;
+}
+
+/**
+ * Connection capability contributed by a sandbox plugin. `test`/`discover`
+ * point at handler files relative to the plugin directory.
+ */
+export interface SandboxPluginConnectionDef {
+  fields: PluginConnectionFieldSchema[];
+  test?: { handler: string };
+  discover?: { handler: string };
+  resourceLabel?: string;
+}
+
+/**
+ * Authoritative declarative definition of a tenant plugin, stored at
+ * `/root/.agents/plugins/<type>/plugin.json`.
+ */
+export interface SandboxPluginManifest {
+  schemaVersion: 1;
+  type: string;
+  name: string;
+  description: string;
+  version: string;
+  icon?: string;
+  category?: string;
+  configSchema?: Record<string, unknown>;
+  defaultConfig?: Record<string, unknown>;
+  connection?: SandboxPluginConnectionDef;
+  tools: SandboxPluginToolDef[];
+  skills?: Record<string, PluginSkillDefinition>;
+  agents?: Record<string, AgentConfig>;
+}
+
+/** Structured load/validation feedback surfaced to authors and operators. */
+export interface SandboxPluginDiagnostic {
+  level: "error" | "warning";
+  code: string;
+  pluginType?: string;
+  tool?: string;
+  message: string;
+}

package/src/SandboxResourceProtocol.ts

@@ -1,3 +1,4 @@
+import type { OpenGrant } from "./OpenProtocol";
 /**
  * SandboxResourceProtocol
  *
@@ -35,6 +36,8 @@ export interface ShareRecord {
   passwordHash: string | null;
   expiresAt: Date | null;
   maxAccess: number | null;
+  /** Extra Open-door grants appended to sandbox tokens (V1: kb read-only). */
+  openGrants?: OpenGrant[];
   accessCount: number;
   revoked: boolean;
   createdAt: Date;
@@ -50,6 +53,8 @@ export interface CreateShareRequest {
   title?: string;
   expiresAt?: string;
   maxAccess?: number;
+  /** Extra Open-door grants for sandbox tokens minted for this share. */
+  openGrants?: OpenGrant[];
 }
 
 /** Response returned to clients after a share is created. */

package/src/UserPushSubscriptionStoreProtocol.ts

@@ -0,0 +1,25 @@
+/** A browser Web Push subscription belonging to one user. */
+export interface UserPushSubscription {
+  id: string;
+  tenantId: string;
+  userId: string;
+  /** Push service endpoint URL from the browser's PushSubscription. */
+  endpoint: string;
+  /** Client public keys used to encrypt the payload. */
+  keys: { p256dh: string; auth: string };
+  userAgent?: string;
+  createdAt: string;
+}
+
+/** Persistence operations for per-user Web Push subscriptions. */
+export interface UserPushSubscriptionStore {
+  /** Lists every subscription for a user (a user may have several devices). */
+  list(tenantId: string, userId: string): Promise<UserPushSubscription[]>;
+  /**
+   * Saves a subscription. Re-saving the same endpoint replaces its keys/agent
+   * (idempotent per tenant+user+endpoint).
+   */
+  save(input: Omit<UserPushSubscription, "id" | "createdAt">): Promise<UserPushSubscription>;
+  /** Deletes one subscription by endpoint. Returns whether a row was removed. */
+  delete(tenantId: string, userId: string, endpoint: string): Promise<boolean>;
+}

package/src/__tests__/AgentWebAppStreamProjection.test.ts

@@ -0,0 +1,59 @@
+/**
+ * AgentWebAppStreamProjection error handling tests.
+ *
+ * Internal `error` chunks (emitted when an Agent run is aborted or fails)
+ * must be projected onto the stable public event surface instead of being
+ * silently dropped or mistaken for assistant text.
+ */
+
+import { projectAgentWebAppChunk } from "../AgentWebAppStreamProjection";
+
+describe("projectAgentWebAppChunk - error chunks", () => {
+  it("projects a stream_error chunk to the real error message", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-1", content: "Provider rate limit exceeded", code: "stream_error" },
+    } as never);
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: { code: "STREAM_FAILED", message: "Provider rate limit exceeded", retryable: false },
+      },
+      { type: "stream.completed" },
+    ]);
+  });
+
+  it("falls back to 'Stream failed' when no content is provided", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-2", code: "stream_error" },
+    } as never);
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: { code: "STREAM_FAILED", message: "Stream failed", retryable: false },
+      },
+      { type: "stream.completed" },
+    ]);
+  });
+
+  it("treats a user abort as a neutral completion without an error event", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-2", content: "Thread aborted", code: "aborted" },
+    } as never);
+
+    expect(events).toEqual([{ type: "stream.completed" }]);
+  });
+
+  it("treats a superseded run as a neutral completion without an error event", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-3", content: "Thread superseded", code: "superseded" },
+    } as never);
+
+    expect(events).toEqual([{ type: "stream.completed" }]);
+  });
+});

package/src/__tests__/ProjectRoomRealtimeProtocol.test.ts

@@ -29,6 +29,7 @@ const message: ProjectRoomBusinessEvent = {
       content: { type: "text", text: "Complete" },
       mentions: [],
       source: "agent",
+      sourceId: "reply-1",
       createdAt: "2026-09-03T00:00:00.000Z",
     },
   },
@@ -84,7 +85,6 @@ describe("Project Room realtime protocol", () => {
       "resync",
     ]);
     expect(JSON.stringify(message)).not.toContain("assistantId");
-    expect(JSON.stringify(message)).not.toContain("sourceId");
     expect(scope).toEqual({ tenantId: "tenant-1", roomId: "room-1", projectId: "project-1" });
     expect(actor).toEqual({
       tenantId: "tenant-1",
@@ -127,7 +127,7 @@ describe("Project Room realtime protocol", () => {
       status: "active", joinedAt: "2026-09-03T00:00:00.000Z", updatedAt: "2026-09-03T00:00:01.000Z",
     });
     expect(JSON.stringify(toProjectRoomPublicMessage(internalMessage))).not.toMatch(
-      /tenantId|workspaceId|projectId|assistantId|thread|idempotency|sourceId/,
+      /tenantId|workspaceId|projectId|assistantId|thread|idempotency/,
     );
   });
 

package/src/__tests__/a2a-types.test.ts

@@ -1,6 +1,5 @@
 import type { TaskFileRef, CreateTaskRequest } from "../TaskStoreProtocol";
 import type { A2AApiKeyRecord, CreateA2AApiKeyInput } from "../A2AApiKeyStoreProtocol";
-import type { A2AExposure } from "../A2AProtocol";
 
 describe("A2A protocol types", () => {
   it("TaskFileRef supports mimeType", () => {
@@ -22,9 +21,4 @@ describe("A2A protocol types", () => {
     };
     expect("workspaceId" in rec).toBe(false);
   });
-
-  it("A2AExposure shape", () => {
-    const exp: A2AExposure = { enabled: true, skills: [{ id: "s", name: "n", description: "d" }] };
-    expect(exp.enabled).toBe(true);
-  });
 });

package/src/__tests__/open-grants.test.ts

@@ -0,0 +1,29 @@
+import { effectiveGrants } from "../OpenProtocol";
+
+describe("effectiveGrants", () => {
+  it("explicit grants win", () => {
+    const grants = [{ domain: "kb", items: ["search"] }];
+    expect(
+      effectiveGrants({ grants, assistantIds: ["a1"] }),
+    ).toEqual(grants);
+  });
+
+  it("assistantIds derive an agent-domain grant", () => {
+    expect(effectiveGrants({ assistantIds: ["a1", "a2"] })).toEqual([
+      { domain: "agent", items: ["a1", "a2"] },
+    ]);
+  });
+
+  it("legacy empty assistantIds = bare agent grant (all exposed agents)", () => {
+    expect(effectiveGrants({ assistantIds: [] })).toEqual([
+      { domain: "agent" },
+    ]);
+    expect(effectiveGrants({})).toEqual([{ domain: "agent" }]);
+  });
+
+  it("empty explicit grants array falls through to legacy derivation", () => {
+    expect(effectiveGrants({ grants: [], assistantIds: ["a1"] })).toEqual([
+      { domain: "agent", items: ["a1"] },
+    ]);
+  });
+});

package/src/index.ts

@@ -57,6 +57,7 @@ export * from "./ProjectMembershipStoreProtocol";
 export * from "./ProjectBotMembershipStoreProtocol";
 export * from "./ProjectRoomMessageStoreProtocol";
 export * from "./ProjectRoomReadStateProtocol";
+export * from "./UserPushSubscriptionStoreProtocol";
 export * from "./ExactDataSnapshot";
 export * from "./ProjectRoomRealtimeProtocol";
 
@@ -85,6 +86,9 @@ export type {
   PluginMiddlewareFactory,
 } from "./PluginProtocol";
 
+export * from "./SandboxPluginProtocol";
+
 // 导出通用类型
 export * from "./types";
 export * from "./TrustedRunContextProtocol";
+export * from "./OpenProtocol";