@astrosheep/keiyaku 4.6.13 → 4.6.15

package/build/src/plugin/runtime.js

@@ -216,8 +216,10 @@ function isSignalKind(kind) {
 function handlers(pluginId, instance) {
     if (!object(instance))
         throw new TypeError("plugin activation must return an object");
-    if (Object.keys(instance).some((name) => name !== "signals"))
+    if (Object.keys(instance).some((name) => name !== "signals" && name !== "waitDeferral"))
         throw new TypeError("plugin instance has unknown fields");
+    if (instance.waitDeferral !== undefined && typeof instance.waitDeferral !== "function")
+        throw new TypeError("plugin waitDeferral must be a function");
     if (instance.signals === undefined)
         return [];
     if (!object(instance.signals))
@@ -283,11 +285,11 @@ async function activate(input) {
     catch (error) {
         markStarted();
         reportPluginDiagnostic(report, selected.id, "import", error);
-        return [];
+        return { handlers: [] };
     }
     if (cancellation.aborted) {
         markStarted();
-        return [];
+        return { handlers: [] };
     }
     let candidate;
     try {
@@ -301,7 +303,7 @@ async function activate(input) {
     catch (error) {
         markStarted();
         reportPluginDiagnostic(report, selected.id, "validation", error);
-        return [];
+        return { handlers: [] };
     }
     let context;
     try {
@@ -320,24 +322,27 @@ async function activate(input) {
     catch (error) {
         markStarted();
         reportPluginDiagnostic(report, selected.id, "validation", error);
-        return [];
+        return { handlers: [] };
     }
     if (cancellation.aborted) {
         markStarted();
-        return [];
+        return { handlers: [] };
     }
     markStarted();
     try {
         const instance = await candidate.activate(context, cancellation);
         if (cancellation.aborted)
-            return [];
+            return { handlers: [] };
         const registered = handlers(candidate.manifest.id, instance);
         activated.add(candidate.manifest.id);
-        return registered;
+        return {
+            handlers: registered,
+            ...(instance.waitDeferral === undefined ? {} : { waitDeferral: instance.waitDeferral.bind(instance) }),
+        };
     }
     catch (error) {
         reportPluginDiagnostic(report, selected.id, "activation", error);
-        return [];
+        return { handlers: [] };
     }
 }
 async function deliver(entry, signal, reportDiagnostic, timeoutMs) {
@@ -347,6 +352,60 @@ async function deliver(entry, signal, reportDiagnostic, timeoutMs) {
     if (result.kind === "failed")
         reportPluginDiagnostic(reportDiagnostic, entry.pluginId, "signal", result.error);
 }
+async function closeWaitDeferral(pluginId, scope, reportDiagnostic) {
+    const result = await boundedAttempt((cancellation) => scope.close(cancellation));
+    if (result.kind === "timed-out")
+        reportPluginDiagnostic(reportDiagnostic, pluginId, "wait deferral cleanup", timeoutError());
+    if (result.kind === "failed")
+        reportPluginDiagnostic(reportDiagnostic, pluginId, "wait deferral cleanup", result.error);
+}
+async function acquireWaitDeferral({ pluginId, activation }, input, signal, deadline, reportDiagnostic) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    const cancellation = controller.signal;
+    const timer = setTimeout(() => controller.abort(timeoutError()), Math.max(0, deadline - performance.now()));
+    const completed = activation
+        .then(async (activated) => {
+        if (cancellation.aborted)
+            return undefined;
+        const value = await activated.waitDeferral?.(input, cancellation);
+        return value === undefined ? undefined : waitDeferralResource(value, pluginId, reportDiagnostic);
+    })
+        .catch((error) => {
+        if (!cancellation.aborted)
+            reportPluginDiagnostic(reportDiagnostic, pluginId, "wait deferral", error);
+        return undefined;
+    });
+    const result = await settleBefore(completed, cancellation);
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", abort);
+    if (result !== ABORTED)
+        return result;
+    if (signal?.aborted !== true)
+        reportPluginDiagnostic(reportDiagnostic, pluginId, "wait deferral", timeoutError());
+    void completed.then(async (scope) => {
+        if (scope !== undefined)
+            await closeWaitDeferral(pluginId, scope, reportDiagnostic);
+    });
+    return undefined;
+}
+function waitDeferralResource(value, pluginId, reportDiagnostic) {
+    try {
+        const close = object(value) ? value.close : undefined;
+        if (typeof close !== "function")
+            throw new TypeError("resource close must be a function");
+        // Normal and late acquisition have disjoint cleanup paths; the plugin owns its close lifetime.
+        return { close: close.bind(value) };
+    }
+    catch (error) {
+        reportPluginDiagnostic(reportDiagnostic, pluginId, "wait deferral validation", error);
+        return undefined;
+    }
+}
 export async function pluginRuntime(input) {
     let runtime = PROCESS_RUNTIMES.get(input.world);
     if (runtime === undefined) {
@@ -369,12 +428,12 @@ async function createPluginRuntime(input) {
             const result = await boundedAttempt((cancellation) => activate({ selected: entry, world: input.world, activated, report, cancellation, onStarted: releaseStarted }));
             releaseStarted();
             if (result.kind === "settled")
-                return { handlers: result.value, timedOut: false };
+                return { ...result.value, timedOut: false };
             reportPluginDiagnostic(report, entry.id, "activation", result.kind === "failed" ? result.error : timeoutError());
             return { handlers: [], timedOut: result.kind === "timed-out" };
         });
         previousStarted = started;
-        return activation;
+        return { pluginId: entry.id, activation };
     });
     return Object.freeze({
         async emit(signal, reportDiagnostic = report) {
@@ -382,10 +441,10 @@ async function createPluginRuntime(input) {
             const expiry = new AbortController();
             const timer = setTimeout(() => expiry.abort(), PLUGIN_ATTEMPT_TIMEOUT_MS);
             try {
-                await Promise.all(activations.map(async (activation, index) => {
+                await Promise.all(activations.map(async ({ pluginId, activation }) => {
                     const activated = await settleBefore(activation, expiry.signal);
                     if (activated === ABORTED || activated.timedOut) {
-                        reportPluginDiagnostic(reportDiagnostic, selected[index].id, "signal", timeoutError());
+                        reportPluginDiagnostic(reportDiagnostic, pluginId, "signal", timeoutError());
                         if (activated === ABORTED)
                             return;
                     }
@@ -398,5 +457,18 @@ async function createPluginRuntime(input) {
                 clearTimeout(timer);
             }
         },
+        async withWaitDeferrals(akumaIds, signal, action, reportDiagnostic = report) {
+            signal?.throwIfAborted();
+            const input = Object.freeze({ akumaIds: Object.freeze([...akumaIds]) });
+            const deadline = performance.now() + PLUGIN_ATTEMPT_TIMEOUT_MS;
+            const scopes = await Promise.all(activations.map((plugin) => acquireWaitDeferral(plugin, input, signal, deadline, reportDiagnostic)));
+            try {
+                signal?.throwIfAborted();
+                return await action();
+            }
+            finally {
+                await Promise.all(scopes.map((scope, index) => scope === undefined ? undefined : closeWaitDeferral(activations[index].pluginId, scope, reportDiagnostic)));
+            }
+        },
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "4.6.13",
+  "version": "4.6.15",
   "workspaces": [
     "plugins/square",
     "plugins/paseo/forwarder"
@@ -81,8 +81,8 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.3.0",
     "@anthropic-ai/claude-agent-sdk": "^0.3.226",
-    "@astrosheep/keiyaku-plugin-square": "0.1.10",
-    "@astrosheep/square": "^0.3.81",
+    "@astrosheep/keiyaku-plugin-square": "0.1.11",
+    "@astrosheep/square": "^0.3.91",
     "@getpaseo/client": "0.11.2",
     "@getpaseo/protocol": "0.11.2",
     "@opencode/client": "2.0.20",

package/skills/keiyaku/SKILL.md

@@ -36,6 +36,9 @@ selects the Contract repository; it never retargets that World. `call
 cwd). Without it, the call uses the invocation cwd; `--contract` associates a
 Contract without selecting an execution directory.
 
+An Akuma caller can find its own delegation tree with `keiyaku ls --mine` (or an
+explicit `--caller`); see `keiyaku-akuma` for the roster and its text labels.
+
 `deliver` and `review` may take time after their leading admission.
 `deliver --dry-run` only observes the prospective candidate, standing evidence,
 and target followability; it never runs Verification or hooks or admits work.

package/skills/keiyaku-akuma/SKILL.md

@@ -87,16 +87,36 @@ keiyaku status
 keiyaku status @reviewer
 keiyaku ls aku/
 keiyaku ls "aku/*/*"
+keiyaku ls --mine
 keiyaku history @reviewer --last
 keiyaku history @reviewer --id turn/3
 ```
 
 `status` shows the roster or one Akuma's workdir and effective actions.
 `ls aku/` shows callable names; `ls "aku/*/*"` shows born workers.
+`ls --mine` narrows that roster to Akumas this process's caller called and their
+transitive descendants in this World; `--caller <integration>:<id>` or
+`--caller aku/<name>/<suffix>` names the same selection explicitly. Descendant
+rows show their immediate caller as `· by <akuId>`. The selection is World-local
+and refuses for Contract, Debt, and Akuma-name catalogues.
 `history --last` reads the latest complete answer; `history --id` reads an
 exact result named by status or wait. Use the complete AkuId when an alias may
 move; see `history --help` for paging.
 
+## Retention
+
+An Akuma whose latest durable life or activity is older than fifteen days may be
+retired after a later successful `call` or `fork`. Retention keeps any running
+Akuma, any current alias target, any Akuma dispatched to a Contract that is not
+yet `claimed` or `abandoned`, unborn or stillborn allocations, and unreadable
+entries. It removes only the Akuma's recognized runtime custody; it never kills
+a worker and never rewrites another Akuma, Contract, Debt, or alias. Its final
+Heart re-read keeps a pending Tell it observes; a Tell admitted immediately
+after that read is best-effort, not atomic. There is no timer and no prune
+command. Observation and Tell commands (`status`, `ls`, `history`, `wait`,
+`tell`, `ask`) never trigger retention; without a later successful
+`call`/`fork`, old entries simply remain.
+
 ## Stop and branch
 
 ```bash