@astrosheep/keiyaku 4.5.26 → 4.5.28

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

@@ -1,14 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { handoffPendingTells, wakeRecordedTell } from "./body.js";
-import { HeldAkumaLeash, activitySlice, readForkPoint, readHeart, readKill, readLastAnsweredTurn, readSoul, recordTell, requestPause, requestStop, } from "./heart/index.js";
+import { HeldAkumaLeash, activitySlice, readForkPoint, readHeart, readKill, readLastAnsweredTurn, readSoul, readTell, readTurn, recordTell, requestPause, requestStop, projectTell, } from "./heart/index.js";
 import { acquireLeash } from "./control.js";
 import { parsePublicHistoryId, pathsForAkuId } from "./identity.js";
 import { projectTurns, selectHistory, selectExactHistory, } from "./projection.js";
 import { resolveProviderExecution } from "./providers/index.js";
 import { publishAkuma } from "./publication.js";
 import { spawnAkumaBody } from "./body.js";
-import { AkumaNotBornError } from "./akuma-errors.js";
-import { bornStatus, defaultWaitComplete, readWaitComplete, waitForObservation, } from "./akuma-observe.js";
+import { AkumaNotBornError, AkumaProviderError } from "./akuma-errors.js";
+import { bornStatus, bornLiveStatus, defaultWaitComplete, readWaitComplete, waitForObservation, } from "./akuma-observe.js";
 const CALL_EXECUTION = Symbol("akuma-call-execution");
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
@@ -151,6 +151,17 @@ export class AkumaHandle {
         return (await this.waitReceipt(predicate, options)).status;
     }
     async tell(body, tellId = randomUUID(), recordedAt = new Date().toISOString(), runtime, options = {}) {
+        const admitted = await this.admitTell(body, tellId, recordedAt, runtime, options);
+        if (admitted.kind === "not-born")
+            throw new AkumaNotBornError(this.id);
+        return await admitted.wake;
+    }
+    /**
+     * Record one Tell and start its wake without waiting for delivery. A bounded
+     * caller starts its own deadline at this admission boundary while the wake
+     * continues in the background; the unbounded public Tell awaits `wake`.
+     */
+    async admitTell(body, tellId = randomUUID(), recordedAt = new Date().toISOString(), runtime, options = {}) {
         const { schemaJson, initiator, signal } = options;
         const admitted = await recordTell(this.paths, {
             kind: "tell",
@@ -161,10 +172,69 @@ export class AkumaHandle {
             ...(schemaJson === undefined ? {} : { schemaJson }),
         });
         if (admitted.kind === "not-born")
-            throw new AkumaNotBornError(this.id);
-        return await wakeRecordedTell(this.paths, admitted.tell.id, runtime, signal);
+            return admitted;
+        return {
+            kind: "admitted",
+            tell: admitted.tell,
+            wake: wakeRecordedTell(this.paths, admitted.tell.id, runtime, signal),
+        };
+    }
+    /**
+     * The admitted Tell's receipt as it stands now. A bounded caller that stops
+     * waiting before the wake settles reports this honest instant rather than a
+     * delivery that has not happened yet.
+     */
+    async admittedReceipt(tellId) {
+        const tell = await readTell(this.paths, tellId);
+        if (tell === null)
+            throw new AkumaProviderError(`recorded Tell ${tellId} is missing from Heart`);
+        const latestBody = (await readHeart(this.paths)).latestBody;
+        return {
+            admission: { tellId, fact: "recorded" },
+            row: projectTell(tell),
+            wake: tell.state === "told" || tell.binding !== undefined
+                ? { kind: "told" }
+                : latestBody !== null && latestBody.end === undefined && latestBody.hung === undefined
+                    ? { kind: "pursuing", bodySequence: latestBody.sequence }
+                    : { kind: "held" },
+        };
+    }
+    /** Observe the exact admitted Tell's bound Turn without substituting Akuma-wide idleness. */
+    async tellOutcome(tellId, options = {}) {
+        const waited = await waitForObservation({
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            observe: async () => {
+                const tell = await readTell(this.paths, tellId);
+                if (tell === null)
+                    throw new AkumaProviderError(`recorded Tell ${tellId} is missing from Heart`);
+                const outcome = await this.boundTellOutcome(tell);
+                if (options.observe !== undefined) {
+                    await options.observe(await bornLiveStatus(this.paths, this.id, { aperture: "monitoring", admittedTellId: tellId }));
+                }
+                return { outcome, terminalWithoutTurn: tell.state === "told" && tell.binding === undefined };
+            },
+            complete: (observed) => observed.outcome !== null || observed.terminalWithoutTurn,
+        });
+        return { reason: waited.reason, outcome: waited.value.outcome };
+    }
+    async boundTellOutcome(tell) {
+        if (tell.binding === undefined)
+            return null;
+        const turn = await readTurn(this.paths, tell.binding.turnSequence);
+        return turn?.end?.outcome ?? null;
     }
     async interrupt(body, options = {}) {
+        const admitted = await this.admitInterrupt(body, options);
+        if (admitted.kind === "unavailable")
+            return admitted;
+        return { kind: "interrupted", putDown: admitted.putDown, tell: await admitted.wake };
+    }
+    /**
+     * Settle the predecessor and record the interrupt Tell, returning at the
+     * admission boundary so a bounded caller owns the wake wait.
+     */
+    async admitInterrupt(body, options = {}) {
         const request = await requestPause(this.paths, new Date().toISOString(), options.signal);
         if (request.kind === "not-born") {
             throw new AkumaNotBornError(this.id);
@@ -204,15 +274,16 @@ export class AkumaHandle {
             });
             if (admitted.kind === "not-born")
                 throw new AkumaNotBornError(this.id);
-            recorded = { kind: "recorded", tellId: admitted.tell.id };
+            recorded = admitted.tell;
         }
         finally {
             leash.release();
         }
         return {
-            kind: "interrupted",
+            kind: "admitted",
+            tell: recorded,
             putDown,
-            tell: await wakeRecordedTell(this.paths, recorded.tellId, options.runtime, options.signal),
+            wake: wakeRecordedTell(this.paths, recorded.id, options.runtime, options.signal),
         };
     }
     async fork(input) {

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

@@ -6,7 +6,7 @@ import { AkumaDecodeError, AkumaProviderError } from "./akuma-errors.js";
 import { AkumaHandle } from "./akuma-handle.js";
 import { bornStatus, defaultWaitComplete, waitForObservation } from "./akuma-observe.js";
 import { loadArchetype } from "./archetype.js";
-import { activitySlice, readTell, readTurn } from "./heart/index.js";
+import { activitySlice } from "./heart/index.js";
 import { parseAkuId, pathsForAkuId } from "./identity.js";
 import { birthAkuma, launchAkuma } from "./publication.js";
 import { projectTurns, selectHistory } from "./projection.js";
@@ -72,26 +72,10 @@ function outcomeError(outcome) {
         throw new AkumaProviderError(outcome.diagnostic);
     throw new AkumaProviderError("Akuma answered without a value");
 }
-async function boundOutcome(paths, tell) {
-    if (tell.binding === undefined)
-        return null;
-    const turn = await readTurn(paths, tell.binding.turnSequence);
-    return turn?.end?.outcome ?? null;
-}
-async function awaitTellOutcome(paths, tellId, signal) {
-    const waited = await waitForObservation({
-        ...(signal === undefined ? {} : { signal }),
-        observe: async () => {
-            const tell = await readTell(paths, tellId);
-            if (tell === null)
-                throw new AkumaProviderError(`recorded Tell ${tellId} is missing from Heart`);
-            const outcome = await boundOutcome(paths, tell);
-            return { outcome, terminalWithoutTurn: tell.state === "told" && tell.binding === undefined };
-        },
-        complete: (observed) => observed.outcome !== null || observed.terminalWithoutTurn,
-    });
-    if (waited.value.outcome !== null)
-        return waited.value.outcome;
+async function awaitTellOutcome(handle, tellId, signal) {
+    const observed = await handle.tellOutcome(tellId, signal === undefined ? {} : { signal });
+    if (observed.outcome !== null)
+        return observed.outcome;
     throw new AkumaProviderError(`recorded Tell ${tellId} reached a terminal delivery without a Turn binding`);
 }
 export class Akuma {
@@ -172,7 +156,7 @@ export class Akuma {
                 ...(schemaOptions.initiator === undefined ? {} : { initiator: schemaOptions.initiator }),
                 ...(signal === undefined ? {} : { signal }),
             });
-        const outcome = await awaitTellOutcome(this.paths, recorded.tellId, signal);
+        const outcome = await awaitTellOutcome(new AkumaHandle(this.id, this.root), recorded.tellId, signal);
         if (outcome.kind !== "answered")
             outcomeError(outcome);
         if (schema === undefined)

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

@@ -15,6 +15,12 @@ export type BudgetedStatusObservation = Readonly<{
 export type LiveStatusObservation = BudgetedStatusObservation & Readonly<{
     rows: readonly ActivityRow[];
 }>;
+/** Internal live companion for an observation loop; it is not a public result. */
+export declare function bornLiveStatus(paths: AkumaPaths, expected: AkuId, input: Readonly<{
+    aperture: "monitoring" | "receipt";
+    ordinaryBudget?: number;
+    admittedTellId?: string;
+}>): Promise<LiveStatusObservation>;
 export declare function bornStatus(paths: AkumaPaths, expected: AkuId, input: Readonly<{
     aperture: "monitoring" | "receipt";
     ordinaryBudget?: number;

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

@@ -56,7 +56,8 @@ async function bornObservation(paths, expected, read, snapshot) {
         claim?.release();
     }
 }
-async function bornLiveStatus(paths, expected, input) {
+/** Internal live companion for an observation loop; it is not a public result. */
+export async function bornLiveStatus(paths, expected, input) {
     if (input.ordinaryBudget !== undefined && (!Number.isSafeInteger(input.ordinaryBudget) || input.ordinaryBudget < 0))
         throw new TypeError("ordinary budget must be a nonnegative safe integer");
     const { snapshot, soul, currentLife } = await bornObservation(paths, expected, () => readLifeSnapshot(paths));
@@ -74,6 +75,7 @@ async function bornLiveStatus(paths, expected, input) {
         status: {
             id: soul.id,
             life: currentLife,
+            cwd: soul.cwd,
             allowed: soul.allowed,
             ...(soul.readonly === undefined ? {} : { readonly: soul.readonly }),
             ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),

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

@@ -1,3 +1,22 @@
 import { type AkuId } from "./identity.js";
 import type { WorldRoot } from "../world.js";
-export declare function probeBornAkuma(worldPath: WorldRoot, id: AkuId): Promise<boolean>;
+/**
+ * How one Akuma coordinate stands in a World, decided in the single place that
+ * reads a Heart for addressing. Absence and unreadability are different facts,
+ * and each consumer below maps them to its own caller terms.
+ */
+export type AkumaAddressability = Readonly<{
+    kind: "born";
+}> | Readonly<{
+    kind: "absent";
+}> | Readonly<{
+    kind: "unreadable";
+    reason: string;
+}>;
+export declare function akumaAddressability(worldPath: WorldRoot, id: AkuId): Promise<AkumaAddressability>;
+/**
+ * The one normalization of addressability into caller terms: an Akuma whose
+ * Heart is absent was never born, and one whose Heart cannot be read is an
+ * observation failure that keeps its reason with the identity.
+ */
+export declare function requireBornAkuma(worldPath: WorldRoot, id: AkuId): Promise<void>;

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

@@ -1,6 +1,23 @@
+import { AkumaNotBornError, AkumaObservationError } from "./akuma-errors.js";
 import { readSoul } from "./heart/index.js";
 import { pathsForAkuId } from "./identity.js";
-export async function probeBornAkuma(worldPath, id) {
-    const soul = await readSoul(pathsForAkuId(worldPath, id));
-    return soul !== null;
+export async function akumaAddressability(worldPath, id) {
+    try {
+        return (await readSoul(pathsForAkuId(worldPath, id))) === null ? { kind: "absent" } : { kind: "born" };
+    }
+    catch (error) {
+        return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * The one normalization of addressability into caller terms: an Akuma whose
+ * Heart is absent was never born, and one whose Heart cannot be read is an
+ * observation failure that keeps its reason with the identity.
+ */
+export async function requireBornAkuma(worldPath, id) {
+    const addressability = await akumaAddressability(worldPath, id);
+    if (addressability.kind === "absent")
+        throw new AkumaNotBornError(id);
+    if (addressability.kind === "unreadable")
+        throw new AkumaObservationError(id, addressability.reason);
 }

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

@@ -32,6 +32,7 @@ export declare const akumaStatusSchema: z.ZodObject<{
         asleep: "asleep";
         stranded: "stranded";
     }>;
+    cwd: z.ZodOptional<z.ZodString>;
     allowed: z.ZodPipe<z.ZodArray<z.ZodEnum<{
         "task.add": "task.add";
         "task.addDocument": "task.addDocument";
@@ -207,6 +208,10 @@ export declare const akumaStatusSchema: z.ZodObject<{
                 }, z.core.$strict>, z.ZodObject<{
                     kind: z.ZodLiteral<"other">;
                     display: z.ZodString;
+                    input: z.ZodOptional<z.ZodObject<{
+                        json: z.ZodString;
+                        truncated: z.ZodBoolean;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>]>;
                 state: z.ZodLiteral<"active">;
                 truncated: z.ZodOptional<z.ZodLiteral<true>>;
@@ -254,6 +259,10 @@ export declare const akumaStatusSchema: z.ZodObject<{
                 }, z.core.$strict>, z.ZodObject<{
                     kind: z.ZodLiteral<"other">;
                     display: z.ZodString;
+                    input: z.ZodOptional<z.ZodObject<{
+                        json: z.ZodString;
+                        truncated: z.ZodBoolean;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>]>;
                 state: z.ZodObject<{
                     status: z.ZodEnum<{
@@ -409,6 +418,10 @@ export declare const akumaStatusSchema: z.ZodObject<{
                 }, z.core.$strict>, z.ZodObject<{
                     kind: z.ZodLiteral<"other">;
                     display: z.ZodString;
+                    input: z.ZodOptional<z.ZodObject<{
+                        json: z.ZodString;
+                        truncated: z.ZodBoolean;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>]>;
                 state: z.ZodObject<{
                     status: z.ZodEnum<{

package/build/src/akuma/akuma.js

@@ -26,6 +26,7 @@ export const akumaStatusSchema = z
     .object({
     id: akumaIdSchema,
     life: z.enum(["running", "asleep", "stranded", "hung", "untidy", "killed"]),
+    cwd: z.string().optional(),
     allowed: allowedActionsSchema,
     readonly: readonlySchema.optional(),
     timeline: activitySnapshotSchema,

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

@@ -2,6 +2,7 @@ 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 const DEFAULT_ALLOWED_ACTIONS: AllowedActions;
 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. */
@@ -23,6 +24,6 @@ export declare const allowedActionsSchema: z.ZodPipe<z.ZodArray<z.ZodEnum<{
     "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 historicalAllowedActions(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,14 +1,19 @@
 import { TASK_MUTATION_ACTIONS } from "../task/mutation.js";
 import { z } from "zod";
+const AKUMA_MUTATION_ACTIONS = Object.freeze(["akuma.call", "akuma.kill", "akuma.tell"]);
 export const ALLOWED_ACTIONS = Object.freeze([
-    "akuma.call",
-    "akuma.kill",
-    "akuma.tell",
+    ...AKUMA_MUTATION_ACTIONS,
     "contract.audit",
     "contract.deliver",
     "contract.review",
     ...TASK_MUTATION_ACTIONS,
 ]);
+export const DEFAULT_ALLOWED_ACTIONS = Object.freeze([
+    ...AKUMA_MUTATION_ACTIONS,
+    "contract.audit",
+    "contract.deliver",
+    ...TASK_MUTATION_ACTIONS,
+]);
 const ALLOWED_ACTION_SET = new Set(ALLOWED_ACTIONS);
 export function isAllowedAction(value) {
     return typeof value === "string" && ALLOWED_ACTION_SET.has(value);
@@ -36,7 +41,7 @@ export const allowedActionsSchema = z.array(z.enum(ALLOWED_ACTIONS)).transform((
         return z.NEVER;
     }
 });
-export function effectiveAllowedActions(value) {
+export function historicalAllowedActions(value) {
     return value === undefined ? ALLOWED_ACTIONS : decodeAllowedActions(value);
 }
 export function unionAllowedActions(base, additions) {

package/build/src/akuma/archetype.js

@@ -5,7 +5,7 @@ import { parseDocument } from "yaml";
 import { archetypeName } from "./identity.js";
 import { decodeProviderOptions, decodeProviderRecipe, } from "./provider-recipe.js";
 import { resolveProviderExecution } from "./providers/index.js";
-import { effectiveAllowedActions } from "./allowed.js";
+import { DEFAULT_ALLOWED_ACTIONS, decodeAllowedActions } from "./allowed.js";
 export class AkumaArchetypeError extends Error {
     archetype;
     searched;
@@ -135,7 +135,7 @@ function decodeArchetypeFields(values) {
     const sandbox = archetypeEnum(values, "sandbox", ["full-access"]);
     const description = archetypeField(values, "description");
     const allowedPresent = "allowed" in values;
-    const allowed = allowedPresent ? effectiveAllowedActions(values.allowed) : undefined;
+    const allowed = allowedPresent ? decodeAllowedActions(values.allowed) : undefined;
     const systemPromptMode = archetypeEnum(values, "systemPromptMode", ["append", "replace"]);
     return {
         ...(base === undefined ? {} : { base }),
@@ -186,7 +186,7 @@ function mergeArchetype(base, local) {
     if (provider === undefined)
         throw new TypeError("Akuma provider must be a nonblank string");
     const options = decodeProviderOptions({ ...(base?.options ?? {}), ...local.options });
-    const allowed = local.allowedPresent ? local.allowed : (base?.allowed ?? effectiveAllowedActions(undefined));
+    const allowed = local.allowedPresent ? local.allowed : (base?.allowed ?? DEFAULT_ALLOWED_ACTIONS);
     return Object.freeze({
         name: local.name,
         path: local.path,

package/build/src/akuma/body.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { abortable, 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 { HeldAkumaLeash, breakBody, decidePendingTellDisposition, drainPendingTells, endTurn, failOpenBoundTurns, finishBodyIfIdle, heartExists, isHeartAbsent, probeLeash, projectTell, readHeart, readLatestTurnForBody, 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";
@@ -291,7 +291,9 @@ function turnOutcomeEmitter(launch, soul) {
     return {
         async emit(turnSequence, outcome) {
             try {
-                const initiator = (await readTurn(launch.paths, turnSequence))?.initiator;
+                const turn = await readTurn(launch.paths, turnSequence);
+                if (turn === null)
+                    throw new Error(`Committed Turn ${turnSequence} is missing from Heart`);
                 plugins ??= pluginRuntime({
                     world: await World.at(worldRootForAkumaPaths(launch.paths)),
                     reportDiagnostic,
@@ -299,8 +301,9 @@ function turnOutcomeEmitter(launch, soul) {
                 await (await plugins).emit({
                     kind: "akuma.turn-outcome",
                     akumaId: soul.id,
+                    bodySequence: turn.bodySequence,
                     turnSequence,
-                    ...(initiator === undefined ? {} : { initiator }),
+                    ...(turn.initiator === undefined ? {} : { initiator: turn.initiator }),
                     outcome: outcome.outcome === "answered"
                         ? { kind: "answered", text: outcome.answer }
                         : { kind: "failed", reason: outcome.diagnostic },
@@ -320,6 +323,7 @@ function bodyEndEmitter(launch, soul) {
     };
     return (bodySequence, end, diagnostic) => (async () => {
         try {
+            const initiator = (await readLatestTurnForBody(launch.paths, bodySequence))?.initiator;
             plugins ??= pluginRuntime({
                 world: await World.at(worldRootForAkumaPaths(launch.paths)),
                 reportDiagnostic,
@@ -330,6 +334,7 @@ function bodyEndEmitter(launch, soul) {
                 akumaId: soul.id,
                 bodySequence,
                 end,
+                ...(initiator === undefined ? {} : { initiator }),
                 ...(diagnostic === undefined ? {} : { diagnostic }),
                 ...(launch.completion?.contractId === undefined ? {} : { contractId: launch.completion.contractId }),
             }, reportDiagnostic);

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

@@ -1,9 +1,10 @@
-import { type AkumaStatus } from "./akuma.js";
+import { type AkumaStatus, type TellResult } from "./akuma.js";
+import { type LiveStatusObservation } from "./akuma-observe.js";
 import type { ActivityRow } from "./projection.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";
+import { type AkumaKillResult, type AkumaTellResult, type AkumaTellWaitResult, 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;
@@ -40,6 +41,10 @@ export type WaitExecutionInput = Readonly<{
     observe?: (observed: readonly WaitObservedAkuma[]) => void;
 }>;
 export declare function executeWaitAkuma(input: WaitExecutionInput): Promise<AkumaWaitResult>;
+export type TellWaitObserver = Readonly<{
+    admitted?: (tell: TellResult, id: AkumaStatus["id"]) => void | Promise<void>;
+    observe?: (observation: LiveStatusObservation) => void | Promise<void>;
+}>;
 export type TellExecutionInput = Readonly<{
     path: WorldRoot;
     id: AkumaStatus["id"];
@@ -48,8 +53,14 @@ export type TellExecutionInput = Readonly<{
     recordedAt?: string;
     initiator?: string;
     signal?: AbortSignal;
+    onObserve?: TellWaitObserver;
 }>;
 export declare function executeTellAkuma(input: TellExecutionInput): Promise<AkumaTellResult>;
+export declare function executeTellWaitAkuma(input: TellExecutionInput & Readonly<{
+    timeoutMs: number;
+    schemaJson?: string;
+    interrupt?: boolean;
+}>): Promise<AkumaTellWaitResult>;
 export type KillExecutionInput = Readonly<{
     path: WorldRoot;
     ids: readonly AkumaStatus["id"][];

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

@@ -1,3 +1,4 @@
+import { AkumaDecodeError, AkumaProviderError } from "./akuma-errors.js";
 import { AkumaNotBornError, defaultWaitComplete } from "./akuma.js";
 import { createAkumaProduct } from "./akuma-product.js";
 import { readLiveStatus, waitForObservation } from "./akuma-observe.js";
@@ -125,6 +126,50 @@ export async function executeTellAkuma(input) {
         tell,
     });
 }
+function tellWaitObservation(observed) {
+    if (observed.outcome === null)
+        return observed.reason === "deadline" ? { reason: "deadline" } : { reason: "unanswered" };
+    if (observed.outcome.kind === "answered")
+        return { reason: "answered", answer: observed.outcome.answerJson ?? observed.outcome.answer };
+    if (observed.outcome.kind === "failed")
+        return { reason: "failed", diagnostic: observed.outcome.diagnostic };
+    throw new AkumaDecodeError(observed.outcome.diagnostic, observed.outcome.answer);
+}
+export async function executeTellWaitAkuma(input) {
+    input.signal?.throwIfAborted();
+    const handle = source(input.path).selectHandle({ id: input.id });
+    const admission = input.interrupt === true
+        ? await handle.admitInterrupt(input.body, {
+            ...(input.tellId === undefined ? {} : { tellId: input.tellId }),
+            ...(input.schemaJson === undefined ? {} : { schemaJson: input.schemaJson }),
+            ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        })
+        : await handle.admitTell(input.body, input.tellId, input.recordedAt, undefined, {
+            ...(input.schemaJson === undefined ? {} : { schemaJson: input.schemaJson }),
+            ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+    if (admission.kind === "unavailable")
+        throw new AkumaProviderError(`Tell interrupt unavailable: ${admission.evidence}`);
+    if (admission.kind === "not-born")
+        throw new AkumaNotBornError(input.id);
+    await input.onObserve?.admitted?.(await handle.admittedReceipt(admission.tell.id), input.id);
+    // The wake runs behind the window; a settled wake is preferred, otherwise the
+    // receipt reports the admitted Tell as it stands when the window closes.
+    let settled;
+    void admission.wake.then((receipt) => {
+        settled = receipt;
+    }, () => undefined);
+    const observed = await handle.tellOutcome(admission.tell.id, {
+        timeoutMs: input.timeoutMs,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        ...(input.onObserve?.observe === undefined ? {} : { observe: input.onObserve.observe }),
+    });
+    const observation = tellWaitObservation(observed);
+    const tell = settled ?? (await handle.admittedReceipt(admission.tell.id));
+    return fleetResultSchemas.tellWait.parse({ akuma: input.id, tell, observation });
+}
 export async function executeKillAkuma(input) {
     input.signal?.throwIfAborted();
     const handles = input.ids.map((id) => source(input.path).selectHandle({ id }));