@astrosheep/keiyaku 4.6.8 → 4.6.9

package/build/src/settlement/settle.js

@@ -1,24 +1,24 @@
 import { contractIdSchema } from "../git/identity.js";
 import { z } from "zod";
-import { taskIdSchema } from "../task/identity.js";
+import { debtIdSchema } from "../debt/identity.js";
 import { observeContractsForAdmissionAt } from "../git/observe.js";
 import { appendPrivateStateSeatClose, withPrivateStatePublicationSeat, } from "../git/private-state-seat.js";
 import { GitPlumbingError } from "../git/process.js";
 import { SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
-import { settleTask } from "../task/operations.js";
-import { publishTaskHolderRelease, readTaskHolderProjectionFromDecision, taskHolderObservationSelection, } from "./holder.js";
-import { acquireTaskSettlementFence } from "./fence.js";
+import { settleDebt } from "../debt/operations.js";
+import { publishDebtHolderRelease, readDebtHolderProjectionFromDecision, debtHolderObservationSelection, } from "./holder.js";
+import { acquireDebtSettlementFence } from "./fence.js";
 import { World } from "../world.js";
 export const settlementActionSchema = z
-    .object({ kind: z.literal("task"), taskId: taskIdSchema, action: z.literal("done") })
+    .object({ kind: z.literal("debt"), debtId: debtIdSchema, action: z.literal("done") })
     .strict();
 export const settlementLagSchema = z
     .object({
     kind: z.literal("settlement-failed"),
-    surface: z.enum(["task-holder", "task"]),
+    surface: z.enum(["debt-holder", "debt"]),
     contractId: contractIdSchema,
-    taskId: taskIdSchema.optional(),
+    debtId: debtIdSchema.optional(),
     path: z
         .string()
         .refine((value) => value.trim() !== "")
@@ -36,10 +36,10 @@ function operational(error) {
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function taskFailure(result) {
+function debtFailure(result) {
     return result.kind === "retry"
-        ? `Task settlement requires retry: ${result.reason}`
-        : `Task settlement refused: ${JSON.stringify(result.refusal)}`;
+        ? `Debt settlement requires retry: ${result.reason}`
+        : `Debt settlement refused: ${JSON.stringify(result.refusal)}`;
 }
 function recordLag(input, lag) {
     input.lags.push(lag);
@@ -53,11 +53,11 @@ async function observeApplicableHolder(input) {
     const { repository, channel, candidate } = input;
     let observation;
     try {
-        observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], taskHolderObservationSelection());
+        observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], debtHolderObservationSelection());
         const state = observation.journals.get(candidate.id)?.state ?? null;
         if (state === null || state.terminal?.kind !== "claimed")
             return null;
-        const holder = (await readTaskHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
+        const holder = (await readDebtHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
         return holder?.disposition === "held" ? holder : null;
     }
     catch (error) {
@@ -65,15 +65,15 @@ async function observeApplicableHolder(input) {
             throw error;
         recordLag(input, {
             kind: "settlement-failed",
-            surface: "task-holder",
+            surface: "debt-holder",
             contractId: candidate.id,
             diagnostic: diagnostic(error),
         });
         return null;
     }
 }
-async function completeHeldTask(input) {
-    const { repository, candidate, taskId } = input;
+async function completeHeldDebt(input) {
+    const { repository, candidate, debtId } = input;
     let world;
     try {
         world = await World.at(repository.primaryWorktree);
@@ -83,38 +83,38 @@ async function completeHeldTask(input) {
             throw error;
         recordLag(input, {
             kind: "settlement-failed",
-            surface: "task",
+            surface: "debt",
             contractId: candidate.id,
-            taskId,
+            debtId,
             diagnostic: diagnostic(error),
         });
         return false;
     }
     let result;
     try {
-        result = await settleTask(world, taskId);
+        result = await settleDebt(world, debtId);
     }
     catch (error) {
         if (!operational(error))
             throw error;
         recordLag(input, {
             kind: "settlement-failed",
-            surface: "task",
+            surface: "debt",
             contractId: candidate.id,
-            taskId,
+            debtId,
             diagnostic: diagnostic(error),
         });
         return false;
     }
     if (result.kind === "changed")
-        recordAction(input, { kind: "task", taskId, action: "done" });
+        recordAction(input, { kind: "debt", debtId, action: "done" });
     if (result.kind === "changed" && result.cleanup !== undefined) {
         for (const detail of result.cleanup.diagnostics) {
             recordLag(input, {
                 kind: "settlement-failed",
-                surface: "task",
+                surface: "debt",
                 contractId: candidate.id,
-                taskId,
+                debtId,
                 diagnostic: detail,
             });
         }
@@ -123,32 +123,32 @@ async function completeHeldTask(input) {
         return true;
     recordLag(input, {
         kind: "settlement-failed",
-        surface: "task",
+        surface: "debt",
         contractId: candidate.id,
-        taskId,
-        diagnostic: taskFailure(result),
+        debtId,
+        diagnostic: debtFailure(result),
     });
     return false;
 }
-async function releaseHeldTaskHolder(input) {
-    const { repository, channel, candidate, seatClose, taskId } = input;
+async function releaseHeldDebtHolder(input) {
+    const { repository, channel, candidate, seatClose, debtId } = input;
     try {
         const outcome = await withPrivateStatePublicationSeat(repository, async (seat) => {
-            const observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], taskHolderObservationSelection());
+            const observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], debtHolderObservationSelection());
             const state = observation.journals.get(candidate.id)?.state ?? null;
             if (state === null || state.terminal?.kind !== "claimed")
                 return "inert";
-            const holder = (await readTaskHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
-            if (holder === null || holder.disposition !== "held" || holder.taskId !== taskId)
+            const holder = (await readDebtHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
+            if (holder === null || holder.disposition !== "held" || holder.debtId !== debtId)
                 return "inert";
-            const publication = await publishTaskHolderRelease(repository, channel, observation, candidate.id, seat);
+            const publication = await publishDebtHolderRelease(repository, channel, observation, candidate.id, seat);
             if (publication.kind === "non-published") {
                 recordLag(input, {
                     kind: "settlement-failed",
-                    surface: "task-holder",
+                    surface: "debt-holder",
                     contractId: candidate.id,
-                    taskId,
-                    diagnostic: `Task holder release requires retry: ${publication.diagnostic}`,
+                    debtId,
+                    diagnostic: `Debt holder release requires retry: ${publication.diagnostic}`,
                 });
                 return "held";
             }
@@ -165,51 +165,51 @@ async function releaseHeldTaskHolder(input) {
             throw error;
         recordLag(input, {
             kind: "settlement-failed",
-            surface: "task-holder",
+            surface: "debt-holder",
             contractId: candidate.id,
-            taskId,
+            debtId,
             diagnostic: diagnostic(error),
         });
         return "held";
     }
 }
-async function settleTasks(input) {
+async function settleDebts(input) {
     const { repository, channel, candidate, lags, seatClose } = input;
     const hint = await observeApplicableHolder(input);
     if (hint === null)
         return false;
-    const taskId = hint.taskId;
+    const debtId = hint.debtId;
     let fence;
     try {
-        fence = await acquireTaskSettlementFence(repository, taskId);
+        fence = await acquireDebtSettlementFence(repository, debtId);
     }
     catch (error) {
         if (!operational(error))
             throw error;
         recordLag(input, {
             kind: "settlement-failed",
-            surface: "task",
+            surface: "debt",
             contractId: candidate.id,
-            taskId,
+            debtId,
             diagnostic: diagnostic(error),
         });
         return true;
     }
     let failure;
-    let taskSettled = false;
+    let debtSettled = false;
     let holderDisposition = null;
     try {
         const holder = await observeApplicableHolder(input);
-        if (holder === null || holder.taskId !== taskId)
+        if (holder === null || holder.debtId !== debtId)
             return false;
-        taskSettled = await completeHeldTask({ ...input, taskId });
-        if (!taskSettled)
+        debtSettled = await completeHeldDebt({ ...input, debtId });
+        if (!debtSettled)
             return true;
-        holderDisposition = await releaseHeldTaskHolder({
+        holderDisposition = await releaseHeldDebtHolder({
             repository,
             channel,
             candidate,
-            taskId,
+            debtId,
             lags,
             seatClose,
             ...(input.progress === undefined ? {} : { progress: input.progress }),
@@ -229,15 +229,15 @@ async function settleTasks(input) {
                 if (failure === undefined)
                     throw error;
             }
-            else if (!taskSettled && failure === undefined)
+            else if (!debtSettled && failure === undefined)
                 throw error;
             // Post-release fence teardown is custodial residue, not an owed holder publication.
             if (holderDisposition !== "released") {
                 recordLag(input, {
                     kind: "settlement-failed",
-                    surface: "task-holder",
+                    surface: "debt-holder",
                     contractId: candidate.id,
-                    taskId,
+                    debtId,
                     diagnostic: diagnostic(error),
                 });
             }
@@ -258,7 +258,7 @@ async function settleObserved(input) {
     const candidate = input.state;
     if (candidate.terminal?.kind === "claimed") {
         try {
-            await settleTasks({
+            await settleDebts({
                 repository: input.repository,
                 channel: input.channel,
                 candidate,
@@ -273,7 +273,7 @@ async function settleObserved(input) {
                 throw error;
             recordLag({ candidate, lags, ...(input.progress === undefined ? {} : { progress: input.progress }) }, {
                 kind: "settlement-failed",
-                surface: "task",
+                surface: "debt",
                 contractId: candidate.id,
                 diagnostic: diagnostic(error),
             });

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "4.6.8",
+  "version": "4.6.9",
   "workspaces": [
-    "plugins/square"
+    "plugins/square",
+    "plugins/paseo/forwarder"
   ],
   "files": [
     "build",
     "plugins/pi",
+    "plugins/paseo/plugin",
     "skills"
   ],
   "main": "./build/src/index.js",
@@ -31,7 +33,7 @@
   },
   "scripts": {
     "release": "npm run test:release && npm version patch && npm publish",
-    "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('build', { recursive: true, force: true })\" && tsc -p tsconfig.json && npm run build --workspace @astrosheep/keiyaku-plugin-square && node scripts/copy-plugins.js && node scripts/build-windows-launcher.js && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('build/src/cli/index.js', 0o755)\"",
+    "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('build', { recursive: true, force: true })\" && tsc -p tsconfig.json && npm run build --workspace @astrosheep/keiyaku-plugin-square && npm run build --workspace @astrosheep/keiyaku-plugin-paseo && node scripts/copy-plugins.js && node scripts/build-windows-launcher.js && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('build/src/cli/index.js', 0o755)\"",
     "prepack": "node scripts/verify-package.js",
     "postpack": "node scripts/verify-package.js",
     "harness:version": "node scripts/update-harness-version.js",
@@ -63,8 +65,10 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@getpaseo/plugin": "0.11.2",
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^25.0.0",
+    "@types/ws": "^8.18.2",
     "@typescript-eslint/parser": "^8.66.0",
     "eslint": "^9.39.5",
     "knip": "^6.31.0",
@@ -75,13 +79,15 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.3.0",
     "@anthropic-ai/claude-agent-sdk": "^0.3.226",
-    "@astrosheep/keiyaku-plugin-square": "0.1.8",
-    "@astrosheep/square": "^0.3.70",
+    "@astrosheep/keiyaku-plugin-paseo": "0.1.0",
+    "@astrosheep/keiyaku-plugin-square": "0.1.9",
+    "@astrosheep/square": "^0.3.79",
     "@getpaseo/client": "0.11.2",
     "@getpaseo/protocol": "0.11.2",
-    "@opencode-ai/sdk": "1.18.3",
+    "@opencode/client": "2.0.20",
     "cross-spawn": "^7.0.6",
     "diff": "^8.0.4",
+    "undici": "8.10.2",
     "yaml": "^2.9.0",
     "zod": "^4.5.2"
   },

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

@@ -0,0 +1,17 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { createProvider } from "./server/provider.js";
+import { createSdkTransport } from "./server/sdk.js";
+import { attach } from "./server/attach.js";
+import { attachRpc } from "./shared/attach-rpc.js";
+import { refreshRpc } from "./shared/refresh-rpc.js";
+
+export default function contribute(server: PluginServerContext) {
+  const transport = createSdkTransport();
+  const mirror = createProvider(transport);
+  server.registerProvider(mirror.provider);
+  server.handle(refreshRpc, (input) => mirror.refresh(input));
+  server.handle(attachRpc, (input, context) => attach(input, context, mirror.sync));
+  return async () => {
+    try { await mirror.close(); } finally { await transport.close(); }
+  };
+}

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