@axiom-lattice/protocols 4.1.4 → 4.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.1.4",
+  "version": "4.2.1",
   "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/McpLatticeProtocol.ts

@@ -29,8 +29,14 @@ export interface McpServerConfig {
   args?: string[];
   /** URL for HTTP/SSE transport */
   url?: string;
-  /** Environment variables */
+  /** Environment variables (stdio transport; credentials passed to the server process) */
   env?: Record<string, string>;
+  /**
+   * Custom HTTP headers sent with every request (streamable_http / sse only).
+   * Commonly used for authentication, e.g. `{ Authorization: "Bearer <token>" }`.
+   * Ignored for stdio transport. Values are encrypted at rest by config stores.
+   */
+  headers?: Record<string, string>;
   /** Connection timeout in milliseconds */
   timeout?: number;
   /** Retry attempts on connection failure */

package/src/McpServerConfigStoreProtocol.ts

@@ -38,7 +38,8 @@ export interface McpServerConfigEntry {
   selectedTools: string[];
 
   /**
-   * Whether the env field is encrypted in storage
+   * Whether secret values (env vars and headers) are encrypted at rest.
+   * Field name kept for backward compatibility; it covers config.headers too.
    */
   isEnvEncrypted: boolean;
 

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;
@@ -23,4 +26,12 @@ export interface ProjectRoomMessageStore {
 
   /** Finds a room message by identifier within a tenant. */
   findById(tenantId: string, id: string): Promise<ProjectRoomMessage | null>;
+
+  /** Counts messages created strictly after a horizon, optionally excluding one human author. */
+  countAfter(input: {
+    tenantId: string;
+    roomId: string;
+    after: Date;
+    excludeAuthorUserId?: string;
+  }): Promise<number>;
 }

package/src/ProjectRoomReadStateProtocol.ts

@@ -0,0 +1,20 @@
+/** A user's per-room read marker used to compute unread counts. */
+export interface ProjectRoomReadState {
+  tenantId: string;
+  roomId: string;
+  userId: string;
+  /** Read horizon: messages created strictly after this instant are unread. */
+  lastReadAt: Date;
+  updatedAt: Date;
+}
+
+/** Persistence operations for per-user, per-room read markers. */
+export interface ProjectRoomReadStateStore {
+  /** Returns the user's read marker for a room, or null when never reported. */
+  get(tenantId: string, roomId: string, userId: string): Promise<ProjectRoomReadState | null>;
+  /**
+   * Upserts the read marker monotonically: an earlier lastReadAt never moves
+   * the marker backwards. Returns the stored state after the write.
+   */
+  markRead(input: { tenantId: string; roomId: string; userId: string; lastReadAt: Date }): Promise<ProjectRoomReadState>;
+}

package/src/ProjectRoomRealtimeProtocol.ts

@@ -83,25 +83,41 @@ export type ProjectRoomTaskChangedEvent = ProjectRoomEventOf<
   }
 >;
 
+/** A read-marker update broadcast on the acting user's channel. */
+export type ProjectRoomReadChangedEvent = ProjectRoomEventOf<
+  "read.changed",
+  { projectId: string; roomId: string; lastReadAt: string }
+>;
+
+/** A membership mutation that may change a user's room subscription set. */
+export type ProjectRoomMembershipAffectedEvent = ProjectRoomEventOf<
+  "membership.affected",
+  { change: "added" | "removed" | "role_changed"; projectId: string; roomId: string }
+>;
+
 /** All identified business events retained by the realtime broker. */
 export type ProjectRoomBusinessEvent =
   | ProjectRoomMessageCreatedEvent
   | ProjectRoomRosterChangedEvent
   | ProjectRoomMembershipChangedEvent
-  | ProjectRoomTaskChangedEvent;
+  | ProjectRoomTaskChangedEvent
+  | ProjectRoomReadChangedEvent
+  | ProjectRoomMembershipAffectedEvent;
 
 /** A business event before the broker assigns its process-local ID. */
 export type ProjectRoomBusinessEventDraft =
   | Omit<ProjectRoomMessageCreatedEvent, "id">
   | Omit<ProjectRoomRosterChangedEvent, "id">
   | Omit<ProjectRoomMembershipChangedEvent, "id">
-  | Omit<ProjectRoomTaskChangedEvent, "id">;
+  | Omit<ProjectRoomTaskChangedEvent, "id">
+  | Omit<ProjectRoomReadChangedEvent, "id">
+  | Omit<ProjectRoomMembershipAffectedEvent, "id">;
 
 /** A connection control event; control events are never replayed. */
 export type ProjectRoomControlEvent =
   | { type: "ready"; data: { epoch: string; headEventId: string | null } }
   | { type: "resync"; data: { reason: "SERVER_RESTART" | "CURSOR_EXPIRED" | "SLOW_CONSUMER" } }
-  | { type: "access.revoked"; data: { reason: "PROJECT_ACCESS_REVOKED" | "TOKEN_EXPIRED" } };
+  | { type: "access.revoked"; data: { reason: "PROJECT_ACCESS_REVOKED" | "TOKEN_EXPIRED" | "CONNECTION_SUPERSEDED" } };
 
 /** The authenticated identity used by Project Room realtime access checks. */
 export interface ProjectRoomRealtimeActor {
@@ -194,6 +210,15 @@ export function isProjectRoomEventId(value: unknown): value is string {
   return parseProjectRoomEventId(value) !== undefined;
 }
 
+/** projectId sentinel marking a per-user event channel inside the room broker. */
+export const PROJECT_ROOM_USER_CHANNEL_PROJECT = "__user_channel__";
+
+/** Builds the per-user broker scope used for membership and read broadcasts. */
+export function projectRoomUserEventScope(tenantId: string, userId: string): ProjectRoomEventScope {
+  if (!tenantId || !userId) throw new TypeError("Project Room user scope requires non-empty identifiers");
+  return { tenantId, roomId: `__user__:${userId}`, projectId: PROJECT_ROOM_USER_CHANNEL_PROJECT };
+}
+
 function isoDate(value: unknown): string | undefined {
   if (typeof value !== "object" || value === null) return undefined;
   try {

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/__tests__/ProjectRoomReadStateProtocol.test.ts

@@ -0,0 +1,16 @@
+import { projectRoomUserEventScope, parseProjectRoomEventId } from "../ProjectRoomRealtimeProtocol";
+
+describe("projectRoomUserEventScope", () => {
+  it("builds a stable per-user scope that cannot collide with room scopes", () => {
+    expect(projectRoomUserEventScope("t1", "u1")).toEqual({
+      tenantId: "t1", roomId: "__user__:u1", projectId: "__user_channel__",
+    });
+    expect(projectRoomUserEventScope("t1", "u1")).toEqual(projectRoomUserEventScope("t1", "u1"));
+    expect(projectRoomUserEventScope("t1", "u2")).not.toEqual(projectRoomUserEventScope("t1", "u1"));
+  });
+  it("user scope ids are valid broker event id candidates", () => {
+    const scope = projectRoomUserEventScope("t1", "u1");
+    expect(typeof scope.roomId).toBe("string");
+    expect(parseProjectRoomEventId(`${"0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"}:1`)?.sequence).toBe(1);
+  });
+});

package/src/__tests__/ProjectRoomStores.test.ts

@@ -264,6 +264,10 @@ class FakeProjectRoomMessageStore implements ProjectRoomMessageStore {
     const [tenantId, id] = args;
     return tenantId === "tenant-1" && id === "message-1" ? message : null;
   }
+
+  async countAfter(input: Parameters<ProjectRoomMessageStore["countAfter"]>[0]): Promise<number> {
+    return input.tenantId === "tenant-1" && input.roomId === "room-1" ? 1 : 0;
+  }
 }
 
 describe("ProjectRoomStore", () => {

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

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