@baique/pi-web-sky 0.1.35 → 0.1.36

package/lib/agent-event-stream.test.mjs

@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const { createAgentEventStream } = await jiti.import("./agent-event-stream.ts");
+const decoder = new TextDecoder();
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+async function readWithin(reader, timeoutMs = 1_000) {
+  let timeout;
+  try {
+    return await Promise.race([
+      reader.read(),
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new Error("Timed out reading SSE chunk")), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function decodeData(chunk) {
+  const text = decoder.decode(chunk.value);
+  assert.match(text, /^data: /);
+  return JSON.parse(text.slice("data: ".length));
+}
+
+test("opens the transport before a slow session is ready and snapshots after subscribing", async () => {
+  const startup = deferred();
+  const abortController = new AbortController();
+  const stream = createAgentEventStream(
+    new Request("http://localhost/events", { signal: abortController.signal }),
+    "session-id",
+    startup.promise,
+  );
+  const reader = stream.getReader();
+
+  const transport = await readWithin(reader);
+  assert.equal(decoder.decode(transport.value), ":\n\n");
+
+  const snapshot = { role: "assistant", content: [{ type: "text", text: "Hello" }] };
+  let listener;
+  let subscribeCount = 0;
+  let unsubscribeCount = 0;
+  startup.resolve({
+    isStreaming: true,
+    streamingMessage: snapshot,
+    onEvent(nextListener) {
+      subscribeCount += 1;
+      listener = nextListener;
+      nextListener({
+        type: "message_update",
+        message: snapshot,
+        assistantMessageEvent: { type: "text_delta", delta: "ignored" },
+      });
+      nextListener({ type: "agent_start" });
+      return () => { unsubscribeCount += 1; };
+    },
+  });
+
+  const connected = decodeData(await readWithin(reader));
+  const messageStart = decodeData(await readWithin(reader));
+  const replayedEvent = decodeData(await readWithin(reader));
+  assert.equal(subscribeCount, 1);
+  assert.deepEqual(connected, {
+    type: "connected",
+    sessionId: "session-id",
+    isStreaming: true,
+  });
+  assert.deepEqual(messageStart, { type: "agent_start" });
+  assert.deepEqual(replayedEvent, { type: "message_start", message: snapshot });
+
+  listener({
+    type: "message_update",
+    message: { ...snapshot },
+    assistantMessageEvent: {
+      type: "text_delta",
+      delta: "!",
+      partial: { ...snapshot },
+    },
+  });
+  assert.deepEqual(decodeData(await readWithin(reader)), {
+    type: "message_update",
+    assistantMessageEvent: { type: "text_delta", delta: "!" },
+  });
+
+  abortController.abort();
+  assert.equal(unsubscribeCount, 1);
+  assert.equal((await readWithin(reader)).done, true);
+});
+
+test("reports a startup failure in-band after opening the transport", async () => {
+  const stream = createAgentEventStream(
+    new Request("http://localhost/events"),
+    "session-id",
+    Promise.reject(new Error("broken config")),
+  );
+  const reader = stream.getReader();
+
+  assert.equal(decoder.decode((await readWithin(reader)).value), ":\n\n");
+  assert.deepEqual(decodeData(await readWithin(reader)), {
+    type: "startup_error",
+    errorMessage: "Failed to start agent: broken config",
+  });
+  assert.equal((await readWithin(reader)).done, true);
+});
+
+test("does not subscribe when the client cancels during startup", async () => {
+  const startup = deferred();
+  let subscribeCount = 0;
+  const stream = createAgentEventStream(
+    new Request("http://localhost/events"),
+    "session-id",
+    startup.promise,
+  );
+  const reader = stream.getReader();
+
+  await readWithin(reader);
+  await reader.cancel();
+  startup.resolve({
+    isStreaming: false,
+    streamingMessage: undefined,
+    onEvent() {
+      subscribeCount += 1;
+      return () => {};
+    },
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.equal(subscribeCount, 0);
+});
+
+test("closes an already-aborted request and handles a later startup rejection", async () => {
+  const abortController = new AbortController();
+  abortController.abort();
+  const stream = createAgentEventStream(
+    new Request("http://localhost/events", { signal: abortController.signal }),
+    "session-id",
+    Promise.reject(new Error("startup failed after disconnect")),
+  );
+
+  assert.equal((await readWithin(stream.getReader())).done, true);
+  await new Promise((resolve) => setImmediate(resolve));
+});

package/lib/agent-event-stream.ts

@@ -0,0 +1,132 @@
+import {
+  isEventIncludedInSnapshot,
+  toClientAgentEvent,
+  type AgentEventLike,
+} from "./agent-event-wire";
+
+export interface AgentEventStreamSession {
+  readonly isStreaming: boolean;
+  readonly streamingMessage: unknown;
+  onEvent(listener: (event: AgentEventLike) => void): () => void;
+}
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Open the SSE transport immediately, then publish the session snapshot only
+ * after the agent is ready and its event listener has been installed.
+ */
+export function createAgentEventStream(
+  req: Request,
+  sessionId: string,
+  sessionPromise: Promise<AgentEventStreamSession>,
+): ReadableStream<Uint8Array> {
+  let cancelStream: (closeController: boolean) => void = () => {};
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      const encoder = new TextEncoder();
+      let closed = false;
+      let heartbeat: ReturnType<typeof setInterval> | null = null;
+      let unsubscribe: (() => void) | null = null;
+      let abortHandler: (() => void) | null = null;
+
+      const cleanup = (closeController: boolean) => {
+        if (closed) return;
+        closed = true;
+        if (heartbeat !== null) clearInterval(heartbeat);
+        unsubscribe?.();
+        unsubscribe = null;
+        if (abortHandler) req.signal.removeEventListener("abort", abortHandler);
+        if (closeController) {
+          try { controller.close(); } catch { /* stream already closed */ }
+        }
+      };
+      cancelStream = cleanup;
+
+      const enqueueText = (text: string) => {
+        if (closed) return;
+        try {
+          controller.enqueue(encoder.encode(text));
+        } catch {
+          cleanup(false);
+        }
+      };
+      const encode = (data: unknown) => {
+        enqueueText(`data: ${JSON.stringify(data)}\n\n`);
+      };
+      const forwardEvent = (event: AgentEventLike, snapshot: unknown) => {
+        if (isEventIncludedInSnapshot(event, snapshot)) return;
+        const clientEvent = toClientAgentEvent(event);
+        if (clientEvent) encode(clientEvent);
+      };
+
+      const publishSession = async () => {
+        try {
+          const session = await sessionPromise;
+          if (closed) return;
+
+          const bufferedEvents: AgentEventLike[] = [];
+          let snapshotPublished = false;
+          const handleEvent = (event: AgentEventLike) => {
+            if (!snapshotPublished) {
+              bufferedEvents.push(event);
+              return;
+            }
+            forwardEvent(event, snapshot);
+          };
+
+          const stopListening = session.onEvent(handleEvent);
+          if (closed) {
+            stopListening();
+            return;
+          }
+          unsubscribe = stopListening;
+
+          const snapshot = session.streamingMessage;
+          encode({
+            type: "connected",
+            sessionId,
+            isStreaming: session.isStreaming,
+          });
+          for (const event of bufferedEvents) forwardEvent(event, snapshot);
+          if (snapshot !== undefined && snapshot !== null) {
+            encode({ type: "message_start", message: snapshot });
+          }
+          snapshotPublished = true;
+        } catch (error) {
+          if (closed) return;
+          encode({
+            type: "startup_error",
+            errorMessage: `Failed to start agent: ${errorMessage(error)}`,
+          });
+          cleanup(true);
+        }
+      };
+
+      // Attach the rejection handler before checking the request signal. The
+      // route may already have started a shared cold-start promise.
+      void publishSession();
+
+      abortHandler = () => cleanup(true);
+      if (req.signal.aborted) {
+        cleanup(true);
+        return;
+      }
+      req.signal.addEventListener("abort", abortHandler, { once: true });
+
+      heartbeat = setInterval(() => enqueueText(":\n\n"), HEARTBEAT_INTERVAL_MS);
+
+      // Force the response headers through without claiming that the agent is
+      // ready. The client waits for the later `connected` data event.
+      enqueueText(":\n\n");
+    },
+    cancel() {
+      cancelStream(false);
+    },
+  });
+}

package/lib/agent-event-wire.test.mjs

@@ -0,0 +1,278 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const {
+  isEventIncludedInSnapshot,
+  toClientAgentEvent,
+} = await jiti.import("./agent-event-wire.ts");
+
+function assistantMessage(text) {
+  return {
+    role: "assistant",
+    content: [{ type: "text", text }],
+    api: "anthropic-messages",
+    provider: "anthropic",
+    model: "claude-sonnet-4-6",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: "pending",
+    timestamp: 1,
+  };
+}
+
+test("projects message_update onto Pi 0.84's JSON/RPC delta shape", () => {
+  const partial = assistantMessage("Hello");
+  const projected = toClientAgentEvent({
+    type: "message_update",
+    message: partial,
+    assistantMessageEvent: {
+      type: "text_delta",
+      contentIndex: 0,
+      delta: "o",
+      partial,
+    },
+  });
+
+  assert.deepEqual(projected, {
+    type: "message_update",
+    assistantMessageEvent: {
+      type: "text_delta",
+      contentIndex: 0,
+      delta: "o",
+    },
+  });
+  assert.equal(Object.hasOwn(projected, "message"), false);
+  assert.equal(Object.hasOwn(projected.assistantMessageEvent, "partial"), false);
+});
+
+test("keeps tool identity on toolcall_start without sending the cumulative partial", () => {
+  const partial = {
+    ...assistantMessage(""),
+    content: [{
+      type: "toolCall",
+      id: "call-write-1",
+      name: "write",
+      arguments: {},
+      partialJson: "",
+    }],
+  };
+  const projected = toClientAgentEvent({
+    type: "message_update",
+    message: partial,
+    assistantMessageEvent: {
+      type: "toolcall_start",
+      contentIndex: 0,
+      partial,
+    },
+  });
+
+  assert.deepEqual(projected, {
+    type: "message_update",
+    assistantMessageEvent: {
+      type: "toolcall_start",
+      contentIndex: 0,
+      id: "call-write-1",
+      toolName: "write",
+    },
+  });
+  assert.equal(Object.hasOwn(projected, "message"), false);
+  assert.equal(Object.hasOwn(projected.assistantMessageEvent, "partial"), false);
+});
+
+test("refreshes late tool identity on toolcall_delta", () => {
+  const partial = {
+    ...assistantMessage(""),
+    content: [{
+      type: "toolCall",
+      id: "call-late-1",
+      name: "write",
+      arguments: { path: "/tmp/file" },
+      partialJson: '{"path":"/tmp/file"',
+    }],
+  };
+  const projected = toClientAgentEvent({
+    type: "message_update",
+    message: partial,
+    assistantMessageEvent: {
+      type: "toolcall_delta",
+      contentIndex: 0,
+      delta: '"/tmp/file"',
+      partial,
+    },
+  });
+
+  assert.deepEqual(projected, {
+    type: "message_update",
+    assistantMessageEvent: {
+      type: "toolcall_delta",
+      contentIndex: 0,
+      delta: '"/tmp/file"',
+      id: "call-late-1",
+      toolName: "write",
+    },
+  });
+});
+
+test("does not whitelist assistant delta event types", () => {
+  const projected = toClientAgentEvent({
+    type: "message_update",
+    message: assistantMessage("future"),
+    assistantMessageEvent: {
+      type: "future_delta",
+      contentIndex: 3,
+      value: "kept",
+      partial: assistantMessage("future"),
+    },
+  });
+
+  assert.deepEqual(projected, {
+    type: "message_update",
+    assistantMessageEvent: {
+      type: "future_delta",
+      contentIndex: 3,
+      value: "kept",
+    },
+  });
+});
+
+test("rejects a malformed message_update without breaking the stream", () => {
+  assert.equal(toClientAgentEvent({
+    type: "message_update",
+    assistantMessageEvent: null,
+  }), null);
+});
+
+test("recognizes only the in-flight event already covered by a snapshot", () => {
+  const snapshot = assistantMessage("Hello");
+  assert.equal(isEventIncludedInSnapshot({
+    type: "message_update",
+    message: snapshot,
+    assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "o" },
+  }, snapshot), true);
+  assert.equal(isEventIncludedInSnapshot({
+    type: "message_update",
+    message: { ...snapshot },
+    assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "!" },
+  }, snapshot), false);
+  assert.equal(isEventIncludedInSnapshot({
+    type: "message_end",
+    message: snapshot,
+  }, snapshot), false);
+});
+
+test("keeps the existing event omissions and slim agent_end", () => {
+  assert.equal(toClientAgentEvent({ type: "turn_start" }), null);
+  assert.equal(toClientAgentEvent({ type: "turn_end" }), null);
+  assert.deepEqual(
+    toClientAgentEvent({ type: "agent_end", messages: [assistantMessage("done")] }),
+    { type: "agent_end" },
+  );
+
+  const messageStart = { type: "message_start", message: assistantMessage("") };
+  assert.strictEqual(toClientAgentEvent(messageStart), messageStart);
+});
+
+test("forwards tool execution progress without repeating tool arguments", () => {
+  const partialResult = {
+    content: [{ type: "text", text: "Running phase 2" }],
+    details: { phase: 2 },
+  };
+
+  assert.deepEqual(toClientAgentEvent({
+    type: "tool_execution_update",
+    toolCallId: "call-workflow-1",
+    toolName: "workflow",
+    args: { large: "repeated input" },
+    partialResult,
+  }), {
+    type: "tool_execution_update",
+    toolCallId: "call-workflow-1",
+    toolName: "workflow",
+    partialResult,
+  });
+});
+
+function projectedStreamBytes(totalLength) {
+  const chunkSize = 64;
+  let text = "";
+  let bytes = 0;
+
+  for (let offset = 0; offset < totalLength; offset += chunkSize) {
+    const delta = "x".repeat(Math.min(chunkSize, totalLength - offset));
+    text += delta;
+    const partial = assistantMessage(text);
+    const projected = toClientAgentEvent({
+      type: "message_update",
+      message: partial,
+      assistantMessageEvent: {
+        type: "text_delta",
+        contentIndex: 0,
+        delta,
+        partial,
+      },
+    });
+
+    assert.equal(Object.hasOwn(projected, "message"), false);
+    assert.equal(Object.hasOwn(projected.assistantMessageEvent, "partial"), false);
+    bytes += Buffer.byteLength(JSON.stringify(projected));
+  }
+
+  return bytes;
+}
+
+test("serialized streaming traffic grows linearly with response length", () => {
+  const twoKiB = projectedStreamBytes(2 * 1024);
+  const fourKiB = projectedStreamBytes(4 * 1024);
+  assert.ok(fourKiB / twoKiB < 2.2, `expected near-linear growth, got ${fourKiB / twoKiB}`);
+});
+
+function projectedToolStreamBytes(totalLength) {
+  const chunkSize = 64;
+  let rawInput = "";
+  let bytes = 0;
+
+  for (let offset = 0; offset < totalLength; offset += chunkSize) {
+    const delta = "x".repeat(Math.min(chunkSize, totalLength - offset));
+    rawInput += delta;
+    const partial = {
+      ...assistantMessage(""),
+      content: [{
+        type: "toolCall",
+        id: "call-write-1",
+        name: "write",
+        arguments: { content: rawInput },
+        partialJson: rawInput,
+      }],
+    };
+    const projected = toClientAgentEvent({
+      type: "message_update",
+      message: partial,
+      assistantMessageEvent: {
+        type: "toolcall_delta",
+        contentIndex: 0,
+        delta,
+        partial,
+      },
+    });
+
+    assert.equal(Object.hasOwn(projected, "message"), false);
+    assert.equal(Object.hasOwn(projected.assistantMessageEvent, "partial"), false);
+    bytes += Buffer.byteLength(JSON.stringify(projected));
+  }
+
+  return bytes;
+}
+
+test("serialized tool-input traffic grows linearly with write content", () => {
+  const twoKiB = projectedToolStreamBytes(2 * 1024);
+  const fourKiB = projectedToolStreamBytes(4 * 1024);
+  assert.ok(fourKiB / twoKiB < 2.2, `expected near-linear growth, got ${fourKiB / twoKiB}`);
+});

package/lib/agent-event-wire.ts

@@ -0,0 +1,107 @@
+import type { JsonAgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+export interface AgentEventLike {
+  type: string;
+  [key: string]: unknown;
+}
+
+type JsonMessageUpdateEvent = Extract<
+  JsonAgentSessionEvent,
+  { type: "message_update" }
+>;
+
+type JsonAssistantMessageEvent = JsonMessageUpdateEvent["assistantMessageEvent"];
+type JsonToolCallStartEvent = Extract<JsonAssistantMessageEvent, { type: "toolcall_start" }>;
+type JsonToolCallDeltaEvent = Extract<JsonAssistantMessageEvent, { type: "toolcall_delta" }>;
+
+export type ClientAssistantMessageEvent =
+  | Exclude<JsonAssistantMessageEvent, { type: "toolcall_start" | "toolcall_delta" }>
+  | (JsonToolCallStartEvent & { id?: string; toolName?: string })
+  | (JsonToolCallDeltaEvent & { id?: string; toolName?: string });
+
+export type ClientMessageUpdateEvent = Omit<JsonMessageUpdateEvent, "assistantMessageEvent"> & {
+  assistantMessageEvent: ClientAssistantMessageEvent;
+};
+
+const OMITTED_EVENT_TYPES = new Set([
+  "turn_start",
+  "turn_end",
+]);
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toolCallMetadata(
+  event: Record<string, unknown>,
+): { id: string; toolName: string } | null {
+  if (
+    (event.type !== "toolcall_start" && event.type !== "toolcall_delta")
+    || !isObject(event.partial)
+  ) return null;
+  const content = event.partial.content;
+  const contentIndex = event.contentIndex;
+  if (!Array.isArray(content) || typeof contentIndex !== "number") return null;
+
+  const block = content[contentIndex];
+  if (!isObject(block) || block.type !== "toolCall") return null;
+  const id = typeof block.id === "string"
+    ? block.id
+    : (typeof block.toolCallId === "string" ? block.toolCallId : null);
+  const toolName = typeof block.name === "string"
+    ? block.name
+    : (typeof block.toolName === "string" ? block.toolName : null);
+  return id !== null && toolName !== null ? { id, toolName } : null;
+}
+
+/** Apply pi-web's event filters plus Pi 0.84's message_update projection. */
+export function toClientAgentEvent(
+  event: AgentEventLike,
+): AgentEventLike | ClientMessageUpdateEvent | null {
+  if (OMITTED_EVENT_TYPES.has(event.type)) return null;
+
+  if (event.type === "message_update") {
+    const assistantMessageEvent = event.assistantMessageEvent;
+    if (
+      typeof assistantMessageEvent !== "object"
+      || assistantMessageEvent === null
+      || Array.isArray(assistantMessageEvent)
+    ) return null;
+
+    if (!("partial" in assistantMessageEvent)) {
+      return {
+        type: "message_update",
+        assistantMessageEvent,
+      } as ClientMessageUpdateEvent;
+    }
+
+    const metadata = toolCallMetadata(assistantMessageEvent as Record<string, unknown>);
+    const { partial: _partial, ...deltaEvent } = assistantMessageEvent;
+    void _partial;
+    return {
+      type: "message_update",
+      assistantMessageEvent: metadata ? { ...deltaEvent, ...metadata } : deltaEvent,
+    } as ClientMessageUpdateEvent;
+  }
+
+  if (event.type === "tool_execution_update") {
+    return {
+      type: "tool_execution_update",
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      partialResult: event.partialResult,
+    };
+  }
+
+  if (event.type === "agent_end") return { type: "agent_end" };
+  return event;
+}
+
+export function isEventIncludedInSnapshot(
+  event: AgentEventLike,
+  snapshot: unknown,
+): boolean {
+  return snapshot !== undefined
+    && (event.type === "message_start" || event.type === "message_update")
+    && event.message === snapshot;
+}

package/lib/agent-phase.ts

@@ -0,0 +1,24 @@
+import type { AgentPhase } from "@/hooks/useAgentSession";
+
+/** 播报槽用阶段文案（从 ChatWindow 抽出，供 ChatInput 使用，避免循环依赖） */
+export function phaseLabel(phase: AgentPhase, t: (key: string, params?: Record<string, string | number>) => string): string | null {
+  if (phase?.kind === "running_tools") {
+    const latest = phase.tools[phase.tools.length - 1];
+    if (latest?.progress) {
+      return `${t("chat.runningNamedTool", { name: latest.name })} ${latest.progress}`;
+    }
+    const names = phase.tools.map((t) => t.name);
+    if (names.length === 0) return t("chat.runningTool");
+    if (names.length === 1) return t("chat.runningNamedTool", { name: names[0] });
+    if (names.length <= 3) return t("chat.runningTools", { names: names.join(", ") });
+    return t("chat.runningToolsMore", { names: names.slice(0, 2).join(", "), count: names.length - 2 });
+  }
+  if (phase?.kind === "waiting_model") return t("chat.waitingModel");
+  if (phase?.kind === "running_command") return t("chat.runningCommand");
+  return null;
+}
+
+/** 状态行的思考球：等待模型 = breathing，执行工具/命令 = working */
+export function orbModeForPhase(phase: AgentPhase): "breathing" | "working" {
+  return phase?.kind === "waiting_model" ? "breathing" : "working";
+}