@astrosheep/keiyaku 4.5.24 → 4.5.26

package/build/src/library/address.d.ts

@@ -51,7 +51,7 @@ export declare function addressAkuma(input: UncheckedAkumaAddressInput): Promise
 }>>;
 export declare function addressAkumaSet(input: UncheckedAkumaAddressInput): Promise<Readonly<{
     path: WorldRoot;
-    /** The complete selected set in canonical order: the durable result order. */
+    /** The complete selected set in canonical order. */
     ids: readonly AkuId[];
     /** The same set in the caller's selector order, for surfaces that name the selection as chosen. */
     orderedIds: readonly AkuId[];

package/build/src/library/address.js

@@ -39,12 +39,6 @@ export function resolveNamedAddress(input) {
     if (selector.startsWith("aku/"))
         return { kind: "akuma", id: parseAkuId(selector).id };
     const alias = parseAkumaAlias(selector);
-    if (input.report.contracts.kind === "failed") {
-        throw new TypeError("cannot resolve a named selector while the Contract world is failed");
-    }
-    if (input.aliases.kind === "failed") {
-        throw new TypeError("cannot resolve a named selector while Alias authority is failed");
-    }
     const contractMatches = (input.report.contracts.kind === "present" ? input.report.contracts.value.rows : []).filter((row) => row.disposition === "active" &&
         row.workspace === "worktree" &&
         row.worktreePath !== null &&
@@ -54,12 +48,20 @@ export function resolveNamedAddress(input) {
         : null;
     if (contractMatches.length > 0 && aliasId !== null)
         throw new TypeError(`ambiguous selector matches Contract and Akuma: ${selector}`);
+    // A readable alias selects its Akuma independently. Contract composition can
+    // enrich the subsequent observation, but cannot erase this core address.
+    if (aliasId !== null)
+        return { kind: "akuma", id: aliasId };
     if (contractMatches.length === 1)
         return { kind: "contract", id: contractMatches[0].id };
     if (contractMatches.length > 1)
         throw new TypeError(`ambiguous Contract selector: ${selector}`);
-    if (aliasId !== null)
-        return { kind: "akuma", id: aliasId };
+    if (input.report.contracts.kind === "failed") {
+        throw new TypeError("cannot resolve a named selector while the Contract world is failed");
+    }
+    if (input.aliases.kind === "failed") {
+        throw new TypeError("cannot resolve a named selector while Alias authority is failed");
+    }
     throw new TypeError(`unknown selector: ${selector}`);
 }
 export async function addressAkuma(input) {

package/build/src/library/akuma-creation.d.ts

@@ -55,11 +55,13 @@ export type CallInput = Readonly<{
     allowed?: readonly AllowedAction[];
     schema?: Schema<unknown>;
     initiator?: string;
+    signal?: AbortSignal;
 }>;
 export type CallObservation = Readonly<{
     kind: "detached";
 }> | Readonly<{
     kind: "observed";
+    reason: "completed" | "deadline";
     status: AkumaStatus;
 }> | Readonly<{
     kind: "failed";
@@ -85,6 +87,7 @@ export type BornCall = Readonly<{
     execution: CallExecution;
     mode: "wait" | "detach";
     timeoutMs: number;
+    signal?: AbortSignal;
     dispatch: DispatchStage;
     alias: AliasStage;
     schemaTell?: Readonly<{

package/build/src/library/akuma-creation.js

@@ -1,6 +1,7 @@
 /** @architectureCompositionRoot */
 import { appendFile } from "node:fs/promises";
 import { moveAlias } from "../alias/index.js";
+import { defaultWaitComplete } from "../akuma/akuma.js";
 import { createAkumaProduct } from "../akuma/akuma-product.js";
 import { pathsForAkuId } from "../akuma/identity.js";
 import { readSoul } from "../akuma/heart/index.js";
@@ -83,6 +84,13 @@ function callTimeout(value, mode) {
     }
     return value;
 }
+function callSignal(value) {
+    if (value === undefined)
+        return undefined;
+    if (!(value instanceof AbortSignal))
+        throw new TypeError("signal must be an AbortSignal");
+    return value;
+}
 function callSeat(contract) {
     if (contract === undefined)
         return undefined;
@@ -91,14 +99,17 @@ function callSeat(contract) {
         throw new TypeError("contract must be a Keiyaku");
     return seat;
 }
-async function observeCall(handle, mode, timeoutMs) {
+async function observeCall(handle, mode, timeoutMs, signal) {
     if (mode === "detach") {
         return { kind: "detached" };
     }
     try {
-        return { kind: "observed", status: await handle.wait(undefined, { timeoutMs }) };
+        const observed = await handle.waitReceipt(undefined, { timeoutMs, ...(signal === undefined ? {} : { signal }) });
+        return { kind: "observed", reason: observed.reason, status: observed.status };
     }
     catch (error) {
+        if (signal?.aborted)
+            throw error;
         return { kind: "failed", failure: integrationFailure(error) };
     }
 }
@@ -257,8 +268,9 @@ const CALL_INPUT_KEYS = [
     "allowed",
     "schema",
     "initiator",
+    "signal",
 ];
-async function prepareCall(input, context) {
+async function parseCallInput(input) {
     const values = requireInput(input, "Keiyaku.call input");
     onlyKeys(values, CALL_INPUT_KEYS, "Keiyaku.call input");
     const path = await World.prove(nonblank(values.path, "path"));
@@ -269,55 +281,81 @@ async function prepareCall(input, context) {
     const cwd = values.cwd === undefined ? undefined : nonblank(values.cwd, "cwd");
     const mode = callMode(values.mode);
     const timeoutMs = callTimeout(values.timeoutMs, mode);
+    const signal = callSignal(values.signal);
     const home = homeOption(values.home);
     const settings = settingsOption(values.settings);
     const alias = values.alias === undefined ? undefined : parseAkumaAlias(nonblank(values.alias, "alias"));
     const seat = callSeat(values.contract);
-    const execution = await resolveCallExecution({
+    return {
+        values,
         path,
-        ...(cwd === undefined ? {} : { cwd }),
-        ...(seat === undefined ? {} : { contract: values.contract }),
-    });
-    const world = akumaWorld(path, home, settings, context);
-    const call = {
         archetype,
-        ...(values.schema === undefined ? { body } : {}),
+        body,
         ...(initiator === undefined ? {} : { initiator }),
-        ...(readonlyRequested === undefined ? {} : { readonly: readonlyRequested }),
-        ...(values.allowed === undefined ? {} : { allowed: values.allowed }),
-        ...(values.schema === undefined ? {} : { schema: values.schema }),
+        ...(readonlyRequested === undefined ? {} : { readonlyRequested }),
+        ...(cwd === undefined ? {} : { cwd }),
+        mode,
+        timeoutMs,
+        ...(signal === undefined ? {} : { signal }),
+        ...(home === undefined ? {} : { home }),
+        ...(settings === undefined ? {} : { settings }),
+        ...(alias === undefined ? {} : { alias }),
+        seat,
+    };
+}
+function callAdmissionInput(input, execution) {
+    return {
+        archetype: input.archetype,
+        ...(input.values.schema === undefined ? { body: input.body } : {}),
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+        ...(input.readonlyRequested === undefined ? {} : { readonly: input.readonlyRequested }),
+        ...(input.values.allowed === undefined ? {} : { allowed: input.values.allowed }),
+        ...(input.values.schema === undefined ? {} : { schema: input.values.schema }),
         ...(execution === undefined ? {} : { cwd: execution.cwd }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
     };
+}
+function schemaTell(input) {
+    if (input.values.schema === undefined)
+        return undefined;
+    return {
+        body: input.body,
+        schema: input.values.schema,
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+    };
+}
+async function prepareCall(input, context) {
+    const parsed = await parseCallInput(input);
+    const execution = await resolveCallExecution({
+        path: parsed.path,
+        ...(parsed.cwd === undefined ? {} : { cwd: parsed.cwd }),
+        ...(parsed.seat === undefined ? {} : { contract: parsed.values.contract }),
+    });
+    const world = akumaWorld(parsed.path, parsed.home, parsed.settings, context);
     const { born, akuma } = await admitCall({
-        path,
+        path: parsed.path,
         world,
-        call: call,
+        call: callAdmissionInput(parsed, execution),
         context: execution === undefined ? {} : { cwdCanonical: true },
-        ...(settings === undefined ? {} : { settings }),
-        ...(seat === undefined ? {} : { contractId: seat.id }),
+        ...(parsed.settings === undefined ? {} : { settings: parsed.settings }),
+        ...(parsed.seat === undefined ? {} : { contractId: parsed.seat.id }),
     });
     const completedExecution = execution ?? born.execution;
-    const dispatch = seat === undefined
+    const dispatch = parsed.seat === undefined
         ? { kind: "none" }
-        : await dispatchStage({ repository: seat.scope, akuId: akuma, contractId: seat.id });
-    const aliasStage = await resolveAliasStage(path, alias, dispatch, akuma);
+        : await dispatchStage({ repository: parsed.seat.scope, akuId: akuma, contractId: parsed.seat.id });
+    const aliasStage = await resolveAliasStage(parsed.path, parsed.alias, dispatch, akuma);
+    const initialSchemaTell = schemaTell(parsed);
     return {
-        path,
+        path: parsed.path,
         born,
         execution: completedExecution,
-        mode,
-        timeoutMs,
+        mode: parsed.mode,
+        timeoutMs: parsed.timeoutMs,
+        ...(parsed.signal === undefined ? {} : { signal: parsed.signal }),
         dispatch,
         alias: aliasStage,
-        ...(values.schema === undefined
-            ? {}
-            : {
-                schemaTell: {
-                    body,
-                    schema: values.schema,
-                    ...(initiator === undefined ? {} : { initiator }),
-                },
-            }),
+        ...(initialSchemaTell === undefined ? {} : { schemaTell: initialSchemaTell }),
     };
 }
 async function publishCall(born, execution) {
@@ -325,31 +363,58 @@ async function publishCall(born, execution) {
     const contractId = born.dispatch.kind === "dispatched" ? born.dispatch.dispatch.contractId : undefined;
     const handle = await world.publish(born.born, {
         ...(contractId === undefined ? {} : { contractId }),
-    });
+    }, born.signal);
+    const deadline = born.mode === "wait" ? performance.now() + born.timeoutMs : undefined;
+    const remaining = () => (deadline === undefined ? born.timeoutMs : Math.max(0, deadline - performance.now()));
+    const schemaSignal = () => {
+        if (deadline === undefined)
+            return born.signal;
+        const timeout = AbortSignal.timeout(Math.ceil(remaining()));
+        return born.signal === undefined ? timeout : AbortSignal.any([born.signal, timeout]);
+    };
     const readonly = (await handle.status()).readonly;
     let schemaAnswer;
     if (born.schemaTell !== undefined) {
         const tell = born.schemaTell;
         // Birth publishes Soul before its prompt-free Body has necessarily settled.
         // Schema admission still belongs to Tell, after that initial Body is idle.
-        const pending = handle.wait().then(() => execution.channel.kind === "body-request"
-            ? requestForwardedFleetTellAnswer({
-                directory: execution.channel.directory,
-                target: handle.id,
-                body: tell.body,
-                schema: tell.schema,
-                ...(tell.initiator === undefined ? {} : { initiator: tell.initiator }),
-            })
-            : PublicAkuma.select(born.path, handle.id).tell(tell.body, {
-                schema: tell.schema,
-                ...(tell.initiator === undefined ? {} : { initiator: tell.initiator }),
-            }));
+        const pending = handle
+            .wait(undefined, {
+            timeoutMs: remaining(),
+            ...(born.signal === undefined ? {} : { signal: born.signal }),
+        })
+            .then(async (initial) => {
+            if (initial.life !== "asleep" || !defaultWaitComplete(initial) || (deadline !== undefined && remaining() <= 0))
+                return undefined;
+            const signal = schemaSignal();
+            try {
+                return execution.channel.kind === "body-request"
+                    ? await requestForwardedFleetTellAnswer({
+                        directory: execution.channel.directory,
+                        target: handle.id,
+                        body: tell.body,
+                        schema: tell.schema,
+                        ...(tell.initiator === undefined ? {} : { initiator: tell.initiator }),
+                        ...(signal === undefined ? {} : { signal }),
+                    })
+                    : await PublicAkuma.select(born.path, handle.id).tell(tell.body, {
+                        schema: tell.schema,
+                        ...(tell.initiator === undefined ? {} : { initiator: tell.initiator }),
+                        ...(signal === undefined ? {} : { signal }),
+                    });
+            }
+            catch (error) {
+                if (born.signal?.aborted || deadline === undefined || remaining() > 0)
+                    throw error;
+                return undefined;
+            }
+        });
         if (born.mode === "detach")
             void pending.catch(() => undefined);
         else
             schemaAnswer = await pending;
     }
-    const observation = await observeCall(handle, born.mode, born.timeoutMs);
+    const observation = await observeCall(handle, born.mode, remaining(), born.signal);
     return {
         kind: "called",
         akuma: handle.id,

package/build/src/library/composition.d.ts

@@ -85,7 +85,8 @@ export declare function composeLibrary(context?: ExecutionContext, composition?:
         };
     }>;
     wait: (input: Parameters<typeof waitAkuma>[0]) => Promise<{
-        completion: "any" | "all";
+        mode: "any" | "all";
+        reason: "deadline" | "completed";
         observations: {
             status: {
                 id: import("./keiyaku.js").AkuId;
@@ -238,6 +239,7 @@ export declare function composeLibrary(context?: ExecutionContext, composition?:
                         };
                     })[];
                     omitted: number;
+                    openingSequence?: number | undefined;
                 } | {
                     reportedChanges: readonly {
                         sequence: number;

package/build/src/library/fleet.d.ts

@@ -8,10 +8,12 @@ import { type AkumaKillResult, type AkumaObservation, type AkumaObservationStage
 export type AkumaWaitInput = AkumaSetAddressInput & Readonly<{
     completion?: "any" | "all";
     timeoutMs?: number;
+    signal?: AbortSignal;
 }>;
 export type AkumaTellInput = AkumaAddressInput & Readonly<{
     body: string;
     initiator?: string;
+    signal?: AbortSignal;
 }>;
 export type { TellResult, TellWake } from "../akuma/akuma.js";
 export type { CreatedTaskObservation } from "../task/created-observation.js";
@@ -20,6 +22,10 @@ export type { AkumaKillResult, AkumaObservation, AkumaObservationStage, AkumaTel
 export type AkumaInterruptInput = AkumaAddressInput & Readonly<{
     body: string;
     initiator?: string;
+    signal?: AbortSignal;
+}>;
+export type AkumaKillInput = AkumaSetAddressInput & Readonly<{
+    signal?: AbortSignal;
 }>;
 export type AkumaInterruptResult = Readonly<{
     id: AkumaStatus["id"];
@@ -60,7 +66,7 @@ export type AkumaHistoryResult = Readonly<{
 }>;
 export declare function statusAkuma(input: AkumaAddressInput): Promise<AkumaObservation>;
 export declare function waitAkuma(input: AkumaWaitInput, execution?: ExecutionContext, observer?: WaitObserver): Promise<AkumaWaitResult>;
-export declare function killAkuma(input: AkumaSetAddressInput, execution?: ExecutionContext): Promise<AkumaKillResult>;
+export declare function killAkuma(input: AkumaKillInput, execution?: ExecutionContext): Promise<AkumaKillResult>;
 export declare function tellAkuma(input: AkumaTellInput, execution?: ExecutionContext): Promise<AkumaTellResult>;
 export declare function interruptAkuma(input: AkumaInterruptInput): Promise<AkumaInterruptResult>;
 export declare function historyAkuma(input: AkumaHistoryInput): Promise<AkumaHistoryResult>;

package/build/src/library/fleet.js

@@ -115,6 +115,13 @@ function timeout(value) {
     }
     return value;
 }
+function signal(value) {
+    if (value === undefined)
+        return undefined;
+    if (!(value instanceof AbortSignal))
+        throw new TypeError("signal must be an AbortSignal");
+    return value;
+}
 async function attachWaitAssociations(path, repo, result) {
     const created = await createdTasksFor(path, result.observations.map((observation) => observation.status));
     const discharged = placementDischarged(repo);
@@ -151,7 +158,7 @@ export async function statusAkuma(input) {
 export async function waitAkuma(input, execution = localExecutionContext(), observer) {
     const values = requireInput(input, "Keiyaku.wait input");
     for (const key of Object.keys(values)) {
-        if (!["path", "akuma", "repo", "completion", "timeoutMs"].includes(key)) {
+        if (!["path", "akuma", "repo", "completion", "timeoutMs", "signal"].includes(key)) {
             throw new TypeError(`Keiyaku.wait input has unknown field: ${key}`);
         }
     }
@@ -163,21 +170,24 @@ export async function waitAkuma(input, execution = localExecutionContext(), obse
     // An omitted mode is any: a plural wait returns when any selected Akuma is complete.
     const selected = completion ?? "any";
     const timeoutMs = timeout(values.timeoutMs);
+    const callerSignal = signal(values.signal);
     const channel = executionChannel(execution);
     const repo = values.repo;
     if (channel.kind === "body-request") {
         return await attachWaitAssociations(addressed.path, repo, await requestForwardedFleetWait({
             directory: channel.directory,
-            targets: addressed.ids,
+            targets: addressed.orderedIds,
             completion: selected,
             ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            ...(callerSignal === undefined ? {} : { signal: callerSignal }),
         }));
     }
     return await attachWaitAssociations(addressed.path, repo, await executeWaitAkuma({
         path: addressed.path,
-        ids: addressed.ids,
+        ids: addressed.orderedIds,
         completion: selected,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(callerSignal === undefined ? {} : { signal: callerSignal }),
         identity: waitIdentityFacts(addressed.path, repo),
         selectionOrder: addressed.orderedIds,
         ...(observer?.selected === undefined ? {} : { onSelected: observer.selected }),
@@ -185,28 +195,38 @@ export async function waitAkuma(input, execution = localExecutionContext(), obse
     }));
 }
 export async function killAkuma(input, execution = localExecutionContext()) {
-    const addressed = await addressAkumaSet(input);
+    const values = requireInput(input, "Keiyaku.kill input");
+    for (const key of Object.keys(values)) {
+        if (!["path", "akuma", "repo", "signal"].includes(key)) {
+            throw new TypeError(`Keiyaku.kill input has unknown field: ${key}`);
+        }
+    }
+    const callerSignal = signal(values.signal);
+    const addressed = await addressAkumaSet(setAddress(values));
     const channel = executionChannel(execution);
     if (channel.kind === "body-request") {
         return await requestForwardedFleetKill({
             directory: channel.directory,
-            targets: addressed.ids,
+            targets: addressed.orderedIds,
+            ...(callerSignal === undefined ? {} : { signal: callerSignal }),
         });
     }
     return await executeKillAkuma({
         path: addressed.path,
-        ids: addressed.ids,
+        ids: addressed.orderedIds,
+        ...(callerSignal === undefined ? {} : { signal: callerSignal }),
     });
 }
 export async function tellAkuma(input, execution = localExecutionContext()) {
     const values = requireInput(input, "Keiyaku.tell input");
     for (const key of Object.keys(values)) {
-        if (!["path", "akuma", "body", "repo", "initiator"].includes(key)) {
+        if (!["path", "akuma", "body", "repo", "initiator", "signal"].includes(key)) {
             throw new TypeError(`Keiyaku.tell input has unknown field: ${key}`);
         }
     }
     if (typeof values.body !== "string")
         throw new TypeError("body must be a string");
+    const callerSignal = signal(values.signal);
     const addressed = await addressAkuma(directAddress(values));
     const channel = executionChannel(execution);
     if (channel.kind === "body-request") {
@@ -215,6 +235,7 @@ export async function tellAkuma(input, execution = localExecutionContext()) {
             target: addressed.id,
             body: values.body,
             ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+            ...(callerSignal === undefined ? {} : { signal: callerSignal }),
         });
     }
     return await executeTellAkuma({
@@ -222,20 +243,25 @@ export async function tellAkuma(input, execution = localExecutionContext()) {
         id: addressed.id,
         body: values.body,
         ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+        ...(callerSignal === undefined ? {} : { signal: callerSignal }),
     });
 }
 export async function interruptAkuma(input) {
     const values = requireInput(input, "Keiyaku.interrupt input");
     for (const key of Object.keys(values)) {
-        if (!["path", "akuma", "body", "repo", "initiator"].includes(key)) {
+        if (!["path", "akuma", "body", "repo", "initiator", "signal"].includes(key)) {
             throw new TypeError(`Keiyaku.interrupt input has unknown field: ${key}`);
         }
     }
     if (typeof values.body !== "string")
         throw new TypeError("body must be a string");
+    const callerSignal = signal(values.signal);
     const addressed = await addressAkuma(directAddress(values));
     const handle = source(addressed.path).selectHandle({ id: addressed.id });
-    const receipt = await handle.interrupt(values.body, input.initiator === undefined ? {} : { initiator: input.initiator });
+    const receipt = await handle.interrupt(values.body, {
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+        ...(callerSignal === undefined ? {} : { signal: callerSignal }),
+    });
     const observation = await observeAkumaStage(addressed.path, addressed.id, values.repo);
     return { id: addressed.id, receipt, observation };
 }

package/build/src/library/keiyaku.d.ts

@@ -117,7 +117,8 @@ export declare const Keiyaku: Readonly<{
         };
     }>;
     wait: (input: Parameters<typeof import("./fleet.js").waitAkuma>[0]) => Promise<{
-        completion: "any" | "all";
+        mode: "any" | "all";
+        reason: "deadline" | "completed";
         observations: {
             status: {
                 id: import("../akuma/identity.js").AkuId;
@@ -270,6 +271,7 @@ export declare const Keiyaku: Readonly<{
                         };
                     })[];
                     omitted: number;
+                    openingSequence?: number | undefined;
                 } | {
                     reportedChanges: readonly {
                         sequence: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "4.5.24",
+  "version": "4.5.26",
   "workspaces": [
     "plugins/*"
   ],
@@ -80,8 +80,8 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.3.0",
     "@anthropic-ai/claude-agent-sdk": "^0.3.226",
-    "@astrosheep/keiyaku-plugin-square": "0.1.5",
-    "@astrosheep/square": "^0.3.50",
+    "@astrosheep/keiyaku-plugin-square": "0.1.6",
+    "@astrosheep/square": "^0.3.57",
     "@earendil-works/pi-coding-agent": "0.85.1",
     "@opencode-ai/sdk": "1.18.3",
     "cross-spawn": "^7.0.6",