@alpacakit/agents 0.1.0-beta.19

package/dist/kernel/handle.js

@@ -0,0 +1,97 @@
+/**
+ * RunHandle internals: a bounded-replay broadcast and an awaitable
+ * handle (`then` delegates to `result`). Not consuming events never
+ * blocks the run. Subscribers attached while the run streams receive
+ * every event live; a LATE subscriber gets the retained replay window —
+ * bounded by payload bytes so a verbose run cannot hold its whole
+ * output in memory a second time (the capped raw transcript already
+ * lives on the result).
+ */
+import { AsyncQueue } from "../core/async-queue.js";
+import { AGENT_EVENT_TYPE } from "../core/run.js";
+const DEFAULT_REPLAY_BUDGET_BYTES = 4 * 1024 * 1024;
+const EVENT_BASE_COST_BYTES = 64;
+function replayCost(event) {
+    if (event.type === AGENT_EVENT_TYPE.output) {
+        return EVENT_BASE_COST_BYTES + event.chunk.length;
+    }
+    if (event.type === AGENT_EVENT_TYPE.message) {
+        return EVENT_BASE_COST_BYTES + event.text.length;
+    }
+    return EVENT_BASE_COST_BYTES;
+}
+export class EventBroadcast {
+    replayBudgetBytes;
+    eventCost;
+    history = [];
+    historyStart = 0;
+    retainedBytes = 0;
+    subscribers = new Set();
+    ended = false;
+    constructor(replayBudgetBytes = DEFAULT_REPLAY_BUDGET_BYTES, eventCost = replayCost) {
+        this.replayBudgetBytes = replayBudgetBytes;
+        this.eventCost = eventCost;
+    }
+    push(event) {
+        if (this.ended) {
+            return;
+        }
+        this.history.push(event);
+        this.retainedBytes += this.eventCost(event);
+        this.evictOverBudget();
+        for (const queue of this.subscribers) {
+            queue.push(event);
+        }
+    }
+    /** The most recent event always survives, however large. */
+    evictOverBudget() {
+        while (this.retainedBytes > this.replayBudgetBytes &&
+            this.historyStart < this.history.length - 1) {
+            const evicted = this.history[this.historyStart];
+            if (evicted === undefined) {
+                break;
+            }
+            this.retainedBytes -= this.eventCost(evicted);
+            this.historyStart += 1;
+        }
+        if (this.historyStart > 0 && this.historyStart * 2 >= this.history.length) {
+            this.history = this.history.slice(this.historyStart);
+            this.historyStart = 0;
+        }
+    }
+    end() {
+        this.ended = true;
+        for (const queue of this.subscribers) {
+            queue.end();
+        }
+        this.subscribers.clear();
+    }
+    get events() {
+        return {
+            [Symbol.asyncIterator]: () => {
+                const queue = new AsyncQueue();
+                for (const event of this.history.slice(this.historyStart)) {
+                    queue.push(event);
+                }
+                if (this.ended) {
+                    queue.end();
+                }
+                else {
+                    this.subscribers.add(queue);
+                }
+                return queue[Symbol.asyncIterator]();
+            },
+        };
+    }
+}
+export function createRunHandle(runId, broadcast, result) {
+    // A consumer may only iterate events; keep its rejection observed.
+    result.catch(() => { });
+    return {
+        runId,
+        events: broadcast.events,
+        result,
+        // biome-ignore lint/suspicious/noThenProperty: RunHandle is deliberately awaitable — `await handle` is the documented shorthand for `await handle.result`.
+        then: (onFulfilled, onRejected) => result.then(onFulfilled, onRejected),
+    };
+}

package/dist/kernel/keyed.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Keyed handler record dispatch (design principle 7): key presence
+ * declares support; absence is a typed `invalid_input`, enforced here
+ * for every dispatch site (sandbox argv, auth materials, skill sources,
+ * MCP transports). The record's mapped type proves the handler at key K
+ * takes the K-narrowed variant; the widening casts in this module are
+ * the ONE place that correlation is asserted instead of proven to the
+ * compiler.
+ */
+export declare function keyedHandler<Wide>(record: object, key: string): Wide | null;
+/**
+ * Dispatch over a TOTAL keyed record: the caller proves (via `satisfies`
+ * on a mapped registry type) that every key of the discriminant union is
+ * present, so lookup by a variant's kind always succeeds and no typed
+ * "unsupported" arm exists.
+ */
+export declare function totalKeyedHandler<Wide>(record: object, key: string): Wide;
+export declare function requireKeyedHandler<Wide>(record: object, key: string, agentId: string, what: string): Wide;
+//# sourceMappingURL=keyed.d.ts.map

package/dist/kernel/keyed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed.d.ts","sourceRoot":"","sources":["../../src/kernel/keyed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAG3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EACtC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,IAAI,CAWN"}

package/dist/kernel/keyed.js

@@ -0,0 +1,35 @@
+/**
+ * Keyed handler record dispatch (design principle 7): key presence
+ * declares support; absence is a typed `invalid_input`, enforced here
+ * for every dispatch site (sandbox argv, auth materials, skill sources,
+ * MCP transports). The record's mapped type proves the handler at key K
+ * takes the K-narrowed variant; the widening casts in this module are
+ * the ONE place that correlation is asserted instead of proven to the
+ * compiler.
+ */
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+export function keyedHandler(record, key) {
+    const handler = record[key];
+    return handler ?? null;
+}
+/**
+ * Dispatch over a TOTAL keyed record: the caller proves (via `satisfies`
+ * on a mapped registry type) that every key of the discriminant union is
+ * present, so lookup by a variant's kind always succeeds and no typed
+ * "unsupported" arm exists.
+ */
+export function totalKeyedHandler(record, key) {
+    return record[key];
+}
+export function requireKeyedHandler(record, key, agentId, what) {
+    const handler = keyedHandler(record, key);
+    if (handler === null) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.invalidInput,
+            message: `Agent "${agentId}" does not support ${what}`,
+            data: { reason: `unsupported: ${what}` },
+            agentId,
+        });
+    }
+    return handler;
+}

package/dist/kernel/login.d.ts

@@ -0,0 +1,20 @@
+import type { LoginHandle, LoginHandler, LoginRequest } from "../auth/login.js";
+import type { HostContext } from "../host/context.js";
+type StartLoginInput = {
+    readonly agentId: string;
+    readonly request: LoginRequest;
+    readonly ctx: HostContext;
+    readonly handler: LoginHandler;
+    /** Caller cancellation; `null` when the caller passed no signal. */
+    readonly callerSignal: AbortSignal | null;
+};
+/**
+ * Drive a login handler's generator: tee each event to the broadcast, return
+ * the outcome, and end the stream in `finally`. The run plane's `RunDriver`
+ * earns a class (timers, guards, abort); login is a linear flow, so it is a
+ * function. Errors cross the boundary as `AgentError`, stamped with the agent
+ * id the handler could not know.
+ */
+export declare function startLogin(input: StartLoginInput): LoginHandle;
+export {};
+//# sourceMappingURL=login.d.ts.map

package/dist/kernel/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/kernel/login.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,WAAW,EACX,YAAY,EAEZ,YAAY,EACb,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,KAAK,eAAe,GAAG;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,WAAW,CAW9D"}

package/dist/kernel/login.js

@@ -0,0 +1,74 @@
+import { AGENT_ERROR_CODE, AgentError, isAgentError } from "../core/error.js";
+import { redactSecrets } from "../core/redact.js";
+import { EventBroadcast } from "./handle.js";
+/**
+ * Drive a login handler's generator: tee each event to the broadcast, return
+ * the outcome, and end the stream in `finally`. The run plane's `RunDriver`
+ * earns a class (timers, guards, abort); login is a linear flow, so it is a
+ * function. Errors cross the boundary as `AgentError`, stamped with the agent
+ * id the handler could not know.
+ */
+export function startLogin(input) {
+    const broadcast = new EventBroadcast();
+    const result = driveLogin(input, broadcast);
+    // A consumer may only iterate events; keep its rejection observed.
+    result.catch(() => { });
+    return {
+        events: broadcast.events,
+        result,
+        // biome-ignore lint/suspicious/noThenProperty: LoginHandle mirrors RunHandle — `await handle` delegates to `result`.
+        then: (onFulfilled, onRejected) => result.then(onFulfilled, onRejected),
+    };
+}
+async function driveLogin(input, broadcast) {
+    const ctx = {
+        location: input.ctx.location,
+        // Login's only stop source is the caller signal — its total timeout lives in
+        // the handler and there are no guards. So, unlike `RunDriver` (which owns a
+        // controller to merge caller + timeout + guard trips into one signal), the
+        // driver funnels the caller signal straight through. A never-aborting signal
+        // keeps `ctx.signal` always live when the caller passed none — mirroring
+        // `RunContext.signal` — so handlers never branch on its presence.
+        signal: input.callerSignal ?? new AbortController().signal,
+        env: input.ctx.env,
+        exec: input.ctx.exec,
+        clock: input.ctx.clock,
+    };
+    try {
+        const generator = input.handler(input.request, ctx);
+        let step = await generator.next();
+        while (!step.done) {
+            broadcast.push(step.value);
+            step = await generator.next();
+        }
+        return step.value;
+    }
+    catch (thrown) {
+        throw toLoginError(input.agentId, thrown);
+    }
+    finally {
+        broadcast.end();
+    }
+}
+function toLoginError(agentId, thrown) {
+    if (isAgentError(thrown)) {
+        return thrown.agentId === null ? withAgentId(thrown, agentId) : thrown;
+    }
+    const message = thrown instanceof Error ? thrown.message : String(thrown);
+    return new AgentError({
+        code: AGENT_ERROR_CODE.failed,
+        message: redactSecrets(message),
+        data: { exitCode: null, stdoutTail: null, stderrTail: null },
+        cause: thrown,
+        agentId,
+    });
+}
+function withAgentId(error, agentId) {
+    return new AgentError({
+        code: error.code,
+        message: error.message,
+        data: error.data,
+        agentId,
+        cause: error.cause,
+    });
+}

package/dist/kernel/options.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Inbound run options (rule 1: `?` = "use the documented default"),
+ * normalized exactly once into the resolved twins (rule 2) — agent
+ * definitions only ever see the resolved types.
+ */
+import { type EnvPatch } from "../core/env.js";
+import type { GuardFactory } from "./guard.js";
+export declare const GRANT_KIND: {
+    readonly shell: "shell";
+    readonly tool: "tool";
+};
+export type Grant = {
+    kind: typeof GRANT_KIND.shell;
+    command: string;
+} | {
+    kind: typeof GRANT_KIND.tool;
+    name: string;
+};
+export declare const SANDBOX_MODE: {
+    readonly full: "full";
+    readonly readOnly: "read-only";
+};
+export type SandboxMode = (typeof SANDBOX_MODE)[keyof typeof SANDBOX_MODE];
+export type Sandbox = {
+    mode: typeof SANDBOX_MODE.full;
+} | {
+    mode: typeof SANDBOX_MODE.readOnly;
+    grants?: Grant[];
+};
+export type ResolvedSandbox = {
+    mode: typeof SANDBOX_MODE.full;
+} | {
+    mode: typeof SANDBOX_MODE.readOnly;
+    grants: Grant[];
+};
+/** Omission means no limit: the kernel never imposes an unasked timeout. */
+export type Limits = {
+    totalMs?: number;
+    idleMs?: number;
+    guards?: GuardFactory[];
+};
+export type ResolvedLimits = {
+    totalMs: number | null;
+    idleMs: number | null;
+    guards: GuardFactory[];
+};
+type BaseRunOptions = {
+    prompt: string;
+    workspace: string;
+    model?: string;
+    effort?: string;
+    sandbox?: Sandbox;
+    env?: EnvPatch;
+    limits?: Limits;
+    signal?: AbortSignal;
+};
+export type RunOptions = BaseRunOptions & {
+    contract?: never;
+};
+export type ResolvedRunOptions = {
+    prompt: string;
+    workspace: string;
+    model: string | null;
+    effort: string | null;
+    sandbox: ResolvedSandbox;
+    env: EnvPatch;
+    limits: ResolvedLimits;
+};
+export declare function resolveSandbox(sandbox: Sandbox | undefined): ResolvedSandbox;
+export declare function resolveLimits(limits: Limits | undefined): ResolvedLimits;
+export declare function resolveRunOptions(options: RunOptions): ResolvedRunOptions;
+export {};
+//# sourceMappingURL=options.d.ts.map

package/dist/kernel/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/kernel/options.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,UAAU;;;CAGb,CAAC;AAEX,MAAM,MAAM,KAAK,GACb;IAAE,IAAI,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,UAAU,CAAC,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,IAAI,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAE7D,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,IAAI,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAE5D,4EAA4E;AAC5E,MAAM,MAAM,MAAM,GAAG;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG;IACxC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;IACzB,GAAG,EAAE,QAAQ,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;CACxB,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,eAAe,CAQ5E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAMxE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,kBAAkB,CAUzE"}

package/dist/kernel/options.js

@@ -0,0 +1,41 @@
+/**
+ * Inbound run options (rule 1: `?` = "use the documented default"),
+ * normalized exactly once into the resolved twins (rule 2) — agent
+ * definitions only ever see the resolved types.
+ */
+import { EMPTY_ENV_PATCH } from "../core/env.js";
+export const GRANT_KIND = {
+    shell: "shell",
+    tool: "tool",
+};
+export const SANDBOX_MODE = {
+    full: "full",
+    readOnly: "read-only",
+};
+export function resolveSandbox(sandbox) {
+    if (sandbox === undefined) {
+        return { mode: SANDBOX_MODE.full };
+    }
+    if (sandbox.mode === SANDBOX_MODE.full) {
+        return { mode: SANDBOX_MODE.full };
+    }
+    return { mode: SANDBOX_MODE.readOnly, grants: sandbox.grants ?? [] };
+}
+export function resolveLimits(limits) {
+    return {
+        totalMs: limits?.totalMs ?? null,
+        idleMs: limits?.idleMs ?? null,
+        guards: limits?.guards ?? [],
+    };
+}
+export function resolveRunOptions(options) {
+    return {
+        prompt: options.prompt,
+        workspace: options.workspace,
+        model: options.model ?? null,
+        effort: options.effort ?? null,
+        sandbox: resolveSandbox(options.sandbox),
+        env: options.env ?? EMPTY_ENV_PATCH,
+        limits: resolveLimits(options.limits),
+    };
+}

package/dist/kernel/run.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The run driver: drives an adapter generator exactly once, brackets the
+ * stream with `started`/`ended`, tees every event to the handle,
+ * telemetry, and the guard observers, and enforces limits centrally by
+ * tripping one internal abort. Adapters implement exactly one behavior:
+ * stop on abort.
+ */
+import type { Ports } from "../core/ports.js";
+import type { RunHandle } from "../core/run.js";
+import type { AgentDefinition } from "./definition.js";
+import type { ResolvedRunOptions } from "./options.js";
+export type StartRunInput = {
+    definition: AgentDefinition;
+    options: ResolvedRunOptions;
+    callerSignal: AbortSignal | null;
+    env: Record<string, string>;
+    ports: Ports;
+};
+export declare function startRun(input: StartRunInput): RunHandle;
+//# sourceMappingURL=run.d.ts.map

package/dist/kernel/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/kernel/run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAIV,SAAS,EAEV,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,iBAAiB,CAAC;AAGnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AASvD,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AA4QF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAExD"}

package/dist/kernel/run.js

@@ -0,0 +1,245 @@
+/**
+ * The run driver: drives an adapter generator exactly once, brackets the
+ * stream with `started`/`ended`, tees every event to the handle,
+ * telemetry, and the guard observers, and enforces limits centrally by
+ * tripping one internal abort. Adapters implement exactly one behavior:
+ * stop on abort.
+ */
+import { randomUUID } from "node:crypto";
+import { AGENT_ERROR_CODE, AgentError, isAgentError, TIMEOUT_KIND, withRunIdentity, } from "../core/error.js";
+import { redactSecrets } from "../core/redact.js";
+import { RUN_EVENT_TYPE, RUN_OUTCOME } from "../core/run.js";
+import { createRunHandle, EventBroadcast } from "./handle.js";
+const GUARD_POLL_MS = 1_000;
+const RUN_TRIP_KIND = {
+    timeout: "timeout",
+    limit: "limit",
+    cancelled: "cancelled",
+};
+function scopedLogger(logger, runId) {
+    return {
+        log: (level, message, data) => logger.log(level, `[run ${runId}] ${message}`, data),
+    };
+}
+class RunDriver {
+    input;
+    runId = randomUUID();
+    broadcast = new EventBroadcast();
+    controller = new AbortController();
+    guards;
+    cancels = [];
+    cancelIdle = null;
+    tripReason = null;
+    agentStarted = false;
+    settled = false;
+    startedAtMs;
+    constructor(input) {
+        this.input = input;
+        this.startedAtMs = input.ports.clock.now();
+        this.guards = input.options.limits.guards.map((factory) => factory({ clock: input.ports.clock }));
+    }
+    start() {
+        this.installCallerSignal();
+        this.installTimers();
+        return createRunHandle(this.runId, this.broadcast, this.execute());
+    }
+    trip(reason) {
+        if (this.tripReason !== null || this.settled) {
+            return;
+        }
+        this.tripReason = reason;
+        this.controller.abort();
+    }
+    installCallerSignal() {
+        const signal = this.input.callerSignal;
+        if (signal === null) {
+            return;
+        }
+        const cancel = () => this.trip({
+            kind: RUN_TRIP_KIND.cancelled,
+            reason: typeof signal.reason === "string" ? signal.reason : null,
+        });
+        if (signal.aborted) {
+            cancel();
+            return;
+        }
+        signal.addEventListener("abort", cancel, { once: true });
+        this.cancels.push(() => signal.removeEventListener("abort", cancel));
+    }
+    installTimers() {
+        const { clock } = this.input.ports;
+        const { totalMs, idleMs } = this.input.options.limits;
+        if (totalMs !== null) {
+            this.cancels.push(clock.setTimeout(() => this.trip({
+                kind: RUN_TRIP_KIND.timeout,
+                timeoutKind: TIMEOUT_KIND.total,
+                limitMs: totalMs,
+            }), totalMs));
+        }
+        if (idleMs !== null) {
+            this.resetIdleTimer(idleMs);
+        }
+        if (this.guards.length > 0) {
+            this.scheduleGuardPoll();
+        }
+    }
+    resetIdleTimer(idleMs) {
+        this.cancelIdle?.();
+        this.cancelIdle = this.input.ports.clock.setTimeout(() => this.trip({
+            kind: RUN_TRIP_KIND.timeout,
+            timeoutKind: TIMEOUT_KIND.idle,
+            limitMs: idleMs,
+        }), idleMs);
+    }
+    scheduleGuardPoll() {
+        const poll = () => {
+            if (this.settled || this.tripReason !== null) {
+                return;
+            }
+            this.checkGuards();
+            this.cancels.push(this.input.ports.clock.setTimeout(poll, GUARD_POLL_MS));
+        };
+        this.cancels.push(this.input.ports.clock.setTimeout(poll, GUARD_POLL_MS));
+    }
+    checkGuards() {
+        for (const guard of this.guards) {
+            const violation = guard.violation();
+            if (violation !== null) {
+                this.trip({ kind: RUN_TRIP_KIND.limit, violation });
+                return;
+            }
+        }
+    }
+    emit(event) {
+        this.broadcast.push(event);
+        this.input.ports.telemetry.emit({
+            runId: this.runId,
+            agentId: this.input.definition.id,
+            event,
+        });
+        for (const guard of this.guards) {
+            guard.observe(event);
+        }
+        this.checkGuards();
+    }
+    emitAgentEvent(event) {
+        this.agentStarted = true;
+        const idleMs = this.input.options.limits.idleMs;
+        if (idleMs !== null) {
+            this.resetIdleTimer(idleMs);
+        }
+        this.emit(event);
+    }
+    async execute() {
+        const { definition, options, env, ports } = this.input;
+        this.emit({ type: RUN_EVENT_TYPE.started, model: options.model });
+        const ctx = {
+            signal: this.controller.signal,
+            env,
+            exec: ports.exec,
+            http: ports.http,
+            clock: ports.clock,
+            logger: scopedLogger(ports.logger, this.runId),
+        };
+        try {
+            const generator = definition.run(options, ctx);
+            let step = await generator.next();
+            while (!step.done) {
+                this.emitAgentEvent(step.value);
+                step = await generator.next();
+            }
+            if (this.tripReason !== null) {
+                throw this.errorFromTrip(this.tripReason);
+            }
+            const result = this.buildResult(step.value);
+            this.emit({ type: RUN_EVENT_TYPE.ended, outcome: RUN_OUTCOME.completed });
+            return result;
+        }
+        catch (thrown) {
+            const error = this.toAgentError(thrown);
+            this.emit({
+                type: RUN_EVENT_TYPE.ended,
+                outcome: error.code === AGENT_ERROR_CODE.cancelled
+                    ? RUN_OUTCOME.cancelled
+                    : RUN_OUTCOME.failed,
+            });
+            throw error;
+        }
+        finally {
+            this.settled = true;
+            this.cancelIdle?.();
+            for (const cancel of this.cancels.splice(0)) {
+                cancel();
+            }
+            this.broadcast.end();
+        }
+    }
+    buildResult(outcome) {
+        const endedAtMs = this.input.ports.clock.now();
+        return {
+            runId: this.runId,
+            text: outcome.text,
+            agentId: this.input.definition.id,
+            model: outcome.model ?? this.input.options.model,
+            timing: {
+                startedAt: new Date(this.startedAtMs).toISOString(),
+                endedAt: new Date(endedAtMs).toISOString(),
+                durationMs: endedAtMs - this.startedAtMs,
+            },
+            exit: outcome.exit,
+            raw: outcome.raw,
+            usage: outcome.usage,
+        };
+    }
+    identity() {
+        return {
+            runId: this.runId,
+            agentId: this.input.definition.id,
+            started: this.agentStarted,
+            durationMs: this.input.ports.clock.now() - this.startedAtMs,
+        };
+    }
+    errorFromTrip(trip) {
+        if (trip.kind === RUN_TRIP_KIND.timeout) {
+            return new AgentError({
+                code: AGENT_ERROR_CODE.timeout,
+                message: `Run exceeded its ${trip.timeoutKind} timeout of ${trip.limitMs}ms`,
+                data: { kind: trip.timeoutKind, limitMs: trip.limitMs },
+                ...this.identity(),
+            });
+        }
+        if (trip.kind === RUN_TRIP_KIND.limit) {
+            return new AgentError({
+                code: AGENT_ERROR_CODE.limit,
+                message: `Guard "${trip.violation.guardId}" tripped: ${trip.violation.reason}`,
+                data: { violation: trip.violation },
+                ...this.identity(),
+            });
+        }
+        return new AgentError({
+            code: AGENT_ERROR_CODE.cancelled,
+            message: "Run was cancelled",
+            data: { reason: trip.reason },
+            ...this.identity(),
+        });
+    }
+    toAgentError(thrown) {
+        if (this.tripReason !== null) {
+            return this.errorFromTrip(this.tripReason);
+        }
+        if (isAgentError(thrown)) {
+            return withRunIdentity(thrown, this.identity());
+        }
+        const message = thrown instanceof Error ? thrown.message : String(thrown);
+        return new AgentError({
+            code: AGENT_ERROR_CODE.failed,
+            message: redactSecrets(message),
+            data: { exitCode: null, stdoutTail: null, stderrTail: null },
+            cause: thrown,
+            ...this.identity(),
+        });
+    }
+}
+export function startRun(input) {
+    return new RunDriver(input).start();
+}