@astrosheep/keiyaku 4.6.7 → 4.6.9

package/plugins/paseo/plugin/paseo-plugin.json

@@ -0,0 +1,4 @@
+{
+  "id": "keiyaku-paseo",
+  "requirements": { "paseo": ">=0.11.2" }
+}

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

@@ -0,0 +1,52 @@
+import { realpath } from "node:fs/promises";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type { z } from "zod";
+import type { attachRpc } from "../shared/attach-rpc.js";
+
+function skip(reason: string) {
+  console.warn(`Keiyaku mirror not attached: ${reason}`);
+  return { attached: false };
+}
+export async function attach(input: z.output<typeof attachRpc.input>, { paseo }: PluginHandlerContext,
+  sync: (input: { world: string; akuId: string }) => Promise<void>) {
+  const caller = input.caller;
+  if (caller?.kind !== "external") return skip("caller is not an external host");
+  const native = ["codex", "pi", "claude"].includes(caller.integration);
+  let parentId = caller.id;
+  const matches = (agent: { persistence?: { provider: string; sessionId: string } | null }) =>
+    agent.persistence?.provider === caller.integration && agent.persistence.sessionId === caller.id;
+  if (native) {
+    const candidates: string[] = [];
+    let cursor: string | undefined;
+    do {
+      const filter = { includeArchived: true };
+      const page = await paseo.agents.list({ filter, page: { limit: 200, ...(cursor ? { cursor } : {}) } });
+      for (const { agent } of page.entries) if (matches(agent)) candidates.push(agent.id);
+      if (candidates.length > 1) return skip(`ambiguous ${caller.integration} session ${caller.id}: multiple parents`);
+      if (!page.pageInfo.hasMore) break;
+      const next = page.pageInfo.nextCursor;
+      if (!next || next === cursor) return skip("incomplete parent directory pagination");
+      cursor = next;
+    } while (cursor);
+    if (!candidates[0]) return skip(`no parent for ${caller.integration} session ${caller.id}`);
+    parentId = candidates[0];
+  } else if (caller.integration !== "paseo") {
+    return skip(`unsupported caller integration ${caller.integration}`);
+  }
+  const parent = await paseo.agents.ref(parentId).refresh();
+  if (!parent) return skip(`parent ${parentId} does not exist`);
+  if (parent.agent.archivedAt) return skip(`parent ${parentId} is archived`);
+  if (native && !matches(parent.agent)) return skip(`parent ${parentId} changed native identity`);
+  const world = await realpath(input.world);
+  // Keep the creation fingerprint immutable: aliases belong to the forwarder's
+  // rename path, not this idempotent request (including retries after rename).
+  await paseo.agents.create({ parent: parentId, cwd: parent.agent.cwd, title: input.akuId,
+    config: { provider: "keiyaku/mirror", options: { world, akuId: input.akuId } },
+    idempotencyKey: `keiyaku:${world}:${input.akuId}`,
+  });
+  // Creation returns only after the host has registered and subscribed to the session.
+  // Opening's ready event is too early to restore running presentation there.
+  try { await sync({ world, akuId: input.akuId }); }
+  catch (error) { console.warn(`Keiyaku mirror attached, but synchronization failed: ${error instanceof Error ? error.message : String(error)}`); }
+  return { attached: true };
+}

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

@@ -0,0 +1,44 @@
+import { z } from "zod";
+
+export const identityKeys = [
+  "CLAUDE_CODE_SESSION_ID", "CLAUDE_CODE_CHILD_SESSION", "CLAUDECODE", "CODEX_THREAD_ID",
+  "OPENCODE_SESSION_ID", "PI_SESSION_ID", "PI_SESSION_FILE", "PASEO_AGENT_ID",
+  "SQUARE_PARTICIPANT_NAME", "AKUMA_REQUESTS", "KEIYAKU_ACTOR_ID", "KEIYAKU_EXTERNAL_CALLER",
+] as const;
+const count = z.number().int().nonnegative();
+const base = z.object({ sequence: count, at: z.string() });
+const turnFields = { turnSequence: count };
+const input = z.object({ json: z.string(), truncated: z.boolean() });
+const call = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("run"), command: z.string() }),
+  z.object({ kind: z.literal("read"), path: z.string(), offset: count.optional(), limit: count.optional() }),
+  z.object({ kind: z.literal("search"), query: z.string(), scope: z.enum(["content", "files", "web"]).optional(),
+    path: z.string().optional(), glob: z.string().optional() }),
+  z.object({ kind: z.literal("fileChange"), changes: z.array(z.object({
+    op: z.enum(["add", "update", "delete", "unspecified"]), path: z.string(),
+    diffstat: z.object({ added: count, removed: count }).optional(), patch: z.string().optional(),
+  })) }),
+  z.object({ kind: z.literal("other"), display: z.string(), input: input.optional() }),
+]);
+const row = z.union([
+  base.extend({ kind: z.literal("turn"), ...turnFields, bodySequence: count.optional() }),
+  base.extend({ kind: z.literal("tell"), tellId: z.string(), text: z.string(), state: z.enum(["pending", "told"]),
+    deliveries: z.array(z.object({ deliveredAt: z.string(), route: z.enum(["launch", "live"]),
+      turnSequence: count, receipt: z.enum(["unavailable", "required"]).optional() })).optional() }),
+  base.extend({ kind: z.literal("outcome"), ...turnFields, outcome: z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("answered"), historyId: z.string().optional(), answer: z.string(),
+      foldedSaidSequence: count.optional() }),
+    z.object({ kind: z.literal("failed"), historyId: z.string().optional(), diagnostic: z.string() }),
+  ]) }),
+  base.extend({ kind: z.literal("tool"), ...turnFields, name: z.string(), toolId: z.string().optional(), call,
+    state: z.union([z.enum(["active", "unsettled"]), z.object({ status: z.enum(["ok", "error"]),
+      message: z.string().optional(), exitCode: z.number().int().optional(), output: z.string().optional() })]),
+    durationMs: z.number().nonnegative().optional(), truncated: z.literal(true).optional() }),
+  base.extend({ kind: z.enum(["said", "thought", "note", "call"]), ...turnFields, text: z.string(),
+    truncated: z.literal(true).optional() }),
+]);
+export const historySchema = z.object({ rows: z.array(row), omitted: count,
+  hasEarlier: z.boolean(), hasLater: z.boolean(), historyLost: z.boolean(),
+  lowestRetained: count.nullable(), highest: count.nullable() });
+export type Row = z.infer<typeof row>;
+export type History = z.infer<typeof historySchema>;

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

@@ -0,0 +1,60 @@
+import type { ProviderEvent, ProviderPrompt } from "@getpaseo/plugin/server/provider";
+import { z } from "zod";
+
+const sequence = z.number().int().nonnegative();
+export const tellReceiptSchema = z.object({
+  akuma: z.string(),
+  tell: z.object({
+    admission: z.object({ fact: z.literal("recorded"), tellId: z.string().min(1) }),
+    row: z.object({ kind: z.literal("tell"), sequence, at: z.string(), tellId: z.string().min(1), text: z.string(),
+      state: z.enum(["pending", "told"]), deliveries: z.array(z.object({
+        route: z.enum(["live", "launch"]), turnSequence: sequence, deliveredAt: z.string(),
+        receipt: z.enum(["unavailable", "required"]).optional(),
+      })).optional() }),
+    wake: z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("told") }), z.object({ kind: z.literal("held") }),
+      z.object({ kind: z.literal("pursuing"), bodySequence: sequence }),
+      z.object({ kind: z.literal("failed"), diagnostic: z.string() }),
+    ]),
+  }),
+});
+/** One durable Tell admission and the wake it observed, however that wake settled. */
+export type TellAdmission = z.infer<typeof tellReceiptSchema>["tell"];
+export type AdmittedMessage = TellAdmission["row"];
+/** Submit one plain-text Tell and return its admission receipt. */
+export type Tell = (world: string, akuId: string, signal: AbortSignal, text: string) => Promise<TellAdmission>;
+type PromptResult = Extract<ProviderEvent, { type: "session.prompt_result" }>["result"];
+
+export function messageText(prompt: ProviderPrompt): string {
+  // Paseo requests stale permission cleanup on ordinary steering. This mirror
+  // owns no permission requests, so there is nothing to clear.
+  if (prompt.outputSchema !== undefined) {
+    throw new Error("Keiyaku messages do not support output schemas");
+  }
+  if (prompt.input.type !== "message") {
+    throw new Error("Keiyaku messages support plain text only, not commands");
+  }
+  const parts: string[] = [];
+  for (const part of prompt.input.content) {
+    if (part.type !== "text" || "mimeType" in part) throw new Error("Keiyaku messages support plain text only, not attachments");
+    parts.push(part.text);
+  }
+  const text = parts.join("\n");
+  if (!text.trim()) throw new Error("Keiyaku messages require nonblank text");
+  return text;
+}
+
+/**
+ * Map one admitted Tell to its Paseo presentation. Paseo steering acknowledges
+ * durable input acceptance, never native delivery: the observed Turn is a host
+ * presentation correlation, never a Heart binding.
+ */
+export function tellPresentation(admitted: TellAdmission, steerTurnId?: string): { row: AdmittedMessage; result: PromptResult } {
+  const { row, wake } = admitted;
+  if (wake.kind === "failed") console.warn(`Keiyaku Tell ${row.tellId} recorded; wake failed: ${wake.diagnostic}`);
+  if (steerTurnId !== undefined) return { row, result: { type: "steer", turnId: steerTurnId } };
+  const delivery = row.deliveries?.at(-1);
+  if (delivery) return { row, result: { type: "turn", turnId: `turn/${delivery.turnSequence}` } };
+  // The host may complete its send command; no Akuma outcome is manufactured.
+  return { row, result: { type: "completed" } };
+}

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