@astrosheep/keiyaku 4.6.8 → 4.6.9

package/plugins/paseo/plugin/server/sdk-worker.ts

@@ -0,0 +1,237 @@
+/**
+ * The dedicated Keiyaku worker the Paseo bridge spawns.
+ *
+ * Paseo compiles a directory-source plugin into one evaluated bundle, so the
+ * plugin directory has no worker module to point at once it is loaded, and a
+ * static or literal dynamic import of the package root is rejected by Paseo's
+ * own module boundary (the repository self-link resolves outside the plugin
+ * directory). The worker therefore travels as source text and is started with
+ * `node --input-type=module -e`. It locates the installed public package
+ * portably: the `keiyaku` executable on PATH, then the package root that owns
+ * it, then that package's own declared public entry. An explicit entry
+ * argument overrides discovery for tests and embedding.
+ *
+ * The worker is deliberately the thinnest possible host: it imports the public
+ * package root, serves one JSON request per line, and answers with the public
+ * operations' own values. It never formats CLI arguments, never renders text,
+ * and never decides a lifecycle outcome. Identity is stripped by the spawning
+ * transport's environment; this module never touches `process.env`.
+ *
+ * `tests/paseo-sdk-transport.test.ts` type-checks this text against the public
+ * TypeScript surface and runs it as a real process, so keep it valid JavaScript
+ * with JSDoc types and free of backticks and template substitutions.
+ */
+export const WORKER_SOURCE = String.raw`import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createInterface } from "node:readline";
+
+const EXPLICIT_ENTRY = process.argv[1];
+
+/** @param {string} candidate @returns {Promise<string | undefined>} */
+async function realFile(candidate) {
+  try { return await realpath(candidate); } catch { return undefined; }
+}
+
+/** @param {string} name @returns {Promise<string | undefined>} */
+async function findOnPath(name) {
+  const extensions = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+  for (const directory of (process.env.PATH || "").split(path.delimiter)) {
+    if (directory === "") continue;
+    for (const extension of extensions) {
+      const found = await realFile(path.join(directory, name + extension));
+      if (found !== undefined) return found;
+    }
+  }
+  return undefined;
+}
+
+/** @param {string} bin @returns {Promise<{ root: string, manifest: any } | undefined>} */
+async function packageRoot(bin) {
+  let directory = path.dirname(bin);
+  for (;;) {
+    try {
+      const manifest = JSON.parse(await readFile(path.join(directory, "package.json"), "utf8"));
+      if (manifest.name === "@astrosheep/keiyaku") return { root: directory, manifest };
+    } catch {}
+    const parent = path.dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+/** @param {string} root @param {any} manifest @returns {string | undefined} */
+function declaredEntry(root, manifest) {
+  const main = manifest.exports === undefined ? undefined : manifest.exports["."];
+  const relative = typeof main === "string" ? main : main === undefined ? undefined : main.import || main.default;
+  const chosen = relative === undefined ? manifest.main : relative;
+  return typeof chosen === "string" ? pathToFileURL(path.join(root, chosen)).href : undefined;
+}
+
+/** @returns {Promise<string>} */
+async function resolveEntry() {
+  if (EXPLICIT_ENTRY !== undefined && EXPLICIT_ENTRY !== "") {
+    return EXPLICIT_ENTRY.startsWith("file:") ? EXPLICIT_ENTRY : pathToFileURL(path.resolve(EXPLICIT_ENTRY)).href;
+  }
+  const bin = await findOnPath("keiyaku");
+  if (bin === undefined) throw new Error("the keiyaku executable is not on PATH; the Paseo bridge cannot locate its public package");
+  const found = await packageRoot(bin);
+  if (found === undefined) throw new Error("no @astrosheep/keiyaku package owns " + bin);
+  const entry = declaredEntry(found.root, found.manifest);
+  if (entry === undefined) throw new Error("the installed @astrosheep/keiyaku package declares no public entry");
+  return entry;
+}
+
+/** @returns {Promise<typeof import("@astrosheep/keiyaku")>} */
+async function loadSdk() {
+  const entry = await resolveEntry();
+  /** @type {typeof import("@astrosheep/keiyaku")} */
+  const sdk = await import(entry);
+  if (typeof sdk.Akuma?.select !== "function") {
+    throw new Error("the public @astrosheep/keiyaku entry does not expose Akuma.select");
+  }
+  return sdk;
+}
+
+const boot = loadSdk();
+// A boot that fails before the first request still belongs to those requests;
+// keep the rejection handled until one of them observes it.
+boot.catch(() => {});
+
+/** @type {Map<number, AbortController>} */
+const controllers = new Map();
+
+/**
+ * One live observation of an Akuma's current window. The iterator is undefined
+ * only while the opening request is still resolving the public package.
+ * @typedef {{ controller: AbortController, iterator: AsyncIterator<unknown> | undefined }} Subscription
+ */
+/** @type {Map<number, Subscription>} */
+const subscriptions = new Map();
+
+/**
+ * The installed public package may predate the streaming surface, so probe the
+ * capability at runtime instead of assuming this bridge's own vintage.
+ * @param {unknown} value @returns {value is { stream(options: { signal: AbortSignal }): AsyncIterable<unknown> }}
+ */
+function exposesStream(value) {
+  return typeof value === "object" && value !== null &&
+    typeof (/** @type {{ stream?: unknown }} */ (value)).stream === "function";
+}
+
+/**
+ * The model configuration a public status reports, when it reports one. An
+ * installed package that carries no model in status stays unknown here; the
+ * bridge never invents a configuration from its own defaults.
+ * @param {unknown} status @returns {{ provider?: string, model?: string }}
+ */
+function modelConfiguration(status) {
+  if (typeof status !== "object" || status === null) return {};
+  const fields = /** @type {Record<string, unknown>} */ (status);
+  return {
+    ...(typeof fields.provider === "string" ? { provider: fields.provider } : {}),
+    ...(typeof fields.model === "string" ? { model: fields.model } : {}),
+  };
+}
+
+/** @param {any} message */
+function respond(message) {
+  process.stdout.write(JSON.stringify(message) + "\n");
+}
+
+/** @param {unknown} error @returns {string} */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * One request through the public operations only. Every value is the
+ * producer's own admission, evidence, page, or status projection.
+ * @param {any} request @param {typeof import("@astrosheep/keiyaku")} sdk @param {AbortController} controller @returns {Promise<any>}
+ */
+async function operate(request, sdk, controller) {
+  const akuma = sdk.Akuma.select(request.world, request.aku);
+  if (request.op === "tell") return await akuma.tell(request.text, { signal: controller.signal });
+  if (request.op === "stop") return { evidence: await akuma.kill({ signal: controller.signal }) };
+  if (request.op === "status") return modelConfiguration(await akuma.status());
+  throw new Error("unsupported Keiyaku SDK operation: " + String(request.op));
+}
+
+/** @param {string} line */
+async function dispatch(line) {
+  /** @type {any} */
+  let request;
+  try { request = JSON.parse(line); } catch { return; }
+  if (request === null || typeof request !== "object" || typeof request.id !== "number") return;
+  if (request.op === "cancel") {
+    const cancelled = controllers.get(request.target);
+    if (cancelled !== undefined) cancelled.abort();
+    return;
+  }
+  // A stream subscription outlives its opening request: the pull requests that
+  // follow carry the subscription's own identity, so ordinary requests keep
+  // their own lifetime and cancellation never reaches an unrelated observation.
+  if (request.op === "stream") {
+    const controller = new AbortController();
+    subscriptions.set(request.id, { controller, iterator: undefined });
+    try {
+      const sdk = await boot;
+      const akuma = sdk.Akuma.select(request.world, request.aku);
+      if (!exposesStream(akuma)) {
+        throw new Error("the installed @astrosheep/keiyaku package does not expose Akuma.stream; " +
+          "the Paseo bridge cannot observe this Akuma continuously");
+      }
+      if (controller.signal.aborted) throw new Error("Keiyaku SDK stream was cancelled before it opened");
+      const observed = akuma.stream({ signal: controller.signal })[Symbol.asyncIterator]();
+      subscriptions.set(request.id, { controller, iterator: observed });
+      respond({ id: request.id, ok: true, value: { subscription: request.id } });
+    } catch (error) {
+      subscriptions.delete(request.id);
+      controller.abort();
+      respond({ id: request.id, ok: false, error: { message: messageOf(error) } });
+    }
+    return;
+  }
+  if (request.op === "stream-pull") {
+    const subscription = subscriptions.get(request.target);
+    if (subscription === undefined || subscription.iterator === undefined) {
+      respond({ id: request.id, ok: false, error: { message: "Keiyaku SDK stream subscription is not open" } });
+      return;
+    }
+    try {
+      const frame = await subscription.iterator.next();
+      // A released subscription discards its late frame instead of publishing it
+      // into whatever observation the caller opened next.
+      if (subscriptions.get(request.target) !== subscription) throw new Error("Keiyaku SDK stream subscription was released");
+      respond({ id: request.id, ok: true, value: frame.done === true ? { done: true } : { done: false, history: frame.value } });
+    } catch (error) {
+      respond({ id: request.id, ok: false, error: { message: messageOf(error) } });
+    }
+    return;
+  }
+  if (request.op === "stream-cancel") {
+    const subscription = subscriptions.get(request.target);
+    if (subscription !== undefined) {
+      subscriptions.delete(request.target);
+      subscription.controller.abort();
+    }
+    respond({ id: request.id, ok: true, value: null });
+    return;
+  }
+  const controller = new AbortController();
+  controllers.set(request.id, controller);
+  try {
+    const sdk = await boot;
+    if (controller.signal.aborted) throw new Error("Keiyaku SDK request was cancelled before it started");
+    respond({ id: request.id, ok: true, value: await operate(request, sdk, controller) });
+  } catch (error) {
+    respond({ id: request.id, ok: false, error: { message: messageOf(error) } });
+  } finally {
+    controllers.delete(request.id);
+  }
+}
+
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+lines.on("line", (line) => { void dispatch(line); });
+lines.on("close", () => { process.exit(0); });
+`;

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

@@ -0,0 +1,289 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { z } from "zod";
+import { historySchema, identityKeys, type History } from "./keiyaku.js";
+import { tellReceiptSchema } from "./message.js";
+import { WORKER_SOURCE } from "./sdk-worker.js";
+import { stopAttempt } from "./stop.js";
+import type { AkumaTransport } from "./transport.js";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const STDERR_LIMIT = 8 * 1024;
+
+/**
+ * How one request behaves when it is abandoned or when its worker retires. A
+ * bounded ordinary request carries its own id and its own outcome; an unbounded
+ * stream frame carries the subscription it belongs to, so releasing it cancels
+ * that observation alone and says what became of the frame.
+ */
+type RequestMode = Readonly<{ timeout: boolean; subscription: boolean; tail: string }>;
+const ORDINARY_REQUEST: RequestMode = {
+  timeout: true, subscription: false, tail: "its outcome is uncertain",
+};
+/** Opening a subscription is one bounded handshake naming the observation to serve. */
+const OPEN_STREAM: RequestMode = { timeout: true, subscription: true, tail: "the observation was released" };
+/** An idle frame has no bound: waiting for the next change is the stream's whole job. */
+const STREAM_FRAME: RequestMode = { timeout: false, subscription: true, tail: "the observation was released" };
+
+const workerResponse = z.union([
+  z.object({ id: z.number().int().positive(), ok: z.literal(true), value: z.unknown() }),
+  z.object({ id: z.number().int().positive(), ok: z.literal(false), error: z.object({ message: z.string() }) }),
+]);
+const statusObservation = z.object({ provider: z.string().optional(), model: z.string().optional() });
+const stopEvidence = z.object({ evidence: z.string() });
+
+export type SdkTransportOptions = Readonly<{
+  /** An explicit public-entry file or URL; discovery through PATH is the production path. */
+  entry?: string;
+  /** One request's bound. A mutation that outlives it is uncertain, never retried. */
+  timeoutMs?: number;
+}>;
+
+/**
+ * The identity-free environment the worker inherits. The worker runs the
+ * public operations in its own process, so inherited harness, Square, and
+ * Keiyaku caller identities are removed rather than inherited or replaced. The
+ * shared process environment is never mutated.
+ */
+export function cleanEnvironment(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...source };
+  for (const key of identityKeys) delete env[key];
+  return env;
+}
+
+function diagnostic(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+type Pending = {
+  /** The worker that owns this request; another worker's exit never settles it. */
+  worker: ChildProcessWithoutNullStreams;
+  resolve(value: unknown): void;
+  reject(error: Error): void;
+  /** Drop every listener and timer this request added, once it has settled. */
+  release(): void;
+  timer: NodeJS.Timeout | undefined;
+  /** How this request's disappearance is spoken about when it never settles itself. */
+  tail: string;
+};
+
+/**
+ * The dedicated public-SDK transport. One worker process serves every request
+ * over a typed line protocol; requests carry their own cancellation and never
+ * terminate one another. A worker that exits or fails to start settles only the
+ * requests it owned, and the next request starts a fresh one.
+ */
+export function createSdkTransport(options: SdkTransportOptions = {}): AkumaTransport {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let child: ChildProcessWithoutNullStreams | undefined;
+  let nextId = 1;
+  let buffered = "";
+  let stderr = "";
+  let closed = false;
+  const pending = new Map<number, Pending>();
+
+  function settle(id: number, entry: Pending, outcome: Readonly<{ value: unknown }> | Readonly<{ error: Error }>): void {
+    if (pending.get(id) !== entry) return;
+    pending.delete(id);
+    entry.release();
+    if ("error" in outcome) entry.reject(outcome.error);
+    else entry.resolve(outcome.value);
+  }
+
+  function retire(worker: ChildProcessWithoutNullStreams, diagnostic: (entry: Pending) => string): void {
+    if (child === worker) child = undefined;
+    for (const [id, entry] of [...pending]) if (entry.worker === worker) settle(id, entry, { error: new Error(diagnostic(entry)) });
+  }
+
+  function ensure(): ChildProcessWithoutNullStreams {
+    if (child !== undefined) return child;
+    const args = ["--input-type=module", "-e", WORKER_SOURCE];
+    if (options.entry !== undefined) args.push(options.entry);
+    const spawned = spawn(process.execPath, args, { env: cleanEnvironment(), stdio: "pipe" });
+    child = spawned;
+    buffered = "";
+    stderr = "";
+    spawned.stdout.setEncoding("utf8");
+    spawned.stderr.setEncoding("utf8");
+    spawned.stdout.on("data", (chunk: string) => { buffered += chunk; read(); });
+    spawned.stderr.on("data", (chunk: string) => {
+      stderr = (stderr + chunk).slice(-STDERR_LIMIT);
+      process.stderr.write(chunk);
+    });
+    // EPIPE can race a worker that is already retiring; the exit event owns its diagnostic.
+    spawned.stdin.on("error", () => {});
+    spawned.on("error", (error) => retire(spawned,
+      (entry) => `Keiyaku SDK worker failed to start: ${diagnostic(error)}; ${entry.tail}`));
+    spawned.on("exit", (code, signal) => retire(spawned, (entry) =>
+      `Keiyaku SDK worker exited (${signal === null ? String(code) : signal})` +
+      `${stderr.trim() === "" ? "" : `: ${stderr.trim()}`}; ${entry.tail}`));
+    return spawned;
+  }
+
+  function read(): void {
+    for (;;) {
+      const newline = buffered.indexOf("\n");
+      if (newline < 0) return;
+      const line = buffered.slice(0, newline);
+      buffered = buffered.slice(newline + 1);
+      if (line.trim() === "") continue;
+      const decoded = workerResponse.safeParse((() => { try { return JSON.parse(line); } catch { return undefined; } })());
+      if (!decoded.success) {
+        process.stderr.write("Keiyaku SDK worker wrote an unrecognized response line\n");
+        continue;
+      }
+      const entry = pending.get(decoded.data.id);
+      if (entry === undefined) continue;
+      settle(decoded.data.id, entry, decoded.data.ok ? { value: decoded.data.value } : { error: new Error(decoded.data.error.message) });
+    }
+  }
+
+  function request(op: string, payload: Record<string, unknown>, signal: AbortSignal, mode: RequestMode = ORDINARY_REQUEST): Promise<unknown> {
+    signal.throwIfAborted();
+    if (closed) return Promise.reject(new Error("Keiyaku SDK transport is closed"));
+    const worker = ensure();
+    const id = nextId++;
+    // A stream request names the subscription it serves; every other request is
+    // its own subject.
+    const target = mode.subscription && typeof payload.target === "number" ? payload.target : id;
+    return new Promise<unknown>((resolve, reject) => {
+      const cancel = () => {
+        if (!worker.stdin.writable) return;
+        worker.stdin.write(JSON.stringify(mode.subscription
+          ? { id, op: "stream-cancel", target }
+          : { id, op: "cancel", target: id }) + "\n");
+      };
+      const entry: Pending = {
+        worker, resolve, reject, tail: mode.tail,
+        release: () => { clearTimeout(entry.timer); signal.removeEventListener("abort", abandon); },
+        timer: undefined,
+      };
+      // A cancelled request tells the worker to stop observing it. The worker
+      // keeps serving every other request, and an observation of its own is
+      // released without reaching any unrelated one.
+      const abandon = () => {
+        cancel();
+        settle(id, entry, { error: signal.reason instanceof Error ? signal.reason : new Error("Keiyaku SDK request was cancelled") });
+      };
+      if (mode.timeout) entry.timer = setTimeout(() => {
+        cancel();
+        settle(id, entry, { error: new Error(`Keiyaku SDK request timed out after ${timeoutMs}ms; any admitted work's outcome is uncertain`) });
+      }, timeoutMs);
+      pending.set(id, entry);
+      signal.addEventListener("abort", abandon, { once: true });
+      worker.stdin.write(JSON.stringify({ id, op, ...payload }) + "\n", (error) => {
+        if (error) settle(id, entry, { error: new Error(`Keiyaku SDK worker is not writable: ${diagnostic(error)}`) });
+      });
+    });
+  }
+
+  /**
+   * Release one subscription without owning its response: the observation's
+   * frames are already worthless to the caller that gave it up, and the worker
+   * answers the cancel itself.
+   */
+  function releaseSubscription(target: number): void {
+    if (closed) return;
+    const worker = child;
+    if (worker === undefined || !worker.stdin.writable) return;
+    worker.stdin.write(JSON.stringify({ id: nextId++, op: "stream-cancel", target }) + "\n", () => {});
+  }
+
+  const tell: AkumaTransport["tell"] = async (world, akuId, signal, text) => {
+    const value = await request("tell", { world, aku: akuId, text }, signal);
+    const decoded = tellReceiptSchema.parse(value);
+    if (decoded.akuma !== akuId || decoded.tell.admission.tellId !== decoded.tell.row.tellId || decoded.tell.row.text !== text)
+      throw new Error("Keiyaku Tell outcome is uncertain: the admission receipt did not name the submitted Tell");
+    return decoded.tell;
+  };
+
+  const stop: AkumaTransport["stop"] = async (world, akuId, signal) => {
+    const value = await request("stop", { world, aku: akuId }, signal);
+    return stopAttempt(stopEvidence.parse(value).evidence, akuId);
+  };
+
+  const status: AkumaTransport["status"] = async (world, akuId, signal) => {
+    const decoded = statusObservation.parse(await request("status", { world, aku: akuId }, signal));
+    return {
+      ...(decoded.provider === undefined ? {} : { provider: decoded.provider }),
+      ...(decoded.model === undefined ? {} : { model: decoded.model }),
+    };
+  };
+
+  /**
+   * One pull-backed observation. The subscription is established by the first
+   * pull, each pull has at most one outstanding frame, and abandoning the
+   * caller's signal or the iterator releases exactly this subscription.
+   */
+  const stream: AkumaTransport["stream"] = (world, akuId, signal) => ({
+    [Symbol.asyncIterator](): AsyncIterator<History> {
+      let subscription: number | undefined;
+      let released = false;
+      let finished = false;
+      let pulling = false;
+      const release = (): void => {
+        const target = subscription;
+        subscription = undefined;
+        if (target !== undefined) releaseSubscription(target);
+      };
+      // Abort releases the observation even while the caller is not pulling.
+      const abandon = () => { released = true; release(); };
+      signal.addEventListener("abort", abandon, { once: true });
+      const unwind = (): void => { signal.removeEventListener("abort", abandon); release(); };
+      return {
+        async next(): Promise<IteratorResult<History>> {
+          // One frame at a time is the transport's own contract, not a habit of
+          // its caller: a second pull here would put two frames in flight.
+          if (pulling)
+            throw new Error("Keiyaku SDK stream subscription already has a frame in flight; pull one frame at a time");
+          pulling = true;
+          try {
+            if (finished || released || signal.aborted) { unwind(); return { done: true, value: undefined }; }
+            if (subscription === undefined) {
+              const opened = z.object({ subscription: z.number().int().positive() })
+                .parse(await request("stream", { world, aku: akuId }, signal, OPEN_STREAM));
+              subscription = opened.subscription;
+            }
+            const frame = z.union([z.object({ done: z.literal(true) }),
+              z.object({ done: z.literal(false), history: z.unknown() })])
+              .parse(await request("stream-pull", { target: subscription }, signal, STREAM_FRAME));
+            if (frame.done) { unwind(); return { done: true, value: undefined }; }
+            return { done: false, value: historySchema.parse(frame.history) };
+          } catch (error) {
+            // A failed or released observation is over: it never silently reopens
+            // a subscription the caller did not ask for again.
+            finished = true;
+            unwind();
+            throw error;
+          } finally {
+            pulling = false;
+          }
+        },
+        async return(): Promise<IteratorResult<History>> {
+          finished = true;
+          unwind();
+          return { done: true, value: undefined };
+        },
+        async throw(error?: unknown): Promise<IteratorResult<History>> { finished = true; unwind(); throw error; },
+      };
+    },
+  });
+
+  async function close(): Promise<void> {
+    if (closed) return;
+    closed = true;
+    const worker = child;
+    child = undefined;
+    for (const [id, entry] of [...pending])
+      settle(id, entry, { error: new Error(`Keiyaku SDK transport closed while the request was in flight; ${entry.tail}`) });
+    if (worker === undefined) return;
+    if (worker.exitCode !== null || worker.signalCode !== null) return;
+    await new Promise<void>((resolve) => {
+      const force = setTimeout(() => worker.kill("SIGKILL"), 2_000);
+      worker.once("close", () => { clearTimeout(force); resolve(); });
+      try { worker.stdin.end(); } catch { /* the worker may already be gone */ }
+      worker.kill("SIGTERM");
+    });
+  }
+
+  return Object.freeze({ stream, tell, stop, status, close });
+}

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

@@ -0,0 +1,26 @@
+/**
+ * One Stop attempt's honest verdict. Only `stopped` proves the Akuma's current
+ * execution settled; `not-stopped` carries the public evidence's own refusal or
+ * unsettled outcome, and `uncertain` admits that no decided answer exists — a
+ * timeout or lost receipt never proves either outcome.
+ */
+export type StopAttempt =
+  | Readonly<{ kind: "stopped" }>
+  | Readonly<{ kind: "not-stopped"; message: string }>
+  | Readonly<{ kind: "uncertain"; message: string }>;
+
+const settledEvidence = new Set(["killed", "already-killed", "already-stopped"]);
+
+/**
+ * One public kill evidence's honest verdict. Only settled evidence proves the
+ * Akuma's current execution ended; every other evidence names a refusal or an
+ * unsettled outcome in Keiyaku's own words.
+ */
+export function stopAttempt(evidence: string, akuId: string): StopAttempt {
+  return settledEvidence.has(evidence)
+    ? { kind: "stopped" }
+    : { kind: "not-stopped", message: `Keiyaku reported ${evidence} for ${akuId}` };
+}
+
+/** Stop one Akuma and return its verdict; transport failure rejects. */
+export type Stop = (world: string, akuId: string, signal: AbortSignal) => Promise<StopAttempt>;

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

@@ -0,0 +1,35 @@
+import type { History } from "./keiyaku.js";
+import type { Tell } from "./message.js";
+import type { Stop } from "./stop.js";
+
+/** The public Akuma configuration one read-only observation reports, when it is known. */
+export type StatusObservation = Readonly<{ provider?: string; model?: string }>;
+/** Read one Akuma's public status projection for display; failure rejects. */
+export type StatusReader = (world: string, akuId: string, signal: AbortSignal) => Promise<StatusObservation>;
+/**
+ * Observe one Akuma's current retained window continuously, including while it is
+ * idle and across later Turns. Each frame is a complete bounded window, never a
+ * delta; the subscription releases its reader when the caller stops pulling or
+ * aborts. Failure rejects the pull that saw it and ends that subscription.
+ */
+export type Stream = (world: string, akuId: string, signal: AbortSignal) => AsyncIterable<History>;
+
+/**
+ * The one typed boundary between the Paseo bridge and the Keiyaku public
+ * surface. It replaces the earlier CLI-shaped executor: no command strings, no
+ * stdout JSON, no exit-code interpretation. Every operation carries its World
+ * and Akuma coordinates, observes the caller's cancellation, and rejects with
+ * its own diagnostic when it cannot answer; mutation outcomes are only ever the
+ * public operations' own receipts.
+ *
+ * `close` owns the transport's whole lifecycle: it refuses new requests and
+ * settles every request still in flight as uncertain, but a single request's
+ * cancellation must never terminate unrelated work.
+ */
+export type AkumaTransport = Readonly<{
+  stream: Stream;
+  tell: Tell;
+  stop: Stop;
+  status: StatusReader;
+  close(): Promise<void>;
+}>;

package/plugins/paseo/plugin/shared/attach-rpc.ts

@@ -0,0 +1,10 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+export const attachRpc = defineRpc({ name: "attach",
+  input: z.object({ world: z.string(), akuId: z.string(), caller: z.union([
+    z.object({ kind: z.literal("akuma"), world: z.string(), akuId: z.string() }),
+    z.object({ kind: z.literal("external"), integration: z.string(), id: z.string() }),
+    z.object({ kind: z.literal("unknown") }),
+  ]).optional() }),
+  output: z.object({ attached: z.boolean() }),
+});

package/plugins/paseo/plugin/shared/refresh-rpc.ts

@@ -0,0 +1,6 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+export const refreshRpc = defineRpc({ name: "refresh",
+  input: z.object({ world: z.string(), akuId: z.string() }),
+  output: z.object({ woken: z.number().int().nonnegative() }),
+});

package/plugins/paseo/plugin/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": { "noEmit": true, "rootDir": "." },
+  "include": ["**/*.ts"],
+  "exclude": []
+}

package/skills/keiyaku/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: keiyaku
 description: >-
-  Keiyaku is a CLI that records plans, writes handoff terms for deliveries,
+  Keiyaku is a CLI that records unresolved work, writes handoff terms for deliveries,
   and calls delegates. Use this skill when you need to figure out which
   Keiyaku skill or command to reach for.
 ---
@@ -10,8 +10,8 @@ description: >-
 
 ## Model
 
-Keiyaku is three independent pillars, not a bundle: **Task** remembers plans
-and dependencies, **Contract** makes acceptance standing and auditable,
+Keiyaku is three independent pillars, not a bundle: **Debt** records unresolved
+work and dependencies, **Contract** makes acceptance standing and auditable,
 **Akuma** invokes capability. Use any one alone; combine them only when the
 work calls for it. Behind every Contract in flight there is one holder of its
 fulfillment loop — whoever turns intent into commissions and returns into
@@ -23,9 +23,8 @@ equally. See `keiyaku-workflow` for the loop, `keiyaku-bind` for authoring,
 ## Quick Start
 
 ```bash
-keiyaku -C <repo> task add "title"
-keiyaku -C <repo> task start <task-id>
-keiyaku -C <repo> bind [--task <task-id>] -
+keiyaku -C <repo> debt add "title"
+keiyaku -C <repo> bind [--debt <debt-id>] -
 keiyaku -C <repo> status
 keiyaku -C <repo> deliver [<contract>|@<contract>]
 keiyaku -C <repo> review [<contract>|@<contract>] --satisfied

package/skills/keiyaku-akuma/SKILL.md

@@ -113,7 +113,7 @@ complete grammar.
 ## JavaScript automation
 
 Use [Automation With The Akuma API](references/automation.md) for a
-task-specific JavaScript coordinator, structured answers, or multi-worker
+debt-specific JavaScript coordinator, structured answers, or multi-worker
 orchestration. The CLI is enough for one commission and its return. A
 prompt-free birth followed by one input-bound ask uses the same identity: