@elie-laloum/outpost 5.0.0 → 7.0.0

package/dist/domain/observation.js

@@ -0,0 +1,190 @@
+import { observationDefaults } from "./observation.constants.js";
+export function createObservationHub(options = {}) {
+    const capacity = options.capacity ?? observationDefaults.capacity;
+    const timeout = options.deliveryTimeoutMs ?? observationDefaults.deliveryTimeoutMs;
+    for (const value of [capacity, timeout])
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error("Observation capacity and timeout must be positive integers");
+    let seq = 0, dropped = 0, emitting = false;
+    const errors = [];
+    const deliveries = new Set();
+    const emissions = [];
+    function fail(error) {
+        if (errors.length < observationDefaults.errorLimit)
+            errors.push(error);
+    }
+    async function bounded(action, expired) {
+        let timer;
+        try {
+            await Promise.race([
+                action,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        expired();
+                        reject(new Error("Observation sink delivery timed out; sink disabled"));
+                    }, timeout);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    function disable(delivery) {
+        delivery.disabled = true;
+        dropped += delivery.queue.length;
+        delivery.queue.length = 0;
+    }
+    function deliver(delivery, observation) {
+        if (delivery.disabled) {
+            dropped++;
+            return;
+        }
+        if (delivery.pending) {
+            if (delivery.queue.length >= capacity) {
+                dropped++;
+                delivery.dropped++;
+                if (delivery.dropped === 1)
+                    fail(new Error("Observation sink queue overflow; newest events dropped"));
+                return;
+            }
+            delivery.queue.push(observation);
+            return;
+        }
+        try {
+            const result = delivery.sink.observe(structuredClone(observation));
+            if (!result) {
+                delivery.completedSeq = observation.seq;
+                return;
+            }
+            delivery.pendingSeq = observation.seq;
+            delivery.pending = bounded(result, () => disable(delivery))
+                .catch(fail)
+                .then(() => {
+                delivery.completedSeq = observation.seq;
+                delete delivery.pendingSeq;
+                delete delivery.pending;
+                while (!delivery.pending && delivery.queue.length)
+                    deliver(delivery, delivery.queue.shift());
+            });
+        }
+        catch (error) {
+            delivery.completedSeq = observation.seq;
+            fail(error);
+        }
+    }
+    async function flush(targets) {
+        const snapshots = [...targets].map((delivery) => ({
+            delivery,
+            seq: delivery.queue.at(-1)?.seq ?? delivery.pendingSeq ?? 0,
+        }));
+        for (const { delivery, seq } of snapshots) {
+            while (delivery.pending && (delivery.completedSeq ?? 0) < seq)
+                await delivery.pending;
+            if (delivery.disabled)
+                continue;
+            try {
+                await bounded(Promise.resolve(delivery.sink.flush?.()), () => disable(delivery));
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+    }
+    function hub(scope, inherited, sinks, parentActive, parentTrack) {
+        const local = sinks.map((sink) => ({
+            sink,
+            queue: [],
+            dropped: 0,
+        }));
+        const owned = new Set();
+        const track = (delivery, add) => {
+            if (add)
+                owned.add(delivery);
+            if (!add)
+                owned.delete(delivery);
+            parentTrack(delivery, add);
+        };
+        for (const delivery of local) {
+            deliveries.add(delivery);
+            track(delivery, true);
+        }
+        const targets = [...inherited, ...local];
+        const frozen = Object.freeze({ ...scope });
+        let closed = false;
+        let closing;
+        const active = () => !closed && parentActive();
+        return {
+            scope: frozen,
+            errors,
+            get dropped() {
+                return dropped;
+            },
+            verbose: options.verbose ?? false,
+            emit(source, event) {
+                if (!active())
+                    return;
+                if (emissions.length >= capacity) {
+                    dropped++;
+                    fail(new Error("Reentrant observation queue overflow"));
+                    return;
+                }
+                const draining = !emitting;
+                try {
+                    emissions.push({
+                        targets,
+                        observation: {
+                            seq: ++seq,
+                            at: new Date().toISOString(),
+                            source,
+                            scope: frozen,
+                            event: structuredClone(event),
+                        },
+                    });
+                    if (!draining)
+                        return;
+                    emitting = true;
+                    let processed = 0;
+                    for (let item = emissions.shift(); item; item = emissions.shift()) {
+                        if (++processed > capacity) {
+                            dropped +=
+                                item.targets.length +
+                                    emissions.reduce((sum, value) => sum + value.targets.length, 0);
+                            emissions.length = 0;
+                            fail(new Error("Reentrant observation delivery limit exceeded"));
+                            break;
+                        }
+                        for (const target of item.targets)
+                            deliver(target, item.observation);
+                    }
+                }
+                catch (error) {
+                    fail(error);
+                }
+                finally {
+                    if (draining)
+                        emitting = false;
+                }
+            },
+            child(addition, sinks = []) {
+                return hub({ ...scope, ...addition }, targets, sinks, active, track);
+            },
+            flush: () => flush(deliveries),
+            close() {
+                if (closing)
+                    return closing;
+                closed = true;
+                closing = (async () => {
+                    await flush([...inherited, ...owned]);
+                    for (const delivery of [...owned]) {
+                        deliveries.delete(delivery);
+                        track(delivery, false);
+                    }
+                })();
+                return closing;
+            },
+        };
+    }
+    return hub(options.scope ?? {}, [], options.sinks ?? [], () => true, () => { });
+}
+//# sourceMappingURL=observation.js.map

package/dist/domain/observation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.js","sourceRoot":"","sources":["../../src/domain/observation.ts"],"names":[],"mappings":"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","sourcesContent":["import { observationDefaults } from \"./observation.constants.ts\";\nimport type {\n  Observation,\n  ObservationHub,\n  ObservationHubOptions,\n  ObservationScope,\n  ObservationSink,\n  SinkDelivery,\n  PendingObservation,\n} from \"./observation.types.ts\";\n\nexport function createObservationHub(\n  options: ObservationHubOptions = {},\n): ObservationHub {\n  const capacity = options.capacity ?? observationDefaults.capacity;\n  const timeout =\n    options.deliveryTimeoutMs ?? observationDefaults.deliveryTimeoutMs;\n  for (const value of [capacity, timeout])\n    if (!Number.isSafeInteger(value) || value <= 0)\n      throw new Error(\n        \"Observation capacity and timeout must be positive integers\",\n      );\n  let seq = 0,\n    dropped = 0,\n    emitting = false;\n  const errors: unknown[] = [];\n  const deliveries = new Set<SinkDelivery>();\n  const emissions: PendingObservation[] = [];\n  function fail(error: unknown): void {\n    if (errors.length < observationDefaults.errorLimit) errors.push(error);\n  }\n  async function bounded(\n    action: Promise<void>,\n    expired: () => void,\n  ): Promise<void> {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      await Promise.race([\n        action,\n        new Promise<never>((_, reject) => {\n          timer = setTimeout(() => {\n            expired();\n            reject(\n              new Error(\"Observation sink delivery timed out; sink disabled\"),\n            );\n          }, timeout);\n        }),\n      ]);\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n  function disable(delivery: SinkDelivery): void {\n    delivery.disabled = true;\n    dropped += delivery.queue.length;\n    delivery.queue.length = 0;\n  }\n  function deliver(delivery: SinkDelivery, observation: Observation): void {\n    if (delivery.disabled) {\n      dropped++;\n      return;\n    }\n    if (delivery.pending) {\n      if (delivery.queue.length >= capacity) {\n        dropped++;\n        delivery.dropped++;\n        if (delivery.dropped === 1)\n          fail(\n            new Error(\"Observation sink queue overflow; newest events dropped\"),\n          );\n        return;\n      }\n      delivery.queue.push(observation);\n      return;\n    }\n    try {\n      const result = delivery.sink.observe(structuredClone(observation));\n      if (!result) {\n        delivery.completedSeq = observation.seq;\n        return;\n      }\n      delivery.pendingSeq = observation.seq;\n      delivery.pending = bounded(result, () => disable(delivery))\n        .catch(fail)\n        .then(() => {\n          delivery.completedSeq = observation.seq;\n          delete delivery.pendingSeq;\n          delete delivery.pending;\n          while (!delivery.pending && delivery.queue.length)\n            deliver(delivery, delivery.queue.shift()!);\n        });\n    } catch (error) {\n      delivery.completedSeq = observation.seq;\n      fail(error);\n    }\n  }\n  async function flush(targets: Iterable<SinkDelivery>): Promise<void> {\n    const snapshots = [...targets].map((delivery) => ({\n      delivery,\n      seq: delivery.queue.at(-1)?.seq ?? delivery.pendingSeq ?? 0,\n    }));\n    for (const { delivery, seq } of snapshots) {\n      while (delivery.pending && (delivery.completedSeq ?? 0) < seq)\n        await delivery.pending;\n      if (delivery.disabled) continue;\n      try {\n        await bounded(Promise.resolve(delivery.sink.flush?.()), () =>\n          disable(delivery),\n        );\n      } catch (error) {\n        fail(error);\n      }\n    }\n  }\n  function hub(\n    scope: ObservationScope,\n    inherited: readonly SinkDelivery[],\n    sinks: readonly ObservationSink[],\n    parentActive: () => boolean,\n    parentTrack: (delivery: SinkDelivery, add: boolean) => void,\n  ): ObservationHub {\n    const local: SinkDelivery[] = sinks.map((sink) => ({\n      sink,\n      queue: [],\n      dropped: 0,\n    }));\n    const owned = new Set<SinkDelivery>();\n    const track = (delivery: SinkDelivery, add: boolean) => {\n      if (add) owned.add(delivery);\n      if (!add) owned.delete(delivery);\n      parentTrack(delivery, add);\n    };\n    for (const delivery of local) {\n      deliveries.add(delivery);\n      track(delivery, true);\n    }\n    const targets = [...inherited, ...local];\n    const frozen = Object.freeze({ ...scope });\n    let closed = false;\n    let closing: Promise<void> | undefined;\n    const active = () => !closed && parentActive();\n    return {\n      scope: frozen,\n      errors,\n      get dropped() {\n        return dropped;\n      },\n      verbose: options.verbose ?? false,\n      emit(source, event) {\n        if (!active()) return;\n        if (emissions.length >= capacity) {\n          dropped++;\n          fail(new Error(\"Reentrant observation queue overflow\"));\n          return;\n        }\n        const draining = !emitting;\n        try {\n          emissions.push({\n            targets,\n            observation: {\n              seq: ++seq,\n              at: new Date().toISOString(),\n              source,\n              scope: frozen,\n              event: structuredClone(event),\n            },\n          });\n          if (!draining) return;\n          emitting = true;\n          let processed = 0;\n          for (let item = emissions.shift(); item; item = emissions.shift()) {\n            if (++processed > capacity) {\n              dropped +=\n                item.targets.length +\n                emissions.reduce((sum, value) => sum + value.targets.length, 0);\n              emissions.length = 0;\n              fail(new Error(\"Reentrant observation delivery limit exceeded\"));\n              break;\n            }\n            for (const target of item.targets)\n              deliver(target, item.observation);\n          }\n        } catch (error) {\n          fail(error);\n        } finally {\n          if (draining) emitting = false;\n        }\n      },\n      child(addition, sinks = []) {\n        return hub({ ...scope, ...addition }, targets, sinks, active, track);\n      },\n      flush: () => flush(deliveries),\n      close() {\n        if (closing) return closing;\n        closed = true;\n        closing = (async () => {\n          await flush([...inherited, ...owned]);\n          for (const delivery of [...owned]) {\n            deliveries.delete(delivery);\n            track(delivery, false);\n          }\n        })();\n        return closing;\n      },\n    };\n  }\n  return hub(\n    options.scope ?? {},\n    [],\n    options.sinks ?? [],\n    () => true,\n    () => {},\n  );\n}\n"]}

package/dist/domain/observation.types.d.ts

@@ -0,0 +1,84 @@
+import type { AgentEvent } from "./agent.types.ts";
+import type { WorkflowEvent } from "./workflow.types.ts";
+export interface ObservationScope {
+    readonly executionId?: string;
+    readonly taskKey?: string;
+    readonly attempt?: number;
+    readonly dispatchId?: string;
+    readonly pass?: number;
+    readonly subagentId?: string;
+    readonly candidate?: string;
+}
+export type ObservationSource = "agent" | "harness" | "workflow" | "sandbox" | "git" | "hooks" | "transfer" | "conversation" | "recovery";
+export interface OperationEvent {
+    readonly kind: "operation";
+    readonly id: string;
+    readonly name: string;
+    readonly status: "started" | "finished" | "failed";
+    readonly durationMs?: number;
+}
+export type ObservationEvent = AgentEvent | OperationEvent | {
+    readonly kind: "dispatch-start";
+} | {
+    readonly kind: "workflow";
+    readonly event: WorkflowEvent;
+} | {
+    readonly kind: "dispatch-finished";
+    readonly status: "done" | "failed" | "cancelled";
+    readonly completed: boolean;
+    readonly branch?: string;
+    readonly commits?: readonly import("./workspace.types.ts").Commit[];
+    readonly usage: import("./agent.types.ts").Usage;
+} | {
+    readonly kind: "command-output";
+    readonly channel: "stdout" | "stderr";
+    readonly text: string;
+} | {
+    readonly kind: "candidate";
+    readonly status: "validated" | "accepted" | "rejected" | "cleanup";
+} | {
+    readonly kind: "queue";
+    readonly id: string;
+    readonly status: "enqueued" | "polled" | "completed" | "failed";
+};
+export interface Observation {
+    readonly seq: number;
+    readonly at: string;
+    readonly source: ObservationSource;
+    readonly scope: ObservationScope;
+    readonly event: ObservationEvent;
+}
+export interface ObservationSink {
+    observe(observation: Observation): void | Promise<void>;
+    flush?(): void | Promise<void>;
+}
+export interface ObservationHubOptions {
+    readonly sinks?: readonly ObservationSink[];
+    readonly scope?: ObservationScope;
+    readonly capacity?: number;
+    readonly deliveryTimeoutMs?: number;
+    readonly verbose?: boolean;
+}
+export interface ObservationHub {
+    readonly scope: ObservationScope;
+    readonly errors: readonly unknown[];
+    readonly dropped: number;
+    readonly verbose: boolean;
+    emit(source: ObservationSource, event: ObservationEvent): void;
+    child(scope: ObservationScope, sinks?: readonly ObservationSink[]): ObservationHub;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface SinkDelivery {
+    readonly sink: ObservationSink;
+    readonly queue: Observation[];
+    completedSeq?: number;
+    pendingSeq?: number;
+    disabled?: boolean;
+    pending?: Promise<void>;
+    dropped: number;
+}
+export interface PendingObservation {
+    readonly targets: readonly SinkDelivery[];
+    readonly observation: Observation;
+}

package/dist/domain/observation.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=observation.types.js.map

package/dist/domain/observation.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.types.js","sourceRoot":"","sources":["../../src/domain/observation.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { AgentEvent } from \"./agent.types.ts\";\nimport type { WorkflowEvent } from \"./workflow.types.ts\";\n\nexport interface ObservationScope {\n  readonly executionId?: string;\n  readonly taskKey?: string;\n  readonly attempt?: number;\n  readonly dispatchId?: string;\n  readonly pass?: number;\n  readonly subagentId?: string;\n  readonly candidate?: string;\n}\n\nexport type ObservationSource =\n  | \"agent\"\n  | \"harness\"\n  | \"workflow\"\n  | \"sandbox\"\n  | \"git\"\n  | \"hooks\"\n  | \"transfer\"\n  | \"conversation\"\n  | \"recovery\";\n\nexport interface OperationEvent {\n  readonly kind: \"operation\";\n  readonly id: string;\n  readonly name: string;\n  readonly status: \"started\" | \"finished\" | \"failed\";\n  readonly durationMs?: number;\n}\n\nexport type ObservationEvent =\n  | AgentEvent\n  | OperationEvent\n  | { readonly kind: \"dispatch-start\" }\n  | {\n      readonly kind: \"workflow\";\n      readonly event: WorkflowEvent;\n    }\n  | {\n      readonly kind: \"dispatch-finished\";\n      readonly status: \"done\" | \"failed\" | \"cancelled\";\n      readonly completed: boolean;\n      readonly branch?: string;\n      readonly commits?: readonly import(\"./workspace.types.ts\").Commit[];\n      readonly usage: import(\"./agent.types.ts\").Usage;\n    }\n  | {\n      readonly kind: \"command-output\";\n      readonly channel: \"stdout\" | \"stderr\";\n      readonly text: string;\n    }\n  | {\n      readonly kind: \"candidate\";\n      readonly status: \"validated\" | \"accepted\" | \"rejected\" | \"cleanup\";\n    }\n  | {\n      readonly kind: \"queue\";\n      readonly id: string;\n      readonly status: \"enqueued\" | \"polled\" | \"completed\" | \"failed\";\n    };\n\nexport interface Observation {\n  readonly seq: number;\n  readonly at: string;\n  readonly source: ObservationSource;\n  readonly scope: ObservationScope;\n  readonly event: ObservationEvent;\n}\n\nexport interface ObservationSink {\n  observe(observation: Observation): void | Promise<void>;\n  flush?(): void | Promise<void>;\n}\n\nexport interface ObservationHubOptions {\n  readonly sinks?: readonly ObservationSink[];\n  readonly scope?: ObservationScope;\n  readonly capacity?: number;\n  readonly deliveryTimeoutMs?: number;\n  readonly verbose?: boolean;\n}\n\nexport interface ObservationHub {\n  readonly scope: ObservationScope;\n  readonly errors: readonly unknown[];\n  readonly dropped: number;\n  readonly verbose: boolean;\n  emit(source: ObservationSource, event: ObservationEvent): void;\n  child(\n    scope: ObservationScope,\n    sinks?: readonly ObservationSink[],\n  ): ObservationHub;\n  flush(): Promise<void>;\n  close(): Promise<void>;\n}\n\nexport interface SinkDelivery {\n  readonly sink: ObservationSink;\n  readonly queue: Observation[];\n  completedSeq?: number;\n  pendingSeq?: number;\n  disabled?: boolean;\n  pending?: Promise<void>;\n  dropped: number;\n}\n\nexport interface PendingObservation {\n  readonly targets: readonly SinkDelivery[];\n  readonly observation: Observation;\n}\n"]}

package/dist/domain/observed-operation.d.ts

@@ -0,0 +1,2 @@
+import type { ObservationHub, ObservationSource } from "./observation.types.ts";
+export declare function observedOperation<T>(hub: ObservationHub | undefined, source: ObservationSource, name: string, action: () => Promise<T>): Promise<T>;

package/dist/domain/observed-operation.js

@@ -0,0 +1,30 @@
+import { randomUUID } from "node:crypto";
+export async function observedOperation(hub, source, name, action) {
+    if (!hub)
+        return action();
+    const id = randomUUID();
+    const started = performance.now();
+    hub.emit(source, { kind: "operation", id, name, status: "started" });
+    try {
+        const result = await action();
+        hub.emit(source, {
+            kind: "operation",
+            id,
+            name,
+            status: "finished",
+            durationMs: performance.now() - started,
+        });
+        return result;
+    }
+    catch (error) {
+        hub.emit(source, {
+            kind: "operation",
+            id,
+            name,
+            status: "failed",
+            durationMs: performance.now() - started,
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=observed-operation.js.map

package/dist/domain/observed-operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-operation.js","sourceRoot":"","sources":["../../src/domain/observed-operation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAA+B,EAC/B,MAAyB,EACzB,IAAY,EACZ,MAAwB;IAExB,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;IACxB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE;YACf,IAAI,EAAE,WAAW;YACjB,EAAE;YACF,IAAI;YACJ,MAAM,EAAE,UAAU;YAClB,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO;SACxC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE;YACf,IAAI,EAAE,WAAW;YACjB,EAAE;YACF,IAAI;YACJ,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO;SACxC,CAAC,CAAC;QACH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { ObservationHub, ObservationSource } from \"./observation.types.ts\";\n\nexport async function observedOperation<T>(\n  hub: ObservationHub | undefined,\n  source: ObservationSource,\n  name: string,\n  action: () => Promise<T>,\n): Promise<T> {\n  if (!hub) return action();\n  const id = randomUUID();\n  const started = performance.now();\n  hub.emit(source, { kind: \"operation\", id, name, status: \"started\" });\n  try {\n    const result = await action();\n    hub.emit(source, {\n      kind: \"operation\",\n      id,\n      name,\n      status: \"finished\",\n      durationMs: performance.now() - started,\n    });\n    return result;\n  } catch (error) {\n    hub.emit(source, {\n      kind: \"operation\",\n      id,\n      name,\n      status: \"failed\",\n      durationMs: performance.now() - started,\n    });\n    throw error;\n  }\n}\n"]}

package/dist/domain/sandbox.types.d.ts

@@ -5,6 +5,7 @@ export interface Volume {
     readonly readOnly?: boolean;
 }
 export interface SandboxContext {
+    readonly registerRecovery?: (resourceId: string) => Promise<void>;
     readonly repository: string;
     readonly directory: string;
     readonly gitDirectories: readonly string[];
@@ -37,6 +38,7 @@ export interface SandboxLease {
     release(): Promise<void>;
 }
 export interface SandboxProvider {
+    readonly recover?: (resourceId: string, options?: TransferOptions) => Promise<void>;
     readonly name: string;
     readonly placement: "mounted" | "remote" | "host";
     readonly variables?: Variables;

package/dist/domain/sandbox.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.types.js","sourceRoot":"","sources":["../../src/domain/sandbox.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Command, CommandResult, Variables } from \"./command.types.ts\";\n\nexport interface Volume {\n  readonly source: string;\n  readonly target: string;\n  readonly readOnly?: boolean;\n}\n\nexport interface SandboxContext {\n  readonly repository: string;\n  readonly directory: string;\n  readonly gitDirectories: readonly string[];\n  readonly variables: Variables;\n  readonly signal?: AbortSignal;\n}\n\nexport interface TransferOptions {\n  readonly signal?: AbortSignal;\n  readonly deadlineMs?: number;\n}\n\nexport interface FileManifestEntry {\n  readonly path: string;\n  readonly kind: \"file\" | \"link\";\n  readonly mode: number;\n  readonly size: number;\n  readonly sha256: string;\n}\n\nexport interface FileTransfers {\n  uploadBatch?(\n    source: string,\n    entries: readonly FileManifestEntry[],\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n  manifest(\n    source: string,\n    paths: readonly string[],\n    options?: TransferOptions,\n  ): Promise<readonly FileManifestEntry[]>;\n  downloadBatch(\n    source: string,\n    entries: readonly FileManifestEntry[],\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n}\n\nexport interface SandboxLease {\n  readonly fileTransfers?: FileTransfers;\n  readonly root: string;\n  readonly home: string;\n  invoke(command: Command): Promise<CommandResult>;\n  upload(\n    source: string,\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n  download(\n    source: string,\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n  release(): Promise<void>;\n}\n\nexport interface SandboxProvider {\n  readonly name: string;\n  readonly placement: \"mounted\" | \"remote\" | \"host\";\n  readonly variables?: Variables;\n  acquire(context: SandboxContext): Promise<SandboxLease>;\n}\n"]}
+{"version":3,"file":"sandbox.types.js","sourceRoot":"","sources":["../../src/domain/sandbox.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Command, CommandResult, Variables } from \"./command.types.ts\";\n\nexport interface Volume {\n  readonly source: string;\n  readonly target: string;\n  readonly readOnly?: boolean;\n}\n\nexport interface SandboxContext {\n  readonly registerRecovery?: (resourceId: string) => Promise<void>;\n  readonly repository: string;\n  readonly directory: string;\n  readonly gitDirectories: readonly string[];\n  readonly variables: Variables;\n  readonly signal?: AbortSignal;\n}\n\nexport interface TransferOptions {\n  readonly signal?: AbortSignal;\n  readonly deadlineMs?: number;\n}\n\nexport interface FileManifestEntry {\n  readonly path: string;\n  readonly kind: \"file\" | \"link\";\n  readonly mode: number;\n  readonly size: number;\n  readonly sha256: string;\n}\n\nexport interface FileTransfers {\n  uploadBatch?(\n    source: string,\n    entries: readonly FileManifestEntry[],\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n  manifest(\n    source: string,\n    paths: readonly string[],\n    options?: TransferOptions,\n  ): Promise<readonly FileManifestEntry[]>;\n  downloadBatch(\n    source: string,\n    entries: readonly FileManifestEntry[],\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n}\n\nexport interface SandboxLease {\n  readonly fileTransfers?: FileTransfers;\n  readonly root: string;\n  readonly home: string;\n  invoke(command: Command): Promise<CommandResult>;\n  upload(\n    source: string,\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n  download(\n    source: string,\n    destination: string,\n    options?: TransferOptions,\n  ): Promise<void>;\n  release(): Promise<void>;\n}\n\nexport interface SandboxProvider {\n  readonly recover?: (\n    resourceId: string,\n    options?: TransferOptions,\n  ) => Promise<void>;\n  readonly name: string;\n  readonly placement: \"mounted\" | \"remote\" | \"host\";\n  readonly variables?: Variables;\n  acquire(context: SandboxContext): Promise<SandboxLease>;\n}\n"]}

package/dist/domain/subagent.constants.d.ts

@@ -0,0 +1,13 @@
+export declare const SUBAGENT_FIELDS: Set<string>;
+export declare const SUBAGENT_INPUT: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+    readonly required: readonly ["prompt"];
+    readonly additionalProperties: false;
+};
+export declare const MAX_DELEGATION_DEPTH = 3;

package/dist/domain/subagent.constants.js

@@ -0,0 +1,9 @@
+export const SUBAGENT_FIELDS = new Set(["name", "description", "agent"]);
+export const SUBAGENT_INPUT = {
+    type: "object",
+    properties: { prompt: { type: "string", minLength: 1 } },
+    required: ["prompt"],
+    additionalProperties: false,
+};
+export const MAX_DELEGATION_DEPTH = 3;
+//# sourceMappingURL=subagent.constants.js.map

package/dist/domain/subagent.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.constants.js","sourceRoot":"","sources":["../../src/domain/subagent.constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;AACzE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE;IACxD,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACpB,oBAAoB,EAAE,KAAK;CACnB,CAAC;AACX,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC","sourcesContent":["export const SUBAGENT_FIELDS = new Set([\"name\", \"description\", \"agent\"]);\nexport const SUBAGENT_INPUT = {\n  type: \"object\",\n  properties: { prompt: { type: \"string\", minLength: 1 } },\n  required: [\"prompt\"],\n  additionalProperties: false,\n} as const;\nexport const MAX_DELEGATION_DEPTH = 3;\n"]}

package/dist/domain/subagent.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessSubagent, HarnessSubagentOptions } from "./subagent.types.ts";
+import type { HarnessTool } from "./tool.types.ts";
+export declare function defineHarnessSubagent(options: HarnessSubagentOptions): HarnessSubagent;
+export declare function isHarnessSubagent(tool: HarnessTool): tool is HarnessSubagent;

package/dist/domain/subagent.js

@@ -0,0 +1,28 @@
+import { agent } from "./agent.js";
+import { invariant, OutpostError } from "./errors.js";
+import { SUBAGENT_FIELDS, SUBAGENT_INPUT } from "./subagent.constants.js";
+import { defineHarnessTool } from "./tool.js";
+export function defineHarnessSubagent(options) {
+    invariant(options !== null && typeof options === "object", "Subagent options must be an object");
+    invariant(Object.keys(options).every((key) => SUBAGENT_FIELDS.has(key)), "Unsupported subagent option");
+    invariant(options.agent?.kind === "custom", "Subagents require a built-in harness agent");
+    const child = agent({
+        harness: options.agent.harness,
+        model: options.agent.model,
+    });
+    return Object.freeze({
+        ...defineHarnessTool({
+            name: options.name,
+            description: options.description,
+            input: SUBAGENT_INPUT,
+            execute() {
+                throw new OutpostError("configuration", "Subagents must be invoked by the harness runtime");
+            },
+        }),
+        subagent: child,
+    });
+}
+export function isHarnessSubagent(tool) {
+    return "subagent" in tool;
+}
+//# sourceMappingURL=subagent.js.map

package/dist/domain/subagent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.js","sourceRoot":"","sources":["../../src/domain/subagent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAM1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG9C,MAAM,UAAU,qBAAqB,CACnC,OAA+B;IAE/B,SAAS,CACP,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAC/C,oCAAoC,CACrC,CAAC;IACF,SAAS,CACP,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAC7D,6BAA6B,CAC9B,CAAC;IACF,SAAS,CACP,OAAO,CAAC,KAAK,EAAE,IAAI,KAAK,QAAQ,EAChC,4CAA4C,CAC7C,CAAC;IACF,MAAM,KAAK,GAAG,KAAK,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK;KAC3B,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,iBAAiB,CAAuB;YACzC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,KAAK,EAAE,cAAc;YACrB,OAAO;gBACL,MAAM,IAAI,YAAY,CACpB,eAAe,EACf,kDAAkD,CACnD,CAAC;YACJ,CAAC;SACF,CAAC;QACF,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,OAAO,UAAU,IAAI,IAAI,CAAC;AAC5B,CAAC","sourcesContent":["import { agent } from \"./agent.ts\";\nimport { invariant, OutpostError } from \"./errors.ts\";\nimport { SUBAGENT_FIELDS, SUBAGENT_INPUT } from \"./subagent.constants.ts\";\nimport type {\n  HarnessSubagent,\n  HarnessSubagentInput,\n  HarnessSubagentOptions,\n} from \"./subagent.types.ts\";\nimport { defineHarnessTool } from \"./tool.ts\";\nimport type { HarnessTool } from \"./tool.types.ts\";\n\nexport function defineHarnessSubagent(\n  options: HarnessSubagentOptions,\n): HarnessSubagent {\n  invariant(\n    options !== null && typeof options === \"object\",\n    \"Subagent options must be an object\",\n  );\n  invariant(\n    Object.keys(options).every((key) => SUBAGENT_FIELDS.has(key)),\n    \"Unsupported subagent option\",\n  );\n  invariant(\n    options.agent?.kind === \"custom\",\n    \"Subagents require a built-in harness agent\",\n  );\n  const child = agent({\n    harness: options.agent.harness,\n    model: options.agent.model,\n  });\n  return Object.freeze({\n    ...defineHarnessTool<HarnessSubagentInput>({\n      name: options.name,\n      description: options.description,\n      input: SUBAGENT_INPUT,\n      execute() {\n        throw new OutpostError(\n          \"configuration\",\n          \"Subagents must be invoked by the harness runtime\",\n        );\n      },\n    }),\n    subagent: child,\n  });\n}\n\nexport function isHarnessSubagent(tool: HarnessTool): tool is HarnessSubagent {\n  return \"subagent\" in tool;\n}\n"]}

package/dist/domain/subagent.types.d.ts

@@ -0,0 +1,13 @@
+import type { CustomAgent } from "./agent.types.ts";
+import type { HarnessTool } from "./tool.types.ts";
+export interface HarnessSubagentInput {
+    readonly prompt: string;
+}
+export interface HarnessSubagentOptions {
+    readonly name: string;
+    readonly description: string;
+    readonly agent: CustomAgent;
+}
+export interface HarnessSubagent extends HarnessTool<HarnessSubagentInput> {
+    readonly subagent: CustomAgent;
+}

package/dist/domain/subagent.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=subagent.types.js.map

package/dist/domain/subagent.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.types.js","sourceRoot":"","sources":["../../src/domain/subagent.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { CustomAgent } from \"./agent.types.ts\";\nimport type { HarnessTool } from \"./tool.types.ts\";\n\nexport interface HarnessSubagentInput {\n  readonly prompt: string;\n}\n\nexport interface HarnessSubagentOptions {\n  readonly name: string;\n  readonly description: string;\n  readonly agent: CustomAgent;\n}\n\nexport interface HarnessSubagent extends HarnessTool<HarnessSubagentInput> {\n  readonly subagent: CustomAgent;\n}\n"]}

package/dist/domain/transcript.types.d.ts

@@ -5,6 +5,8 @@ export type TranscriptRecord = {
     readonly id: string;
     readonly model: string;
     readonly parent?: string;
+    readonly parentConversation?: string;
+    readonly parentCallId?: string;
     readonly createdAt: string;
 } | {
     readonly type: "message";

package/dist/domain/transcript.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.types.js","sourceRoot":"","sources":["../../src/domain/transcript.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ModelMessage } from \"./model.types.ts\";\n\nexport type TranscriptRecord =\n  | {\n      readonly type: \"session\";\n      readonly version: 1;\n      readonly id: string;\n      readonly model: string;\n      readonly parent?: string;\n      readonly createdAt: string;\n    }\n  | { readonly type: \"message\"; readonly message: ModelMessage }\n  | { readonly type: \"compaction\"; readonly messages: readonly ModelMessage[] };\n"]}
+{"version":3,"file":"transcript.types.js","sourceRoot":"","sources":["../../src/domain/transcript.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ModelMessage } from \"./model.types.ts\";\n\nexport type TranscriptRecord =\n  | {\n      readonly type: \"session\";\n      readonly version: 1;\n      readonly id: string;\n      readonly model: string;\n      readonly parent?: string;\n      readonly parentConversation?: string;\n      readonly parentCallId?: string;\n      readonly createdAt: string;\n    }\n  | { readonly type: \"message\"; readonly message: ModelMessage }\n  | { readonly type: \"compaction\"; readonly messages: readonly ModelMessage[] };\n"]}

package/dist/domain/usage.d.ts

@@ -1,2 +1,3 @@
 import type { Usage } from "./agent.types.ts";
 export declare function addUsage(left: Usage, right: Usage): Usage;
+export declare function usageDifference(next: Usage, previous: Usage): Usage;

package/dist/domain/usage.js

@@ -3,9 +3,25 @@ export function addUsage(left, right) {
         input: left.input + right.input,
         cached: left.cached + right.cached,
         output: left.output + right.output,
+        ...(left.complete === false || right.complete === false
+            ? { complete: false }
+            : {}),
         ...(left.cacheCreated !== undefined || right.cacheCreated !== undefined
             ? { cacheCreated: (left.cacheCreated ?? 0) + (right.cacheCreated ?? 0) }
             : {}),
     };
 }
+export function usageDifference(next, previous) {
+    return {
+        input: Math.max(0, next.input - previous.input),
+        cached: Math.max(0, next.cached - previous.cached),
+        output: Math.max(0, next.output - previous.output),
+        ...(next.cacheCreated !== undefined || previous.cacheCreated !== undefined
+            ? {
+                cacheCreated: Math.max(0, (next.cacheCreated ?? 0) - (previous.cacheCreated ?? 0)),
+            }
+            : {}),
+        ...(next.complete === false ? { complete: false } : {}),
+    };
+}
 //# sourceMappingURL=usage.js.map

package/dist/domain/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/domain/usage.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,QAAQ,CAAC,IAAW,EAAE,KAAY;IAChD,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK;QAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QAClC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QAClC,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;YACrE,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,EAAE;YACxE,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC","sourcesContent":["import type { Usage } from \"./agent.types.ts\";\n\nexport function addUsage(left: Usage, right: Usage): Usage {\n  return {\n    input: left.input + right.input,\n    cached: left.cached + right.cached,\n    output: left.output + right.output,\n    ...(left.cacheCreated !== undefined || right.cacheCreated !== undefined\n      ? { cacheCreated: (left.cacheCreated ?? 0) + (right.cacheCreated ?? 0) }\n      : {}),\n  };\n}\n"]}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/domain/usage.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,QAAQ,CAAC,IAAW,EAAE,KAAY;IAChD,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK;QAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QAClC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QAClC,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK;YACrD,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE;YACrB,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;YACrE,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,EAAE;YACxE,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAW,EAAE,QAAe;IAC1D,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC/C,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAClD,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAClD,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS;YACxE,CAAC,CAAC;gBACE,YAAY,EAAE,IAAI,CAAC,GAAG,CACpB,CAAC,EACD,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAC,CACxD;aACF;YACH,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC","sourcesContent":["import type { Usage } from \"./agent.types.ts\";\n\nexport function addUsage(left: Usage, right: Usage): Usage {\n  return {\n    input: left.input + right.input,\n    cached: left.cached + right.cached,\n    output: left.output + right.output,\n    ...(left.complete === false || right.complete === false\n      ? { complete: false }\n      : {}),\n    ...(left.cacheCreated !== undefined || right.cacheCreated !== undefined\n      ? { cacheCreated: (left.cacheCreated ?? 0) + (right.cacheCreated ?? 0) }\n      : {}),\n  };\n}\n\nexport function usageDifference(next: Usage, previous: Usage): Usage {\n  return {\n    input: Math.max(0, next.input - previous.input),\n    cached: Math.max(0, next.cached - previous.cached),\n    output: Math.max(0, next.output - previous.output),\n    ...(next.cacheCreated !== undefined || previous.cacheCreated !== undefined\n      ? {\n          cacheCreated: Math.max(\n            0,\n            (next.cacheCreated ?? 0) - (previous.cacheCreated ?? 0),\n          ),\n        }\n      : {}),\n    ...(next.complete === false ? { complete: false } : {}),\n  };\n}\n"]}

package/dist/domain/workflow/budget.d.ts

@@ -1,9 +1,13 @@
 import type { Usage } from "../agent.types.ts";
 import type { WorkflowAccounting, WorkflowBudget, WorkflowUsage } from "./budget.types.ts";
 export declare class WorkflowBudgetExceeded extends Error {
-    readonly dimension: "attempts" | keyof Usage;
+    readonly dimension: "attempts" | Exclude<keyof Usage, "complete">;
     readonly limit: number;
     readonly observed: number;
-    constructor(dimension: "attempts" | keyof Usage, limit: number, observed: number);
+    constructor(dimension: "attempts" | Exclude<keyof Usage, "complete">, limit: number, observed: number);
 }
-export declare function workflowAccounting(budget: WorkflowBudget | undefined, exhaust: (error: WorkflowBudgetExceeded) => void, initial?: WorkflowUsage): WorkflowAccounting;
+export declare class WorkflowUsageUnavailable extends Error {
+    readonly dimension = "usage";
+    constructor();
+}
+export declare function workflowAccounting(budget: WorkflowBudget | undefined, exhaust: (error: WorkflowBudgetExceeded | WorkflowUsageUnavailable) => void, initial?: WorkflowUsage): WorkflowAccounting;

package/dist/domain/workflow/budget.js

@@ -12,6 +12,13 @@ export class WorkflowBudgetExceeded extends Error {
         this.observed = observed;
     }
 }
+export class WorkflowUsageUnavailable extends Error {
+    dimension = "usage";
+    constructor() {
+        super("Token usage is incomplete; configure budget.attempts and task timeouts or dispatch deadlines before continuing");
+        this.name = "WorkflowUsageUnavailable";
+    }
+}
 export function workflowAccounting(budget, exhaust, initial) {
     for (const [key, value] of Object.entries({
         attempts: budget?.attempts,
@@ -36,11 +43,27 @@ export function workflowAccounting(budget, exhaust, initial) {
         }
         return error;
     }
+    function checkCompleteness() {
+        if (tokens.complete !== false ||
+            budget?.attempts !== undefined ||
+            !usageDimensions.some((dimension) => budget?.usage?.[dimension] !== undefined))
+            return;
+        const error = new WorkflowUsageUnavailable();
+        if (!usageExhausted) {
+            exhausted = true;
+            usageExhausted = true;
+            exhaust(error);
+        }
+        return error;
+    }
     return {
         get exhausted() {
             return exhausted;
         },
         admit() {
+            const unavailable = checkCompleteness();
+            if (unavailable)
+                throw unavailable;
             if (budget?.attempts !== undefined && attempts >= budget.attempts)
                 throw fail("attempts", budget.attempts, attempts);
             for (const dimension of usageDimensions) {
@@ -51,12 +74,15 @@ export function workflowAccounting(budget, exhaust, initial) {
             attempts++;
         },
         report(usage) {
+            if (usage.complete !== undefined && typeof usage.complete !== "boolean")
+                throw new Error("Reported usage complete must be a boolean");
             for (const dimension of usageDimensions) {
                 const value = usage[dimension] ?? 0;
                 if (!Number.isSafeInteger(value) || value < 0)
                     throw new Error(`Reported usage ${dimension} must be a nonnegative safe integer`);
             }
             tokens = addUsage(tokens, usage);
+            checkCompleteness();
             for (const dimension of usageDimensions) {
                 const limit = budget?.usage?.[dimension];
                 if (limit !== undefined && (tokens[dimension] ?? 0) >= limit)