@astrosheep/keiyaku 4.6.8 → 4.6.9

package/plugins/paseo/plugin/server/mirror.ts

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import type { ProviderEvent, ProviderTimelineItem } from "@getpaseo/plugin/server/provider";
+import type { History, Row } from "./keiyaku.js";
+import type { AdmittedMessage } from "./message.js";
+
+type Emit = (event: ProviderEvent) => void;
+type Turn = { sequence: number; closed: boolean };
+export function createMirror(sessionId: string, emit: Emit) {
+  let covered: { high: number; signatures: Map<number, string> } | undefined;
+  let turn: Turn | undefined;
+  const openTurns = new Map<number, Turn>();
+  let unhealthy = false;
+  let coverageNotice = "";
+  let submissions = 0;
+  let deferred: History | undefined;
+  let deferredReannounce = false;
+  const displayedTells = new Map<string, number>();
+  const item = (value: ProviderTimelineItem, timestamp?: string) => emit({
+    type: "timeline.item", sessionId, item: value, ...(timestamp === undefined ? {} : { timestamp }),
+  });
+  const finish = (target: Turn | undefined, state: "completed" | "failed" | "canceled", message?: string) => {
+    if (!target || target.closed) return;
+    target.closed = true;
+    openTurns.delete(target.sequence);
+    emit({ type: "session.turn", sessionId, turnId: `turn/${target.sequence}`, state,
+      ...(message === undefined ? {} : { error: { message } }) });
+  };
+  const userMessage = (row: Extract<Row, { kind: "tell" }>, clientMessageId?: string) => {
+    if (displayedTells.has(row.tellId)) return;
+    displayedTells.set(row.tellId, row.sequence);
+    item({ type: "user_message", id: `keiyaku:tell/${row.tellId}`, text: row.text,
+      ...(clientMessageId === undefined ? {} : { clientMessageId }) }, row.at);
+  };
+  const mirror = {
+    seed(history: History) {
+      const { rows } = history;
+      covered = { high: history.highest ?? 0,
+        signatures: new Map(rows.map((row) => [row.sequence, JSON.stringify(row)])) };
+      for (const row of rows) if (row.kind === "tell") displayedTells.set(row.tellId, row.sequence);
+      const latest = rows.filter((row) => row.kind === "turn").sort((a, b) => a.sequence - b.sequence).at(-1);
+      if (latest?.kind === "turn") {
+        turn = { sequence: latest.turnSequence,
+          closed: rows.some((row) => row.kind === "outcome" && row.turnSequence === latest.turnSequence) };
+        if (!turn.closed) {
+          openTurns.set(turn.sequence, turn);
+          emit({ type: "session.turn", sessionId, turnId: `turn/${turn.sequence}`, state: "started" });
+        }
+      }
+    },
+    hold() {
+      submissions++;
+      return (publish = true) => {
+        submissions--;
+        if (submissions === 0) {
+          const rows = deferred;
+          const reannounce = deferredReannounce;
+          deferred = undefined;
+          deferredReannounce = false;
+          if (rows && publish) mirror.publish(rows, reannounce);
+        }
+      };
+    },
+    currentTurnId: () => turn && !turn.closed ? `turn/${turn.sequence}` : undefined,
+    refreshedTurnId() {
+      const latest = deferred?.rows.filter((row) => row.kind === "turn").at(-1);
+      if (latest?.kind !== "turn") return mirror.currentTurnId();
+      if (deferred?.rows.some((row) => row.kind === "outcome" && row.turnSequence === latest.turnSequence)) return undefined;
+      if (turn?.sequence === latest.turnSequence && turn.closed) return undefined;
+      return `turn/${latest.turnSequence}`;
+    },
+    admit(row: AdmittedMessage, clientMessageId: string) {
+      userMessage(row, clientMessageId);
+    },
+    cancel(reason: string) {
+      for (const target of openTurns.values()) finish(target, "canceled", reason);
+    },
+    observedTurn(): Readonly<{ cancel(reason: string): void }> | undefined {
+      if (!turn || turn.closed) return undefined;
+      const observed = turn;
+      return { cancel(reason: string) {
+        if (deferred?.rows.some((row) => row.kind === "outcome" && row.turnSequence === observed.sequence)) return;
+        finish(observed, "canceled", reason);
+      } };
+    },
+    unreadable() {
+      deferredReannounce = false;
+      if (!unhealthy) item({ type: "notification", level: "warning",
+        id: `keiyaku:unreadable/${covered ? Math.min(...covered.signatures.keys()) : 0}`,
+        message: "Keiyaku read surface unavailable; retaining the previous mirror." });
+      unhealthy = true;
+    },
+    publish(input: History, reannounce = false) {
+      // Hold racing reads until native Tell identity can replace the optimistic item.
+      if (submissions > 0) { deferred = input; deferredReannounce ||= reannounce; return; }
+      const rows = [...input.rows].sort((a, b) => a.sequence - b.sequence);
+      const lowest = rows[0]?.sequence;
+      // Public history metadata, not projected sequence holes, owns coverage.
+      // Neither missing retention nor a bounded read is an execution outcome.
+      const uncoveredEarlier = input.hasEarlier && (!covered || lowest === undefined || lowest > covered.high);
+      const notice = input.historyLost ? "retention" : uncoveredEarlier ? "bounded" : "";
+      const noticeKey = notice ? `${notice}/${input.lowestRetained ?? "empty"}` : "";
+      if (noticeKey && noticeKey !== coverageNotice) {
+        item({ type: "notification", level: "warning", id: `keiyaku:window/${lowest ?? "empty"}`,
+          message: input.historyLost
+            ? "Keiyaku reports history outside retention; retained records remain available. Execution state is unchanged."
+            : "Earlier retained history is outside this bounded mirror read. Execution state is unchanged." });
+      }
+      coverageNotice = noticeKey;
+      for (const row of rows) {
+        if (covered?.signatures.get(row.sequence) === JSON.stringify(row)) continue;
+        if (row.kind === "tell") {
+          userMessage(row);
+        } else if (row.kind === "call") {
+          item({ type: "user_message", id: `keiyaku:call/${row.sequence}`, text: row.text }, row.at);
+        } else if (row.kind === "turn") {
+          // Publish retained starts even when their outcomes arrive in this read.
+          // Older starts must not reopen a sealed or superseded Turn.
+          if (!turn || row.turnSequence > turn.sequence) {
+            turn = { sequence: row.turnSequence, closed: false };
+            openTurns.set(turn.sequence, turn);
+            emit({ type: "session.turn", sessionId, turnId: `turn/${turn.sequence}`, state: "started" });
+          }
+        } else if (row.kind === "tool") {
+          // Tool identity comes from the producer, scoped to its Turn. An older
+          // CLI without it can show settled records, never guessed live pairing.
+          const state = row.state;
+          const toolIdentity = row.toolId === undefined ? `record/${row.sequence}` : `${row.turnSequence}/${row.toolId}`;
+          if (typeof state === "string" && row.toolId === undefined) {
+            item({ type: "notification", id: `keiyaku:tool/${row.sequence}`, level: "info",
+              message: `${row.name}: ${state === "active" ? "start observed" : "result not witnessed"}. ${JSON.stringify(row.call)}` }, row.at);
+            continue;
+          }
+          const result = typeof state === "object" ? state : undefined;
+          // The result's own output is the observed text; its diagnostic message is
+          // only the stand-in an older producer wrote instead, so an honestly empty
+          // output is never replaced by its diagnostic.
+          const output = result === undefined ? undefined : result.output === undefined ? result.message : result.output;
+          const single = row.call.kind === "fileChange" && row.call.changes.length === 1 ? row.call.changes[0] : undefined;
+          const detail: Extract<ProviderTimelineItem, { type: "tool_call" }>["detail"] = row.call.kind === "run"
+            ? { type: "shell", command: row.call.command,
+              ...(output === undefined ? {} : { output }),
+              ...(result?.exitCode === undefined ? {} : { exitCode: result.exitCode }) }
+            : row.call.kind === "read"
+              ? { type: "read", filePath: row.call.path,
+                ...(row.call.offset === undefined ? {} : { offset: row.call.offset }),
+                ...(row.call.limit === undefined ? {} : { limit: row.call.limit }),
+                ...(output === undefined ? {} : { content: output }) }
+              : row.call.kind === "search"
+                ? { type: "search", query: row.call.query,
+                  ...(output === undefined ? {} : { content: output }),
+                  ...(row.durationMs === undefined ? {} : { durationMs: row.durationMs }),
+                  ...(row.truncated === undefined ? {} : { truncated: row.truncated }) }
+                // One observed file patch is the whole operation; anything else keeps
+                // the complete change list so no single file stands in for the rest.
+                : row.call.kind === "fileChange" && single?.patch !== undefined
+                  ? { type: "edit", filePath: single.path, unifiedDiff: single.patch }
+                  : { type: "unknown", input: z.json().parse(row.call), output: result === undefined ? null : z.json().parse(result) };
+          item({ type: "tool_call", id: `keiyaku:tool/${toolIdentity}`, callId: `tool/${toolIdentity}`, name: row.name,
+            detail, metadata: { turnSequence: row.turnSequence, sequence: row.sequence,
+              ...(row.durationMs === undefined ? {} : { durationMs: row.durationMs }),
+              ...(row.truncated === undefined ? {} : { truncated: row.truncated }),
+              call: z.json().parse(row.call), state: z.json().parse(state) },
+            ...(typeof state === "object" && state.status === "error"
+              ? { status: "failed", error: z.json().parse(state) }
+              : { status: state === "active" ? "running" : state === "unsettled" ? "canceled" : "completed", error: null }) }, row.at);
+        } else if (row.kind === "said") {
+          item({ type: "assistant_message", id: `keiyaku:said/${row.sequence}`, text: row.text }, row.at);
+        } else if (row.kind === "thought") {
+          item({ type: "reasoning", id: `keiyaku:thought/${row.sequence}`, text: row.text }, row.at);
+        } else if (row.kind === "note") {
+          item({ type: "notification", id: `keiyaku:note/${row.sequence}`, level: "info", message: row.text }, row.at);
+        } else if (row.kind === "outcome") {
+          item(row.outcome.kind === "answered"
+            ? { type: "assistant_message", id: row.outcome.foldedSaidSequence === undefined
+              ? `keiyaku:turn/${row.turnSequence}` : `keiyaku:said/${row.outcome.foldedSaidSequence}`, text: row.outcome.answer }
+            : { type: "error", id: `keiyaku:turn/${row.turnSequence}`, message: row.outcome.diagnostic }, row.at);
+          finish(openTurns.get(row.turnSequence), row.outcome.kind === "answered" ? "completed" : "failed",
+            row.outcome.kind === "failed" ? row.outcome.diagnostic : undefined);
+        }
+      }
+      covered = { high: Math.max(covered?.high ?? 0, input.highest ?? 0),
+        signatures: new Map(rows.map((row) => [row.sequence, JSON.stringify(row)])) };
+      if (lowest !== undefined) for (const [id, sequence] of displayedTells) {
+        if (sequence < lowest) displayedTells.delete(id);
+      }
+      unhealthy = false;
+      const current = turn;
+      if (reannounce && current && !current.closed && rows.some((row) => row.kind === "turn" && row.turnSequence === current.sequence))
+        emit({ type: "session.turn", sessionId, turnId: `turn/${current.sequence}`, state: "started" });
+    },
+  };
+  return mirror;
+}

package/plugins/paseo/plugin/server/model.ts

@@ -0,0 +1,14 @@
+import type { ProviderConfigState } from "@getpaseo/plugin/server/provider";
+
+/** A mirror reports the public Akuma configuration; it cannot change it. */
+export function modelConfig(status: { provider?: string; model?: string }): ProviderConfigState {
+  return {
+    ...(status.model === undefined ? {} : { model: status.model }),
+    models: status.model === undefined ? [] : [{
+      id: status.model,
+      label: status.provider ? `${status.provider} / ${status.model}` : status.model,
+      isSelectable: false,
+    }],
+    modes: [], thinkingOptions: [], settings: [],
+  };
+}

package/plugins/paseo/plugin/server/provider.ts

@@ -0,0 +1,276 @@
+import { realpath } from "node:fs/promises";
+import { z } from "zod";
+import { negotiateProviderCapabilities, type ProviderConnection, type ProviderEvent, type ProviderPrompt, type ProviderRegistration } from "@getpaseo/plugin/server/provider";
+import type { History } from "./keiyaku.js";
+import type { AkumaTransport } from "./transport.js";
+import { messageText, tellPresentation } from "./message.js";
+import { createMirror } from "./mirror.js";
+import { modelConfig } from "./model.js";
+import type { StopAttempt } from "./stop.js";
+
+const identity = z.object({ world: z.string().min(1), akuId: z.string().regex(/^aku\//u) });
+export function createProvider(transport: AkumaTransport) {
+  const sessions = new Set<{ world: string; akuId: string; observe(reannounce?: boolean): Promise<void>; stop(): Promise<void> }>();
+  const provider: ProviderRegistration = {
+    id: "keiyaku", label: "Keiyaku", description: "Akuma runtime mirror",
+    async connect(request): Promise<ProviderConnection> {
+      if (!request.versions.includes(1)) throw new Error("Provider protocol version 1 is required");
+      const capabilities = negotiateProviderCapabilities(request.capabilities, ["session.persistence", "prompt.message", "prompt.steer"]);
+      const listeners = new Set<(event: ProviderEvent) => void>();
+      const local = new Map<string, { stop(): Promise<void>; stopExecution(requestId: string): Promise<void>; prompt(prompt: ProviderPrompt): Promise<void> }>();
+      let closed = false;
+      const emit = (event: ProviderEvent) => { if (!closed) for (const listener of listeners) listener(event); };
+      return {
+        version: 1, capabilities,
+        onEvent(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        async send(input) {
+          if (closed) throw new Error("Provider connection is closed");
+          if (input.type === "catalog") {
+            emit({ type: "catalog", requestId: input.requestId, catalog: {
+              models: [{ id: "mirror", label: "Akuma mirror" }], defaultModel: "mirror", modes: [],
+            } });
+          } else if (input.type === "session.open") {
+            if (local.has(input.sessionId)) throw new Error("Session already open");
+            if (input.persistence && input.persistence.version !== 1) throw new Error("Unsupported persistence version");
+            const target = identity.parse(input.persistence?.data ?? input.config.providerOptions);
+            const world = await realpath(target.world);
+            const mirror = createMirror(input.sessionId, emit);
+            const cancellation = new AbortController();
+            // The opening window seeds retained state instead of announcing it.
+            const skipRetained = input.history === "skip";
+            let opening = true;
+            let pending = false;
+            let pendingReannounce = false;
+            let running: Promise<void> | undefined;
+            let observed: Readonly<{ cancel(): void; pulling: Promise<void> }> | undefined;
+            const submissions = new Set<Promise<void>>();
+            let stopping: Promise<StopAttempt> | undefined;
+            // Release the live subscription. Its pending frame settles as
+            // released and is never published into the next observation.
+            const releaseObservation = (): void => {
+              const current = observed;
+              observed = undefined;
+              current?.cancel();
+            };
+            /**
+             * Observe the current window once, then keep pulling its changes.
+             * A slow pull only bounds the next frame: no producer queue exists
+             * here and no timer retries a failure. A failed or ended
+             * subscription keeps the previous display and waits for the next
+             * explicit refresh, which opens a fresh observation.
+             */
+            async function observeWindow(announce: boolean): Promise<void> {
+              releaseObservation();
+              if (cancellation.signal.aborted) return;
+              const controller = new AbortController();
+              const relay = () => controller.abort(cancellation.signal.reason);
+              cancellation.signal.addEventListener("abort", relay, { once: true });
+              const iterator = transport.stream(world, target.akuId, controller.signal)[Symbol.asyncIterator]();
+              const entry = { cancel: () => {
+                cancellation.signal.removeEventListener("abort", relay);
+                controller.abort();
+              }, pulling: Promise.resolve() };
+              observed = entry;
+              const publish = (history: History, reannounce: boolean): void => {
+                if (cancellation.signal.aborted || observed !== entry) return;
+                if (opening && skipRetained) mirror.seed(history);
+                else mirror.publish(history, reannounce);
+              };
+              try {
+                const first = await iterator.next();
+                if (first.done) {
+                  if (observed === entry) mirror.unreadable();
+                  return;
+                }
+                publish(first.value, announce);
+              } catch {
+                if (observed === entry && !cancellation.signal.aborted) mirror.unreadable();
+                return;
+              } finally {
+                opening = false;
+              }
+              entry.pulling = (async () => {
+                for (;;) {
+                  let frame: IteratorResult<History>;
+                  try {
+                    frame = await iterator.next();
+                  } catch {
+                    // A released or failed observation never reports itself over
+                    // the one that replaced it.
+                    if (observed === entry && !cancellation.signal.aborted) mirror.unreadable();
+                    return;
+                  }
+                  if (observed !== entry) return;
+                  if (frame.done) {
+                    mirror.unreadable();
+                    return;
+                  }
+                  publish(frame.value, false);
+                }
+              })();
+            }
+            // Every explicit refresh, Tell and Stop synchronization reopens the
+            // one observation instead of reading beside it, so a late result can
+            // never overwrite a newer snapshot, and hints coalesce into one.
+            function observe(reannounce = false): Promise<void> {
+              if (cancellation.signal.aborted) return Promise.resolve();
+              pending = true;
+              pendingReannounce ||= reannounce;
+              running ??= (async () => {
+                while (pending && !cancellation.signal.aborted) {
+                  pending = false;
+                  const announce = pendingReannounce;
+                  pendingReannounce = false;
+                  await observeWindow(announce);
+                }
+              })().finally(() => { running = undefined; });
+              return running;
+            }
+            const session = {
+              world, akuId: target.akuId,
+              observe,
+              async prompt(prompt: ProviderPrompt) {
+                const respond = (result: Extract<ProviderEvent, { type: "session.prompt_result" }>["result"]) => emit({
+                  type: "session.prompt_result", sessionId: input.sessionId, clientMessageId: prompt.clientMessageId, result,
+                });
+                let text: string;
+                try {
+                  cancellation.signal.throwIfAborted();
+                  text = messageText(prompt);
+                } catch (error) {
+                  const failure = error instanceof Error ? error : new Error(String(error));
+                  respond({ type: "failed", error: { message: failure.message } });
+                  throw failure;
+                }
+                const steerTurnId = prompt.delivery === "steer" ? mirror.currentTurnId() : undefined;
+                if (prompt.delivery === "steer" && steerTurnId === undefined) {
+                  const failure = new Error("No observed Paseo Turn for steering; Tell was not submitted");
+                  respond({ type: "failed", error: { message: failure.message } });
+                  throw failure;
+                }
+                const release = mirror.hold();
+                const submission = (async () => {
+                  try {
+                    const admitted = tellPresentation(await transport.tell(world, target.akuId, cancellation.signal, text), steerTurnId);
+                    // Observe once while publication is held. An idle send may have
+                    // started real work even when its receipt still says pending.
+                    await session.observe();
+                    mirror.admit(admitted.row, prompt.clientMessageId);
+                    const observed = mirror.refreshedTurnId();
+                    respond(admitted.result.type === "completed" && observed !== undefined
+                      ? { type: "turn", turnId: observed } : admitted.result);
+                  } catch (error) {
+                    const failure = new Error(`${error instanceof Error ? error.message : String(error)}. Input may already be recorded; not retried.`);
+                    respond({ type: "failed", error: { message: failure.message } });
+                    await session.observe();
+                    // Do not let the host treat an uncertain write as "unavailable"
+                    // and replace execution before resubmitting the same text.
+                    throw failure;
+                  } finally {
+                    release(!cancellation.signal.aborted);
+                  }
+                })();
+                submissions.add(submission);
+                try { await submission; } finally { submissions.delete(submission); }
+              },
+              async stop() {
+                mirror.cancel("Observation closed; Akuma was not interrupted");
+                cancellation.abort();
+                const closing = observed;
+                releaseObservation();
+                sessions.delete(session);
+                local.delete(input.sessionId);
+                await Promise.allSettled([...submissions]);
+                await stopping;
+                await running;
+                await closing?.pulling;
+                emit({ type: "session.closed", sessionId: input.sessionId });
+              },
+              stopExecution,
+            };
+            async function attemptStop(): Promise<StopAttempt> {
+              if (cancellation.signal.aborted)
+                return { kind: "uncertain", message: "Keiyaku could not prove the stop: the mirror closed before it was attempted" };
+              const observed = mirror.observedTurn();
+              let attempt: StopAttempt;
+              try {
+                attempt = await transport.stop(world, target.akuId, cancellation.signal);
+              } catch (error) {
+                attempt = { kind: "uncertain", message: `Keiyaku could not prove the stop: ${error instanceof Error ? error.message : String(error)}` };
+              }
+              await session.observe();
+              if (attempt.kind === "stopped")
+                observed?.cancel("Akuma execution was stopped from Paseo; the Akuma is preserved for a later Tell");
+              return attempt;
+            }
+            async function stopExecution(requestId: string): Promise<void> {
+              stopping ??= attemptStop().finally(() => { stopping = undefined; });
+              const attempt = await stopping;
+              if (attempt.kind === "stopped") emit({ type: "request.completed", requestId });
+              else emit({ type: "request.failed", requestId, error: { message: attempt.message } });
+            }
+            sessions.add(session);
+            local.set(input.sessionId, session);
+            emit({ type: "session.opened", requestId: input.requestId, sessionId: input.sessionId,
+              capabilities, restoration: "core", cwd: input.config.cwd,
+              persistence: { version: 1, data: { world, akuId: target.akuId } } });
+            {
+              try {
+                const observed = await transport.status(world, target.akuId, cancellation.signal);
+                if (!cancellation.signal.aborted) emit({ type: "session.config", sessionId: input.sessionId, config: modelConfig(observed) });
+              } catch (error) {
+                if (!cancellation.signal.aborted) emit({ type: "session.notice", sessionId: input.sessionId, notice: {
+                  id: "keiyaku:model", severity: "warning", title: "Akuma model unavailable",
+                  description: error instanceof Error ? error.message : String(error),
+                } });
+              }
+            }
+            // Ready names the first observed window, or the explicit report that
+            // none could be read. It never waits for the observation to end.
+            await session.observe();
+            if (!cancellation.signal.aborted) emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
+          } else if (input.type === "session.interrupt" || input.type === "session.close") {
+            const session = local.get(input.sessionId);
+            if (input.type === "session.close") {
+              await session?.stop();
+              emit({ type: "request.completed", requestId: input.requestId });
+            } else if (session === undefined) {
+              emit({ type: "request.failed", requestId: input.requestId,
+                error: { message: "Keiyaku mirror session is not open" } });
+            } else await session.stopExecution(input.requestId);
+          } else if (input.type === "session.prompt") {
+            const session = local.get(input.sessionId);
+            if (session) await session.prompt(input.prompt);
+            else emit({ type: "session.prompt_result", sessionId: input.sessionId, clientMessageId: input.prompt.clientMessageId,
+              result: { type: "failed", error: { message: "Keiyaku mirror session is not open" } } });
+          } else if ("requestId" in input) {
+            emit({ type: "request.failed", requestId: input.requestId, error: { message: "Unsupported Keiyaku mirror operation" } });
+          }
+        },
+        async close() {
+          await Promise.all([...local.values()].map((session) => session.stop()));
+          closed = true;
+          listeners.clear();
+        },
+      };
+    },
+  };
+  return {
+    provider,
+    async refresh(input: { world: string; akuId: string }) {
+      const world = await realpath(input.world);
+      let woken = 0;
+      for (const session of sessions) if (session.world === world && session.akuId === input.akuId) {
+        void session.observe();
+        woken++;
+      }
+      return { woken };
+    },
+    async sync(input: { world: string; akuId: string }) {
+      const world = await realpath(input.world);
+      await Promise.all([...sessions].filter((session) => session.world === world && session.akuId === input.akuId)
+        .map((session) => session.observe(true)));
+    },
+    async close() { await Promise.all([...sessions].map((session) => session.stop())); },
+  };
+}