@bastani/atomic 0.9.19-alpha.1 → 0.9.19-alpha.11

package/dist/core/tasks/supervisor.js

@@ -0,0 +1,942 @@
+import { AsyncResource } from "node:async_hooks";
+import { createModuleRequire } from "../../utils/module-require.js";
+import { COMMAND_FOREGROUND_BUDGET_MS } from "./command-output.js";
+export const DEFAULT_AGENT_WAIT_BUDGET_MS = 30000;
+/** These objects are live authority, not DTOs, restart tokens or model arguments. */
+class Capability {
+    #live = true;
+    toJSON() {
+        throw new TypeError(`Task capability is not serializable (${this.#live ? "live" : "closed"})`);
+    }
+}
+class HostCapability extends Capability {
+    constructor() {
+        super(...arguments);
+        this.kind = "host";
+    }
+}
+class OwnerCapability extends Capability {
+    constructor() {
+        super(...arguments);
+        this.kind = "owner";
+    }
+}
+class TaskCapability extends Capability {
+    constructor() {
+        super(...arguments);
+        this.kind = "task";
+    }
+}
+class WaitCapability extends Capability {
+    constructor() {
+        super(...arguments);
+        this.kind = "wait";
+    }
+}
+class SubscriptionCapability extends Capability {
+    constructor() {
+        super(...arguments);
+        this.kind = "subscription";
+    }
+}
+class StdinCapability extends Capability {
+    constructor() {
+        super(...arguments);
+        this.kind = "stdin";
+    }
+}
+// Native supervisors share one actor per environment; their JS continuations must too.
+const environment = {
+    hosts: new WeakMap(),
+    owners: new WeakMap(),
+    tasks: new WeakMap(),
+    inputs: new WeakMap(),
+    waits: new WeakMap(),
+    waitRegistry: new Map(),
+    ownerIds: new Map(),
+};
+/** Reads only history bound by the admitted runner, never a caller-selected session. */
+export function taskTranscriptSource(task) {
+    const state = environment.tasks.get(task);
+    if (!state)
+        return { ok: false, error: { code: "UnknownTask", message: "Unknown task" } };
+    if (!state.transcript)
+        return { ok: false, error: { code: "TranscriptUnavailable", message: "Transcript unavailable" } };
+    return { ok: true, value: { session: state.transcript, taskId: state.ref.taskId } };
+}
+/** Promise rejections, setup throws and consumer exceptions may be arbitrary JavaScript values. */
+function rejectionMessage(reason) {
+    try {
+        const message = reason instanceof Error ? reason.message : reason;
+        return typeof message === "string" ? message : String(message);
+    }
+    catch {
+        return "Unprintable JavaScript rejection";
+    }
+}
+function mapped(result, convert, codes) {
+    if (result.ok)
+        return { ok: true, value: convert(result.value) };
+    const code = codes.find((candidate) => candidate === result.error.code);
+    if (!code)
+        throw new Error(`Unexpected native task refusal: ${result.error.code}: ${result.error.message}`);
+    return { ok: false, error: { code, message: result.error.message } };
+}
+const ownerErrors = ["ScopeMismatch", "EnvironmentClosing"];
+const startErrors = [
+    "OwnerClosing",
+    "UnknownAgent",
+    "InvalidCwd",
+    "DepthExceeded",
+    "CapacityExhausted",
+    "DispatchGuardBusy",
+    "OperationConflict",
+    "RunnerUnavailable",
+    "SpawnFailed",
+    "ContainmentUnavailable",
+];
+const waitErrors = ["UnknownTask", "OwnerClosed", "EnvironmentClosing", "ScopeMismatch", "ObserverCancelled"];
+const reportErrors = ["StaleAttempt", "OwnerClosing", "TaskTerminal", "ReportConflict"];
+const watchErrors = ["OwnerClosed", "StaleGeneration", "EnvironmentClosing"];
+function reference(value) {
+    return {
+        ownerId: value.ownerId,
+        taskId: value.taskId,
+        attemptId: value.attemptId,
+        generation: value.generation,
+    };
+}
+function cursor(value) {
+    return { generation: value.generation, sequence: value.sequence };
+}
+function output(value) {
+    return {
+        ownerId: value.ownerId,
+        taskId: value.taskId,
+        artifactId: value.artifactId,
+        byteCount: value.byteCount,
+        omittedRanges: value.omittedRanges.map(({ start, end }) => ({ start, end })),
+    };
+}
+function taskResult(value) {
+    switch (value.kind) {
+        case "completed":
+            return {
+                kind: value.kind,
+                output: output(value.output),
+                ...(value.exitCode === undefined ? {} : { exitCode: value.exitCode }),
+            };
+        case "failed":
+            return {
+                kind: value.kind,
+                code: value.code,
+                message: value.message,
+                ...(value.output === undefined ? {} : { output: output(value.output) }),
+                ...(value.exitCode === undefined ? {} : { exitCode: value.exitCode }),
+            };
+        case "cancelled":
+            return {
+                kind: value.kind,
+                cause: value.cause,
+                ...(value.output === undefined ? {} : { output: output(value.output) }),
+            };
+    }
+}
+function execution(value) {
+    return value.kind === "settled" ? { kind: "settled", result: taskResult(value.result) } : value;
+}
+function observation(value) {
+    if (value.kind === "foreground")
+        return { kind: value.kind, waitId: value.waitId };
+    if (value.kind === "none" && (value.reason === "task-settled" || value.reason === "owner-closing"))
+        return { kind: value.kind, reason: value.reason };
+    const reasons = [
+        "explicit",
+        "default-background",
+        "elapsed",
+        "intercom-coordination",
+        "input-needed",
+        "not-observed",
+        "observer-cancelled",
+    ];
+    const reason = reasons.find((reason) => reason === value.reason);
+    if (value.kind === "background" && reason)
+        return { kind: value.kind, reason };
+    throw new Error("Invalid native host observation");
+}
+function record(value) {
+    if (value.kind !== "agent" && value.kind !== "command")
+        throw new Error(`Invalid native task kind: ${value.kind}`);
+    return {
+        ref: reference(value.ref),
+        launchOperationId: value.launchOperationId,
+        ...(value.parentTaskId === undefined ? {} : { parentTaskId: value.parentTaskId }),
+        ...(value.launchGroupId === undefined ? {} : { launchGroupId: value.launchGroupId }),
+        launchOrdinal: value.launchOrdinal,
+        kind: value.kind,
+        title: value.title,
+        ...(value.agentName === undefined ? {} : { agentName: value.agentName }),
+        ...(value.model === undefined ? {} : { model: value.model }),
+        ...(value.thinking === undefined ? {} : { thinking: value.thinking }),
+        execution: execution(value.execution),
+        observation: observation(value.observation),
+        ...(value.wasBackground === undefined ? {} : { wasBackground: value.wasBackground }),
+        attention: value.attention,
+        cleanup: value.cleanup,
+        ...(value.currentAction === undefined
+            ? {}
+            : { currentAction: { tool: value.currentAction.tool, text: value.currentAction.text } }),
+        ...(value.metrics === undefined
+            ? {}
+            : {
+                metrics: {
+                    ...(value.metrics.elapsedMs === undefined ? {} : { elapsedMs: value.metrics.elapsedMs }),
+                    ...(value.metrics.toolCount === undefined ? {} : { toolCount: value.metrics.toolCount }),
+                    ...(value.metrics.tokenCount === undefined ? {} : { tokenCount: value.metrics.tokenCount }),
+                },
+            }),
+        output: output(value.output),
+    };
+}
+function snapshot(value) {
+    if (value.state !== "open" && value.state !== "closing" && value.state !== "closed")
+        throw new Error(`Invalid native owner state: ${value.state}`);
+    return {
+        ownerId: value.ownerId,
+        scope: value.scope,
+        generation: value.generation,
+        state: value.state,
+        tasks: value.tasks.map(record),
+        cursor: cursor(value.cursor),
+    };
+}
+function activity(value) {
+    if (value.change.kind === "attention-set" && value.change.attention.kind === "none")
+        throw new Error("Native attention-set cannot clear attention");
+    // Native tagged variants are owned wire data; only attention-set has a wider generated declaration.
+    return value;
+}
+function payload(value) {
+    switch (value.kind) {
+        case "task-admitted":
+            return { kind: value.kind, task: record(value.task) };
+        case "task-started":
+            return { kind: value.kind, ref: reference(value.ref) };
+        case "wait-started": {
+            if (value.observer !== "sdk" && value.observer !== "host")
+                throw new Error("Invalid native observer");
+            return {
+                kind: value.kind,
+                ref: reference(value.ref),
+                waitId: value.waitId,
+                observer: value.observer,
+            };
+        }
+        case "wait-yielded":
+            return { kind: value.kind, ref: reference(value.ref), waitId: value.waitId, reason: value.reason };
+        case "host-observation-changed":
+            return { kind: value.kind, ref: reference(value.ref), observation: observation(value.observation) };
+        case "task-activity":
+            return { kind: value.kind, ref: reference(value.ref), activity: activity(value.activity) };
+        case "task-cancelling":
+            return { kind: value.kind, ref: reference(value.ref), cause: value.cause };
+        case "task-settled":
+            return {
+                kind: value.kind,
+                ref: reference(value.ref),
+                result: taskResult(value.result),
+                completionId: value.completionId,
+            };
+        case "cleanup-changed":
+            return { kind: value.kind, ref: reference(value.ref), cleanup: value.cleanup };
+        case "owner-closing":
+        case "owner-closed":
+            return { kind: value.kind };
+    }
+}
+function event(value) {
+    if (value.schemaVersion !== 1)
+        throw new Error("Unsupported native task event schema");
+    return {
+        schemaVersion: 1,
+        cursor: cursor(value.cursor),
+        ownerId: value.ownerId,
+        ...(value.taskId === undefined ? {} : { taskId: value.taskId }),
+        payload: payload(value.payload),
+    };
+}
+function waitOutcome(value) {
+    return value.kind === "settled"
+        ? { kind: value.kind, taskId: value.taskId, result: taskResult(value.result) }
+        : { kind: value.kind, taskId: value.taskId, waitId: value.waitId, reason: value.reason };
+}
+function cancelReceipt(value) {
+    if (value.decision !== "already-settled" && value.decision !== "cancellation-requested")
+        throw new Error("Invalid cancellation decision");
+    return {
+        taskId: value.taskId,
+        decision: value.decision,
+        execution: execution(value.execution),
+        cleanup: value.cleanup,
+    };
+}
+function reportReceipt(value) {
+    if (value.disposition !== "accepted" && value.disposition !== "duplicate")
+        throw new Error("Invalid report disposition");
+    return { reportId: value.reportId, cursor: cursor(value.cursor), disposition: value.disposition };
+}
+/** Projection only: native ordering remains the sole lifecycle authority. */
+function applyEvent(current, value) {
+    const next = { ...current, tasks: [...current.tasks], cursor: value.cursor };
+    const change = value.payload;
+    if (change.kind === "owner-closing") {
+        next.state = "closing";
+        next.tasks = next.tasks.map((task) => task.execution.kind === "settled" ? task : { ...task, attention: { kind: "none" } });
+        return next;
+    }
+    if (change.kind === "owner-closed") {
+        next.state = "closed";
+        return next;
+    }
+    if (change.kind === "task-admitted") {
+        next.tasks.push(change.task);
+        return next;
+    }
+    const index = next.tasks.findIndex((task) => task.ref.taskId === change.ref.taskId);
+    if (index < 0)
+        throw new Error("Native delta references a task absent from its snapshot");
+    const task = { ...next.tasks[index] };
+    next.tasks[index] = task;
+    switch (change.kind) {
+        case "task-started":
+            task.execution = { kind: "running" };
+            break;
+        case "host-observation-changed":
+            task.observation = change.observation;
+            if (change.observation.kind === "background" && change.observation.reason !== "not-observed")
+                task.wasBackground = true;
+            break;
+        case "task-cancelling":
+            task.execution = { kind: "cancelling", cause: change.cause };
+            break;
+        case "task-settled":
+            task.execution = { kind: "settled", result: change.result };
+            task.attention = { kind: "none" };
+            if (change.result.output !== undefined)
+                task.output = change.result.output;
+            break;
+        case "cleanup-changed":
+            task.cleanup = change.cleanup;
+            break;
+        case "task-activity": {
+            const activity = change.activity.change;
+            switch (activity.kind) {
+                case "action":
+                    task.currentAction = { tool: activity.tool, text: activity.text };
+                    if (task.attention.kind === "no-recent-activity")
+                        task.attention = { kind: "none" };
+                    break;
+                case "model":
+                    task.model = activity.model;
+                    task.thinking = activity.thinking;
+                    break;
+                case "metrics":
+                    task.metrics = {
+                        ...task.metrics,
+                        ...(activity.elapsedMs === undefined ? {} : { elapsedMs: activity.elapsedMs }),
+                        ...(activity.toolCount === undefined ? {} : { toolCount: activity.toolCount }),
+                        ...(activity.tokenCount === undefined ? {} : { tokenCount: activity.tokenCount }),
+                    };
+                    break;
+                case "attention-set":
+                    task.attention = activity.attention;
+                    break;
+                case "attention-clear":
+                    if (task.attention.kind === "input-needed" && task.attention.requestId === activity.requestId)
+                        task.attention = { kind: "none" };
+                    break;
+                case "output":
+                    break;
+            }
+            break;
+        }
+        case "wait-started":
+        case "wait-yielded":
+            break;
+    }
+    return next;
+}
+/** One bounded wake poll per live subscription, including a journal with no retained event. */
+const RECONCILE_INTERVAL_MS = 25;
+const MAX_PENDING_EVENTS = 64;
+export class TaskSubscription {
+    #native;
+    #lease;
+    #resource;
+    #timer;
+    #queue;
+    #epoch;
+    #next;
+    #disposed;
+    #snapshot;
+    #cursor;
+    #onDispose;
+    #failure;
+    constructor(actor, initial, onDispose) {
+        this.#resource = new AsyncResource("TaskSubscription");
+        this.#queue = [];
+        this.#epoch = 0;
+        this.#disposed = false;
+        /** Reconciliation supplements the RFC snapshot/cursor/iterable contract. */
+        this.onReconcile = () => { };
+        this.lease = new SubscriptionCapability();
+        Object.freeze(this.lease);
+        this.#native = actor;
+        this.#lease = initial.lease;
+        this.#snapshot = snapshot(initial.snapshot);
+        this.#cursor = cursor(initial.cursor);
+        this.#onDispose = onDispose;
+        this.events = {
+            [Symbol.asyncIterator]: () => {
+                const epoch = this.#epoch;
+                return {
+                    next: () => {
+                        if (epoch !== this.#epoch)
+                            return Promise.resolve({ done: true, value: undefined });
+                        const value = this.#queue.shift();
+                        if (value)
+                            return Promise.resolve({ done: false, value });
+                        if (this.#disposed)
+                            return Promise.resolve({ done: true, value: undefined });
+                        if (this.#next)
+                            return Promise.reject(new Error("Only one pending subscription read is supported"));
+                        return new Promise((resolve) => {
+                            this.#next = resolve;
+                        });
+                    },
+                    return: async () => {
+                        if (epoch === this.#epoch)
+                            this.dispose();
+                        return { done: true, value: undefined };
+                    },
+                };
+            },
+        };
+        this.#arm();
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    get cursor() {
+        return this.#cursor;
+    }
+    /** Consumer exceptions are observable without breaking the native wake or fallback poll. */
+    get failure() {
+        return this.#failure;
+    }
+    /** Callback payloads are authentic hints; only the journal/snapshot is authoritative. */
+    wake(_hint) {
+        this.#resource.runInAsyncScope(() => this.drain());
+    }
+    #arm() {
+        if (this.#disposed || this.#timer)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.#resource.runInAsyncScope(() => this.drain());
+            this.#arm();
+        }, RECONCILE_INTERVAL_MS);
+        this.#timer.unref();
+    }
+    drain() {
+        if (this.#disposed)
+            return;
+        const drained = this.#native.drainOwnerTasks(this.#lease);
+        if (!drained.ok) {
+            this.dispose();
+            return;
+        }
+        const events = drained.value.events.map(event);
+        if (drained.value.snapshot)
+            this.#snapshot = snapshot(drained.value.snapshot);
+        for (const value of events) {
+            if (BigInt(value.cursor.sequence) > BigInt(this.#snapshot.cursor.sequence))
+                this.#snapshot = applyEvent(this.#snapshot, value);
+        }
+        this.#cursor = cursor(drained.value.cursor);
+        this.#snapshot = { ...this.#snapshot, cursor: this.#cursor };
+        const overflow = this.#queue.length + events.length > MAX_PENDING_EVENTS;
+        const reset = drained.value.reset || overflow;
+        if (reset) {
+            this.#queue = [];
+            this.#epoch++;
+            // End the old iterator only after publishing the authoritative snapshot/cursor.
+            // A new iterator on the same iterable observes subsequent authentic deltas.
+            this.#next?.({ done: true, value: undefined });
+            this.#next = undefined;
+        }
+        if (drained.value.snapshot || events.length) {
+            try {
+                this.#resource.runInAsyncScope(this.onReconcile, undefined, this.#snapshot);
+            }
+            catch (error) {
+                this.#failure = new Error(rejectionMessage(error));
+            }
+        }
+        if (this.#disposed)
+            return;
+        if (!reset)
+            for (const value of events) {
+                if (this.#next) {
+                    const next = this.#next;
+                    this.#next = undefined;
+                    next({ done: false, value });
+                }
+                else
+                    this.#queue.push(value);
+            }
+        if (this.#snapshot.state === "closed")
+            this.dispose(false);
+    }
+    dispose(clear = true) {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#native.disposeSubscription(this.#lease);
+        if (clear)
+            this.#queue = [];
+        this.#next?.({ done: true, value: undefined });
+        this.#next = undefined;
+        this.#resource.emitDestroy();
+        this.#onDispose();
+    }
+}
+function createNativeSupervisor() {
+    // Keep loading separate from `new`: type-assertion erasure in the build
+    // must not move construction onto createModuleRequire instead of the class.
+    const binding = createModuleRequire(import.meta.url)("@bastani/atomic-natives");
+    return new binding.TaskSupervisor();
+}
+export class TaskSupervisor {
+    #native = createNativeSupervisor();
+    #hosts = environment.hosts;
+    #owners = environment.owners;
+    #tasks = environment.tasks;
+    #waits = environment.waits;
+    #waitRegistry = environment.waitRegistry;
+    #ownerIds = environment.ownerIds;
+    bindHostSession(binding) {
+        const host = new HostCapability();
+        Object.freeze(host);
+        this.#hosts.set(host, { native: this.#native.bindHostSession(binding.scope), binding });
+        return host;
+    }
+    openTaskOwner(host, scope) {
+        const state = this.#host(host);
+        return mapped(this.#native.openTaskOwner(state.native, scope), (lease) => {
+            const probe = this.#native.watchOwnerTasks(lease, (_hint) => { });
+            if (!probe.ok)
+                throw new Error(probe.error.message);
+            const id = probe.value.snapshot.ownerId;
+            this.#native.disposeSubscription(probe.value.lease);
+            const existing = this.#ownerIds.get(id);
+            if (existing)
+                return existing;
+            const owner = new OwnerCapability();
+            Object.freeze(owner);
+            const ownerState = {
+                native: lease,
+                host: state,
+                tasks: new Map(),
+                watches: new Set(),
+                settledTasks: new Set(),
+                commandAdmissions: new Set(),
+            };
+            this.#owners.set(owner, ownerState);
+            this.#ownerIds.set(id, owner);
+            const watched = this.watchOwnerTasks(owner);
+            if (!watched.ok)
+                throw new Error(watched.error.message);
+            watched.value.onReconcile = (projection) => {
+                if (projection.state === "closed")
+                    this.#ownerIds.delete(projection.ownerId);
+                for (const record of projection.tasks) {
+                    const cause = record.execution.kind === "cancelling"
+                        ? record.execution.cause
+                        : projection.state !== "open" && record.cleanup.kind !== "reaped"
+                            ? "owner-close"
+                            : undefined;
+                    if (!cause)
+                        continue;
+                    const task = this.#owner(owner).tasks.get(record.ref.taskId);
+                    if (task)
+                        this.#task(task).controller.abort(cause);
+                }
+                let failure;
+                for (const record of projection.tasks) {
+                    if (record.execution.kind !== "settled" ||
+                        ownerState.settledTasks.has(record.ref.taskId) ||
+                        !state.binding.onTaskSettled)
+                        continue;
+                    try {
+                        // Cancellation settles at cleanup (or while queued), without a runner outcome.
+                        // Recover its authentic receipt even when the bounded journal has reset.
+                        const task = this.#native.lookupTask(lease, record.ref.taskId);
+                        if (!task.ok)
+                            throw new Error(task.error.message);
+                        const settled = this.#native.taskSettlement(task.value);
+                        if (!settled.ok)
+                            throw new Error(settled.error.message);
+                        this.#notifyTaskSettled(ownerState, record.ref, settled.value);
+                    }
+                    catch (error) {
+                        failure ??= new Error(rejectionMessage(error));
+                    }
+                }
+                if (failure)
+                    throw failure;
+            };
+            watched.value.onReconcile(watched.value.snapshot);
+            return owner;
+        }, ownerErrors);
+    }
+    #notifyTaskSettled(state, ref, receipt) {
+        if (!state.host.binding.onTaskSettled || state.settledTasks.has(ref.taskId))
+            return;
+        // Runner outcomes and snapshot recovery share one delivery door. Mark before
+        // host code so reentrant drains or callback failures cannot redeliver.
+        state.settledTasks.add(ref.taskId);
+        state.host.binding.onTaskSettled(ref, {
+            taskId: receipt.taskId,
+            cursor: cursor(receipt.cursor),
+            result: taskResult(receipt.result),
+            completionId: receipt.completionId,
+        });
+    }
+    async startCommandTask(owner, intent, operation) {
+        const state = this.#owner(owner);
+        state.host.binding.authorizeCommandLaunch?.(intent);
+        // Native command setup can be admitted before its task lease is visible in JS.
+        let finishAdmission;
+        const admission = new Promise((resolve) => {
+            finishAdmission = resolve;
+        });
+        state.commandAdmissions.add(admission);
+        try {
+            const admitted = mapped(await this.#native.startCommandTask(state.native, intent, operation), (lease) => lease, startErrors);
+            if (!admitted.ok)
+                return admitted;
+            const ref = this.#native.taskReference(admitted.value);
+            if (!ref.ok)
+                throw new Error(ref.error.message);
+            const id = ref.value.taskId;
+            const existing = state.tasks.get(id);
+            if (existing)
+                return { ok: true, value: existing };
+            const task = new TaskCapability();
+            this.#tasks.set(task, {
+                native: admitted.value,
+                owner: state,
+                ref: reference(ref.value),
+                controller: new AbortController(),
+                kind: "command",
+            });
+            state.tasks.set(id, task);
+            return { ok: true, value: task };
+        }
+        finally {
+            state.commandAdmissions.delete(admission);
+            finishAdmission();
+        }
+    }
+    /** Caller must hold launch authorization closed while this snapshot drains. */
+    async drainCommandAdmissions(owner) {
+        await Promise.all([...this.#owner(owner).commandAdmissions]);
+    }
+    taskStdin(task) {
+        return mapped(this.#native.taskStdin(this.#task(task).native), (input) => {
+            const lease = new StdinCapability();
+            environment.inputs.set(lease, input);
+            return lease;
+        }, ["TaskTerminal", "StdinClosed", "UnknownTask", "OutputUnavailable"]);
+    }
+    async writeTaskInput(input, operation, data) {
+        const lease = environment.inputs.get(input);
+        if (!lease)
+            throw new TypeError("Foreign stdin capability");
+        return mapped(await this.#native.writeTaskInput(lease, operation, data.kind === "bytes" ? { kind: "bytes", bytes: Buffer.from(data.bytes) } : data), (value) => ({
+            operationId: value.operationId,
+            acceptedBytes: value.acceptedBytes,
+            kind: value.kind,
+        }), ["TaskTerminal", "StdinClosed", "InputBackpressure", "OperationConflict", "InputDeliveryUnknown"]);
+    }
+    async readTaskOutput(task, range) {
+        return mapped(await this.#native.readTaskOutput(this.#task(task).native, range), (page) => ({
+            requested: page.requested,
+            chunks: page.chunks.map((chunk) => ({ offsets: chunk.offsets, bytes: new Uint8Array(chunk.bytes) })),
+            omittedRanges: page.omittedRanges,
+            ...(page.nextOffset === undefined ? {} : { nextOffset: page.nextOffset }),
+        }), ["UnknownTask", "OutputUnavailable"]);
+    }
+    async startAgentTask(owner, intent, operation, schedule) {
+        const state = this.#owner(owner);
+        state.host.binding.authorizeLaunch(intent);
+        const admitted = mapped(this.#native.startAgentTask(state.native, intent, operation), (lease) => lease, startErrors);
+        if (!admitted.ok)
+            return admitted;
+        const ref = this.#native.taskReference(admitted.value);
+        if (!ref.ok)
+            throw new Error(ref.error.message);
+        const id = ref.value.taskId;
+        const existing = state.tasks.get(id);
+        if (existing)
+            return { ok: true, value: existing };
+        const task = new TaskCapability();
+        Object.freeze(task);
+        const taskState = {
+            native: admitted.value,
+            owner: state,
+            ref: reference(ref.value),
+            controller: new AbortController(),
+        };
+        this.#tasks.set(task, taskState);
+        state.tasks.set(id, task);
+        const dispatch = AsyncResource.bind(async () => {
+            if (taskState.controller.signal.aborted)
+                return;
+            const runner = mapped(this.#native.claimTaskRunner(admitted.value), (lease) => lease, startErrors);
+            if (!runner.ok)
+                throw new Error(`${runner.error.code}: ${runner.error.message}`);
+            let execution;
+            try {
+                execution = state.host.binding.createRunner({
+                    ref: reference(taskState.ref),
+                    signal: taskState.controller.signal,
+                    bindTranscript: (session) => {
+                        taskState.transcript = session;
+                    },
+                    reportActivity: (report) => mapped(this.#native.reportTaskActivity(runner.value, report), reportReceipt, reportErrors),
+                }, intent);
+            }
+            catch (error) {
+                const message = rejectionMessage(error);
+                execution = {
+                    result: Promise.resolve({ kind: "failed", code: "SpawnFailed", message }),
+                    cleanup: Promise.resolve({
+                        kind: "failed",
+                        resources: [{ resource: "fake-runner-setup", code: "CleanupUnconfirmed", message }],
+                    }),
+                };
+            }
+            const outcome = execution.result
+                .catch((error) => ({ kind: "failed", code: "RunnerFailed", message: rejectionMessage(error) }))
+                .then((result) => {
+                return mapped(this.#native.reportRunnerOutcome(runner.value, result), (receipt) => this.#notifyTaskSettled(state, taskState.ref, receipt), reportErrors);
+            });
+            const cleanup = execution.cleanup.catch((error) => ({
+                kind: "failed",
+                resources: [{ resource: "fake-runner", code: "CleanupFailed", message: rejectionMessage(error) }],
+            }));
+            taskState.execution = cleanup.then(async (evidence) => {
+                // Natural reaping follows its outcome; cancellation needs only confirmed stop.
+                // A result may never arrive after abort, including when cleanup arrived first.
+                const signal = taskState.controller.signal;
+                let stopped;
+                const cancelled = new Promise((resolve) => {
+                    stopped = () => resolve(undefined);
+                    if (signal.aborted)
+                        stopped();
+                    else
+                        signal.addEventListener("abort", stopped, { once: true });
+                });
+                const reported = await Promise.race([outcome, cancelled]).finally(() => {
+                    signal.removeEventListener("abort", stopped);
+                });
+                const acknowledged = mapped(this.#native.acknowledgeTaskCleanup(runner.value, evidence), (cleanup) => cleanup, reportErrors);
+                if (reported && !reported.ok && !(signal.aborted && reported.error.code === "ReportConflict"))
+                    return reported;
+                return acknowledged;
+            });
+            await taskState.execution;
+        });
+        if (schedule)
+            schedule(dispatch);
+        else
+            void dispatch();
+        // Setup is complete. Do not await execution; ready terminal microtasks may win observation.
+        await Promise.resolve();
+        return { ok: true, value: task };
+    }
+    taskReference(task) {
+        return reference(this.#task(task).ref);
+    }
+    async waitForTask(task, budgetMs, designation) {
+        const registered = mapped(this.#native.waitForTask(this.#task(task).native, this.#agentBudget(this.#task(task).owner, budgetMs, this.#task(task).kind === "command"), designation ? this.#host(designation).native : undefined), (lease) => this.#register(lease), waitErrors);
+        return registered.ok ? this.observeTaskWait(registered.value) : registered;
+    }
+    /** Resolve only a task admitted under this live owner; IDs alone confer no authority. */
+    lookupTask(owner, taskId) {
+        const state = this.#owner(owner);
+        const found = mapped(this.#native.lookupTask(state.native, taskId), () => state.tasks.get(taskId), waitErrors);
+        if (!found.ok)
+            return found;
+        if (!found.value)
+            return { ok: false, error: { code: "UnknownTask", message: "No agent runner bound to task" } };
+        return { ok: true, value: found.value };
+    }
+    async waitForTaskId(owner, taskId, budgetMs, onRegistered) {
+        const found = mapped(this.#native.lookupTask(this.#owner(owner).native, taskId), (lease) => lease, waitErrors);
+        if (!found.ok)
+            return found;
+        const known = this.#owner(owner).tasks.get(taskId);
+        const registered = mapped(this.#native.waitForTask(found.value, this.#agentBudget(this.#owner(owner), budgetMs, known !== undefined && this.#task(known).kind === "command")), (lease) => this.#register(lease), waitErrors);
+        if (!registered.ok)
+            return registered;
+        onRegistered?.(registered.value);
+        return this.observeTaskWait(registered.value);
+    }
+    async foregroundTask(task, budgetMs) {
+        const state = this.#task(task);
+        const errors = ["TaskTerminal", "OwnerClosing", "UnknownTask", "ObserverCancelled"];
+        const registered = mapped(this.#native.foregroundTask(state.native, state.owner.host.native, this.#agentBudget(state.owner, budgetMs, state.kind === "command")), (lease) => this.#register(lease), errors);
+        return registered.ok
+            ? mapped(await this.observeTaskWait(registered.value), (outcome) => outcome, errors)
+            : registered;
+    }
+    waitId(wait) {
+        return this.#wait(wait).native.waitId;
+    }
+    findWait(id) {
+        return this.#waitRegistry.get(id);
+    }
+    observeTaskWait(wait) {
+        return this.#wait(wait).outcome;
+    }
+    yieldTaskWait(wait, reason) {
+        return mapped(this.#native.yieldTaskWait(this.#wait(wait).native, reason), waitOutcome, [
+            "UnknownWait",
+            "StaleGeneration",
+            "ObserverCancelled",
+        ]);
+    }
+    disposeTaskWait(wait) {
+        return mapped(this.#native.disposeTaskWait(this.#wait(wait).native), () => undefined, waitErrors);
+    }
+    async initialObservation(task, policy, onRegistered) {
+        const state = this.#task(task);
+        policy ??= state.kind === "command" ? { kind: "foreground" } : undefined;
+        const registered = mapped(this.#native.waitForTask(state.native, policy?.kind === "foreground"
+            ? this.#agentBudget(state.owner, policy.budgetMs, state.kind === "command")
+            : undefined, state.owner.host.native), (lease) => this.#register(lease), waitErrors);
+        if (!registered.ok)
+            return registered;
+        onRegistered?.(registered.value);
+        if (policy?.kind !== "foreground")
+            this.yieldTaskWait(registered.value, policy ? "explicit" : "default-background");
+        return this.observeTaskWait(registered.value);
+    }
+    async cancelTask(task, cause) {
+        const state = this.#task(task);
+        const result = mapped(this.#native.cancelTask(state.native, cause), cancelReceipt, [
+            "UnknownTask",
+            "CleanupFailed",
+        ]);
+        if (result.ok && result.value.decision === "cancellation-requested")
+            state.controller.abort(cause);
+        return result;
+    }
+    async closeTaskOwner(owner, cause) {
+        const state = this.#owner(owner);
+        const closing = this.#native.closeTaskOwner(state.native, cause);
+        for (const task of state.tasks.values())
+            this.#task(task).controller.abort("owner-close");
+        const result = mapped(await closing, (receipt) => ({
+            ownerId: receipt.ownerId,
+            state: "closed",
+            tasks: receipt.tasks.map(cancelReceipt),
+        }), ["CleanupFailed", "EnvironmentClosing"]);
+        if (result.ok)
+            for (const task of state.tasks.values()) {
+                const completed = await this.#task(task).execution;
+                if (completed && !completed.ok)
+                    throw new Error(`Runner protocol failed: ${completed.error.code}: ${completed.error.message}`);
+            }
+        if (result.ok)
+            for (const watch of state.watches) {
+                watch.drain();
+                watch.dispose(false);
+            }
+        return result;
+    }
+    /**
+     * The bounded stream carries only authentic deltas. Overflow/native reset publishes
+     * snapshot/cursor then ends the current iterator, even with no surviving delta.
+     * Reconcile on completion; obtain a new iterator on the same events iterable to
+     * continue observing. Apply snapshots first and ignore deltas at/below their cursor.
+     * onReconcile is optional; consumer failures never disable the fallback poll.
+     */
+    watchOwnerTasks(owner, from) {
+        const state = this.#owner(owner);
+        let subscription;
+        return mapped(this.#native.watchOwnerTasks(state.native, (hint) => subscription?.wake(hint), from), (initial) => {
+            subscription = new TaskSubscription(this.#native, initial, () => {
+                if (subscription)
+                    state.watches.delete(subscription);
+            });
+            state.watches.add(subscription);
+            return subscription;
+        }, watchErrors);
+    }
+    #agentBudget(owner, budgetMs, command = false) {
+        if (budgetMs !== undefined)
+            return budgetMs;
+        const configuration = owner.host.binding.tasks?.wait;
+        if (configuration?.kind === "until-settled")
+            return undefined;
+        return command
+            ? (configuration?.commandBudgetMs ?? COMMAND_FOREGROUND_BUDGET_MS)
+            : (configuration?.agentBudgetMs ?? DEFAULT_AGENT_WAIT_BUDGET_MS);
+    }
+    #register(lease) {
+        const wait = new WaitCapability();
+        Object.freeze(wait);
+        const id = lease.waitId;
+        this.#waitRegistry.set(id, wait);
+        const outcome = this.#native
+            .observeTaskWait(lease)
+            .then((result) => mapped(result, waitOutcome, waitErrors))
+            .finally(() => {
+            this.#waitRegistry.delete(id);
+        });
+        this.#waits.set(wait, { native: lease, outcome });
+        return wait;
+    }
+    #host(host) {
+        const state = this.#hosts.get(host);
+        if (!state)
+            throw new TypeError("Foreign host capability");
+        return state;
+    }
+    #owner(owner) {
+        const state = this.#owners.get(owner);
+        if (!state)
+            throw new TypeError("Foreign owner capability");
+        return state;
+    }
+    #task(task) {
+        const state = this.#tasks.get(task);
+        if (!state)
+            throw new TypeError("Foreign task capability");
+        return state;
+    }
+    #wait(wait) {
+        const state = this.#waits.get(wait);
+        if (!state)
+            throw new TypeError("Foreign wait capability");
+        return state;
+    }
+}
+//# sourceMappingURL=supervisor.js.map