@astrosheep/keiyaku 4.5.19 → 4.5.21

package/build/src/akuma/akuma-observe.js

@@ -72,6 +72,7 @@ export async function bornStatus(paths, expected, input) {
         status: {
             id: soul.id,
             life: currentLife,
+            allowed: soul.allowed,
             ...(soul.readonly === undefined ? {} : { readonly: soul.readonly }),
             ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
             timeline: selected.snapshot,
@@ -93,6 +94,28 @@ export async function readWaitComplete(worldPath, id) {
     const observed = await bornObservation(paths, id, () => readLifeSnapshot(paths));
     return complete(observed.currentLife, observed.snapshot.hasPendingTell);
 }
+const OBSERVATION_POLL_MS = 100;
+function observeDelay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+/**
+ * Successive status observations of one already born Akuma until its
+ * observation window closes. Every status observed while the window is open is
+ * reported to `observe`; the window's last status is returned. A window that is
+ * already closed, or an Akuma already at its completion judgment, reports
+ * nothing and returns the current status.
+ */
+export async function observeAkumaStatus(worldPath, expected, input) {
+    const paths = pathsForAkuId(worldPath, expected);
+    const deadline = performance.now() + input.timeoutMs;
+    for (;;) {
+        const status = (await bornStatus(paths, expected, { aperture: "monitoring" })).status;
+        if (defaultWaitComplete(status) || performance.now() >= deadline)
+            return status;
+        input.observe(status);
+        await observeDelay(Math.min(OBSERVATION_POLL_MS, Math.max(0, deadline - performance.now())));
+    }
+}
 export async function readAkumaBirthCwd(worldPath, id) {
     const soul = await readSoul(pathsForAkuId(worldPath, id));
     if (soul === null)

package/build/src/akuma/akuma-product.d.ts

@@ -21,7 +21,9 @@ export type BornAkumaCall = Readonly<{
         };
     }>;
     initialBody?: string;
+    initiator?: string;
     initialSchemaJson?: string;
+    awaitAsleep?: true;
     execution: BornExecution;
 }>;
 export type RequestedAkumaCall = Readonly<{

package/build/src/akuma/akuma-product.js

@@ -26,6 +26,8 @@ async function admitBodyRequest(input) {
         world: input.path,
         archetype: input.name,
         ...(input.call.body === undefined ? {} : { body: input.call.body }),
+        ...(input.call.initiator === undefined ? {} : { initiator: input.call.initiator }),
+        ...(input.call.schema === undefined ? {} : { awaitAsleep: true }),
         ...(cwd === undefined ? {} : { cwd }),
         recipe: input.recipe,
     });
@@ -55,7 +57,9 @@ async function admitDirect(input) {
             origin: { kind: "direct" },
         },
         ...(input.call.body === undefined ? {} : { initialBody: input.call.body }),
+        ...(input.call.initiator === undefined ? {} : { initiator: input.call.initiator }),
         ...(input.call.schema === undefined ? {} : { initialSchemaJson: schemaJsonText(input.call.schema) }),
+        ...(input.call.schema === undefined ? {} : { awaitAsleep: true }),
         execution: {
             cwd,
             source: input.call.cwd !== undefined ? "input" : initiatorCwd === undefined ? "world" : "process",
@@ -206,10 +210,12 @@ class AkumaProduct {
         }
         const published = await launchAkuma({
             allocated: born.allocated,
+            ...(born.awaitAsleep === undefined ? {} : { awaitAsleep: born.awaitAsleep }),
             launch: async (allocated) => await spawnAkumaBody({
                 paths: allocated.paths,
                 seed: born.seed,
                 ...(born.initialBody === undefined ? {} : { initialBody: born.initialBody }),
+                ...(born.initiator === undefined ? {} : { initiator: born.initiator }),
                 ...(born.initialSchemaJson === undefined ? {} : { initialSchemaJson: born.initialSchemaJson }),
                 ...(Object.keys(completion).length === 0 ? {} : { completion }),
             }),

package/build/src/akuma/akuma.d.ts

@@ -3,7 +3,7 @@ export type { KillEvidence };
 import { type AkuId } from "./identity.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
-import type { AllowedAction } from "./allowed.js";
+import { type AllowedAction } from "./allowed.js";
 import type { ExecutionContext } from "./requests.js";
 import { z } from "zod";
 import type { BoundedList } from "../bounded-list.js";
@@ -32,6 +32,24 @@ export declare const akumaStatusSchema: z.ZodObject<{
         asleep: "asleep";
         stranded: "stranded";
     }>;
+    allowed: z.ZodPipe<z.ZodArray<z.ZodEnum<{
+        "task.add": "task.add";
+        "task.addDocument": "task.addDocument";
+        "task.compose": "task.compose";
+        "task.done": "task.done";
+        "task.drop": "task.drop";
+        "task.hold": "task.hold";
+        "task.resume": "task.resume";
+        "task.start": "task.start";
+        "task.stop": "task.stop";
+        "task.update": "task.update";
+        "akuma.call": "akuma.call";
+        "akuma.kill": "akuma.kill";
+        "akuma.tell": "akuma.tell";
+        "contract.audit": "contract.audit";
+        "contract.deliver": "contract.deliver";
+        "contract.review": "contract.review";
+    }>>, z.ZodTransform<import("./allowed.js").AllowedActions, ("task.add" | "task.addDocument" | "task.compose" | "task.done" | "task.drop" | "task.hold" | "task.resume" | "task.start" | "task.stop" | "task.update" | "akuma.call" | "akuma.kill" | "akuma.tell" | "contract.audit" | "contract.deliver" | "contract.review")[]>>;
     readonly: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         enforcement: z.ZodLiteral<"native">;
     }, z.core.$strict>, z.ZodObject<{
@@ -439,6 +457,7 @@ export type AkumaCallInput = Readonly<{
     readonly?: true;
     allowed?: readonly AllowedAction[];
     schema?: Schema<unknown>;
+    initiator?: string;
 }>;
 export type AkumaCallContext = Readonly<{
     initiatorCwd?: string;

package/build/src/akuma/akuma.js

@@ -1,5 +1,6 @@
 import { parseAkuId } from "./identity.js";
 import { activitySnapshotSchema } from "./projection.js";
+import { allowedActionsSchema } from "./allowed.js";
 import { z } from "zod";
 import { createAkumaProduct } from "./akuma-product.js";
 import { killAkumaWithRecovery } from "./akuma-handle.js";
@@ -25,6 +26,7 @@ export const akumaStatusSchema = z
     .object({
     id: akumaIdSchema,
     life: z.enum(["running", "asleep", "stranded", "hung", "untidy", "killed"]),
+    allowed: allowedActionsSchema,
     readonly: readonlySchema.optional(),
     timeline: activitySnapshotSchema,
     strandedReason: z.literal("resume-unsupported").optional(),

package/build/src/akuma/allowed.d.ts

@@ -1,8 +1,28 @@
+import { z } from "zod";
 export declare const ALLOWED_ACTIONS: readonly ["akuma.call", "akuma.kill", "akuma.tell", "contract.audit", "contract.deliver", "contract.review", "task.add", "task.addDocument", "task.compose", "task.done", "task.drop", "task.hold", "task.resume", "task.start", "task.stop", "task.update"];
 export type AllowedAction = (typeof ALLOWED_ACTIONS)[number];
 export type AllowedActions = readonly AllowedAction[];
 export declare function isAllowedAction(value: unknown): value is AllowedAction;
 export declare function decodeAllowedActions(value: unknown, label?: string): AllowedActions;
+/** Public codecs retain the Soul's canonical, duplicate-free action membership. */
+export declare const allowedActionsSchema: z.ZodPipe<z.ZodArray<z.ZodEnum<{
+    "task.add": "task.add";
+    "task.addDocument": "task.addDocument";
+    "task.compose": "task.compose";
+    "task.done": "task.done";
+    "task.drop": "task.drop";
+    "task.hold": "task.hold";
+    "task.resume": "task.resume";
+    "task.start": "task.start";
+    "task.stop": "task.stop";
+    "task.update": "task.update";
+    "akuma.call": "akuma.call";
+    "akuma.kill": "akuma.kill";
+    "akuma.tell": "akuma.tell";
+    "contract.audit": "contract.audit";
+    "contract.deliver": "contract.deliver";
+    "contract.review": "contract.review";
+}>>, z.ZodTransform<AllowedActions, ("task.add" | "task.addDocument" | "task.compose" | "task.done" | "task.drop" | "task.hold" | "task.resume" | "task.start" | "task.stop" | "task.update" | "akuma.call" | "akuma.kill" | "akuma.tell" | "contract.audit" | "contract.deliver" | "contract.review")[]>>;
 export declare function effectiveAllowedActions(value: unknown): AllowedActions;
 export declare function unionAllowedActions(base: AllowedActions, additions: AllowedActions): AllowedActions;
 export declare function clipAllowedActions(requested: AllowedActions, parent: AllowedActions): AllowedActions;

package/build/src/akuma/allowed.js

@@ -1,4 +1,5 @@
 import { TASK_MUTATION_ACTIONS } from "../task/mutation.js";
+import { z } from "zod";
 export const ALLOWED_ACTIONS = Object.freeze([
     "akuma.call",
     "akuma.kill",
@@ -25,6 +26,16 @@ export function decodeAllowedActions(value, label = "allowed") {
     }
     return Object.freeze([...seen].sort());
 }
+/** Public codecs retain the Soul's canonical, duplicate-free action membership. */
+export const allowedActionsSchema = z.array(z.enum(ALLOWED_ACTIONS)).transform((value, context) => {
+    try {
+        return decodeAllowedActions(value);
+    }
+    catch (error) {
+        context.addIssue({ code: "custom", message: error instanceof Error ? error.message : String(error) });
+        return z.NEVER;
+    }
+});
 export function effectiveAllowedActions(value) {
     return value === undefined ? ALLOWED_ACTIONS : decodeAllowedActions(value);
 }

package/build/src/akuma/archetype.js

@@ -132,6 +132,7 @@ function decodeArchetypeFields(values) {
     const effort = archetypeField(values, "effort");
     const readonly = archetypeReadonly(values);
     const network = archetypeEnum(values, "network", ["disabled", "enabled"]);
+    const sandbox = archetypeEnum(values, "sandbox", ["full-access"]);
     const description = archetypeField(values, "description");
     const allowedPresent = "allowed" in values;
     const allowed = allowedPresent ? effectiveAllowedActions(values.allowed) : undefined;
@@ -143,6 +144,7 @@ function decodeArchetypeFields(values) {
         ...(effort === undefined ? {} : { effort }),
         ...(readonly === undefined ? {} : { readonly }),
         ...(network === undefined ? {} : { network }),
+        ...(sandbox === undefined ? {} : { sandbox }),
         ...(description === undefined ? {} : { description }),
         ...(allowed === undefined ? {} : { allowed }),
         allowedPresent,
@@ -166,6 +168,7 @@ function decodeArchetype(name, path, markdown) {
             ...(fields.model === undefined ? {} : { model: fields.model }),
             ...(fields.effort === undefined ? {} : { effort: fields.effort }),
             ...(fields.network === undefined ? {} : { network: fields.network }),
+            ...(fields.sandbox === undefined ? {} : { sandbox: fields.sandbox }),
             ...(systemPrompt.length === 0
                 ? {}
                 : {

package/build/src/akuma/body.d.ts

@@ -12,6 +12,7 @@ export type BodyLaunch = Readonly<{
     seed?: Omit<Soul, "createdAt">;
     birthSession?: Omit<SessionFact, "sequence">;
     initialBody?: string;
+    initiator?: string;
     initialSchemaJson?: string;
     refuseIfHeld?: boolean;
     completion?: Readonly<{
@@ -53,16 +54,35 @@ type BodyRuntime = Readonly<{
     world: WorldRoot;
     externalCommands: Readonly<Record<string, ErasedRequestCommand>>;
 }>;
-export declare function bodyProcessInput(launch: BodyLaunch, bodyModuleUrl?: string): Promise<{
+type RuntimeEnvironment = Readonly<{
+    /** The current process executable, preferred only while it is a different live value. */
+    current?: string;
+    /** The present PATH used to resolve the recorded executable basename. */
+    path?: string | undefined;
+    exists?: (path: string) => boolean | Promise<boolean>;
+}>;
+/** One Body launch's runtime input: the runtime recorded for it and its resolution environment. */
+export type BodyLaunchRuntime = Readonly<{
+    recorded?: string;
+    environment?: RuntimeEnvironment;
+}>;
+/**
+ * Resolve the runtime executable a Body spawn will use. The path recorded for
+ * this process's birth wins while it exists. Once it is gone, wake re-resolves
+ * the runtime before any spawn can fail: the current process executable while
+ * that is a different live value, then the recorded executable basename on the
+ * present PATH. An unresolvable runtime refuses with the stale record, the
+ * failed re-resolution, and the kill-and-call-fresh remedy.
+ */
+export declare function resolveRuntimeExecutable(recorded?: string, environment?: RuntimeEnvironment): Promise<string>;
+export declare function bodyProcessInput(launch: BodyLaunch, bodyModuleUrl?: string, runtime?: BodyLaunchRuntime): Promise<{
     argv: string[];
     cwd: string;
-    env: {
-        KEIYAKU_ACTOR_ID: import("./identity.js").AkuId;
-    };
+    env: Record<string, string>;
     log: string;
 }>;
 export declare function handoffPendingTells(paths: AkumaPaths, spawn?: (launch: BodyLaunch) => Promise<OwnedProcess>): Promise<void>;
 export declare function driveAkumaBody(launch: BodyLaunch, adapter?: ProviderAdapter, runtimeInput?: Partial<BodyRuntime>): Promise<"held" | void>;
-export declare function spawnAkumaBody(launch: BodyLaunch): Promise<OwnedProcess>;
+export declare function spawnAkumaBody(launch: BodyLaunch, runtime?: BodyLaunchRuntime): Promise<OwnedProcess>;
 export declare function runAkumaBody(launch: BodyLaunch, world: WorldRoot, externalCommands: Readonly<Record<string, ErasedRequestCommand>>): Promise<"held" | void>;
 export declare function wakeRecordedTell(paths: AkumaPaths, tellId: string, runtime?: TellWakeRuntime): Promise<TellResult>;

package/build/src/akuma/body.js

@@ -1,10 +1,12 @@
-import { appendFile } from "node:fs/promises";
+import { appendFile, stat } from "node:fs/promises";
+import { basename, delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { abortableDelay } from "./abort.js";
 import { BodySupervisor } from "./body-supervisor.js";
 import { driveTurn, turnRecipe } from "./turn-drive.js";
 import { HeldAkumaLeash, breakBody, decidePendingTellDisposition, drainPendingTells, endTurn, failOpenBoundTurns, finishBodyIfIdle, heartExists, isHeartAbsent, probeLeash, projectTell, readHeart, readOpenBoundTurns, readOpenPendingTellDisposition, readTell, readTurn, readNonterminalRequests, resolvePendingTellDisposition, } from "./heart/index.js";
 import { worldRootForAkumaPaths } from "./identity.js";
+import { akumaExecutionEnvironment } from "./providers/execution-environment.js";
 import { pluginRuntime } from "../plugin/runtime.js";
 import { World } from "../world.js";
 import { resolveProviderExecution } from "./providers/index.js";
@@ -144,19 +146,71 @@ const DEFAULT_RUNTIME = {
     externalCommands: {},
     spawnBody: spawnAkumaBody,
 };
-export async function bodyProcessInput(launch, bodyModuleUrl = import.meta.url) {
+/**
+ * The runtime executable this process recorded at its birth. A package-manager
+ * upgrade can remove the file under a live process, so a wake re-resolves that
+ * record instead of surfacing a bare missing-file launch failure.
+ */
+const RECORDED_RUNTIME = process.execPath;
+async function runtimeFileExists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function runtimeCommandOnPath(command, path, exists) {
+    if (command.length === 0 || command.includes("/") || command.includes("\\"))
+        return null;
+    for (const directory of (path ?? "").split(delimiter)) {
+        if (directory.length === 0)
+            continue;
+        const candidate = join(directory, command);
+        if (await exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+class StaleRuntimeError extends Error {
+    constructor(recorded, current, command) {
+        super(`recorded Body runtime ${recorded} no longer exists and re-resolution failed: neither this process executable ` +
+            `${current} nor the command "${command}" on PATH names an existing file; kill this Akuma and call a fresh one`);
+        this.name = "StaleRuntimeError";
+    }
+}
+/**
+ * Resolve the runtime executable a Body spawn will use. The path recorded for
+ * this process's birth wins while it exists. Once it is gone, wake re-resolves
+ * the runtime before any spawn can fail: the current process executable while
+ * that is a different live value, then the recorded executable basename on the
+ * present PATH. An unresolvable runtime refuses with the stale record, the
+ * failed re-resolution, and the kill-and-call-fresh remedy.
+ */
+export async function resolveRuntimeExecutable(recorded = RECORDED_RUNTIME, environment = {}) {
+    const exists = environment.exists ?? runtimeFileExists;
+    if (await exists(recorded))
+        return recorded;
+    const current = environment.current ?? process.execPath;
+    const command = basename(recorded);
+    const reResolved = (current !== recorded && (await exists(current)) ? current : null) ??
+        (await runtimeCommandOnPath(command, environment.path ?? process.env.PATH, exists));
+    if (reResolved === null)
+        throw new StaleRuntimeError(recorded, current, command);
+    return reResolved;
+}
+export async function bodyProcessInput(launch, bodyModuleUrl = import.meta.url, runtime = {}) {
     const encoded = Buffer.from(JSON.stringify(launch), "utf8").toString("base64url");
     const actorId = launch.seed?.id ?? (await readHeart(launch.paths)).soul?.id;
     if (actorId === undefined)
         throw new Error("Akuma wake has no born soul");
+    const executable = await resolveRuntimeExecutable(runtime.recorded, runtime.environment);
     const source = bodyModuleUrl.endsWith(".ts");
     const entry = fileURLToPath(new URL(source ? "../akuma-body.ts" : "../akuma-body.js", bodyModuleUrl));
     return {
-        argv: source
-            ? [process.execPath, "--import", import.meta.resolve("tsx"), entry, encoded]
-            : [process.execPath, entry, encoded],
+        argv: source ? [executable, "--import", import.meta.resolve("tsx"), entry, encoded] : [executable, entry, encoded],
         cwd: await launchCwd(launch),
-        env: { ...process.env, KEIYAKU_ACTOR_ID: actorId },
+        env: akumaExecutionEnvironment(process.env, { KEIYAKU_ACTOR_ID: actorId }),
         log: launch.paths.log,
     };
 }
@@ -231,14 +285,13 @@ async function recoverBodyRequests(input) {
 }
 function turnOutcomeEmitter(launch, soul) {
     let plugins;
-    const pending = new Set();
     const reportDiagnostic = (message) => {
         void recordPluginDiagnostic(launch.paths, "turn outcome", message);
     };
-    const emit = (turnSequence, outcome) => {
-        let delivery;
-        delivery = (async () => {
+    return {
+        async emit(turnSequence, outcome) {
             try {
+                const initiator = (await readTurn(launch.paths, turnSequence))?.initiator;
                 plugins ??= pluginRuntime({
                     world: await World.at(worldRootForAkumaPaths(launch.paths)),
                     reportDiagnostic,
@@ -247,6 +300,7 @@ function turnOutcomeEmitter(launch, soul) {
                     kind: "akuma.turn-outcome",
                     akumaId: soul.id,
                     turnSequence,
+                    ...(initiator === undefined ? {} : { initiator }),
                     outcome: outcome.outcome === "answered"
                         ? { kind: "answered", text: outcome.answer }
                         : { kind: "failed", reason: outcome.diagnostic },
@@ -256,17 +310,8 @@ function turnOutcomeEmitter(launch, soul) {
             catch (error) {
                 await recordPluginDiagnostic(launch.paths, "turn outcome", error);
             }
-        })().finally(() => pending.delete(delivery));
-        pending.add(delivery);
-        return delivery;
+        },
     };
-    const drain = async () => {
-        while (pending.size > 0)
-            await Promise.all([...pending]);
-        if (plugins !== undefined)
-            await (await plugins).drain("akuma.turn-outcome");
-    };
-    return { emit, drain };
 }
 function bodyEndEmitter(launch, soul) {
     let plugins;
@@ -288,7 +333,6 @@ function bodyEndEmitter(launch, soul) {
                 ...(diagnostic === undefined ? {} : { diagnostic }),
                 ...(launch.completion?.contractId === undefined ? {} : { contractId: launch.completion.contractId }),
             }, reportDiagnostic);
-            await (await plugins).drain("akuma.body-ended");
         }
         catch (error) {
             await recordPluginDiagnostic(launch.paths, "body end", error);
@@ -324,6 +368,7 @@ async function runBodyTurns(input) {
             runtimeSpawn: runtime.spawnChild ?? spawnAkumaBody,
             body: initial ?? "",
             ...(initial === undefined ? {} : { call: initial }),
+            ...(launch.initiator === undefined ? {} : { initiator: launch.initiator }),
             launchTells,
             ...(schema === undefined ? {} : { schemaJson: schema }),
             world: runtime.world,
@@ -346,7 +391,7 @@ async function runBodyTurns(input) {
             return;
         }
         const outcome = await persistTurn(launch.paths, result.turnSequence, result, runtime.now());
-        void turnOutcome.emit(result.turnSequence, outcome);
+        await turnOutcome.emit(result.turnSequence, outcome);
         if (outcome.outcome === "failed") {
             await failOpenBoundTurnsIfPresent(launch.paths, bodySequence, outcome.diagnostic, runtime.now());
             await breakBody(launch.paths, { sequence: bodySequence, end: "broke-off", at: runtime.now() });
@@ -508,19 +553,13 @@ export async function driveAkumaBody(launch, adapter, runtimeInput = {}) {
             await resolveDecidedPendingTellDisposition(launch.paths, finished.decided, runtime.spawnBody ?? spawnAkumaBody);
         if (finished.notification !== undefined)
             await finished.notification;
-        void emitTurnOutcome?.drain();
     }
 }
-export async function spawnAkumaBody(launch) {
-    return await spawnDetachedProcess(await bodyProcessInput(launch));
+export async function spawnAkumaBody(launch, runtime = {}) {
+    return await spawnDetachedProcess(await bodyProcessInput(launch, import.meta.url, runtime));
 }
 export async function runAkumaBody(launch, world, externalCommands) {
-    try {
-        return await driveAkumaBody(launch, undefined, { world, externalCommands });
-    }
-    finally {
-        await (await pluginRuntime({ world })).drain();
-    }
+    return await driveAkumaBody(launch, undefined, { world, externalCommands });
 }
 const DIRECT_TELL_WAKE = {
     spawn: async (paths) => await spawnAkumaBody({ paths, refuseIfHeld: true }),

package/build/src/akuma/call-request.d.ts

@@ -19,6 +19,7 @@ declare const akumaCallRecipeSchema: z.ZodObject<{
         effort?: string;
         readonly?: true;
         network?: "disabled" | "enabled";
+        sandbox?: "full-access";
         systemPrompt?: string;
         systemPromptMode?: import("./provider-recipe.js").SystemPromptMode;
     }>, unknown>>;
@@ -28,6 +29,8 @@ declare const akumaCallPayloadSchema: z.ZodObject<{
     world: z.ZodString;
     archetype: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
     body: z.ZodOptional<z.ZodString>;
+    initiator: z.ZodOptional<z.ZodString>;
+    awaitAsleep: z.ZodOptional<z.ZodLiteral<true>>;
     cwd: z.ZodOptional<z.ZodString>;
     recipe: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
@@ -44,6 +47,7 @@ declare const akumaCallPayloadSchema: z.ZodObject<{
             effort?: string;
             readonly?: true;
             network?: "disabled" | "enabled";
+            sandbox?: "full-access";
             systemPrompt?: string;
             systemPromptMode?: import("./provider-recipe.js").SystemPromptMode;
         }>, unknown>>;
@@ -58,6 +62,7 @@ export type AkumaCallRequestChildLaunch = Readonly<{
     paths: AkumaPaths;
     seed: Omit<Soul, "createdAt">;
     initialBody?: string;
+    initiator?: string;
 }>;
 type AkumaCallRequestCapabilities = Readonly<{
     world: WorldRoot;

package/build/src/akuma/call-request.js

@@ -4,7 +4,7 @@ import { refuseRequest, reserveRequest } from "./heart/index.js";
 import { archetypeName, parseAkuId } from "./identity.js";
 import { publishAkuma } from "./publication.js";
 import { decodeProviderOptions, decodeReadonlyRestraint } from "./provider-recipe.js";
-import { decodeProviderExecution } from "./providers/index.js";
+import { decodeProviderExecution, resolveProviderExecution } from "./providers/index.js";
 import { requestBodyCommand } from "./request-rendezvous.js";
 import { eraseRequestCommand, } from "./request-wire.js";
 import { z } from "zod";
@@ -67,6 +67,8 @@ const akumaCallPayloadSchema = z
     world: absolutePathSchema,
     archetype: archetypeSchema,
     body: z.string().optional(),
+    initiator: z.string().min(1).optional(),
+    awaitAsleep: z.literal(true).optional(),
     cwd: absolutePathSchema.optional(),
     recipe: akumaCallRecipeSchema,
 })
@@ -86,17 +88,24 @@ async function executeAkumaCall(request, facts, capabilities) {
         await refuseRequest(paths, facts.id, `request world ${requestWorld} does not match ${world}`);
         throw new Error(`request world ${requestWorld} does not match ${world}`);
     }
+    const selected = await resolveProviderExecution(request.recipe.provider);
+    const admission = selected.adapter.admitOptions(request.recipe.options);
+    if (admission.kind === "refused") {
+        await refuseRequest(paths, facts.id, admission.diagnostic);
+        throw new Error(admission.diagnostic);
+    }
     const recipe = {
         ...(request.recipe.description === undefined ? {} : { description: request.recipe.description }),
         allowed: clipAllowedActions(request.recipe.allowed, parent.allowed),
-        provider: request.recipe.provider,
-        options: request.recipe.options,
-        ...(request.recipe.readonly === undefined ? {} : { readonly: request.recipe.readonly }),
+        provider: selected.execution,
+        options: admission.options,
+        ...(admission.readonly === undefined ? {} : { readonly: admission.readonly }),
     };
     const published = await publishAkuma({
         worldPath: world,
         archetype: request.archetype,
         signal: facts.signal,
+        ...(request.awaitAsleep === undefined ? {} : { awaitAsleep: request.awaitAsleep }),
         launch: async (allocated) => {
             if (!facts.admissionOpen())
                 throw new Error("body closed request admission");
@@ -111,6 +120,7 @@ async function executeAkumaCall(request, facts, capabilities) {
                     origin: { kind: "request", parent: parent.id, requestId: facts.id },
                 },
                 ...(request.body === undefined ? {} : { initialBody: request.body }),
+                ...(request.initiator === undefined ? {} : { initiator: request.initiator }),
             });
         },
     });

package/build/src/akuma/fleet-execution.d.ts

@@ -1,12 +1,39 @@
 import { type AkumaStatus } from "./akuma.js";
+import { type DispatchAssociation } from "./dispatch-association.js";
+import type { AkumaAlias } from "../identity/selector.js";
 import type { WorldRoot } from "../world.js";
 import { type AkumaKillResult, type AkumaTellResult, type AkumaWaitResult } from "./fleet-observation.js";
+export type WaitIdentityFacts = Readonly<{
+    /** The alias currently addressing this Akuma in its world, when one is bound to it. */
+    alias?: AkumaAlias;
+    /** This Akuma's Dispatch association, read from the observing repository. */
+    contract: DispatchAssociation;
+}>;
+/** One observed Akuma as a live wait viewer sees it: its status plus its identity facts. */
+export type WaitObservedAkuma = Readonly<{
+    status: AkumaStatus;
+}> & WaitIdentityFacts;
+/** One selected Akuma's frozen identity, resolved before the first observation round. */
+export type WaitSelectedAkuma = Readonly<{
+    id: AkumaStatus["id"];
+}> & WaitIdentityFacts;
+/** A live wait viewer: the frozen selected set, then every observation round. */
+export type WaitObserver = Readonly<{
+    selected?: (selected: readonly WaitSelectedAkuma[]) => void;
+    observe?: (observed: readonly WaitObservedAkuma[]) => void;
+}>;
 export type WaitExecutionInput = Readonly<{
     path: WorldRoot;
     ids: readonly AkumaStatus["id"][];
     completion: "any" | "all";
     timeoutMs?: number;
     signal?: AbortSignal;
+    /** Resolves one Akuma's identity facts; consulted once per Akuma a viewer first sees. */
+    identity?: (id: AkumaStatus["id"]) => Promise<WaitIdentityFacts>;
+    /** Reports the frozen selected set before the first round, so a viewer can fix its layout. */
+    onSelected?: (selected: readonly WaitSelectedAkuma[]) => void;
+    /** Reports every observation round to a live viewer; absent keeps the cheap completion probe. */
+    observe?: (observed: readonly WaitObservedAkuma[]) => void;
 }>;
 export declare function executeWaitAkuma(input: WaitExecutionInput): Promise<AkumaWaitResult>;
 export type TellExecutionInput = Readonly<{
@@ -15,6 +42,7 @@ export type TellExecutionInput = Readonly<{
     body: string;
     tellId?: string;
     recordedAt?: string;
+    initiator?: string;
     signal?: AbortSignal;
 }>;
 export declare function executeTellAkuma(input: TellExecutionInput): Promise<AkumaTellResult>;

package/build/src/akuma/fleet-execution.js

@@ -89,10 +89,44 @@ function delay(milliseconds, signal) {
 }
 export async function executeWaitAkuma(input) {
     const deadline = input.timeoutMs === undefined ? undefined : performance.now() + input.timeoutMs;
+    // Identity facts are read once per observed Akuma, not once per 100ms round.
+    const facts = new Map();
+    if (input.onSelected !== undefined) {
+        const selected = [];
+        for (const id of input.ids) {
+            input.signal?.throwIfAborted();
+            const known = input.identity === undefined ? undefined : await input.identity(id);
+            const resolved = known ?? { contract: NO_DISPATCH_ASSOCIATION };
+            facts.set(id, resolved);
+            selected.push({ id, ...resolved });
+        }
+        input.onSelected(selected);
+    }
+    const observeRound = async (statuses) => {
+        if (input.observe === undefined)
+            return;
+        const observed = [];
+        for (const status of statuses) {
+            input.signal?.throwIfAborted();
+            let known = facts.get(status.id);
+            if (known === undefined && input.identity !== undefined) {
+                known = await input.identity(status.id);
+                facts.set(status.id, known);
+            }
+            if (known === undefined) {
+                observed.push({ status, contract: NO_DISPATCH_ASSOCIATION });
+                continue;
+            }
+            observed.push({ status, ...known });
+        }
+        input.observe(observed);
+    };
     for (;;) {
-        if ((deadline !== undefined && performance.now() >= deadline) || (await probeWaitRound(input))) {
+        const expired = deadline !== undefined && performance.now() >= deadline;
+        if (expired || input.observe !== undefined || (await probeWaitRound(input))) {
             const round = await observeWaitRound(input.path, input.ids, input.signal);
             input.signal?.throwIfAborted();
+            await observeRound(round.statuses);
             // The probe is not a completion receipt. Judge the actual returned values.
             if (roundComplete(round, input.completion) || (deadline !== undefined && performance.now() >= deadline)) {
                 return fleetResultSchemas.wait.parse({
@@ -108,9 +142,7 @@ export async function executeWaitAkuma(input) {
 export async function executeTellAkuma(input) {
     input.signal?.throwIfAborted();
     const handle = source(input.path).selectHandle({ id: input.id });
-    const tell = input.tellId === undefined
-        ? await handle.tell(input.body)
-        : await handle.tell(input.body, input.tellId, input.recordedAt);
+    const tell = await handle.tell(input.body, input.tellId, input.recordedAt, undefined, input.initiator === undefined ? {} : { initiator: input.initiator });
     input.signal?.throwIfAborted();
     return fleetResultSchemas.tell.parse({
         akuma: input.id,