@baique/pi-web-sky 0.1.35 → 0.1.37

package/lib/agent-client.test.mjs

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, {
+  interopDefault: true,
+  moduleCache: false,
+});
+const { AgentCommandError, isPromptRejectedError, sendAgentCommand } = await jiti.import("./agent-client.ts");
+
+test("agent command HTTP rejections are distinguishable from transport failures", async (t) => {
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  globalThis.fetch = async () => new Response(
+    JSON.stringify({
+      error: "Authentication failed",
+      code: "prompt_rejected",
+      accepted: false,
+    }),
+    { status: 500, headers: { "Content-Type": "application/json" } },
+  );
+
+  await assert.rejects(
+    sendAgentCommand("session-id", { type: "prompt", message: "hello" }),
+    (error) => {
+      assert.equal(error instanceof AgentCommandError, true);
+      assert.equal(error.status, 500);
+      assert.equal(error.message, "Authentication failed");
+      assert.equal(error.code, "prompt_rejected");
+      assert.equal(error.accepted, false);
+      assert.equal(isPromptRejectedError(error), true);
+      return true;
+    },
+  );
+
+  const transportError = new TypeError("connection reset");
+  globalThis.fetch = async () => {
+    throw transportError;
+  };
+
+  await assert.rejects(
+    sendAgentCommand("session-id", { type: "prompt", message: "hello" }),
+    (error) => {
+      assert.equal(error, transportError);
+      assert.equal(error instanceof AgentCommandError, false);
+      assert.equal(isPromptRejectedError(error), false);
+      return true;
+    },
+  );
+});
+
+test("only an explicit negative prompt acknowledgement is definitive", () => {
+  assert.equal(
+    isPromptRejectedError(new AgentCommandError("proxy failure", 502)),
+    false,
+  );
+  assert.equal(
+    isPromptRejectedError(new AgentCommandError("generic API failure", 500, "internal_error", false)),
+    false,
+  );
+});

package/lib/agent-client.ts

@@ -0,0 +1,53 @@
+// Client-side helper for POST /api/agent/[id].
+//
+// Every /api/agent/[id] route returns one of:
+//   { success: true, data: <result> }
+//   { error: string }              (non-2xx)
+//
+// Call sites previously repeated the same 5-line fetch block 13× in
+// hooks/useAgentSession.ts. This helper collapses that down to one line.
+
+export class AgentCommandError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly code?: string,
+    public readonly accepted?: boolean,
+  ) {
+    super(message);
+    this.name = "AgentCommandError";
+  }
+}
+
+export function isPromptRejectedError(error: unknown): error is AgentCommandError {
+  return error instanceof AgentCommandError
+    && error.code === "prompt_rejected"
+    && error.accepted === false;
+}
+
+export async function sendAgentCommand<T = unknown>(
+  sessionId: string,
+  command: Record<string, unknown>,
+): Promise<T> {
+  const res = await fetch(`/api/agent/${encodeURIComponent(sessionId)}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(command),
+  });
+  const body = (await res.json().catch(() => ({}))) as {
+    success?: boolean;
+    data?: T;
+    error?: string;
+    code?: string;
+    accepted?: boolean;
+  };
+  if (!res.ok || body.error) {
+    throw new AgentCommandError(
+      body.error ?? `HTTP ${res.status}`,
+      res.status,
+      body.code,
+      body.accepted,
+    );
+  }
+  return body.data as T;
+}

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

@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const { AgentEventConnection } = await jiti.import("./agent-event-connection.ts");
+
+const CONNECTING = 0;
+const OPEN = 1;
+const CLOSED = 2;
+
+class FakeEventSource {
+  readyState = CONNECTING;
+  onmessage = null;
+  onerror = null;
+  closeCount = 0;
+
+  open() { this.readyState = OPEN; }
+  message(event) { this.onmessage?.({ data: JSON.stringify(event) }); }
+  error() {
+    this.readyState = CLOSED;
+    this.onerror?.(new Event("error"));
+  }
+  close() {
+    this.readyState = CLOSED;
+    this.closeCount += 1;
+  }
+}
+
+function createHarness({ readinessTimeoutMs = 100, reconnectDelayMs = 5 } = {}) {
+  const sources = [];
+  const events = [];
+  const unexpectedErrors = [];
+  let activeSession = "session-a";
+  let demand = false;
+  const connection = new AgentEventConnection({
+    createSource(sessionId) {
+      const source = new FakeEventSource();
+      source.sessionId = sessionId;
+      sources.push(source);
+      return source;
+    },
+    onEvent(event) { events.push(event); },
+    shouldMaintain: (sessionId) => demand && sessionId === activeSession,
+    readinessTimeoutMs,
+    reconnectDelayMs,
+    onUnexpectedError(error) { unexpectedErrors.push(error); },
+  });
+  return {
+    connection,
+    sources,
+    events,
+    unexpectedErrors,
+    setActiveSession(sessionId) { activeSession = sessionId; },
+    setDemand(value) { demand = value; },
+  };
+}
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const nextTurn = () => new Promise((resolve) => setImmediate(resolve));
+
+test("shares one source and waits past the former transport deadline", async () => {
+  const { connection, sources, events } = createHarness();
+  const first = connection.ensureConnected("session-a");
+  const second = connection.ensureConnected("session-a");
+
+  assert.equal(sources.length, 1);
+  sources[0].open();
+  await wait(20);
+  sources[0].message({ type: "connected" });
+  await Promise.all([first, second]);
+
+  sources[0].message({ type: "agent_start" });
+  assert.deepEqual(events.map((event) => event.type), ["connected", "agent_start"]);
+});
+
+test("times out all waiters and closes the stalled source", async () => {
+  const { connection, sources } = createHarness({ readinessTimeoutMs: 10 });
+  const first = connection.ensureConnected("session-a");
+  const second = connection.ensureConnected("session-a");
+
+  await assert.rejects(first, (error) => error.status === "ready_timeout");
+  await assert.rejects(second, (error) => error.status === "ready_timeout");
+  assert.equal(sources[0].closeCount, 1);
+});
+
+test("manual close rejects waiters and isolates late events", async () => {
+  const { connection, sources, events } = createHarness();
+  const abandoned = connection.ensureConnected("session-a");
+  const oldSource = sources[0];
+  connection.close();
+  await assert.rejects(abandoned, (error) => error.status === "closed");
+
+  const replacement = connection.ensureConnected("session-a");
+  oldSource.open();
+  oldSource.message({ type: "connected" });
+  await nextTurn();
+  assert.deepEqual(events, []);
+
+  sources[1].open();
+  sources[1].message({ type: "connected" });
+  await replacement;
+});
+
+test("surfaces startup errors without retrying or dispatching them", async () => {
+  const { connection, sources, events } = createHarness();
+  const ready = connection.ensureConnected("session-a");
+  sources[0].open();
+  sources[0].message({ type: "startup_error", errorMessage: "broken config" });
+
+  await assert.rejects(ready, (error) => (
+    error.status === "startup_error" && error.message === "broken config"
+  ));
+  await wait(10);
+  assert.equal(sources.length, 1);
+  assert.deepEqual(events, []);
+});
+
+test("replaces a previously connected CONNECTING source only once", async () => {
+  const { connection, sources } = createHarness();
+  const initial = connection.ensureConnected("session-a");
+  sources[0].open();
+  sources[0].message({ type: "connected" });
+  await initial;
+
+  sources[0].readyState = CONNECTING;
+  const first = connection.ensureConnected("session-a");
+  const second = connection.ensureConnected("session-a");
+  await nextTurn();
+  assert.equal(sources.length, 2);
+
+  sources[1].open();
+  sources[1].message({ type: "connected" });
+  await Promise.all([first, second]);
+});
+
+test("passive maintenance retries a transient failure once", async () => {
+  const { connection, sources, setDemand } = createHarness();
+  setDemand(true);
+  connection.maintain("session-a");
+  sources[0].error();
+  await wait(10);
+  assert.equal(sources.length, 2);
+
+  sources[1].open();
+  sources[1].message({ type: "connected" });
+  await wait(10);
+  assert.equal(sources.length, 2);
+});
+
+test("an explicit startup error cancels a pending passive retry", async () => {
+  const { connection, sources, setDemand } = createHarness();
+  setDemand(true);
+  connection.maintain("session-a");
+  sources[0].error();
+
+  const explicit = connection.ensureConnected("session-a");
+  sources[1].open();
+  sources[1].message({ type: "startup_error", errorMessage: "terminal" });
+  await assert.rejects(explicit, (error) => error.status === "startup_error");
+  await wait(10);
+  assert.equal(sources.length, 2);
+});
+
+test("dropped demand, session switches, and close cannot revive an old retry", async () => {
+  const first = createHarness();
+  first.setDemand(true);
+  first.connection.maintain("session-a");
+  first.sources[0].error();
+  first.setDemand(false);
+  await wait(10);
+  assert.equal(first.sources.length, 1);
+
+  const second = createHarness();
+  second.setDemand(true);
+  second.connection.maintain("session-a");
+  second.sources[0].error();
+  second.setActiveSession("session-b");
+  const ready = second.connection.ensureConnected("session-b");
+  second.sources[1].open();
+  second.sources[1].message({ type: "connected" });
+  await ready;
+  await wait(10);
+  assert.equal(second.sources.length, 2);
+
+  const closed = createHarness();
+  closed.setDemand(true);
+  closed.connection.maintain("session-a");
+  closed.sources[0].error();
+  closed.connection.close();
+  await wait(10);
+  assert.equal(closed.sources.length, 1);
+});

package/lib/agent-event-connection.ts

@@ -0,0 +1,202 @@
+import type { AgentEventLike } from "./agent-event-wire";
+
+export interface AgentEventSourceLike {
+  readonly readyState: number;
+  onmessage: ((event: MessageEvent<string>) => void) | null;
+  onerror: ((event: Event) => void) | null;
+  close(): void;
+}
+
+export type AgentEventConnectionStatus = "ready_timeout" | "startup_error" | "closed";
+
+export class AgentEventConnectionError extends Error {
+  constructor(public readonly status: AgentEventConnectionStatus, message?: string) {
+    super(message ?? (
+      status === "ready_timeout"
+        ? "Timed out starting the agent session. Please try again."
+        : "Failed to connect to the agent event stream. Please try again."
+    ));
+    this.name = "AgentEventConnectionError";
+  }
+}
+
+type Attempt = {
+  promise: Promise<void>;
+  ready: boolean;
+  succeed(): void;
+  fail(error: AgentEventConnectionError): void;
+};
+
+type Connection = {
+  sessionId: string;
+  source: AgentEventSourceLike;
+  attempt: Attempt;
+};
+
+export interface AgentEventConnectionOptions {
+  createSource(sessionId: string): AgentEventSourceLike;
+  onEvent(event: AgentEventLike): void;
+  shouldMaintain(sessionId: string): boolean;
+  readinessTimeoutMs: number;
+  reconnectDelayMs: number;
+  onUnexpectedError?(error: unknown): void;
+}
+
+const EVENT_SOURCE_OPEN = 1;
+
+/** Owns the EventSource, agent-readiness handshake, and passive reconnect. */
+export class AgentEventConnection {
+  private current: Connection | null = null;
+  private retry: { sessionId: string; timer: ReturnType<typeof setTimeout> } | null = null;
+  private retryGeneration = 0;
+
+  constructor(private readonly options: AgentEventConnectionOptions) {}
+
+  close(): void {
+    this.stopRetrying();
+    if (this.current) this.discard(this.current, new AgentEventConnectionError("closed"));
+  }
+
+  maintain(sessionId: string): void {
+    if (!this.options.shouldMaintain(sessionId)) return;
+    const retryGeneration = this.retryGeneration;
+    void this.ensureConnected(sessionId).catch((error) => {
+      if (retryGeneration !== this.retryGeneration) return;
+      if (error instanceof AgentEventConnectionError) {
+        if (error.status === "startup_error") this.stopRetrying();
+        else this.scheduleRetry(sessionId);
+      } else {
+        this.options.onUnexpectedError?.(error);
+      }
+    });
+  }
+
+  async ensureConnected(sessionId: string): Promise<void> {
+    while (true) {
+      let connection = this.current;
+      if (!connection || connection.sessionId !== sessionId) {
+        connection = this.open(sessionId);
+      } else if (
+        connection.attempt.ready
+        && connection.source.readyState === EVENT_SOURCE_OPEN
+      ) {
+        return;
+      }
+
+      await connection.attempt.promise;
+      if (this.current !== connection) {
+        if (this.current?.sessionId === sessionId) continue;
+        throw new AgentEventConnectionError("closed");
+      }
+      if (connection.source.readyState === EVENT_SOURCE_OPEN) return;
+
+      // A once-ready EventSource may otherwise remain CONNECTING indefinitely.
+      this.discard(connection, new AgentEventConnectionError("closed"));
+    }
+  }
+
+  private open(sessionId: string): Connection {
+    if (this.current) this.discard(this.current, new AgentEventConnectionError("closed"));
+
+    let source: AgentEventSourceLike;
+    try {
+      source = this.options.createSource(sessionId);
+    } catch (error) {
+      throw new AgentEventConnectionError(
+        "closed",
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+
+    let settled = false;
+    let resolve!: () => void;
+    let reject!: (error: AgentEventConnectionError) => void;
+    const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+      resolve = resolvePromise;
+      reject = rejectPromise;
+    });
+    const timeout = setTimeout(() => {
+      this.fail(connection, new AgentEventConnectionError("ready_timeout"));
+    }, this.options.readinessTimeoutMs);
+    const attempt: Attempt = {
+      promise,
+      ready: false,
+      succeed() {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        resolve();
+      },
+      fail(error) {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        reject(error);
+      },
+    };
+    const connection: Connection = { sessionId, source, attempt };
+    this.current = connection;
+
+    source.onmessage = (message) => {
+      if (this.current !== connection) return;
+      let event: AgentEventLike;
+      try {
+        event = JSON.parse(message.data) as AgentEventLike;
+      } catch {
+        return;
+      }
+
+      if (event.type === "connected") {
+        attempt.ready = true;
+        attempt.succeed();
+        this.stopRetrying();
+      } else if (event.type === "startup_error") {
+        const message = typeof event.errorMessage === "string" ? event.errorMessage : undefined;
+        this.fail(connection, new AgentEventConnectionError("startup_error", message));
+        return;
+      }
+      this.options.onEvent(event);
+    };
+    source.onerror = () => {
+      this.fail(connection, new AgentEventConnectionError("closed"));
+    };
+
+    return connection;
+  }
+
+  private fail(connection: Connection, error: AgentEventConnectionError): void {
+    if (this.current !== connection) return;
+    this.discard(connection, error);
+    if (error.status === "startup_error") this.stopRetrying();
+    else this.scheduleRetry(connection.sessionId);
+  }
+
+  private discard(connection: Connection, error: AgentEventConnectionError): void {
+    connection.attempt.fail(error);
+    connection.source.close();
+    if (this.current === connection) this.current = null;
+  }
+
+  private scheduleRetry(sessionId: string): void {
+    if (!this.options.shouldMaintain(sessionId)) return;
+    if (this.retry?.sessionId === sessionId) return;
+    this.clearRetry();
+
+    const timer = setTimeout(() => {
+      if (this.retry?.timer !== timer) return;
+      this.retry = null;
+      this.maintain(sessionId);
+    }, this.options.reconnectDelayMs);
+    this.retry = { sessionId, timer };
+  }
+
+  private stopRetrying(): void {
+    this.retryGeneration += 1;
+    this.clearRetry();
+  }
+
+  private clearRetry(): void {
+    if (this.retry) clearTimeout(this.retry.timer);
+    this.retry = null;
+  }
+}

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));
+});