@axiom-lattice/protocols 4.10.0 → 5.0.0

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/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/VectorStoreProviderProtocol.ts

@@ -17,6 +17,15 @@ export interface VectorStoreCreateParams {
   tableName: string;
   /** Embedding model key to use for embedding operations */
   embeddingKey: string;
+  /**
+   * Tenant whose embedding model the key belongs to.
+   *
+   * Tenant model keys are `${providerId}/${modelId}` and resolve per tenant, so
+   * a provider cannot look one up without knowing whose it is. Omitted means the
+   * deployment namespace (`"default"`), which is where boot-time registrations
+   * live.
+   */
+  tenantId?: string;
   /** Provider-specific configuration */
   config?: Record<string, unknown>;
 }

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";