@axiom-lattice/protocols 4.11.0 → 5.0.0

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__/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,7 @@ export * from "./SandboxPluginProtocol";
 export * from "./types";
 export * from "./TrustedRunContextProtocol";
 export * from "./RunScope";
+export * from "./RunCancelProtocol";
 export * from "./AgentAffinity";
 export * from "./OpenProtocol";
 export * from "./McpUiProtocol";