@axiom-lattice/protocols 4.11.0 → 6.0.0

package/src/RunCancelProtocol.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+
+/**
+ * Upper bound for every contract string. These payloads travel between
+ * replicas and are persisted with A2A tasks, so unbounded input is rejected
+ * at the shared boundary instead of relying on transport limits.
+ */
+const MAX_FIELD_LENGTH = 64 * 1024;
+
+const boundedString = z.string().min(1).max(MAX_FIELD_LENGTH);
+
+/** Terminal cancellation commands delivered to the replica that currently owns a run. */
+const RUN_CANCEL_REASONS = ["abort", "a2a.cancel", "shutdown"] as const;
+
+/**
+ * A cancellation signal routed to the current owner of a run.
+ *
+ * `runId` is mandatory: a signal without it cannot unambiguously identify the
+ * execution to stop, so it is rejected rather than applied to the thread.
+ */
+export interface RunCancelSignal {
+  commandId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  runId: string;
+  reason: "abort" | "a2a.cancel" | "shutdown";
+  createdAt: string;
+}
+
+/**
+ * Identity of a human-in-the-loop interrupt answer, used for distributed
+ * dedupe so multiple replicas settle the same answer at most once.
+ */
+export interface InterruptAnswerKey {
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  interruptId: string;
+}
+
+/**
+ * Durable A2A event delivery cursor stored with the shared A2A task.
+ * `lastEventId` is the last event already handed to the client.
+ */
+export interface A2AEventCursor {
+  taskId: string;
+  lastEventId: string;
+  updatedAt: string;
+}
+
+/** Strict validator for {@link RunCancelSignal}. */
+export const runCancelSignalSchema: z.ZodType<RunCancelSignal> = z.object({
+  commandId: boundedString,
+  tenantId: boundedString,
+  assistantId: boundedString,
+  threadId: boundedString,
+  runId: boundedString,
+  reason: z.enum(RUN_CANCEL_REASONS),
+  createdAt: boundedString,
+}).strict();
+
+/** Strict validator for {@link InterruptAnswerKey}. */
+export const interruptAnswerKeySchema: z.ZodType<InterruptAnswerKey> = z.object({
+  tenantId: boundedString,
+  assistantId: boundedString,
+  threadId: boundedString,
+  interruptId: boundedString,
+}).strict();
+
+/** Strict validator for {@link A2AEventCursor}. */
+export const a2aEventCursorSchema: z.ZodType<A2AEventCursor> = z.object({
+  taskId: boundedString,
+  lastEventId: boundedString,
+  updatedAt: boundedString,
+}).strict();

package/src/ScheduleLatticeProtocol.ts

@@ -361,6 +361,12 @@ export interface ScheduleClient {
    */
   restore(): Promise<number>;
 
+  /**
+   * Reconcile this replica's timers with the shared store. Implementations
+   * that support multi-replica scheduling should expose this.
+   */
+  reconcile?(): Promise<number>;
+
   // ===== Storage =====
 
   /**
@@ -414,4 +420,5 @@ export interface ScheduleLatticeProtocol
 
   // Recovery
   restore: () => Promise<number>;
+  reconcile?: () => Promise<number>;
 }

package/src/StoreProtocol.ts

@@ -0,0 +1,181 @@
+/**
+ * A tenant-scoped namespaced key-value item.
+ */
+export interface StoreItem {
+  /** Hierarchical namespace path. */
+  namespace: string[];
+  /** Item key, unique within `(tenantId, namespace)`. */
+  key: string;
+  /** Arbitrary JSON object stored under the key. */
+  value: Record<string, unknown>;
+  /** Creation timestamp. */
+  createdAt: Date;
+  /** Last write timestamp. */
+  updatedAt: Date;
+  /** Optional expiry timestamp; expired items are invisible. */
+  expiresAt?: Date;
+}
+
+/** Input for {@link StoreProtocol.put}. */
+export interface StorePutInput {
+  /** Non-empty namespace path. */
+  namespace: string[];
+  /** Non-empty item key. */
+  key: string;
+  /** JSON object value. */
+  value: Record<string, unknown>;
+  /**
+   * Optional time-to-live in minutes.
+   *
+   * @remarks Positive finite numbers are accepted; stores compute `expiresAt`.
+   */
+  ttlMinutes?: number;
+  /**
+   * Optional index hint accepted for future indexing.
+   *
+   * @remarks No vector index is created in this slice.
+   */
+  index?: boolean | string[];
+}
+
+/** Input for {@link StoreProtocol.search}. */
+export interface StoreSearchInput {
+  /** Only return items whose namespace starts with this path. */
+  namespacePrefix?: string[];
+  /** Deep partial-equality filter over `value`. */
+  filter?: Record<string, unknown>;
+  /** Case-insensitive substring over the serialized value. */
+  query?: string;
+  /** Maximum items to return. */
+  limit?: number;
+  /** Pagination offset. */
+  offset?: number;
+}
+
+/**
+ * Tenant-scoped namespaced key-value store with TTL and simple search.
+ *
+ * @remarks
+ * - Unique identity is `(tenantId, namespace, key)`.
+ * - Expired items are invisible to {@link get} and {@link search}.
+ * - `filter` is deep partial equality over `value`; `query` is a
+ *   case-insensitive substring over the serialized value. Semantic/embedding
+ *   search is deferred.
+ */
+export interface StoreProtocol {
+  /** Create or replace an item. */
+  put(tenantId: string, input: StorePutInput): Promise<StoreItem>;
+  /** Read an unexpired item. */
+  get(tenantId: string, namespace: string[], key: string): Promise<StoreItem | null>;
+  /** Delete an item regardless of expiry. */
+  delete(tenantId: string, namespace: string[], key: string): Promise<boolean>;
+  /** Search unexpired items. */
+  search(tenantId: string, input: StoreSearchInput): Promise<StoreItem[]>;
+  /** List distinct namespace paths under a prefix. */
+  listNamespaces(tenantId: string, prefix?: string[], limit?: number): Promise<string[][]>;
+  /** Hard-delete expired items across all tenants. */
+  deleteExpired(now: Date, limit: number): Promise<number>;
+}
+
+
+/** Separator reserved for encoded namespace paths. */
+export const STORE_IDENTITY_SEPARATOR = "\u001f";
+
+/** Raised when a store namespace/key identity is malformed. */
+export class StoreValidationError extends Error {
+  readonly code = "STORE_IDENTITY_INVALID" as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "StoreValidationError";
+  }
+}
+
+function validStoreSegment(value: unknown): value is string {
+  return typeof value === "string"
+    && value.length > 0
+    && !value.includes(STORE_IDENTITY_SEPARATOR);
+}
+
+/**
+ * Assert a non-empty namespace array of non-empty segments without the
+ * reserved separator.
+ *
+ * @param namespace - Candidate namespace path.
+ * @throws {StoreValidationError} When the namespace is malformed.
+ */
+export function assertStoreIdentity(namespace: unknown, key: unknown): asserts namespace is string[] {
+  if (!Array.isArray(namespace) || namespace.length === 0) {
+    throw new StoreValidationError("namespace must be a non-empty string array");
+  }
+  for (const segment of namespace) {
+    if (!validStoreSegment(segment)) {
+      throw new StoreValidationError(
+        "namespace segments must be non-empty strings without the reserved separator",
+      );
+    }
+  }
+  if (!validStoreSegment(key)) {
+    throw new StoreValidationError(
+      "key must be a non-empty string without the reserved separator",
+    );
+  }
+}
+
+/**
+ * Assert a namespace prefix (which may be empty for "all namespaces").
+ *
+ * @param prefix - Candidate prefix path.
+ * @throws {StoreValidationError} When any segment is malformed.
+ */
+export function assertStoreNamespacePrefix(prefix: unknown): asserts prefix is string[] {
+  if (!Array.isArray(prefix)) {
+    throw new StoreValidationError("namespace prefix must be a string array");
+  }
+  for (const segment of prefix) {
+    if (!validStoreSegment(segment)) {
+      throw new StoreValidationError(
+        "namespace segments must be non-empty strings without the reserved separator",
+      );
+    }
+  }
+}
+
+/**
+ * Validate and compute an expiry date from `ttlMinutes`.
+ *
+ * @param ttlMinutes - Optional positive finite TTL in minutes.
+ * @param now - Base time (default current time).
+ * @returns The expiry date, or `undefined` when no TTL was supplied.
+ * @throws {StoreValidationError} When the TTL is invalid or out of range.
+ */
+export function storeExpiresAt(
+  ttlMinutes: number | undefined,
+  now: Date = new Date(),
+): Date | undefined {
+  if (ttlMinutes === undefined) return undefined;
+  if (typeof ttlMinutes !== "number" || !Number.isFinite(ttlMinutes) || ttlMinutes <= 0) {
+    throw new StoreValidationError("ttlMinutes must be a positive number");
+  }
+  const expiresAt = new Date(now.getTime() + ttlMinutes * 60_000);
+  if (!Number.isFinite(expiresAt.getTime()) || expiresAt.getUTCFullYear() > 9999) {
+    throw new StoreValidationError("ttlMinutes is out of range");
+  }
+  return expiresAt;
+}
+
+/**
+ * Validate a non-negative safe-integer pagination value.
+ *
+ * @param value - Candidate limit/offset.
+ * @param fallback - Value used when omitted.
+ * @returns The validated number.
+ * @throws {StoreValidationError} When the value is not a non-negative safe integer.
+ */
+export function storePaginationValue(value: number | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new StoreValidationError("limit/offset must be a non-negative safe integer");
+  }
+  return value;
+}

package/src/TaskStoreProtocol.ts

@@ -379,6 +379,14 @@ export interface TaskListFilter {
    */
   priority?: string;
 
+  /**
+   * Filter by the isolated run thread linked from `context.thread_id`.
+   *
+   * @remarks Used to authorize read-only views of task execution threads that
+   * do not have a durable Thread row or AgentRun row.
+   */
+  threadId?: string;
+
   /**
    * Filter by workspace ID
    */

package/src/ThreadStoreProtocol.ts

@@ -38,6 +38,13 @@ export interface Thread {
    * Thread last update timestamp
    */
   updatedAt: Date;
+
+  /**
+   * Optional expiry timestamp used by the thread TTL sweeper.
+   *
+   * @remarks Absent means the thread never expires.
+   */
+  expiresAt?: Date;
 }
 
 /**
@@ -48,6 +55,14 @@ export interface CreateThreadRequest {
    * Thread metadata
    */
   metadata?: Record<string, any>;
+
+  /**
+   * Optional thread expiry timestamp.
+   *
+   * @remarks Routes compute this from `ttlSeconds`/`expiresAt`; the store only
+   * persists it.
+   */
+  expiresAt?: Date;
 }
 
 /**
@@ -123,4 +138,13 @@ export interface ThreadStore {
    * @returns true if thread exists, false otherwise
    */
   hasThread(tenantId: string, threadId: string): Promise<boolean>;
+
+  /**
+   * List expired threads across all tenants.
+   *
+   * @param now Current time; threads with `expiresAt <= now` are returned.
+   * @param limit Maximum number of threads to return.
+   * @returns Expired threads ordered by `expiresAt` ascending.
+   */
+  listExpiredThreads(now: Date, limit: number): Promise<Thread[]>;
 }

package/src/__tests__/McpUiProtocol.test.ts

@@ -41,3 +41,51 @@ describe("parseMcpUiRef", () => {
     expect(isMcpUiRef("x")).toBe(false);
   });
 });
+
+describe("plugin scope", () => {
+  const plugin = {
+    kind: "plugin" as const,
+    pluginType: "p",
+    resource: "ui/x.html",
+  };
+
+  it("preserves a scope between 1 and 4096 characters", () => {
+    const scope = "a".repeat(64);
+    expect(parseMcpUiRef({ ...plugin, scope })).toEqual({
+      ...plugin,
+      displayMode: "inline",
+      scope,
+    });
+  });
+
+  it("preserves boundary scopes of 1 and 4096 characters", () => {
+    for (const scope of ["a", "b".repeat(4096)]) {
+      expect(parseMcpUiRef({ ...plugin, scope })).toEqual({
+        ...plugin,
+        displayMode: "inline",
+        scope,
+      });
+    }
+  });
+
+  it("drops empty, non-string, and over-long scopes", () => {
+    for (const scope of ["", 42, "x".repeat(4097)]) {
+      const ref = parseMcpUiRef({ ...plugin, scope });
+      expect(ref && "scope" in ref).toBe(false);
+    }
+  });
+
+  it("does not carry scope on an mcp ref", () => {
+    const ref = parseMcpUiRef({
+      kind: "mcp",
+      serverKey: "weather",
+      resourceUri: "ui://weather/dashboard",
+      scope: "signed-scope-token",
+    });
+    expect(ref && "scope" in ref).toBe(false);
+  });
+
+  it("keeps a legacy plugin ref unchanged", () => {
+    expect(parseMcpUiRef(plugin)).toEqual({ ...plugin, displayMode: "inline" });
+  });
+});

package/src/__tests__/MenuProtocol.test.ts

@@ -15,10 +15,14 @@ describe("MenuProtocol mcpApp content type", () => {
       pluginType: "my-plugin",
       resource: "ui/report.html",
       title: "Report",
+      scope: "signed-scope-token",
     };
     for (const cfg of [mcp, plugin] as MenuContentConfig[]) {
       expect(JSON.parse(JSON.stringify(cfg))).toEqual(cfg);
     }
+    const parsed = JSON.parse(JSON.stringify(plugin)) as McpAppMenuConfig;
+    expect(parsed.kind).toBe("plugin");
+    expect(parsed.kind === "plugin" ? parsed.scope : undefined).toBe("signed-scope-token");
   });
 
   it("includes file and mcpApp in MenuContentType", () => {

package/src/__tests__/ObservabilityDashboardProtocol.test.ts

@@ -0,0 +1,17 @@
+import {
+  LANGFUSE_OBSERVABILITY_DASHBOARD_VERSION,
+  OBSERVABILITY_DASHBOARD_ELEMENT_KEY_PREFIX,
+  observabilityDashboardElementKey,
+} from "../ObservabilityDashboardProtocol";
+
+describe("observabilityDashboardElementKey", () => {
+  it("namespaces the provider key", () => {
+    expect(observabilityDashboardElementKey("langfuse")).toBe(
+      "observability_dashboard_langfuse",
+    );
+    expect(OBSERVABILITY_DASHBOARD_ELEMENT_KEY_PREFIX).toBe(
+      "observability_dashboard_",
+    );
+    expect(LANGFUSE_OBSERVABILITY_DASHBOARD_VERSION).toBe(3);
+  });
+});

package/src/__tests__/RunCancelProtocol.test.ts

@@ -0,0 +1,148 @@
+import {
+  a2aEventCursorSchema,
+  interruptAnswerKeySchema,
+  runCancelSignalSchema,
+} from "../RunCancelProtocol";
+import type {
+  A2AEventCursor,
+  InterruptAnswerKey,
+  RunCancelSignal,
+} from "../RunCancelProtocol";
+import {
+  a2aEventCursorSchema as a2aEventCursorSchemaFromIndex,
+  interruptAnswerKeySchema as interruptAnswerKeySchemaFromIndex,
+  runCancelSignalSchema as runCancelSignalSchemaFromIndex,
+} from "../index";
+
+const MAX_FIELD_LENGTH = 64 * 1024;
+
+const validCancelSignal: RunCancelSignal = {
+  commandId: "command-1",
+  tenantId: "tenant-1",
+  assistantId: "assistant-1",
+  threadId: "thread-1",
+  runId: "run-1",
+  reason: "abort",
+  createdAt: "2026-10-20T00:00:00.000Z",
+};
+
+const validInterruptAnswerKey: InterruptAnswerKey = {
+  tenantId: "tenant-1",
+  assistantId: "assistant-1",
+  threadId: "thread-1",
+  interruptId: "interrupt-1",
+};
+
+const validA2AEventCursor: A2AEventCursor = {
+  taskId: "task-1",
+  lastEventId: "event-1",
+  updatedAt: "2026-10-20T00:00:00.000Z",
+};
+
+describe("runCancelSignalSchema", () => {
+  it("round-trips a valid cancellation signal", () => {
+    expect(runCancelSignalSchema.parse(validCancelSignal)).toEqual(validCancelSignal);
+  });
+
+  it("accepts every supported reason", () => {
+    for (const reason of ["abort", "a2a.cancel", "shutdown"] as const) {
+      expect(runCancelSignalSchema.parse({ ...validCancelSignal, reason }).reason).toBe(reason);
+    }
+  });
+
+  it.each(["commandId", "tenantId", "assistantId", "threadId", "runId", "createdAt"] as const)(
+    "rejects a signal missing %s",
+    (field) => {
+      const invalid: Record<string, unknown> = { ...validCancelSignal };
+      delete invalid[field];
+
+      expect(runCancelSignalSchema.safeParse(invalid).success).toBe(false);
+    },
+  );
+
+  it.each(["commandId", "tenantId", "threadId", "runId"] as const)(
+    "rejects an empty %s",
+    (field) => {
+      expect(runCancelSignalSchema.safeParse({ ...validCancelSignal, [field]: "" }).success).toBe(false);
+    },
+  );
+
+  it("rejects an unknown reason", () => {
+    expect(runCancelSignalSchema.safeParse({ ...validCancelSignal, reason: "restart" }).success).toBe(false);
+  });
+
+  it("rejects an oversized field", () => {
+    const oversized = "x".repeat(MAX_FIELD_LENGTH + 1);
+
+    expect(runCancelSignalSchema.safeParse({ ...validCancelSignal, runId: oversized }).success).toBe(false);
+    expect(runCancelSignalSchema.safeParse({ ...validCancelSignal, createdAt: oversized }).success).toBe(false);
+  });
+
+  it("rejects unknown keys", () => {
+    expect(runCancelSignalSchema.safeParse({ ...validCancelSignal, extra: true }).success).toBe(false);
+  });
+});
+
+describe("interruptAnswerKeySchema", () => {
+  it("round-trips a valid interrupt answer key", () => {
+    expect(interruptAnswerKeySchema.parse(validInterruptAnswerKey)).toEqual(validInterruptAnswerKey);
+  });
+
+  it.each(["tenantId", "assistantId", "threadId", "interruptId"] as const)(
+    "rejects a key missing %s",
+    (field) => {
+      const invalid: Record<string, unknown> = { ...validInterruptAnswerKey };
+      delete invalid[field];
+
+      expect(interruptAnswerKeySchema.safeParse(invalid).success).toBe(false);
+    },
+  );
+
+  it("rejects an oversized field", () => {
+    const oversized = "x".repeat(MAX_FIELD_LENGTH + 1);
+
+    expect(interruptAnswerKeySchema.safeParse({ ...validInterruptAnswerKey, interruptId: oversized }).success)
+      .toBe(false);
+  });
+
+  it("rejects unknown keys", () => {
+    expect(interruptAnswerKeySchema.safeParse({ ...validInterruptAnswerKey, runId: "run-1" }).success)
+      .toBe(false);
+  });
+});
+
+describe("a2aEventCursorSchema", () => {
+  it("round-trips a valid A2A event cursor", () => {
+    expect(a2aEventCursorSchema.parse(validA2AEventCursor)).toEqual(validA2AEventCursor);
+  });
+
+  it.each(["taskId", "lastEventId", "updatedAt"] as const)(
+    "rejects a cursor missing %s",
+    (field) => {
+      const invalid: Record<string, unknown> = { ...validA2AEventCursor };
+      delete invalid[field];
+
+      expect(a2aEventCursorSchema.safeParse(invalid).success).toBe(false);
+    },
+  );
+
+  it("rejects an oversized field", () => {
+    const oversized = "x".repeat(MAX_FIELD_LENGTH + 1);
+
+    expect(a2aEventCursorSchema.safeParse({ ...validA2AEventCursor, lastEventId: oversized }).success)
+      .toBe(false);
+  });
+
+  it("rejects unknown keys", () => {
+    expect(a2aEventCursorSchema.safeParse({ ...validA2AEventCursor, tenantId: "tenant-1" }).success)
+      .toBe(false);
+  });
+});
+
+describe("package exports", () => {
+  it("exposes the contracts from the package entry point", () => {
+    expect(runCancelSignalSchemaFromIndex).toBe(runCancelSignalSchema);
+    expect(interruptAnswerKeySchemaFromIndex).toBe(interruptAnswerKeySchema);
+    expect(a2aEventCursorSchemaFromIndex).toBe(a2aEventCursorSchema);
+  });
+});

package/src/__tests__/agent-web-app-types.test.ts

@@ -140,6 +140,8 @@ const errorCodes = [
   "THREAD_NOT_FOUND",
   "STREAM_CONFLICT",
   "STREAM_FAILED",
+  "RUN_CANCEL_UNAVAILABLE",
+  "RUN_CANCEL_STORE_UNAVAILABLE",
   "INVALID_REQUEST",
   "INTERNAL_ERROR",
 ] as const satisfies readonly AgentWebAppErrorCode[];
@@ -309,6 +311,8 @@ describe("Agent Web App protocol types", () => {
       "THREAD_NOT_FOUND",
       "STREAM_CONFLICT",
       "STREAM_FAILED",
+      "RUN_CANCEL_UNAVAILABLE",
+      "RUN_CANCEL_STORE_UNAVAILABLE",
       "INVALID_REQUEST",
       "INTERNAL_ERROR",
     ]);

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./STTModelLatticeProtocol";
 export * from "./VectorStoreLatticeProtocol";
 export * from "./LoggerLatticeProtocol";
 export * from "./MessageProtocol";
+export * from "./AgentInterruptProtocol";
 export * from "./ThreadStoreProtocol";
 export * from "./AssistantStoreProtocol";
 export * from "./SkillLatticeProtocol";
@@ -62,6 +63,9 @@ export * from "./UserPushSubscriptionStoreProtocol";
 export * from "./PluginDeploymentStoreProtocol";
 export * from "./LeaseStoreProtocol";
 export * from "./OutboxStoreProtocol";
+export * from "./CheckpointStorageProtocol";
+export * from "./StoreProtocol";
+export * from "./ChannelReplyJobProtocol";
 export * from "./ExactDataSnapshot";
 export * from "./ProjectRoomRealtimeProtocol";
 
@@ -98,6 +102,8 @@ export * from "./SandboxPluginProtocol";
 export * from "./types";
 export * from "./TrustedRunContextProtocol";
 export * from "./RunScope";
+export * from "./RunCancelProtocol";
 export * from "./AgentAffinity";
 export * from "./OpenProtocol";
 export * from "./McpUiProtocol";
+export * from "./ObservabilityDashboardProtocol";