@axiom-lattice/protocols 4.2.1 → 4.2.2

package/package.json

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

package/src/AgentWebAppStreamProjection.ts

@@ -62,6 +62,27 @@ export function projectAgentWebAppChunk(
       { type: "stream.completed" },
     ];
   }
+  if (chunk.type === MessageChunkTypes.ERROR) {
+    const code = typeof chunk.data.code === "string" ? chunk.data.code : "stream_error";
+    if (code === "aborted" || code === "superseded") {
+      return [{ type: "stream.completed" }];
+    }
+    // Expose the real reason to the client for debugging.
+    return [
+      {
+        type: "error",
+        error: {
+          code: "STREAM_FAILED",
+          message:
+            typeof chunk.data.content === "string" && chunk.data.content
+              ? chunk.data.content
+              : "Stream failed",
+          retryable: false,
+        },
+      },
+      { type: "stream.completed" },
+    ];
+  }
   if (chunk.type === MessageChunkTypes.MESSAGE_FAILED) {
     return [
       { type: "error", error: { code: "STREAM_FAILED", message: "Stream failed", retryable: true } },

package/src/ChannelAdapterProtocol.ts

@@ -76,6 +76,18 @@ export interface ChannelAdapter<TConfig = unknown> {
     message: OutboundMessage,
     installation: ChannelInstallation,
   ): Promise<void>;
+  /**
+   * 可选：把 Agent 暂停等待人工输入时的问题/提示投影到会话中。
+   *
+   * 与 `sendReply` 不同，这不是对某条入站消息的最终回复，而是运行中途
+   * 产生的一条独立 bot 消息（例如 Project Room 的 clarify 卡片）。
+   * `message.metadata.inputMessageId` 关联触发该运行的入站队列消息。
+   */
+  sendInterrupt?(
+    replyTarget: ReplyTarget,
+    message: OutboundMessage,
+    installation: ChannelInstallation,
+  ): Promise<void>;
   /**
    * 可选：Channel 自定义 thread ID 生成策略。
    * 如果提供，MessageRouter 会优先使用此方法决定 thread ID，

package/src/MessageProtocol.ts

@@ -82,6 +82,7 @@ export const MessageChunkTypes = {
   AI: 'ai',
   TOOL: 'tool',
   INTERRUPT: 'interrupt',
+  ERROR: 'error',
   MESSAGE_COMPLETED: 'message_completed',
   MESSAGE_FAILED: 'message_failed',
   THREAD_IDLE: 'thread_idle',
@@ -94,6 +95,11 @@ export interface MessageChunk {
   data: {
     id: string;
     content?: string;
+    /**
+     * Machine-readable end reason for {@link MessageChunkTypes.ERROR} chunks.
+     * Known values: `aborted`, `superseded`, `stream_error`.
+     */
+    code?: string;
     tool_call_chunks?: Array<{
       name?: string;
       args?: string;

package/src/ProjectRoomProtocol.ts

@@ -18,6 +18,17 @@ export type ProjectRoomMessageSource =
   | "routine"
   | "system";
 
+/**
+ * Canonical label prefix for the one-time room event that announces agent-to-agent task delegation.
+ *
+ * The projection text is `${PROJECT_ROOM_TASK_DELEGATED_LABEL} · <creator> → <owner>`; the UI maps
+ * the exact label or this prefix to the "delegated" task-event kind and never parses arbitrary prose.
+ */
+export const PROJECT_ROOM_TASK_DELEGATED_LABEL = "Task delegated";
+
+/** Separator between the delegation label and its resolved actor labels. */
+export const PROJECT_ROOM_TASK_DELEGATED_SEPARATOR = " · ";
+
 /** The main room associated with a project. */
 export interface ProjectRoom {
   id: string;

package/src/ProjectRoomRealtimeProtocol.ts

@@ -21,6 +21,8 @@ export interface ProjectRoomPublicMessage {
   mentions: ProjectRoomMention[];
   replyToMessageId?: string;
   source: ProjectRoomMessageSource;
+  /** Canonical source identity (e.g. the Task id for source "task"). */
+  sourceId?: string;
   createdAt: string;
 }
 
@@ -264,6 +266,10 @@ function mapPublicMessageRecord(record: Record<string, unknown>): ProjectRoomPub
     if (typeof record.replyToMessageId !== "string") return undefined;
     result.replyToMessageId = record.replyToMessageId;
   }
+  if (record.sourceId !== undefined) {
+    if (typeof record.sourceId !== "string") return undefined;
+    result.sourceId = record.sourceId;
+  }
   return result;
 }
 

package/src/UserPushSubscriptionStoreProtocol.ts

@@ -0,0 +1,25 @@
+/** A browser Web Push subscription belonging to one user. */
+export interface UserPushSubscription {
+  id: string;
+  tenantId: string;
+  userId: string;
+  /** Push service endpoint URL from the browser's PushSubscription. */
+  endpoint: string;
+  /** Client public keys used to encrypt the payload. */
+  keys: { p256dh: string; auth: string };
+  userAgent?: string;
+  createdAt: string;
+}
+
+/** Persistence operations for per-user Web Push subscriptions. */
+export interface UserPushSubscriptionStore {
+  /** Lists every subscription for a user (a user may have several devices). */
+  list(tenantId: string, userId: string): Promise<UserPushSubscription[]>;
+  /**
+   * Saves a subscription. Re-saving the same endpoint replaces its keys/agent
+   * (idempotent per tenant+user+endpoint).
+   */
+  save(input: Omit<UserPushSubscription, "id" | "createdAt">): Promise<UserPushSubscription>;
+  /** Deletes one subscription by endpoint. Returns whether a row was removed. */
+  delete(tenantId: string, userId: string, endpoint: string): Promise<boolean>;
+}

package/src/__tests__/AgentWebAppStreamProjection.test.ts

@@ -0,0 +1,59 @@
+/**
+ * AgentWebAppStreamProjection error handling tests.
+ *
+ * Internal `error` chunks (emitted when an Agent run is aborted or fails)
+ * must be projected onto the stable public event surface instead of being
+ * silently dropped or mistaken for assistant text.
+ */
+
+import { projectAgentWebAppChunk } from "../AgentWebAppStreamProjection";
+
+describe("projectAgentWebAppChunk - error chunks", () => {
+  it("projects a stream_error chunk to the real error message", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-1", content: "Provider rate limit exceeded", code: "stream_error" },
+    } as never);
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: { code: "STREAM_FAILED", message: "Provider rate limit exceeded", retryable: false },
+      },
+      { type: "stream.completed" },
+    ]);
+  });
+
+  it("falls back to 'Stream failed' when no content is provided", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-2", code: "stream_error" },
+    } as never);
+
+    expect(events).toEqual([
+      {
+        type: "error",
+        error: { code: "STREAM_FAILED", message: "Stream failed", retryable: false },
+      },
+      { type: "stream.completed" },
+    ]);
+  });
+
+  it("treats a user abort as a neutral completion without an error event", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-2", content: "Thread aborted", code: "aborted" },
+    } as never);
+
+    expect(events).toEqual([{ type: "stream.completed" }]);
+  });
+
+  it("treats a superseded run as a neutral completion without an error event", () => {
+    const events = projectAgentWebAppChunk({
+      type: "error",
+      data: { id: "err-3", content: "Thread superseded", code: "superseded" },
+    } as never);
+
+    expect(events).toEqual([{ type: "stream.completed" }]);
+  });
+});

package/src/__tests__/ProjectRoomRealtimeProtocol.test.ts

@@ -29,6 +29,7 @@ const message: ProjectRoomBusinessEvent = {
       content: { type: "text", text: "Complete" },
       mentions: [],
       source: "agent",
+      sourceId: "reply-1",
       createdAt: "2026-09-03T00:00:00.000Z",
     },
   },
@@ -84,7 +85,6 @@ describe("Project Room realtime protocol", () => {
       "resync",
     ]);
     expect(JSON.stringify(message)).not.toContain("assistantId");
-    expect(JSON.stringify(message)).not.toContain("sourceId");
     expect(scope).toEqual({ tenantId: "tenant-1", roomId: "room-1", projectId: "project-1" });
     expect(actor).toEqual({
       tenantId: "tenant-1",
@@ -127,7 +127,7 @@ describe("Project Room realtime protocol", () => {
       status: "active", joinedAt: "2026-09-03T00:00:00.000Z", updatedAt: "2026-09-03T00:00:01.000Z",
     });
     expect(JSON.stringify(toProjectRoomPublicMessage(internalMessage))).not.toMatch(
-      /tenantId|workspaceId|projectId|assistantId|thread|idempotency|sourceId/,
+      /tenantId|workspaceId|projectId|assistantId|thread|idempotency/,
     );
   });
 

package/src/index.ts

@@ -57,6 +57,7 @@ export * from "./ProjectMembershipStoreProtocol";
 export * from "./ProjectBotMembershipStoreProtocol";
 export * from "./ProjectRoomMessageStoreProtocol";
 export * from "./ProjectRoomReadStateProtocol";
+export * from "./UserPushSubscriptionStoreProtocol";
 export * from "./ExactDataSnapshot";
 export * from "./ProjectRoomRealtimeProtocol";