@axiom-lattice/protocols 6.2.0 → 6.3.0

package/package.json

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

package/src/McpAppShareProtocol.ts

@@ -0,0 +1,29 @@
+import type { McpUiRef } from "./McpUiProtocol";
+
+/** Public-facing description of a shared MCP App. */
+export interface McpAppShareBootstrap {
+  title: string | null;
+  visibility: "public" | "password";
+  app: {
+    kind: "plugin" | "mcp";
+    toolName?: string;
+    ref: McpUiRef;
+    /** Initial arguments re-executed on every open. */
+    toolInput?: Record<string, unknown>;
+    /** Fresh tool result produced for this bootstrap. */
+    toolResult?: unknown;
+  };
+}
+
+/** Share card payload rendered inside an MCP App. */
+export interface ShareCardData {
+  token: string;
+  /** Relative gateway path; the host resolves it against its origin. */
+  path: string;
+  /** Optional absolute URL from a deployment-level public base URL. */
+  url?: string;
+  title: string;
+  visibility: "public" | "password";
+  password?: string;
+  warnings?: string[];
+}

package/src/McpUiProtocol.ts

@@ -25,6 +25,8 @@ export type McpUiRef =
       resourceUri: string;
       displayMode: McpUiDisplayMode;
       title?: string;
+      /** Tool that produced the UI resource (1..128 chars), when known. */
+      toolName?: string;
       /**
        * Retained only for backward compatibility with pre-unification
        * messages; no longer emitted. Rich tool results now travel via
@@ -38,6 +40,8 @@ export type McpUiRef =
       resource: string;
       displayMode: McpUiDisplayMode;
       title?: string;
+      /** Tool that produced the UI resource (1..128 chars), when known. */
+      toolName?: string;
       /** Opaque HMAC-signed run/connection scope (1..4096 chars); never contains secrets. */
       scope?: string;
     };
@@ -54,6 +58,7 @@ export interface McpUiResourcePayload {
 
 const MODES: McpUiDisplayMode[] = ["inline", "fullscreen", "pip"];
 const MAX_MCP_UI_SCOPE_LENGTH = 4096;
+const MAX_MCP_UI_TOOL_NAME_LENGTH = 128;
 const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
 
 /** Type guard for a parsed `McpUiRef`. */
@@ -68,6 +73,12 @@ export function parseMcpUiRef(value: unknown): McpUiRef | null {
     ? (value.displayMode as McpUiDisplayMode)
     : "inline";
   const title = typeof value.title === "string" ? value.title : undefined;
+  const toolName =
+    typeof value.toolName === "string" &&
+    value.toolName.length > 0 &&
+    value.toolName.length <= MAX_MCP_UI_TOOL_NAME_LENGTH
+      ? value.toolName
+      : undefined;
   if (value.kind === "mcp" && typeof value.serverKey === "string" && typeof value.resourceUri === "string") {
     return {
       kind: "mcp",
@@ -75,6 +86,7 @@ export function parseMcpUiRef(value: unknown): McpUiRef | null {
       resourceUri: value.resourceUri,
       displayMode,
       ...(title ? { title } : {}),
+      ...(toolName ? { toolName } : {}),
       ...(value.structuredContent !== undefined ? { structuredContent: value.structuredContent } : {}),
     };
   }
@@ -89,6 +101,7 @@ export function parseMcpUiRef(value: unknown): McpUiRef | null {
       resource: value.resource,
       displayMode,
       ...(title ? { title } : {}),
+      ...(toolName ? { toolName } : {}),
       ...(scope ? { scope } : {}),
     };
   }

package/src/MenuProtocol.ts

@@ -44,6 +44,7 @@ export type McpAppMenuConfig =
       resourceUri: string;
       displayMode?: McpUiDisplayMode;
       title?: string;
+      toolName?: string;
       toolInput?: Record<string, unknown>;
       toolResult?: unknown;
       ui?: ToolCallUi;
@@ -54,6 +55,7 @@ export type McpAppMenuConfig =
       resource: string;
       displayMode?: McpUiDisplayMode;
       title?: string;
+      toolName?: string;
       /** Signed scope copied from the ref so a pinned App can keep calling. */
       scope?: string;
       toolInput?: Record<string, unknown>;

package/src/OpenProtocol.ts

@@ -3,6 +3,17 @@
  * capability invocation). See docs/superpowers/specs/2026-09-07-open-platform-api-design.md.
  */
 
+/** Resource constraints attached to a grant (domain-specific). */
+export interface OpenGrantSelector {
+  /** Sandbox self-binding, set only on server-minted sandbox tokens. */
+  sandbox?: "self";
+  /**
+   * Connection keys of this domain's connection type (the plugin type).
+   * Absent/empty keeps the legacy connect-all behavior.
+   */
+  connections?: string[];
+}
+
 /** Authorization grant: default-deny; a grant covers one capability domain. */
 export interface OpenGrant {
   domain: string;
@@ -11,7 +22,7 @@ export interface OpenGrant {
    * Absent/empty = every action in the domain.
    */
   items?: string[];
-  selector?: { sandbox?: "self" };
+  selector?: OpenGrantSelector;
 }
 
 /** Execution context synthesized from a verified credential — never from the caller. */
@@ -20,6 +31,8 @@ export interface OpenExecutionContext {
   projectId: string;
   /** Addressing only, not an authorization dimension (see design §6.2). */
   workspaceId?: string;
+  /** Connection keys pinned by the covering grant (plugin domains only). */
+  connectionKeys?: string[];
   /** Synthesized run identity (mirrors the Agent path's runConfig; plugin tools resolve their own connections). */
   runConfig: Record<string, unknown>;
 }
@@ -67,6 +80,15 @@ export interface OpenCatalogItem {
   annotations?: { readOnlyHint: boolean; destructiveHint: boolean };
 }
 
+/** A tenant connection selectable for a connection-backed plugin domain. */
+export interface OpenCatalogConnection {
+  /** Connection key, stable within `(tenantId, domain type)`. */
+  key: string;
+  /** Human-readable connection name. */
+  name: string;
+  description?: string;
+}
+
 export interface OpenCatalogDomain {
   domain: string;
   label: string;
@@ -76,6 +98,10 @@ export interface OpenCatalogDomain {
   /** How grant items are chosen: per-action or per-instance. */
   itemKind: "action" | "instance";
   items: OpenCatalogItem[];
+  /** True when this domain's tools resolve tenant connections. */
+  connectionBacked?: boolean;
+  /** Tenant connections selectable for this domain (connection-backed only). */
+  connections?: OpenCatalogConnection[];
 }
 
 /** Full grantable capability catalog for a tenant (drives the key picker). */

package/src/SandboxResourceProtocol.ts

@@ -1,4 +1,5 @@
 import type { OpenGrant } from "./OpenProtocol";
+import type { McpUiDisplayMode } from "./McpUiProtocol";
 /**
  * SandboxResourceProtocol
  *
@@ -7,6 +8,9 @@ import type { OpenGrant } from "./OpenProtocol";
  * and file resolution types for the sandbox lattice.
  */
 
+/** Discriminator for the kind of resource a share points at. */
+export type ShareKind = "file" | "mcpApp";
+
 /** Sandbox resource location — project-grained, provider-agnostic. */
 export interface ResourceAddress {
   volume: string;
@@ -21,10 +25,40 @@ export interface ResourceResolver {
 /** Visibility level for resource shares. */
 export type ShareVisibility = "public" | "password" | "internal";
 
-/** Persisted record of a resource share within a project. */
-export interface ShareRecord {
+/** Live target of the MCP App a share points at. */
+export interface McpAppShareApp {
+  /** Where the App comes from. */
+  kind: "plugin" | "mcp";
+  /** Initial invocation tool; required for tool shares, optional for invocation shares. */
+  toolName?: string;
+  displayMode?: McpUiDisplayMode;
+  title?: string;
+  /** Plugin-sourced Apps. */
+  pluginType?: string;
+  resource?: string;
+  /** HMAC-signed scope; persisted on the share record, never emitted in bootstrap. */
+  scope?: string;
+  /** MCP-server-sourced Apps. */
+  serverKey?: string;
+  resourceUri?: string;
+  /**
+   * Initial tool arguments. Stored so a shared link can re-run the tool on
+   * every open; the tool result itself is never persisted.
+   */
+  toolInput?: Record<string, unknown>;
+}
+
+/** App share target stored in the reuse of the `address` column. */
+export interface McpAppShareTarget {
+  kind: "mcpApp";
+  app: McpAppShareApp;
+}
+
+/** Share target: either a file location or an App target. */
+export type ShareTarget = ResourceAddress | McpAppShareTarget;
+
+interface ShareRecordBase {
   token: string;
-  address: ResourceAddress;
   title: string | null;
   createdBy: string;
   tenantId: string;
@@ -44,8 +78,26 @@ export interface ShareRecord {
   version: number;
 }
 
-/** Client-provided payload for creating a new resource share. */
-export interface CreateShareRequest {
+/** Persisted record of a file share within a project. */
+export interface FileShareRecord extends ShareRecordBase {
+  kind: "file";
+  address: ResourceAddress;
+}
+
+/** Persisted record of an MCP App share within a project. */
+export interface McpAppShareRecord extends ShareRecordBase {
+  kind: "mcpApp";
+  address: McpAppShareTarget;
+  /** App shares V1 do not support `internal`. */
+  visibility: "public" | "password";
+}
+
+/** Persisted record of a resource share within a project. */
+export type ShareRecord = FileShareRecord | McpAppShareRecord;
+
+/** Client-provided payload for creating a new file share. */
+export interface CreateFileShareRequest {
+  kind?: "file";
   resourcePath: string;
   assistantId?: string;
   visibility?: ShareVisibility;
@@ -57,25 +109,49 @@ export interface CreateShareRequest {
   openGrants?: OpenGrant[];
 }
 
+/** Client-provided payload for creating a new MCP App share. */
+export interface CreateMcpAppShareRequest {
+  kind: "mcpApp";
+  app: McpAppShareApp;
+  title?: string;
+  /** Required: `public` or `password`; there is no default. */
+  visibility: "public" | "password";
+  password?: string;
+  expiresAt?: string;
+  maxAccess?: number;
+}
+
+/** Client-provided payload for creating a new resource share. */
+export type CreateShareRequest =
+  | CreateFileShareRequest
+  | CreateMcpAppShareRequest;
+
 /** Response returned to clients after a share is created. */
 export interface ShareResult {
   token: string;
   url: string;
 }
 
+/** Mutable fields of a persisted share record. */
+export interface ShareRecordPatch {
+  title?: string;
+  expiresAt?: Date | null;
+  maxAccess?: number | null;
+  revoked?: boolean;
+  visibility?: ShareVisibility;
+  passwordHash?: string | null;
+}
+
+/** Store insert shape for a new share record. */
+export type CreateShareRecord =
+  | Omit<FileShareRecord, "accessCount" | "createdAt" | "version">
+  | Omit<McpAppShareRecord, "accessCount" | "createdAt" | "version">;
+
 /** Store interface for persisting and querying resource shares. */
 export interface SharedResourceStore {
   findByToken(token: string): Promise<ShareRecord | null>;
-  create(record: Omit<ShareRecord, "accessCount" | "createdAt" | "version">): Promise<ShareRecord>;
-  update(
-    token: string,
-    patch: Partial<
-      Pick<
-        ShareRecord,
-        "title" | "expiresAt" | "maxAccess" | "revoked" | "visibility" | "passwordHash"
-      >
-    >,
-  ): Promise<void>;
+  create(record: CreateShareRecord): Promise<ShareRecord>;
+  update(token: string, patch: ShareRecordPatch): Promise<void>;
   listByUser(tenantId: string, userId: string): Promise<ShareRecord[]>;
   incrementAccess(token: string): Promise<void>;
   atomicIncrementAccess(token: string): Promise<boolean>;

package/src/__tests__/McpUiProtocol.toolName.test.ts

@@ -0,0 +1,26 @@
+import { parseMcpUiRef } from "../McpUiProtocol";
+
+describe("McpUiRef toolName", () => {
+  it("preserves toolName", () => {
+    const ref = parseMcpUiRef({
+      kind: "plugin",
+      pluginType: "demo",
+      resource: "ui/app.html",
+      displayMode: "inline",
+      toolName: "render_report",
+      scope: "abc",
+    });
+    expect(ref?.toolName).toBe("render_report");
+  });
+
+  it("parses legacy refs without toolName", () => {
+    const ref = parseMcpUiRef({
+      kind: "mcp",
+      serverKey: "demo",
+      resourceUri: "ui://demo/app",
+      displayMode: "inline",
+    });
+    expect(ref).not.toBeNull();
+    expect(ref?.toolName).toBeUndefined();
+  });
+});

package/src/index.ts

@@ -76,6 +76,7 @@ export * from "./WorkflowDSL";
 export * from "./InternalDSL";
 
 export * from "./SandboxResourceProtocol";
+export * from "./McpAppShareProtocol";
 
 // Plugin system
 export type {