@astrosheep/keiyaku 4.6.7 → 4.6.9

package/build/src/cli/commands/contract-help.js

@@ -5,16 +5,23 @@ export const CONTRACT_COMMAND_SPECS = {
         stdin: "optional",
         flags: {
             actor: "value",
-            task: "value",
+            debt: "value",
             target: "value",
+            "no-target": "boolean",
             after: "repeat",
             gates: "raw-value",
             "fork-of": "value",
             json: "boolean",
         },
-        usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>]",
+        usage: "bind [--debt <debt/...>] [--target <ref> | --no-target] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] - | bind --fork-of <kei/...> [--target <ref> | --no-target] [--actor <actor>]",
         purpose: "Create a Contract from stdin Markdown or copy an existing Contract as a starting point.",
         details: [
+            "--target names one existing local branch literally; it is never created and never",
+            "guessed. Omitting it binds to the current branch of the invocation worktree",
+            "coordinate, or binds without a target on a detached committed HEAD. --no-target",
+            "binds without a target on purpose, and is refused together with --target.",
+            "A fork copies its source target when neither flag is given.",
+            "",
             "Gates are acceptance obligations checked at placement: reviewed awaits a",
             "satisfied review, verified awaits a passing Verification run.",
             "",
@@ -140,11 +147,24 @@ export const CONTRACT_COMMAND_SPECS = {
         usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>]",
         purpose: "End work on a Contract without delivering it; optionally record why.",
     },
+    show: {
+        positional: "optional",
+        stdin: "none",
+        flags: { json: "boolean" },
+        usage: "show [<contract>|@<contract>]",
+        purpose: "Read one Contract's guidance.",
+        details: [
+            "Accepts a complete Contract identity or exact @<contract> short selector.",
+            "Omitted selection uses the exact managed worktree's installed Contract context.",
+            "Akuma, category, and plural selections are refused before reading guidance.",
+            "Text returns guidance directly; --json serializes the same native value.",
+        ].join("\n"),
+    },
     status: {
         positional: "optional",
         stdin: "none",
-        flags: { guidance: "boolean", limit: "value", json: "boolean" },
-        usage: "status [<contract>|@name|<aku/...>]...\nstatus (aku|aku/|aku/*) [--limit <count>]\nstatus (kei|kei/|kei/*) [--limit <count>]\nstatus --guidance [<contract>|@<contract>]",
+        flags: { limit: "value", json: "boolean" },
+        usage: "status [<contract>|@name|<aku/...>]...\nstatus (aku|aku/|aku/*) [--limit <count>]\nstatus (kei|kei/|kei/*) [--limit <count>]",
         purpose: "Show the world overview or selected Contract and Akuma status.",
         details: [
             "Akuma entries show the directory each Akuma was started in.",
@@ -152,18 +172,14 @@ export const CONTRACT_COMMAND_SPECS = {
             "aku, aku/, and aku/* show the recent Akuma board; kei, kei/, and kei/* show the",
             "recent active Contract board. --limit bounds the board to that many recent rows",
             "(default 10). The Contract category requires a Repo; the Akuma category does not.",
-            "",
-            "--guidance reads one Contract's guidance instead of status. It accepts one Contract",
-            "selector or the installed Contract selection context, and refuses an Akuma, plural,",
-            "or world selection before the read.",
         ].join("\n"),
     },
     ls: {
         positional: "optional",
         stdin: "none",
         flags: { limit: "value", json: "boolean" },
-        usage: 'ls task[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]',
-        purpose: "List tasks (ls task), contracts (ls kei), or akumas (ls aku).",
+        usage: 'ls debt[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]',
+        purpose: "List debts (ls debt), contracts (ls kei), or akumas (ls aku).",
         details: [
             "ls kei lists active Contracts; accepted and abandoned ones leave the list, and their record stays in history and Git.",
             "ls aku/ lists the callable Akuma-name catalog; ls aku/<name> lists the living Akumas under one name.",
@@ -198,7 +214,7 @@ export const CONTRACT_COMMAND_SPECS = {
         flags: { confirm: "value", json: "boolean" },
         usage: "nuke [--confirm <world-directory>]",
         purpose: "Remove Keiyaku-owned data from this World.",
-        details: "Stops Akumas and removes this World's Tasks and Keiyaku-created worktrees and Git references. --confirm must exactly match this World's directory; source files are not deleted.",
+        details: "Stops Akumas and removes this World's Debts and Keiyaku-created worktrees and Git references. --confirm must exactly match this World's directory; source files are not deleted.",
     },
     settings: {
         positional: "none",
@@ -245,6 +261,29 @@ export function renderContractHelp(command) {
             "effort, network, allowed, systemPromptMode, and description; the body is",
             "an optional system prompt.",
             "",
+            "Local Paseo provider in settings.json:",
+            '  { "providers": { "paseo": {',
+            '    "kind": "paseo",',
+            '    "config": { "url": "ws://127.0.0.1:6767/ws", "provider": "claude" }',
+            "  } } }",
+            "The native provider id is bare (claude, codex, pi), not provider/model.",
+            "Example .keiyaku/akuma/paseo-worker.md frontmatter:",
+            "  ---",
+            "  provider: paseo",
+            "  model: <native-model-id>",
+            "  effort: high",
+            "  ---",
+            "Model and effort must be offered by the selected native provider;",
+            "effort names its native thinking option id.",
+            'PASEO_PASSWORD=<password> keiyaku call paseo-worker "<prompt>"',
+            "Paseo must already be running locally. Resume keeps its live native",
+            "runtime; after Paseo native reload/restart create a fresh Akuma.",
+            "Observed busy agents refuse; native steer still has a check/send race.",
+            "Explicit control cancels native current execution session-wide and may",
+            "affect concurrent human work. Normal completion only retires the client",
+            "and its sockets; it never cancels later work or closes the native runtime.",
+            "Socket closure does not prove native cancellation succeeded.",
+            "",
             usageLine(spec.usage),
         ].join("\n");
     }

package/build/src/cli/commands/contract.js

@@ -1,18 +1,17 @@
-import { listArchetypeDefinitions } from "../../akuma/archetype.js";
 import { executionChannel } from "../../akuma/requests.js";
-import { Akumas, Keiyaku, KeiyakuError, nuke } from "../../index.js";
-import { kanshi, kanshiCategory, observeKanshi, selectKanshi, selectRegion } from "../../kanshi/index.js";
+import { Akumas, Keiyaku, KeiyakuError, kanshiCategory, listArchetypeDefinitions, nuke } from "../../index.js";
+import { kanshi, observeKanshi, selectRegion } from "../../kanshi/index.js";
 import { resolveNamedAddress } from "../../library/address.js";
 import { composeContractLibrary, observeKeiyaku } from "../../library/contract-composition.js";
 import { validateArcMarkdown, validateContractMarkdown } from "../../library/input.js";
 import { createKeiyakuHandle } from "../../library/keiyaku.js";
 import { SettingsError, settings } from "../../settings.js";
-import { Tasks } from "../../task/index.js";
+import { Debts } from "../../debt/index.js";
 import { actorFromEdge } from "../actor.js";
 import { resolveInvocationCwd } from "../coordinates.js";
 import { BindDraftError, preserveBindDraft } from "../draft.js";
 import { snapshotText } from "../render/akuma-activity.js";
-import { renderAkumaCatalogue, renderArchetypeCatalogue, renderContractCatalogue, renderTaskCatalogue, } from "../render/catalog.js";
+import { renderAkumaCatalogue, renderArchetypeCatalogue, renderContractCatalogue, renderDebtCatalogue, } from "../render/catalog.js";
 import { renderAccepted, renderContractHistory, renderRetry } from "../render/contract.js";
 import { renderKanshiCategoryText, renderKanshiText } from "../render/kanshi.js";
 import { nukeExitCode, renderNukeText } from "../render/nuke.js";
@@ -20,11 +19,9 @@ import { reconcileHasFailure, renderReconcile } from "../render/reconcile.js";
 import { renderConflictMaterialized, renderRefusal } from "../render/refusal.js";
 import { renderRegionText } from "../render/region.js";
 import { renderSettingsText, settingsJsonValue } from "../render/settings.js";
-import { canonicalContractSelector, contractFromInput, resolveContractId, resolveKanshiContract, } from "../selectors.js";
-import { displayContext, emit, writeJson, writeStdout } from "../streams.js";
+import { canonicalContractSelector, contractFromInput, resolveContractId } from "../selectors.js";
+import { displayContext, emit, writeJson, writeStderr, writeStdout } from "../streams.js";
 import { CliUsageError, isBlankInput } from "../usage.js";
-import { amendFromCommand } from "./amend.js";
-import { bindFromCommand } from "./bind.js";
 function requiredRepo(coordinates) {
     if (coordinates.repo === undefined)
         throw new CliUsageError("this command requires a resolved Repo");
@@ -50,17 +47,6 @@ async function contractSettings(command, execution, world, home) {
 function draftWarning(error) {
     return { warning: `bind draft could not be preserved: ${error instanceof Error ? error.message : String(error)}` };
 }
-/** Preserve a refused bind draft at the invocation cwd; coordinates are not yet available. */
-async function bindDraftReceiptAtCwd(input, markdown) {
-    try {
-        return await preserveBindDraft(await resolveInvocationCwd(input), markdown);
-    }
-    catch (error) {
-        if (error instanceof Error && "executionReceipt" in error)
-            throw error;
-        return draftWarning(error);
-    }
-}
 /**
  * The one bind-document admission that runs before coordinate resolution, so a malformed document
  * refuses as a draft-bearing refusal instead of a later Repo/Git failure. Reads the memoized stdin.
@@ -76,7 +62,7 @@ export async function admitBindMarkdown(input) {
             throw error;
         if (!(error instanceof TypeError) && !(error instanceof KeiyakuError && error.category === "invalid-input"))
             throw error;
-        throw new BindDraftError(error, await bindDraftReceiptAtCwd(input, input.markdown));
+        throw new BindDraftError(error, await bindDraftReceipt(() => resolveInvocationCwd(input), input.markdown));
     }
 }
 async function bindDraftReceipt(world, markdown) {
@@ -145,41 +131,32 @@ async function contractLibrary(command, execution, configuration, runtime) {
     return composeContractLibrary(execution, createKeiyakuHandle, {
         ...(configuration === undefined ? {} : { settings: configuration }),
         ...(actor === undefined ? {} : { actor }),
-    }, 
-    // The CLI owns this default: an omitted Markdown --target names the invocation branch.
-    { kind: "current-branch" });
+    });
 }
 async function runBind(command, input, library) {
     const { coordinates, runtime } = input;
     const repo = requiredRepo(coordinates);
     const actor = actorFromEdge(command.actor, runtime.environment);
     if (command.forkOf !== undefined) {
-        const answer = await bindFromCommand({
-            command,
+        const answer = await library.bind({
             repo,
-            library,
+            forkOf: contractFromInput(repo, command.forkOf).id,
+            ...(command.target === undefined ? {} : { target: command.target }),
             ...(actor === undefined ? {} : { actor }),
         });
         return await finishContractAnswer(answer, command.output);
     }
     const markdown = await runtime.readStdin();
-    if (isBlankInput(markdown))
-        throw new CliUsageError("bind requires a nonblank stdin document");
     try {
-        validateContractMarkdown(markdown);
-    }
-    catch (error) {
-        if (!(error instanceof TypeError) && !(error instanceof KeiyakuError && error.category === "invalid-input"))
-            throw error;
-        throw new BindDraftError(error, await bindDraftReceipt(coordinates.establishWorld, markdown));
-    }
-    try {
-        const answer = await bindFromCommand({
-            command,
+        const after = command.after?.map((id) => contractFromInput(repo, id).id);
+        const answer = await library.bind({
             repo,
-            library,
             markdown,
+            ...(command.debt === undefined ? {} : { debt: command.debt }),
+            ...(command.target === undefined ? {} : { target: command.target }),
             ...(actor === undefined ? {} : { actor }),
+            ...(after === undefined ? {} : { after }),
+            ...(command.gates === undefined ? {} : { gates: command.gates }),
         });
         if (answer.kind !== "refused")
             return await finishContractAnswer(answer, command.output);
@@ -203,13 +180,13 @@ async function runAmend(command, input, seat) {
     const markdown = command.stdin === true ? await runtime.readStdin() : undefined;
     if (markdown !== undefined && isBlankInput(markdown))
         throw new CliUsageError("amend requires a nonblank stdin document");
-    const answer = await amendFromCommand({
-        command,
-        repo: requiredRepo(coordinates),
-        contract: seat.contract,
+    const repo = requiredRepo(coordinates);
+    const after = command.clearAfter === true ? [] : command.after?.map((id) => contractFromInput(repo, id).id);
+    const answer = await seat.contract.amend({
         ...(markdown === undefined ? {} : { markdown }),
-        ...(command.gates === undefined ? {} : { gates: command.gates }),
         ...(seat.actor === undefined ? {} : { actor: seat.actor }),
+        ...(after === undefined ? {} : { after }),
+        ...(command.gates === undefined ? {} : { gates: command.gates }),
     });
     return await finishContractAnswer(answer, command.output);
 }
@@ -347,15 +324,15 @@ async function runLs(command, coordinates, home) {
     }
     if (coordinates.world === null)
         throw new CliUsageError("no Keiyaku world contains the invocation cwd");
-    if (query.kind === "tasks") {
-        const listed = await Tasks.of(coordinates.world).list({
+    if (query.kind === "debts") {
+        const listed = await Debts.of(coordinates.world).list({
             selection: "all",
             namespace: query.namespace ?? [],
             ...(query.limit === undefined ? {} : { limit: query.limit }),
         });
         if (listed.kind !== "accepted")
-            throw new Error("Task list did not return an accepted observation");
-        return emit(command.output, listed, () => renderTaskCatalogue(listed.value, query.namespace ?? []), 0);
+            throw new Error("Debt list did not return an accepted observation");
+        return emit(command.output, listed, () => renderDebtCatalogue(listed.value, query.namespace ?? []), 0);
     }
     const listed = await Akumas.of(coordinates.world).list({
         ...(query.archetype === undefined ? {} : { archetype: query.archetype }),
@@ -366,7 +343,7 @@ async function runLs(command, coordinates, home) {
 async function readAkumaStatus(akuma, alias, coordinates) {
     if (coordinates.world === null)
         throw new CliUsageError("no Keiyaku world contains the Akuma selector");
-    const status = await Akumas.of(coordinates.world).status({
+    const status = await Akumas.of(coordinates.world, { reportDiagnostic: writeStderr }).status({
         akuma,
         ...(coordinates.repo === undefined ? {} : { repo: coordinates.repo }),
     });
@@ -398,14 +375,14 @@ async function namedStatus(selector, coordinates, named) {
         return await readAkumaStatus(address.id, selector, coordinates);
     return await readContractStatus(address.id, coordinates, named);
 }
-async function runStatusGuidance(command, coordinates) {
+async function runShow(command, coordinates) {
     const repo = coordinates.repo;
     if (repo === undefined)
         throw new CliUsageError("cannot select a contract while the Contract world is absent");
     const selected = await selectedContract(repo, command.contract, coordinates.cwd);
     const guidance = await selected.contract.guidance();
     if (guidance === null) {
-        const refusal = statusRefusal("status", selected.id);
+        const refusal = statusRefusal(command.command, selected.id);
         return emit(command.output, null, () => renderRefusal(refusal, undefined, displayContext()), 1);
     }
     return emit(command.output, guidance, () => guidance, 0);
@@ -473,17 +450,9 @@ async function runStatusIdentity(command, coordinates) {
         }
         return emit(command.output, report, () => renderKanshiText(report, displayContext(), "contract"), 0);
     }
-    const report = await kanshi({
-        world: coordinates.world,
-        ...(coordinates.repo === undefined ? {} : { repo: coordinates.repo }),
-    });
-    const contract = resolveKanshiContract(report, command.contract);
-    const selected = selectKanshi({ report, contract });
-    return emit(command.output, selected, () => renderKanshiText(selected, displayContext(), "contract"), 0);
+    throw new CliUsageError(`contract selector must use kei/: ${command.contract}`);
 }
 async function runStatus(command, coordinates) {
-    if (command.guidance === true)
-        return await runStatusGuidance(command, coordinates);
     if (command.category !== undefined)
         return await runStatusCategory(command, coordinates);
     if ("selectors" in command && command.selectors !== undefined)
@@ -501,10 +470,10 @@ async function runRegion(command, coordinates) {
         const report = await kanshi({ world: coordinates.world, repo, region: { kind: "path", patterns: command.paths } });
         return emitSection(report.region ?? { kind: "absent" });
     }
+    const contract = command.contract === undefined ? undefined : await resolveContractId(repo, command.contract, coordinates.cwd);
     const report = await kanshi({ world: coordinates.world, repo, region: { kind: "declarations" } });
-    if (command.contract === undefined)
+    if (contract === undefined)
         return emitSection(report.region ?? { kind: "absent" });
-    const contract = resolveKanshiContract(report, command.contract);
     const observed = await observeKeiyaku({ repo, id: contract });
     if (observed.kind === "missing" || observed.row.phase === "claimed" || observed.row.phase === "abandoned") {
         const refusal = {
@@ -579,6 +548,8 @@ export async function runContractCommand(command, coordinates, runtime) {
             return await runNuke(command, coordinates);
         case "ls":
             return await runLs(command, coordinates, home);
+        case "show":
+            return await runShow(command, coordinates);
         case "status":
             return await runStatus(command, coordinates);
         case "region":

package/build/src/cli/commands/debt-grammar.d.ts

@@ -0,0 +1,19 @@
+import { type CliUsageGuide } from "../usage.js";
+import { type DebtQueryExpression } from "./debt-query.js";
+export type DebtAction = "add" | "show" | "ls" | "ready" | "blocked" | "tree" | "doctor" | "update" | "query" | "done" | "drop" | "context";
+type DebtFlagValue = string | true | readonly string[];
+type DebtStdin = "document" | "body" | "append" | "note";
+export type ParsedDebtCommand = Readonly<{
+    command: "debt";
+    action: DebtAction;
+    output: "text" | "json";
+    positionals: readonly string[];
+    flags: Readonly<Record<string, DebtFlagValue>>;
+    stdin?: DebtStdin;
+    where?: DebtQueryExpression;
+}>;
+export declare function isDebtAction(value: string | undefined): value is DebtAction;
+export declare function renderDebtHelp(action?: DebtAction): string;
+export declare function debtUsageGuide(action: DebtAction): CliUsageGuide;
+export declare function parseDebtCommand(argv: readonly string[]): ParsedDebtCommand;
+export {};