@axiom-lattice/protocols 4.10.0 → 5.0.0

package/package.json

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

package/src/AgentInterruptProtocol.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalized human-in-the-loop interrupt exposed by the Agent Server surface.
+ */
+export interface AgentInterrupt {
+  /** Stable id derived from the LangGraph interrupt id or task/index. */
+  interruptId: string;
+  /** Normalized interrupt kind. */
+  type: "clarify" | "task_review" | "custom";
+  /** Thread whose graph is interrupted. */
+  threadId: string;
+  /** Task id that owns the interrupt, when available. */
+  taskId?: string;
+  /** Raw or normalized interrupt payload. */
+  payload: unknown;
+}

package/src/AgentLatticeProtocol.ts

@@ -14,7 +14,6 @@ import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
 export enum AgentType {
   REACT = "react",
   DEEP_AGENT = "deep_agent",
-  TEAM = "team",
   PROCESSING = "processing",
   /** Remote A2A agent — delegates to an external A2A-compatible server */
   A2A_REMOTE = "a2a_remote",
@@ -203,52 +202,6 @@ export interface ProcessingAgentConfig extends BaseAgentConfig {
   internalSubAgents?: AgentConfig[];
 }
 
-/**
- * Team teammate configuration -- describes an available teammate.
- */
-export interface TeamTeammateConfig {
-  /** Unique name for this teammate (used as agent ID) */
-  name: string;
-  /** Role category (e.g. "research", "writing", "review") */
-  role: string;
-  /** Human-readable description of what this teammate does */
-  description: string;
-  /** Tool keys this teammate has access to */
-  tools?: string[];
-  /** Custom system prompt for this teammate */
-  prompt?: string;
-  /** Model key override for this teammate */
-  modelKey?: string;
-}
-
-/**
- * TEAM agent configuration -- a team lead that dynamically creates teammates.
- * Teammates are created on-the-fly from create_team tool input (name, role, description).
- */
-export interface TeamAgentConfig extends BaseAgentConfig {
-  type: AgentType.TEAM;
-  /** Tool keys available to the team lead */
-  tools?: string[];
-  /** Maximum number of teammates running concurrently */
-  maxConcurrency?: number;
-  /**
-   * Schedule lattice key for polling task list / mailbox.
-   * When set, teammates use ScheduleLattice for periodic polling instead of event-driven wait.
-   */
-  scheduleLatticeKey?: string;
-  /** Poll interval in ms when using schedule lattice (default: 5000) */
-  pollIntervalMs?: number;
-}
-
-/**
- * Type guard to check if config is TeamAgentConfig
- */
-export function isTeamAgentConfig(
-  config: AgentConfig
-): config is TeamAgentConfig {
-  return config.type === AgentType.TEAM;
-}
-
 // ─── A2A_REMOTE Agent ──────────────────────────────────────────────────────
 
 export interface LocalRuntimeConfig {
@@ -361,7 +314,6 @@ export function isWorkflowAgentConfig(
 export type AgentConfig =
   | ReactAgentConfig
   | DeepAgentConfig
-  | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
   | WorkflowAgentConfig
@@ -372,7 +324,6 @@ export type AgentConfig =
 export type AgentConfigWithTools =
   | ReactAgentConfig
   | DeepAgentConfig
-  | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
   | WorkflowAgentConfig

package/src/AgentWebAppRuntimeProtocol.ts

@@ -104,6 +104,8 @@ export type AgentWebAppErrorCode =
   | "THREAD_NOT_FOUND"
   | "STREAM_CONFLICT"
   | "STREAM_FAILED"
+  | "RUN_CANCEL_UNAVAILABLE"
+  | "RUN_CANCEL_STORE_UNAVAILABLE"
   | "INVALID_REQUEST"
   | "INTERNAL_ERROR";
 

package/src/ChannelAdapterProtocol.ts

@@ -54,6 +54,13 @@ export interface OutboundStreamChunk {
   text: string;
   /** 是否结束（最后一次刷新必须为 `true`）。 */
   done: boolean;
+  /**
+   * 结束原因；仅对 `done: true` 有意义。未提供视为正常完成。
+   *
+   * 适配器可据此决定是否发送运行中途产生的附加内容（例如企业微信卡片）：
+   * 失败/中断/超时的轮次不应把半成品当成正常结果展示。
+   */
+  reason?: "completed" | "failed" | "interrupted" | "timeout";
 }
 
 export interface DispatchResult {
@@ -80,6 +87,16 @@ export type MessageMiddleware = (
 export interface ChannelAdapter<TConfig = unknown> {
   readonly channel: string;
   readonly configSchema: z.ZodSchema<TConfig>;
+  /**
+   * Whether `sendReply` is safe to call from any Gateway replica.
+   *
+   * @remarks
+   * Only adapters whose reply transport is stateless/HTTP (for example Lark)
+   * may set this. Connection-bound adapters (WeCom/WeChat/Room) leave it
+   * undefined: their replies depend on process-local sockets or context tokens,
+   * so the durable cross-replica reply path must not claim their jobs.
+   */
+  readonly durableReply?: boolean;
   receive(
     rawPayload: unknown,
     installation: ChannelInstallation,

package/src/ChannelReplyJobProtocol.ts

@@ -0,0 +1,184 @@
+/** Lifecycle of one durable channel reply delivery attempt. */
+export type ChannelReplyJobStatus = "pending" | "delivered" | "failed";
+
+/**
+ * A durable, cross-replica channel reply job.
+ *
+ * @remarks
+ * The row is keyed by `runId` but always read/written inside a tenant scope.
+ * Claiming is a lease-based CAS: only a pending, due row with no live lease can
+ * be claimed, and terminal writes must present the current lease owner.
+ */
+export interface ChannelReplyJob {
+  runId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  adapterChannel: string;
+  channelInstallationId: string;
+  replyTarget: Record<string, unknown>;
+  inputMessageId: string;
+  /**
+   * Legacy chunk-buffer cursor captured before the run was created.
+   *
+   * @remarks Retained for schema compatibility. The durable dispatcher now
+   * reads final text from the thread checkpoint and does not use this field.
+   */
+  streamCursor?: string | null;
+  status: ChannelReplyJobStatus;
+  attempts: number;
+  /** Epoch milliseconds. */
+  availableAt: number;
+  leaseOwner: string | null;
+  /** Epoch milliseconds. */
+  leaseExpiresAt: number | null;
+  lastError: string | null;
+  outputMessageId: string | null;
+  /** Epoch milliseconds. */
+  createdAt: number;
+  /** Epoch milliseconds. */
+  updatedAt: number;
+  /** Epoch milliseconds. */
+  deliveredAt: number | null;
+}
+
+/** Fields accepted when enqueuing a reply job. Status/lease/output fields are assigned by the store. */
+export interface CreateChannelReplyJobInput {
+  runId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  adapterChannel: string;
+  channelInstallationId: string;
+  replyTarget: Record<string, unknown>;
+  inputMessageId: string;
+  /**
+   * Legacy chunk-buffer cursor captured before the run was created.
+   *
+   * @remarks Retained for schema compatibility. The durable dispatcher now
+   * reads final text from the thread checkpoint and does not use this field.
+   */
+  streamCursor?: string | null;
+  /** Earliest epoch-ms time the job may be claimed. */
+  availableAt: number;
+}
+
+/** Persistence boundary for durable channel reply jobs. */
+export interface ChannelReplyJobStore {
+  /** Creates a pending job. */
+  create(input: CreateChannelReplyJobInput): Promise<ChannelReplyJob>;
+  /** Reads one job within a tenant scope. */
+  get(tenantId: string, runId: string): Promise<ChannelReplyJob | null>;
+  /** Lists claimable pending jobs that are due at `now`, oldest first. */
+  listPending(now: number, limit?: number): Promise<ChannelReplyJob[]>;
+  /**
+   * Atomically leases a pending, due job that is unleased or has an expired
+   * lease. Returns the claimed job, or `null` when another owner won.
+   */
+  claim(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    leaseMs: number,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Marks a job delivered when `owner` still holds the lease. */
+  markDelivered(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    outputMessageId?: string | null,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Returns a job to pending with an incremented attempt count. */
+  reschedule(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    error: string,
+    availableAt: number,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Marks a job terminally failed. */
+  markFailed(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    error: string,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Deletes one job. Returns whether a row was removed. */
+  delete(tenantId: string, runId: string): Promise<boolean>;
+  /**
+   * Deletes up to `limit` terminal (`delivered`/`failed`) jobs whose last update
+   * is strictly older than `before`.
+   *
+   * @param before Epoch milliseconds retention cutoff.
+   * @param limit Maximum rows to prune in this batch (normalized 1..200).
+   * @returns Number of rows removed.
+   */
+  deleteTerminalBefore(before: number, limit?: number): Promise<number>;
+}
+
+/** Smallest accepted page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_MIN = 1;
+/** Largest accepted page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_MAX = 200;
+/** Default page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_DEFAULT = 100;
+
+/**
+ * Normalizes a caller-supplied page size into the shared 1..200 range.
+ *
+ * @remarks Zero and negative values clamp to 1; non-finite values fall back to
+ * the default. Stores must use this helper so InMemory and PostgreSQL agree.
+ */
+export function normalizeChannelReplyJobListLimit(limit?: number): number {
+  if (limit === undefined || !Number.isFinite(limit)) {
+    return CHANNEL_REPLY_JOB_LIST_LIMIT_DEFAULT;
+  }
+  return Math.min(
+    CHANNEL_REPLY_JOB_LIST_LIMIT_MAX,
+    Math.max(CHANNEL_REPLY_JOB_LIST_LIMIT_MIN, Math.trunc(limit)),
+  );
+}
+
+/** Rejects missing/blank required fields and malformed create payloads at runtime. */
+export function assertValidCreateChannelReplyJobInput(
+  input: CreateChannelReplyJobInput,
+): void {
+  if (input === null || typeof input !== "object") {
+    throw new Error("ChannelReplyJob create input is required");
+  }
+  const required: Array<[string, unknown]> = [
+    ["runId", input.runId],
+    ["tenantId", input.tenantId],
+    ["assistantId", input.assistantId],
+    ["threadId", input.threadId],
+    ["adapterChannel", input.adapterChannel],
+    ["channelInstallationId", input.channelInstallationId],
+    ["inputMessageId", input.inputMessageId],
+  ];
+  for (const [field, value] of required) {
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new Error(`ChannelReplyJob requires a non-empty ${field}`);
+    }
+  }
+  if (
+    typeof input.replyTarget !== "object" ||
+    input.replyTarget === null ||
+    Array.isArray(input.replyTarget)
+  ) {
+    throw new Error("ChannelReplyJob requires a replyTarget object");
+  }
+  if (typeof input.availableAt !== "number" || !Number.isFinite(input.availableAt)) {
+    throw new Error("ChannelReplyJob requires a finite availableAt");
+  }
+  if (
+    input.streamCursor !== undefined &&
+    input.streamCursor !== null &&
+    typeof input.streamCursor !== "string"
+  ) {
+    throw new Error("ChannelReplyJob streamCursor must be a string");
+  }
+}

package/src/CheckpointStorageProtocol.ts

@@ -0,0 +1,98 @@
+/**
+ * Checkpoint storage usage for a single thread.
+ *
+ * This is a read-only accounting view over the checkpointer's persisted rows.
+ */
+export interface ThreadCheckpointStorage {
+  /** Thread whose checkpoint rows were measured. */
+  threadId: string;
+  /** Sum of checkpoint, channel-value, and pending-write bytes. */
+  totalBytes: number;
+  /** Persisted checkpoint rows (`checkpoints` table). */
+  checkpoints: { count: number; bytes: number };
+  /** Persisted channel values (`checkpoint_blobs` table). */
+  channelValues: { count: number; bytes: number };
+  /** Persisted pending writes (`checkpoint_writes` table). */
+  pendingWrites: { count: number; bytes: number };
+}
+
+/**
+ * Read-only checkpoint storage accounting.
+ *
+ * Implementations must not create, copy, prune, or mutate checkpoint rows.
+ */
+export interface CheckpointStorage {
+  /**
+   * Measure the checkpoint storage used by one thread.
+   *
+   * @param threadId - Thread id whose checkpoint rows should be measured.
+   * @returns Counts and byte sizes grouped by checkpoint storage category.
+   */
+  get(threadId: string): Promise<ThreadCheckpointStorage>;
+}
+
+/**
+ * Checkpoint maintenance operations over persisted thread checkpoints.
+ *
+ * Implementations copy, delete, and prune raw checkpoint rows for a thread.
+ * Callers must verify thread ownership and refuse to run while the thread is
+ * active.
+ */
+export interface CheckpointMaintenance {
+  /**
+   * Copy every checkpoint row from a source thread to an empty target thread.
+   *
+   * @param sourceThreadId - Thread whose rows are copied.
+   * @param targetThreadId - Empty thread that receives the rows.
+   * @returns Resolves when the copy commits; an empty source is a no-op.
+   * @throws When the target already has checkpoint rows.
+   */
+  copyThread(sourceThreadId: string, targetThreadId: string): Promise<void>;
+
+  /**
+   * Delete every checkpoint row for a thread.
+   *
+   * @param threadId - Thread whose checkpoint rows are deleted.
+   * @returns Resolves when the deletion commits.
+   */
+  deleteThread(threadId: string): Promise<void>;
+
+  /**
+   * Delete the checkpoints that descend from a base checkpoint.
+   *
+   * Preserves the base checkpoint and every checkpoint that is not descended
+   * from it. Descendants are discovered by following both same-namespace
+   * `parent_checkpoint_id` edges and cross-namespace `metadata.parents` edges
+   * (the `{ "<parent checkpoint_ns>": "<parent checkpoint id>" }` map that
+   * LangGraph writes for subgraph checkpoints), recursively across all
+   * namespaces. Checkpoint-id ordering is not used. LangGraph keys the first
+   * superstep's writes of a resumed execution to the parent/base checkpoint, so
+   * writes keyed to the base itself belong to the rolled-back run and are
+   * deleted with descendant writes. Channel blobs are removed only when no
+   * retained checkpoint references them.
+   *
+   * @param threadId - Thread whose later checkpoint history is deleted.
+   * @param baseCheckpointId - Checkpoint to retain as the new tip, or `null` to
+   * delete every checkpoint for the thread. An empty string is invalid and must
+   * never be treated as the `null` wildcard.
+   * @returns Resolves when the deletion commits; no descendants is a no-op.
+   * @throws When the base checkpoint does not exist on the thread. Callers must
+   * fail closed rather than deleting an unknown range.
+   * @remarks The operation is transactional and idempotent so rollback recovery
+   * can retry it.
+   */
+  deleteAfter(threadId: string, baseCheckpointId: string | null): Promise<void>;
+
+  /**
+   * Retain only the latest N checkpoints per checkpoint namespace.
+   *
+   * @param threadId - Thread whose checkpoint history is pruned.
+   * @param options - Retention options.
+   * @param options.keepLatest - Number of latest checkpoints to retain per namespace.
+   * @returns Counts of deleted checkpoint, blob, and write rows.
+   */
+  pruneThread(
+    threadId: string,
+    options: { keepLatest: number },
+  ): Promise<{ checkpoints: number; blobs: number; writes: number }>;
+}

package/src/MessageProtocol.ts

@@ -114,6 +114,14 @@ export type MessageChunkType = typeof MessageChunkTypes[keyof typeof MessageChun
 
 export interface MessageChunk {
   type: MessageChunkType;
+  /**
+   * Shared append-log cursor for this chunk.
+   *
+   * Set by streaming transports when the chunk is read from a cursor-addressable
+   * log (for example Redis Streams) so reconnects can resume via SSE
+   * `Last-Event-ID`. Omitted by in-memory buffers configured without a log.
+   */
+  cursor?: string;
   data: {
     id: string;
     content?: string;

package/src/ModelProviderProtocol.ts

@@ -34,6 +34,21 @@ export type ModelProviderApiStyle = "chat-completions" | "responses";
  */
 export type ModelProviderLlmProvider = LLMConfig["provider"];
 
+/**
+ * What a model can do.
+ *
+ * Lives on the **model** row, not the provider: one provider is a set of
+ * credentials plus one base URL, and a single DashScope-compatible endpoint
+ * serves chat, embedding and speech at once. Putting this on the provider would
+ * force a tenant to create three providers pointing at the same address with
+ * the same secret.
+ *
+ * `"asr"` is speech-to-text; the runtime is the `stt` lattice, not
+ * `models`. The kinds are deliberately independent: each has its own lattice
+ * manager, its own loader guard, and its own client type.
+ */
+export type ModelKind = "chat" | "embedding" | "asr";
+
 /**
  * Build the tenant-scoped model key.
  *
@@ -360,6 +375,14 @@ export interface ProviderModelInput extends DiscoveredModel {
    * or carry `modelKwargs` the server needs, without duplicating the provider.
    */
   extra?: Record<string, unknown>;
+  /**
+   * What this model does.
+   *
+   * Omitted means "keep the stored kind"; a brand-new row defaults to
+   * `"chat"`. Discovery cannot tell the kinds apart from `/v1/models`, so the
+   * admin sets it.
+   */
+  kind?: ModelKind;
   /**
    * Whether this is the tenant's default model.
    *
@@ -390,6 +413,12 @@ export interface ModelSelection {
    * lose the config it already had.
    */
   extra?: Record<string, unknown>;
+  /**
+   * What this model does.
+   *
+   * Omitted means "leave the stored kind alone", the same rule as `extra`.
+   */
+  kind?: ModelKind;
   /**
    * Whether this is the tenant's default model.
    *
@@ -424,6 +453,13 @@ export interface ModelProviderModelEntry {
    */
   modelId: string;
 
+  /**
+   * What this model does — chat, embedding or speech-to-text.
+   *
+   * Rows created before this column existed are all `"chat"`.
+   */
+  kind: ModelKind;
+
   /**
    * Optional human-readable name from the upstream
    */
@@ -576,6 +612,12 @@ export interface TenantModelPublicEntry {
    */
   modelKey: string;
 
+  /**
+   * What this model does. Pickers filter on it: a chat selector must not offer
+   * an embedding model, and the collection picker must not offer a chat model.
+   */
+  kind: ModelKind;
+
   /**
    * Optional human-readable name
    */
@@ -703,6 +745,21 @@ export interface ModelProviderProbeRequest {
    * Wire protocol to speak. Defaults to `openai-compatible`.
    */
   protocol?: ModelProviderWireProtocol;
+
+  /**
+   * What kind of model to probe.
+   *
+   * A model-list probe proves the address and the credential, not that a model
+   * can actually run. For embeddings the meaningful check is one inference
+   * request, which is why the caller names the model and the kind.
+   */
+  kind?: ModelKind;
+
+  /**
+   * Model id to probe. Required when `kind` is `"embedding"`: the probe sends
+   * one tiny input to that model and reports the resulting vector's dimension.
+   */
+  modelId?: string;
 }
 
 /**
@@ -736,6 +793,14 @@ export interface ModelProviderProbeResult {
    * errors rather than as an unreachable probe.
    */
   error?: ModelProviderUpstreamErrorCode;
+
+  /**
+   * Dimension of the vector an embedding probe got back.
+   *
+   * Absent for a model-list probe, and for an upstream that answered but
+   * returned no usable vector.
+   */
+  dimensions?: number;
 }
 
 /**

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();