aec-agent 1.0.1 → 1.0.4

package/dist/components/multi-agent-orchestration/agent/job-manager/job-manager.js

@@ -0,0 +1,1207 @@
+import { randomUUID } from "node:crypto";
+import { SDKError } from "../../../../kernel/errors/sdk-error.js";
+import { JobError } from "../../../../kernel/errors/job-error.js";
+import { SDKEventType } from "../../../event-handler/events.js";
+import { JobClock } from "./clock.js";
+import { armTimer } from "./timers.js";
+import { INTERNAL_BUS_EVENT_TYPES, internalEnvelope, resolvedSince } from "./internal-events.js";
+import { DEFAULT_MAX_RUN_MS, DEFAULT_PAUSE_AFTER_FAILURES, MAX_EVENT_DATA_BYTES, MAX_JOBS_PER_AGENT, MAX_WEBHOOK_BODY_BYTES, canonicalJson, dataBytes, defaultLimits, filterMismatch, renderJobPrompt, replyOutcome, resolveCoalesce, resolveLimits, toRevision, toSubject, typeMatches, usesRunHistory, validateCreateInput, validateJobAction, validateJobDeliveries, validateJobDescription, validateJobFilter, validateJobName, validatePromptFor, validateJobWhen, validateSessionMode, } from "./rules.js";
+import { describeSchedule } from "./schedule.js";
+import { generateWebhookSecret, parseWebhookEvent, verifyWebhookSignature } from "./webhook.js";
+import { isScheduleWhen, } from "./types.js";
+/** How long a claimed run is leased; renewed every third of it while the turn runs. */
+export const JOB_LEASE_MS = 60_000;
+/** How often the worker looks for due runs it was not told about (other processes, expired leases). */
+export const JOB_POLL_MS = 10_000;
+/** First retry delay; doubles per attempt, with ±25% jitter, at most 15 minutes. */
+export const JOB_RETRY_BASE_MS = 30_000;
+/** Job runs of one agent at once in this process. */
+export const MAX_PARALLEL_JOB_RUNS = 4;
+/** History kept per job. */
+export const KEEP_JOB_EVENTS = 200;
+export const KEEP_JOB_RUNS = 100;
+const MAX_RETRY_DELAY_MS = 15 * 60_000;
+const MAX_OUTPUT_CHARS = 100_000;
+/** A-103: most of a failed tool's output put into the run's error (the session keeps all of it). */
+const MAX_TOOL_ERROR_CHARS = 2_000;
+const HOUR = 60 * 60_000;
+const DAY = 24 * HOUR;
+/**
+ * One agent's event triggers (A-70): takes events into the durable inbox and
+ * runs them as agent turns.
+ *
+ *  - Intake: the agent's own SDK events (pub-sub, never a direct call from the
+ *    scheduler or channels), signed webhooks (handleWebhook) and test events go
+ *    through one path: filter → loop guard → TriggerStore.accept() (dedupe +
+ *    coalesce into a run, atomically).
+ *  - Worker: claims due runs with a lease (TriggerStore.claim), so a run is
+ *    worked by one worker at a time and a run whose worker died is taken over
+ *    when its lease expires. Before a turn it re-checks the trigger (deleted,
+ *    disabled, changed), stale revisions, a resolved condition and the rate and
+ *    token limits. The turn goes through the host's TriggerRunner in a fresh
+ *    session; per-session ordering and the agent's turn cap apply as for any turn,
+ *    and runs leave a turn free for people's chats.
+ *  - Results: the reply is checkpointed before the run is marked finished, so a
+ *    crash in between only re-records the result, it does not re-run the turn.
+ *    Transient failures retry with backoff within maxAttempts and the run's
+ *    deadline. Approvals cannot be given in an unattended run: the tool is denied
+ *    and the run ends "blocked".
+ *
+ * Update (A-126): the JobManager — one agent's jobs of every kind. Schedule jobs'
+ * ticks (the JobClock), run now, bus events, webhooks and test events all go through
+ * the intake above, and one worker runs them. A run's session follows the job's
+ * sessionMode (fresh, or one reused session). A run's reply may carry a marker:
+ * [[SILENT]] (nothing to report: succeeded, never delivered) or [[FAILED]] <reason>
+ * (failed, not retried).
+ */
+export class JobManager {
+    deps;
+    /** This worker's lease identity. */
+    owner = `job-worker:${randomUUID()}`;
+    active = new Map();
+    /** sessionId -> the run working in it. */
+    bySession = new Map();
+    /** Intakes and runs in flight — dispose() waits for them. */
+    inFlight = new Set();
+    /**
+     * Schedule jobs whose overlap check and queueing are in progress: a second tick or
+     * run now meanwhile sees the job as busy, so two fired at the same moment cannot
+     * both pass the check (the slot is taken before any await).
+     */
+    queuing = new Set();
+    unsubscribe;
+    clock;
+    pollTimer;
+    wakeTimer;
+    pumping = false;
+    pumpAgain = false;
+    started = false;
+    disposed = false;
+    now;
+    random;
+    leaseMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.random = deps.random ?? Math.random;
+        this.leaseMs = deps.leaseMs ?? JOB_LEASE_MS;
+        this.clock = new JobClock({
+            agentId: deps.agentId,
+            getStore: deps.getStore,
+            onTick: (job, scheduledAt, cause) => this.onTick(job, scheduledAt, cause),
+            now: this.now,
+        });
+        // The "event" source: the agent's own SDK events, by subscription only.
+        this.unsubscribe = INTERNAL_BUS_EVENT_TYPES.map((type) => deps.eventBus.on(type, (event) => {
+            this.track(this.onBusEvent(event));
+        }));
+    }
+    /**
+     * The InteractionHandler for a session while a job run works in it: nobody
+     * is there to answer, so approvals are denied (the run ends "blocked") and
+     * questions fail. Undefined for any other session.
+     */
+    interactionFor(sessionId) {
+        const entry = this.bySession.get(sessionId);
+        if (!entry)
+            return undefined;
+        return {
+            requestApproval: async (request) => {
+                // A-103: a tool job's stored call was approved when the job was made — exactly that
+                // tool with exactly those arguments, nothing else.
+                const approved = entry.approvedCall;
+                if (approved && request.toolName === approved.tool && canonicalJson(request.arguments) === approved.args) {
+                    return { approved: true, reason: "approved with the job" };
+                }
+                if (!entry.deniedTools.includes(request.toolName))
+                    entry.deniedTools.push(request.toolName);
+                return {
+                    approved: false,
+                    reason: "This run was started by a job and nobody is there to approve tools, so the tool is denied. Say in your reply which action needs approval.",
+                };
+            },
+            askUser: async () => {
+                throw new Error("this run was started by a job and nobody is there to answer");
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    /**
+     * Start the agent's jobs: arm schedule jobs (a time missed while the host was down
+     * runs once), and work the queue — due runs, runs left by a previous process (their
+     * leases expire) and retries. Call once the host is ready to run turns. Idempotent.
+     */
+    async start() {
+        if (this.started || this.disposed)
+            return;
+        this.started = true;
+        this.pollTimer = setInterval(() => this.pump(), this.deps.pollMs ?? JOB_POLL_MS);
+        this.pollTimer.unref?.();
+        await this.clock.start();
+        this.pump();
+    }
+    /**
+     * Stop the clock, intake and the worker. Runs in progress are aborted and released,
+     * so they are taken up again (not lost, not counted as an attempt) after a restart.
+     */
+    async dispose() {
+        this.disposed = true;
+        this.clock.dispose();
+        for (const off of this.unsubscribe)
+            off();
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        this.wakeTimer?.cancel();
+        for (const entry of this.active.values())
+            entry.controller.abort();
+        while (this.inFlight.size > 0)
+            await Promise.allSettled([...this.inFlight]);
+    }
+    // ---------------------------------------------------------------------------
+    // AgentJobs — configuration
+    // ---------------------------------------------------------------------------
+    async list() {
+        return this.store().listByAgent(this.deps.agentId);
+    }
+    async get(id) {
+        const job = await this.store().get(id);
+        return job && job.agentId === this.deps.agentId ? job : null;
+    }
+    async create(input) {
+        if (this.disposed)
+            throw new JobError("The agent is stopped", "invalid_argument");
+        if (typeof input !== "object" || input === null)
+            throw new JobError("A job needs a configuration object", "invalid_argument");
+        const fields = validateCreateInput(input);
+        if (fields.action)
+            this.checkToolAction(fields.action);
+        const existing = await this.store().listByAgent(this.deps.agentId);
+        if (existing.length >= MAX_JOBS_PER_AGENT) {
+            throw new JobError(`This agent already has ${MAX_JOBS_PER_AGENT} jobs — delete one first`, "limit_reached");
+        }
+        if (existing.some((j) => j.name === fields.name)) {
+            throw new JobError(`A job named "${fields.name}" already exists`, "name_conflict");
+        }
+        const nowIso = this.iso(this.now());
+        const job = {
+            id: randomUUID(),
+            agentId: this.deps.agentId,
+            ...fields,
+            version: 1,
+            nextRunAt: fields.enabled && isScheduleWhen(fields.when) ? this.clock.firstRun(fields.when) : null,
+            ...(fields.when.kind === "webhook" ? { secret: generateWebhookSecret() } : {}),
+            createdAt: nowIso,
+            updatedAt: nowIso,
+        };
+        await this.store().save(job);
+        this.clock.sync(job.id, job);
+        return job;
+    }
+    async update(id, patch) {
+        const job = await this.require(id);
+        if (typeof patch !== "object" || patch === null)
+            throw new JobError("A job update must be an object", "invalid_argument", id);
+        const next = { ...job };
+        if (patch.name !== undefined) {
+            const name = validateJobName(patch.name, id);
+            if (name !== job.name) {
+                const clash = await this.store().findByName(this.deps.agentId, name);
+                if (clash && clash.id !== id)
+                    throw new JobError(`A job named "${name}" already exists`, "name_conflict", id);
+            }
+            next.name = name;
+        }
+        if (patch.description !== undefined) {
+            const description = validateJobDescription(patch.description, id);
+            if (description)
+                next.description = description;
+            else
+                delete next.description;
+        }
+        if (patch.enabled !== undefined) {
+            if (typeof patch.enabled !== "boolean")
+                throw new JobError('"enabled" must be true or false', "invalid_argument", id);
+            next.enabled = patch.enabled;
+        }
+        if (patch.sessionMode !== undefined)
+            next.sessionMode = validateSessionMode(patch.sessionMode, id);
+        const whenChanged = patch.when !== undefined;
+        if (whenChanged)
+            next.when = validateJobWhen(patch.when, id);
+        // A-103: the action is checked against the (possibly new) when, and the prompt against
+        // the action (a tool job needs a prompt only for its follow-up).
+        const actionChanged = patch.action !== undefined;
+        if (actionChanged || whenChanged) {
+            const action = validateJobAction(actionChanged ? patch.action : job.action, next.when, id);
+            if (action)
+                next.action = action;
+            else
+                delete next.action;
+            if (actionChanged && action)
+                this.checkToolAction(action, id);
+        }
+        if (patch.prompt !== undefined || actionChanged)
+            next.prompt = validatePromptFor(next.action, patch.prompt ?? job.prompt, id);
+        const kindChanged = isScheduleWhen(next.when) !== isScheduleWhen(job.when);
+        // The filter is checked against the (possibly new) when; a job that moves to a clock drops its filter.
+        if (patch.filter !== undefined || whenChanged) {
+            const filter = patch.filter !== undefined ? patch.filter : isScheduleWhen(next.when) ? {} : job.filter;
+            next.filter = validateJobFilter(filter, next.when, id);
+        }
+        if (patch.coalesce !== undefined)
+            next.coalesce = resolveCoalesce(patch.coalesce, job.coalesce, id);
+        // A job that changes between a clock and events takes the other kind's default limits.
+        const baseLimits = kindChanged ? defaultLimits(next.when) : job.limits;
+        if (patch.limits !== undefined || kindChanged)
+            next.limits = resolveLimits(patch.limits, baseLimits, id);
+        // Update (A-127): the deliveries are replaced as a whole; null or [] removes them.
+        if (patch.deliveries !== undefined) {
+            const deliveries = validateJobDeliveries(patch.deliveries, id);
+            if (deliveries.length)
+                next.deliveries = deliveries;
+            else
+                delete next.deliveries;
+        }
+        if (next.when.kind === "webhook" && !next.secret)
+            next.secret = generateWebhookSecret();
+        if (next.when.kind !== "webhook")
+            delete next.secret;
+        if (!next.enabled || !isScheduleWhen(next.when)) {
+            next.nextRunAt = null;
+        }
+        else if (whenChanged || !job.enabled || next.nextRunAt === null) {
+            // A new schedule, or turned back on: count from now — no catch-up for the time it was off.
+            const at = this.clock.firstRun(next.when);
+            if (!at)
+                throw new JobError(`${describeSchedule(next.when)} has no future run time`, "invalid_argument", id);
+            next.nextRunAt = at;
+        }
+        next.version = job.version + 1;
+        next.updatedAt = this.iso(this.now());
+        await this.store().save(next);
+        this.clock.sync(id, next);
+        // Re-enabled: queued runs may be due.
+        if (next.enabled && !job.enabled)
+            this.pump();
+        return next;
+    }
+    async delete(id) {
+        await this.require(id);
+        this.clock.sync(id, null);
+        for (const entry of this.active.values()) {
+            if (entry.run.jobId === id) {
+                entry.stopRequested = true;
+                entry.controller.abort();
+            }
+        }
+        await this.store().delete(id);
+    }
+    async rotateSecret(id) {
+        const job = await this.require(id);
+        if (job.when.kind !== "webhook")
+            throw new JobError("Only a webhook job has a secret", "invalid_argument", id);
+        const next = { ...job, secret: generateWebhookSecret(), updatedAt: this.iso(this.now()) };
+        await this.store().save(next);
+        return next;
+    }
+    // ---------------------------------------------------------------------------
+    // AgentJobs — intake
+    // ---------------------------------------------------------------------------
+    async runNow(id) {
+        const job = await this.require(id);
+        if (this.disposed)
+            throw new JobError("The agent is stopped", "invalid_argument", id);
+        if (!isScheduleWhen(job.when)) {
+            throw new JobError("Run now is for schedule jobs — send a test event to an event or webhook job", "invalid_argument", id);
+        }
+        // Never overlap a job with itself.
+        if (this.queuing.has(id))
+            throw new JobError("A run of this job is already queued or running", "invalid_argument", id);
+        this.queuing.add(id);
+        try {
+            if (await this.store().hasActiveRun(id)) {
+                throw new JobError("A run of this job is already queued or running", "invalid_argument", id);
+            }
+            const nowIso = this.iso(this.now());
+            const result = await this.ingest(job, { source: "manual", sourceEventId: randomUUID(), type: "job.run-now", time: nowIso, data: null }, "manual");
+            if (!result.run)
+                throw new JobError(`The run was not queued: ${result.event.reason ?? result.event.status}`, "invalid_argument", id);
+            return result.run;
+        }
+        finally {
+            this.queuing.delete(id);
+        }
+    }
+    async sendTestEvent(id, input) {
+        const job = await this.require(id);
+        if (isScheduleWhen(job.when))
+            throw new JobError("A schedule job takes no events — use run now", "invalid_argument", id);
+        if (typeof input !== "object" || input === null)
+            throw new JobError("A test event must be an object", "invalid_argument", id);
+        const type = typeof input.type === "string" ? input.type.trim() : "";
+        if (!type || type.length > 200)
+            throw new JobError('A test event needs a "type" (at most 200 characters)', "invalid_argument", id);
+        if (input.subject !== undefined && toSubject(input.subject) === undefined) {
+            throw new JobError('"subject" must be a non-empty string', "invalid_argument", id);
+        }
+        if (input.revision !== undefined && toRevision(input.revision) === undefined) {
+            throw new JobError('"revision" must be a number', "invalid_argument", id);
+        }
+        if (dataBytes(input.data) > MAX_EVENT_DATA_BYTES) {
+            throw new JobError(`"data" is larger than ${MAX_EVENT_DATA_BYTES / 1024} KB`, "invalid_argument", id);
+        }
+        const subject = input.subject !== undefined ? toSubject(input.subject) : undefined;
+        const revision = input.revision !== undefined ? toRevision(input.revision) : undefined;
+        return this.ingest(job, {
+            source: "manual",
+            sourceEventId: randomUUID(),
+            type,
+            ...(subject !== undefined ? { subject } : {}),
+            ...(revision !== undefined ? { revision } : {}),
+            data: input.data ?? null,
+        }, "test");
+    }
+    async handleWebhook(id, request) {
+        if (request.method.toUpperCase() !== "POST")
+            return { status: 405, body: { error: "Use POST" } };
+        const job = await this.get(id);
+        if (!job || this.disposed)
+            return { status: 404, body: { error: "Job not found" } };
+        if (job.when.kind !== "webhook")
+            return { status: 404, body: { error: "This job takes no webhooks" } };
+        if (!job.enabled)
+            return { status: 409, body: { error: "The job is disabled" } };
+        if (!job.secret)
+            return { status: 503, body: { error: "The job has no secret" } };
+        const size = typeof request.body === "string" ? Buffer.byteLength(request.body, "utf8") : request.body.byteLength;
+        if (size > MAX_WEBHOOK_BODY_BYTES)
+            return { status: 413, body: { error: `The body is larger than ${MAX_WEBHOOK_BODY_BYTES / 1024} KB` } };
+        // The signature is checked on the raw bytes, before anything is parsed.
+        const invalid = verifyWebhookSignature(job.when.signature, job.secret, request, this.now());
+        if (invalid)
+            return { status: 401, body: { error: `Unauthorized: ${invalid}` } };
+        const envelope = parseWebhookEvent(job.when, request);
+        if ("error" in envelope)
+            return { status: 400, body: { error: envelope.error } };
+        if (dataBytes(envelope.data) > MAX_EVENT_DATA_BYTES) {
+            return { status: 413, body: { error: `The event data is larger than ${MAX_EVENT_DATA_BYTES / 1024} KB` } };
+        }
+        // Resolves only once the store has the event: a store failure rejects, so the host
+        // answers 5xx and the sender keeps the delivery.
+        const result = await this.ingest(job, envelope, "webhook");
+        if (result.duplicate)
+            return { status: 200, body: { duplicate: true, eventId: result.event.id } };
+        return {
+            status: 202,
+            body: {
+                eventId: result.event.id,
+                status: result.event.status,
+                ...(result.run ? { runId: result.run.id } : {}),
+                ...(result.event.reason ? { reason: result.event.reason } : {}),
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // AgentJobs — history and control
+    // ---------------------------------------------------------------------------
+    async listEvents(id, limit = 50) {
+        await this.require(id);
+        return this.store().listEvents(id, clampLimit(limit));
+    }
+    async listRuns(id, limit = 50) {
+        await this.require(id);
+        return this.store().listRuns(id, clampLimit(limit));
+    }
+    async getRun(runId) {
+        const run = await this.store().getRun(runId);
+        return run && run.agentId === this.deps.agentId ? run : null;
+    }
+    async getRunEvents(runId) {
+        const run = await this.requireRun(runId);
+        return this.store().getEvents(run.eventIds);
+    }
+    async stopRun(runId) {
+        const run = await this.requireRun(runId);
+        const entry = this.active.get(runId);
+        if (entry) {
+            entry.stopRequested = true;
+            entry.controller.abort();
+            return true;
+        }
+        if (run.status !== "pending" && run.status !== "waiting")
+            return false;
+        const nowIso = this.iso(this.now());
+        const stopped = await this.store().updateRun(runId, null, { status: "stopped", finishedAt: nowIso, reason: "Stopped before it started" }, nowIso);
+        if (stopped)
+            await this.emitFinished(stopped, "stopped", { reason: "Stopped before it started" });
+        return stopped !== null;
+    }
+    async replayRun(runId) {
+        const original = await this.requireRun(runId);
+        if (original.status === "pending" || original.status === "waiting" || original.status === "running") {
+            throw new JobError("The run has not finished yet", "invalid_argument", original.jobId);
+        }
+        const job = await this.require(original.jobId);
+        const now = this.now();
+        const nowIso = this.iso(now);
+        const replay = {
+            id: randomUUID(),
+            jobId: job.id,
+            agentId: this.deps.agentId,
+            jobVersion: job.version,
+            cause: "replay",
+            bucketKey: original.bucketKey,
+            status: "waiting",
+            // The same events: replay keeps their identity.
+            eventIds: [...original.eventIds],
+            ...(original.revision !== undefined ? { revision: original.revision } : {}),
+            correlationId: original.correlationId,
+            depth: original.depth,
+            notBefore: nowIso,
+            deadline: nowIso,
+            expiresAt: this.iso(now + job.limits.runDeadlineMs),
+            attempts: 0,
+            maxAttempts: job.limits.maxAttempts,
+            replayOf: original.id,
+            createdAt: nowIso,
+            updatedAt: nowIso,
+        };
+        await this.store().insertRun(replay);
+        this.pump();
+        return replay;
+    }
+    /** Whether a run of this job is queued or running. */
+    async isRunning(id) {
+        return this.store().hasActiveRun(id);
+    }
+    /** A-103: a tool job's tool must be one of the agent's tools and marked schedulable. */
+    checkToolAction(action, id) {
+        if (action.kind !== "tool")
+            return;
+        if (!this.deps.runTool)
+            throw new JobError("This agent can't run tool jobs", "invalid_argument", id);
+        const problem = this.deps.checkTool?.(action.tool);
+        if (problem)
+            throw new JobError(problem, "invalid_argument", id);
+    }
+    // ---------------------------------------------------------------------------
+    // Intake
+    // ---------------------------------------------------------------------------
+    /** A schedule job's time came (the JobClock): one tick into its inbox. */
+    async onTick(job, scheduledAt, cause) {
+        if (this.disposed)
+            return;
+        // Never overlap a job with itself: a tick while a run is still queued or running is
+        // recorded as suppressed (it was "skipped").
+        const taken = this.queuing.has(job.id);
+        if (!taken)
+            this.queuing.add(job.id);
+        try {
+            const busy = taken || (await this.store().hasActiveRun(job.id));
+            await this.ingest(job, { source: "schedule", sourceEventId: scheduledAt, type: "job.tick", time: scheduledAt, data: { scheduledAt } }, cause, undefined, undefined, busy ? "The previous run was still in progress" : undefined);
+        }
+        finally {
+            if (!taken)
+                this.queuing.delete(job.id);
+        }
+    }
+    /** One of the agent's SDK events: offer it to every enabled "event" job. */
+    async onBusEvent(event) {
+        if (this.disposed)
+            return;
+        const envelope = internalEnvelope(this.deps.agentId, event);
+        if (!envelope)
+            return;
+        try {
+            const jobs = (await this.store().listByAgent(this.deps.agentId)).filter((j) => j.enabled && j.when.kind === "event");
+            // Only jobs that asked for this type see it — no inbox entry for every job run.
+            const interested = jobs.filter((j) => j.filter.types?.some((p) => typeMatches(p, envelope.type)));
+            if (interested.length === 0)
+                return;
+            const origin = await this.originOf(event.sessionId);
+            for (const job of interested) {
+                await this.ingest(job, envelope, "event", origin, event.id);
+            }
+        }
+        catch (err) {
+            console.error(`[jobs] agent=${this.deps.agentId} could not take event ${event.type}:`, err);
+        }
+    }
+    /**
+     * The single intake path: build the inbox entry, filter it, apply the loop
+     * guard, and accept it into the store (dedupe + coalesce, atomically).
+     * `suppress` records the event as suppressed for that reason (a busy schedule job).
+     */
+    async ingest(job, envelope, cause, origin, causationId, suppress) {
+        const now = this.now();
+        const nowIso = this.iso(now);
+        const event = {
+            id: randomUUID(),
+            jobId: job.id,
+            agentId: this.deps.agentId,
+            source: envelope.source,
+            sourceEventId: envelope.sourceEventId,
+            type: envelope.type,
+            ...(envelope.subject !== undefined ? { subject: envelope.subject } : {}),
+            ...(envelope.revision !== undefined ? { revision: envelope.revision } : {}),
+            time: envelope.time ?? nowIso,
+            receivedAt: nowIso,
+            data: envelope.data ?? null,
+            correlationId: origin?.correlationId ?? randomUUID(),
+            ...(causationId ? { causationId } : {}),
+            ...(origin ? { originRunId: origin.originRunId } : {}),
+            depth: origin?.depth ?? 0,
+            status: "accepted",
+        };
+        const schedule = isScheduleWhen(job.when);
+        const mismatch = schedule ? undefined : filterMismatch(job.filter, viewOf(event));
+        if (suppress) {
+            event.status = "suppressed";
+            event.reason = suppress;
+        }
+        else if (mismatch) {
+            event.status = "filtered";
+            event.reason = mismatch;
+        }
+        else if (event.depth > job.limits.maxDepth) {
+            // Loop guard: output of an event job's run does not wake a job unless allowed (maxDepth).
+            event.status = "suppressed";
+            event.reason = `caused by job run ${event.originRunId} (chain depth ${event.depth} is over the limit of ${job.limits.maxDepth})`;
+        }
+        let runPlan;
+        if (event.status === "accepted") {
+            const bucketKey = event.subject ?? "";
+            // A clock tick or run now is due at once and never coalesces with another one.
+            const coalesce = schedule ? { quietMs: 0, maxWaitMs: 0, maxBatch: 1 } : job.coalesce;
+            let notBefore = now + coalesce.quietMs;
+            if (job.limits.cooldownMs > 0) {
+                const last = await this.store().lastSucceeded(job.id, bucketKey);
+                if (last?.finishedAt)
+                    notBefore = Math.max(notBefore, Date.parse(last.finishedAt) + job.limits.cooldownMs);
+            }
+            const deadline = Math.max(now + coalesce.maxWaitMs, notBefore);
+            runPlan = {
+                newRun: {
+                    id: randomUUID(),
+                    jobId: job.id,
+                    agentId: this.deps.agentId,
+                    jobVersion: job.version,
+                    cause,
+                    bucketKey,
+                    status: "pending",
+                    eventIds: [event.id],
+                    ...(event.revision !== undefined ? { revision: event.revision } : {}),
+                    correlationId: event.correlationId,
+                    depth: event.depth,
+                    notBefore: this.iso(notBefore),
+                    deadline: this.iso(deadline),
+                    expiresAt: this.iso(notBefore + job.limits.runDeadlineMs),
+                    attempts: 0,
+                    maxAttempts: job.limits.maxAttempts,
+                    createdAt: nowIso,
+                    updatedAt: nowIso,
+                },
+                joinNotBefore: this.iso(now + coalesce.quietMs),
+                maxBatch: coalesce.maxBatch,
+            };
+        }
+        const result = await this.store().accept({ event, ...(runPlan ? { run: runPlan } : {}) });
+        this.deps.eventBus.emit({
+            type: SDKEventType.JobEventReceived,
+            sessionId: "",
+            payload: {
+                agentId: this.deps.agentId,
+                jobId: job.id,
+                eventId: result.event.id,
+                type: result.event.type,
+                status: result.duplicate ? "duplicate" : result.event.status,
+                ...(result.run ? { runId: result.run.id } : {}),
+                ...(result.event.reason ? { reason: result.event.reason } : {}),
+            },
+        });
+        if (result.run)
+            this.wakeAt(Date.parse(result.run.notBefore));
+        // Filtered and suppressed events start no run (whose end prunes), so they prune here.
+        else if (!result.duplicate) {
+            await this.store()
+                .prune(job.id, KEEP_JOB_EVENTS, KEEP_JOB_RUNS)
+                .catch((err) => console.warn(`[jobs] agent=${this.deps.agentId} could not prune history:`, err));
+        }
+        return result;
+    }
+    /** When `sessionId` is a job run's session, the run and chain depth an event from it continues. */
+    async originOf(sessionId) {
+        if (!sessionId)
+            return undefined;
+        const entry = this.bySession.get(sessionId);
+        if (entry)
+            return { originRunId: entry.run.id, correlationId: entry.run.correlationId, depth: entry.eventDepth };
+        const session = await this.deps.getSessions().get(sessionId).catch(() => null);
+        const meta = session?.metadata;
+        if (!meta || meta["source"] !== "job" || typeof meta["runId"] !== "string")
+            return undefined;
+        return {
+            originRunId: meta["runId"],
+            correlationId: typeof meta["correlationId"] === "string" ? meta["correlationId"] : randomUUID(),
+            depth: typeof meta["eventDepth"] === "number" ? meta["eventDepth"] : 0,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Worker
+    // ---------------------------------------------------------------------------
+    /** Arm a wake-up for a run that becomes due at `at` (only the soonest is kept). */
+    wakeAt(at) {
+        if (!this.started || this.disposed)
+            return;
+        if (at <= this.now()) {
+            this.pump();
+            return;
+        }
+        if (this.wakeTimer && this.wakeTimer.at <= at)
+            return;
+        this.wakeTimer?.cancel();
+        this.wakeTimer = armTimer(at, () => {
+            this.wakeTimer = undefined;
+            this.pump();
+        }, this.now);
+    }
+    /** Claim and start due runs while there is room. Re-entrant calls coalesce. */
+    pump() {
+        if (!this.started || this.disposed)
+            return;
+        if (this.pumping) {
+            this.pumpAgain = true;
+            return;
+        }
+        this.pumping = true;
+        this.track(this.claimLoop()
+            .catch((err) => console.error(`[jobs] agent=${this.deps.agentId} could not claim runs:`, err))
+            .finally(() => {
+            this.pumping = false;
+            if (this.pumpAgain) {
+                this.pumpAgain = false;
+                this.pump();
+            }
+        }));
+    }
+    async claimLoop() {
+        while (!this.disposed && this.hasRoom()) {
+            // Jobs already at their own concurrency limit are skipped this round.
+            const jobs = await this.store().listByAgent(this.deps.agentId);
+            const exclude = jobs
+                .filter((j) => [...this.active.values()].filter((a) => a.run.jobId === j.id).length >= j.limits.maxConcurrentRuns)
+                .map((j) => j.id);
+            const now = this.now();
+            const run = await this.store().claim({
+                agentId: this.deps.agentId,
+                now: this.iso(now),
+                owner: this.owner,
+                leaseUntil: this.iso(now + this.leaseMs),
+                ...(exclude.length ? { excludeJobIds: exclude } : {}),
+            });
+            if (!run)
+                return;
+            this.launch(run);
+        }
+    }
+    /** Room for one more run: under this manager's cap, and a turn left for people's chats. */
+    hasRoom() {
+        if (this.active.size >= (this.deps.maxParallelRuns ?? MAX_PARALLEL_JOB_RUNS))
+            return false;
+        const { running, max } = this.deps.getCapacity();
+        if (max <= 0)
+            return true;
+        if (max === 1)
+            return running === 0;
+        return running < max - 1;
+    }
+    launch(run) {
+        const entry = { run, controller: new AbortController(), stopRequested: false, leaseLost: false, deniedTools: [], eventDepth: 0 };
+        this.active.set(run.id, entry);
+        this.track(this.process(entry)
+            .catch((err) => console.error(`[jobs] agent=${this.deps.agentId} run=${run.id} failed unexpectedly:`, err))
+            .finally(() => {
+            this.active.delete(run.id);
+            if (entry.sessionId && this.bySession.get(entry.sessionId) === entry)
+                this.bySession.delete(entry.sessionId);
+            this.pump();
+        }));
+    }
+    /** Work one claimed run to its next state. */
+    async process(entry) {
+        let run = entry.run;
+        const job = await this.store().get(run.jobId);
+        if (!job || job.agentId !== this.deps.agentId)
+            return void (await this.finish(entry, "suppressed", { reason: "The job was deleted" }));
+        // Run now works on a disabled job too (as before A-126), and a one-off ("at") job turns itself
+        // off as its time fires; anything else waits for the job to be enabled.
+        const oneOffTick = job.when.kind === "at" && (run.cause === "schedule" || run.cause === "catch-up");
+        if (!job.enabled && run.cause !== "manual" && !oneOffTick)
+            return void (await this.finish(entry, "suppressed", { reason: "The job is disabled" }));
+        entry.eventDepth = eventDepthOf(job, run);
+        // The turn already finished before a crash: only record the result.
+        if (run.resultAt)
+            return void (await this.finalize(entry, job));
+        if (run.attempts > run.maxAttempts) {
+            return void (await this.finish(entry, "failed", { error: `Gave up after ${run.maxAttempts} attempts${run.error ? `: ${run.error}` : ""}` }));
+        }
+        const now = this.now();
+        if (now > Date.parse(run.expiresAt)) {
+            return void (await this.finish(entry, "failed", { error: `The run's deadline passed${run.error ? `: ${run.error}` : ""}` }));
+        }
+        // -- Is the work still wanted? --
+        let events = await this.store().getEvents(run.eventIds);
+        if (run.jobVersion !== job.version && !isScheduleWhen(job.when)) {
+            // The job was edited after these events were queued: keep the ones it still accepts.
+            events = events.filter((e) => !filterMismatch(job.filter, viewOf(e)));
+        }
+        if (events.length === 0)
+            return void (await this.finish(entry, "suppressed", { reason: "The job no longer accepts these events" }));
+        if (run.revision !== undefined) {
+            const last = await this.store().lastSucceeded(job.id, run.bucketKey);
+            if (last && last.id !== run.id && last.revision !== undefined && last.revision >= run.revision) {
+                return void (await this.finish(entry, "suppressed", { reason: `Revision ${run.revision} is not newer than revision ${last.revision}, already handled` }));
+            }
+        }
+        const resolved = await resolvedSince(events, this.store());
+        if (resolved)
+            return void (await this.finish(entry, "suppressed", { reason: `Resolved: ${resolved}` }));
+        // -- Limits --
+        const maxRunsPerHour = job.limits.maxRunsPerHour;
+        if (maxRunsPerHour !== undefined) {
+            const hour = await this.store().usageSince(job.id, this.iso(now - HOUR));
+            if (hour.runs >= maxRunsPerHour) {
+                const retryAt = now + Math.max(60_000, Math.ceil(HOUR / maxRunsPerHour));
+                // Waiting for the window is not an attempt.
+                await this.write(entry, {
+                    status: "waiting",
+                    notBefore: this.iso(retryAt),
+                    attempts: Math.max(0, run.attempts - 1),
+                    reason: `Rate limit: ${hour.runs} runs in the last hour (limit ${maxRunsPerHour})`,
+                    releaseLease: true,
+                });
+                this.wakeAt(retryAt);
+                return;
+            }
+        }
+        if (job.limits.maxTokensPerDay !== undefined) {
+            const day = await this.store().usageSince(job.id, this.iso(now - DAY));
+            if (day.tokens >= job.limits.maxTokensPerDay) {
+                return void (await this.finish(entry, "blocked", { reason: `Token budget used up: ${day.tokens} of ${job.limits.maxTokensPerDay} tokens in the last 24 hours` }));
+            }
+        }
+        // -- Run the turn --
+        // A-103: a tool job runs its stored call (and maybe a follow-up turn) instead of a turn.
+        const toolAction = job.action?.kind === "tool" ? job.action : undefined;
+        // A-103: "since last run" placeholders read the history before this run joins it.
+        const history = usesRunHistory(job.prompt) ? await this.runHistory(job.id, run.id) : undefined;
+        const sessionId = run.sessionId ?? (await this.resolveSession(job, run, entry.eventDepth));
+        const started = await this.write(entry, {
+            sessionId,
+            ...(run.startedAt ? {} : { startedAt: this.iso(now) }),
+            ...(toolAction ? { action: "tool" } : {}),
+            clear: ["reason"],
+        });
+        if (!started)
+            return;
+        run = started;
+        entry.sessionId = sessionId;
+        this.bySession.set(sessionId, entry);
+        await this.setJobState(job.id, { lastRunAt: run.startedAt, lastStatus: "running" });
+        this.deps.eventBus.emit({
+            type: SDKEventType.JobRunStarted,
+            sessionId,
+            payload: { agentId: this.deps.agentId, jobId: job.id, jobName: job.name, runId: run.id, cause: run.cause, attempt: run.attempts },
+        });
+        console.log(`[jobs] agent=${this.deps.agentId} job="${job.name}" run=${run.id} cause=${run.cause} attempt=${run.attempts} events=${events.length} session=${sessionId}`);
+        const renew = setInterval(() => {
+            void this.store()
+                .renewLease(run.id, this.owner, this.iso(this.now() + this.leaseMs))
+                .then((held) => {
+                if (!held && !entry.leaseLost) {
+                    entry.leaseLost = true;
+                    entry.controller.abort();
+                }
+            })
+                .catch(() => undefined);
+        }, Math.max(1_000, Math.floor(this.leaseMs / 3)));
+        renew.unref?.();
+        // A-103: no attempt runs longer than the job's time limit.
+        const maxRunMs = job.limits.maxRunMs ?? DEFAULT_MAX_RUN_MS;
+        const timeLimit = setTimeout(() => {
+            entry.timedOut = true;
+            entry.controller.abort();
+        }, maxRunMs);
+        timeLimit.unref?.();
+        const context = {
+            agentId: this.deps.agentId,
+            jobId: job.id,
+            jobName: job.name,
+            runId: run.id,
+            cause: run.cause,
+            attempt: run.attempts,
+            sessionId,
+            prompt: renderJobPrompt(job, events, history),
+            signal: entry.controller.signal,
+        };
+        let result;
+        let failure;
+        try {
+            result = toolAction ? await this.runToolAction(entry, toolAction, context) : await this.deps.getRunner()(context);
+        }
+        catch (err) {
+            failure = err;
+        }
+        finally {
+            clearInterval(renew);
+            clearTimeout(timeLimit);
+            entry.approvedCall = undefined;
+        }
+        if (entry.leaseLost) {
+            console.warn(`[jobs] agent=${this.deps.agentId} run=${run.id} lost its lease; another worker has it`);
+            return;
+        }
+        // A-103: past its time limit — a failure, not a person's stop, and not retried.
+        if (entry.timedOut && !entry.stopRequested && !this.disposed) {
+            return void (await this.finish(entry, "failed", {
+                error: `Timed out after ${describeDuration(maxRunMs)} (the job's time limit)`,
+                ...(result?.output ? { output: result.output.slice(0, MAX_OUTPUT_CHARS) } : {}),
+            }, job));
+        }
+        // Stopped here (stopRun / delete) or through the host (its stop button for the session).
+        if (entry.stopRequested || (failure === undefined && result?.aborted && !this.disposed)) {
+            return void (await this.finish(entry, "stopped", {
+                reason: "Stopped by a person",
+                ...(result?.output ? { output: result.output.slice(0, MAX_OUTPUT_CHARS) } : {}),
+            }));
+        }
+        // A turn that finished before the shutdown keeps its result (recorded below), so it is not run again.
+        const finishedTurn = failure === undefined && result !== undefined && !result.aborted;
+        if (this.disposed && entry.controller.signal.aborted && !finishedTurn) {
+            // Shut down mid-run: give the run back so it is taken up after the restart.
+            await this.write(entry, {
+                status: "waiting",
+                notBefore: this.iso(this.now()),
+                attempts: Math.max(0, run.attempts - 1),
+                reason: "Interrupted: the agent stopped during the run",
+                releaseLease: true,
+            });
+            return;
+        }
+        // A-103: the tool failed and no follow-up turn ran — the run failed with the start of
+        // the tool's output (the session keeps all of it). Retried like any failed attempt.
+        if (failure === undefined && result?.toolError !== undefined && !result.followedUp) {
+            failure = new Error(`${toolAction?.tool ?? "The tool"} failed: ${result.toolError.slice(0, MAX_TOOL_ERROR_CHARS)}`);
+        }
+        if (failure === undefined && result && !result.aborted) {
+            const blocked = entry.deniedTools.length ? `Needs approval: ${entry.deniedTools.join(", ")} (approvals cannot be given in a run started by a job)` : undefined;
+            // Checkpoint the result first: if the process dies now, a reclaim only records it.
+            const checkpoint = await this.write(entry, {
+                resultAt: this.iso(this.now()),
+                ...(result.output ? { output: result.output.slice(0, MAX_OUTPUT_CHARS) } : {}),
+                ...(result.usage ? { usage: { inputTokens: result.usage.inputTokens, outputTokens: result.usage.outputTokens } } : {}),
+                ...(result.stopReason ? { stopReason: result.stopReason } : {}),
+                ...(blocked ? { reason: blocked } : {}),
+                // A-103: a tool that printed nothing — a silent run (finalize).
+                ...(result.empty ? { silent: true } : {}),
+                // A-103: a follow-up turn after a failed tool — the run stays failed (finalize).
+                ...(result.toolError !== undefined ? { error: `${toolAction?.tool ?? "The tool"} failed: ${result.toolError.slice(0, MAX_TOOL_ERROR_CHARS)}` } : {}),
+                ...(result.toolError !== undefined ? {} : { clear: ["error"] }),
+            });
+            if (!checkpoint)
+                return;
+            entry.run = checkpoint;
+            return void (await this.finalize(entry, job));
+        }
+        const error = failure !== undefined ? errorMessage(failure) : "The turn ended without a result";
+        // An SDKError says whether retrying can help; anything else (a network error...) is treated as transient.
+        const retryable = !(failure instanceof SDKError) || failure.retryable;
+        const delay = this.retryDelay(run.attempts);
+        const retryAt = this.now() + delay;
+        if (retryable && run.attempts < run.maxAttempts && retryAt < Date.parse(run.expiresAt)) {
+            await this.write(entry, { status: "waiting", notBefore: this.iso(retryAt), error, releaseLease: true });
+            this.deps.eventBus.emit({
+                type: SDKEventType.JobRunRetrying,
+                sessionId,
+                payload: { agentId: this.deps.agentId, jobId: job.id, jobName: job.name, runId: run.id, attempt: run.attempts, error, retryAt: this.iso(retryAt) },
+            });
+            console.warn(`[jobs] agent=${this.deps.agentId} run=${run.id} attempt ${run.attempts} failed, retrying at ${this.iso(retryAt)}: ${error}`);
+            this.wakeAt(retryAt);
+            return;
+        }
+        await this.finish(entry, "failed", { error });
+    }
+    /**
+     * Record the checkpointed result as the run's outcome; the in-app delivery is this same write.
+     * Update (A-126): the reply's marker decides it — [[SILENT]] succeeds without anything to
+     * deliver, [[FAILED]] <reason> fails (a deliberate answer, so it is not retried).
+     */
+    async finalize(entry, job) {
+        const run = entry.run;
+        const deliveredAt = this.iso(this.now());
+        if (run.reason)
+            return void (await this.finish(entry, "blocked", { deliveredAt }, job));
+        const outcome = replyOutcome(run.output);
+        if (outcome.kind === "silent")
+            return void (await this.finish(entry, "succeeded", { deliveredAt, silent: true }, job));
+        if (outcome.kind === "failed")
+            return void (await this.finish(entry, "failed", { deliveredAt, error: outcome.reason }, job));
+        // A-103: a tool job whose tool failed stays failed after its follow-up turn; the reply
+        // (e.g. "what went wrong and how to fix it") is the error people are told.
+        if (run.action === "tool" && run.error) {
+            const reply = run.output?.trim();
+            return void (await this.finish(entry, "failed", { deliveredAt, error: reply ? reply.slice(0, MAX_OUTPUT_CHARS) : run.error }, job));
+        }
+        // A-103: a tool job that printed nothing has nothing to report, like [[SILENT]].
+        if (run.action === "tool" && (run.silent || !run.output?.trim()))
+            return void (await this.finish(entry, "succeeded", { deliveredAt, silent: true }, job));
+        await this.finish(entry, "succeeded", { deliveredAt }, job);
+    }
+    async finish(entry, status, fields, job) {
+        const done = await this.write(entry, { status, finishedAt: this.iso(this.now()), releaseLease: true, ...fields });
+        if (!done)
+            return;
+        // A suppressed run did no work: the job's last status stays what it was.
+        let paused = false;
+        if (status !== "suppressed") {
+            const error = fields.error ?? (status === "blocked" ? done.reason : undefined);
+            // A-103: too many failed runs in a row turn the job off.
+            const streak = status === "failed" || status === "blocked" ? await this.failureStreak(done.jobId) : undefined;
+            paused = streak !== undefined;
+            await this.setJobState(done.jobId, {
+                lastStatus: status,
+                lastError: paused ? `Paused after ${streak} failed runs in a row${error ? `: ${error}` : ""}` : (error ?? null),
+                ...(paused ? { enabled: false, nextRunAt: null } : {}),
+            });
+            if (paused) {
+                const off = await this.store().get(done.jobId).catch(() => null);
+                if (off)
+                    this.clock.sync(off.id, off);
+                console.warn(`[jobs] agent=${this.deps.agentId} job=${done.jobId} paused after ${streak} failed runs in a row`);
+            }
+        }
+        await this.emitFinished(done, status, { ...fields, ...(paused ? { paused } : {}) }, job);
+        const log = `[jobs] agent=${this.deps.agentId} run=${done.id} ${status}${done.silent ? " (silent)" : ""}${fields.error ? `: ${fields.error}` : fields.reason ? `: ${fields.reason}` : ""}`;
+        if (status === "failed")
+            console.error(log);
+        else
+            console.log(log);
+        await this.store()
+            .prune(done.jobId, KEEP_JOB_EVENTS, KEEP_JOB_RUNS)
+            .catch((err) => console.warn(`[jobs] agent=${this.deps.agentId} could not prune history:`, err));
+    }
+    async emitFinished(run, status, fields, known) {
+        // The job as it is now: the user may have changed its delivery while the run went on.
+        // A job deleted meanwhile has nothing to deliver to.
+        const job = await this.store().get(run.jobId).catch(() => null);
+        this.deps.eventBus.emit({
+            type: SDKEventType.JobRunFinished,
+            sessionId: run.sessionId ?? "",
+            payload: {
+                agentId: this.deps.agentId,
+                jobId: run.jobId,
+                runId: run.id,
+                cause: run.cause,
+                status,
+                // A blocked turn's reason was checkpointed on the run, not passed to finish().
+                ...((fields.error ?? run.error) ? { error: fields.error ?? run.error } : {}),
+                ...((fields.reason ?? run.reason) ? { reason: fields.reason ?? run.reason } : {}),
+                ...(job ? { jobName: job.name } : known ? { jobName: known.name } : {}),
+                ...(run.output !== undefined ? { output: run.output } : {}),
+                ...(run.silent ? { silent: true } : {}),
+                ...(run.action === "tool" ? { action: "tool" } : {}),
+                ...(fields.paused ? { paused: true } : {}),
+                ...(job?.deliveries?.length ? { deliveries: job.deliveries } : {}),
+            },
+        });
+    }
+    /** A lease-guarded write. Null (and the entry marked) when this worker no longer holds the run. */
+    async write(entry, patch) {
+        const updated = await this.store().updateRun(entry.run.id, this.owner, patch, this.iso(this.now()));
+        if (!updated) {
+            entry.leaseLost = true;
+            return null;
+        }
+        entry.run = updated;
+        return updated;
+    }
+    /** Record a job's run state; a failure is logged — the run's own record is what counts. */
+    async setJobState(jobId, patch) {
+        await this.store()
+            .updateJobState(jobId, patch)
+            .catch((err) => console.warn(`[jobs] agent=${this.deps.agentId} job=${jobId} could not record its state:`, err));
+    }
+    /**
+     * The session a run writes into — created on the first attempt and reused by retries.
+     * A "reuse" job appends every run to one session, created on its first run.
+     */
+    async resolveSession(job, run, eventDepth) {
+        const sessions = this.deps.getSessions();
+        if (job.sessionMode === "reuse" && job.sessionId) {
+            const existing = await sessions.get(job.sessionId).catch(() => null);
+            if (existing && existing.metadata["agentId"] === this.deps.agentId) {
+                // A session from before Session.jobId existed: tag it so it groups with the job's runs.
+                if (existing.jobId === undefined)
+                    await sessions.update({ ...existing, jobId: job.id });
+                return existing.id;
+            }
+        }
+        const title = job.sessionMode === "reuse" ? job.name : `${job.name} · ${this.iso(this.now()).slice(0, 16).replace("T", " ")} UTC`;
+        const session = await sessions.create({
+            // Same ownership key the host routes use, so the session lists and opens like any other.
+            agentId: this.deps.agentId,
+            source: "job",
+            jobId: job.id,
+            jobName: job.name,
+            runId: run.id,
+            cause: run.cause,
+            correlationId: run.correlationId,
+            // The depth of events this session's runs cause (the loop guard reads it after a restart).
+            eventDepth,
+            title,
+        });
+        // Tag the session with its job (Session.jobId) so clients can group a job's runs.
+        await sessions.update({ ...session, jobId: job.id });
+        if (job.sessionMode === "reuse")
+            await this.setJobState(job.id, { sessionId: session.id });
+        return session.id;
+    }
+    /**
+     * A-103: one attempt of a tool job. The stored call runs through the agent loop like a
+     * turn's call (policy, approval gate, retries, traces); its approval handler approves
+     * exactly this call. The call and its result go into the run's session, so the session
+     * shows what ran and a follow-up turn sees the output. A follow-up turn ("always", or
+     * "on-failure" when the tool failed) then runs through the host's runner as usual.
+     */
+    async runToolAction(entry, action, context) {
+        const runTool = this.deps.runTool;
+        if (!runTool)
+            throw new JobError("This agent can't run tool jobs", "invalid_argument", context.jobId);
+        const call = { id: `job_${context.runId}_${context.attempt}`, name: action.tool, arguments: structuredClone(action.args) };
+        entry.approvedCall = { tool: action.tool, args: canonicalJson(action.args) };
+        await this.deps.appendMessage?.(context.sessionId, { role: "assistant", content: "", toolCalls: [call] });
+        const result = await runTool(call, { sessionId: context.sessionId, signal: context.signal });
+        entry.approvedCall = undefined;
+        // Every call gets its result in the session, a stopped one too.
+        const stored = {
+            toolCallId: result.toolCallId,
+            content: result.content,
+            ...(result.isError ? { isError: true } : {}),
+            // A-132: what the call produced for the user to open, so the chat can link to it
+            ...(result.link ? { link: result.link } : {}),
+        };
+        await this.deps.appendMessage?.(context.sessionId, { role: "assistant", content: "", toolResults: [stored] });
+        if (context.signal.aborted)
+            return { aborted: true, output: result.content };
+        const toolError = result.isError ? result.content || "the tool reported an error" : undefined;
+        const followUp = action.followUp ?? "never";
+        if (followUp === "always" || (followUp === "on-failure" && toolError !== undefined)) {
+            const reply = await this.deps.getRunner()(context);
+            return { ...reply, followedUp: true, ...(toolError !== undefined ? { toolError } : {}) };
+        }
+        return { output: result.content, ...(toolError !== undefined ? { toolError } : {}), ...(result.empty ? { empty: true } : {}) };
+    }
+    /**
+     * A-103: the number of finished runs in a row that failed or were blocked, when it has
+     * reached the job's pauseAfterFailures (undefined otherwise, or when the job is already
+     * off). Succeeded runs end the streak; suppressed and stopped runs are skipped. Runs from
+     * before the job's last edit don't count, so turning it back on starts a fresh streak.
+     */
+    async failureStreak(jobId) {
+        const job = await this.store().get(jobId).catch(() => null);
+        if (!job || !job.enabled)
+            return undefined;
+        const limit = job.limits.pauseAfterFailures ?? DEFAULT_PAUSE_AFTER_FAILURES;
+        if (limit <= 0)
+            return undefined;
+        const runs = await this.store().listRuns(jobId, Math.min(200, limit * 4 + 10)).catch(() => []);
+        let streak = 0;
+        for (const r of runs) {
+            if (r.createdAt < job.updatedAt)
+                break;
+            if (r.status === "succeeded")
+                break;
+            if (r.status === "failed" || r.status === "blocked") {
+                streak++;
+                if (streak >= limit)
+                    return streak;
+            }
+        }
+        return undefined;
+    }
+    /** A-103: the job's earlier runs, for the "since last run" placeholders. */
+    async runHistory(jobId, currentRunId) {
+        const history = { now: this.iso(this.now()) };
+        const runs = await this.store().listRuns(jobId, 50).catch(() => []);
+        for (const r of runs) {
+            if (r.id === currentRunId || !r.startedAt)
+                continue;
+            if (!history.lastRunAt && (r.status === "succeeded" || r.status === "failed" || r.status === "blocked"))
+                history.lastRunAt = r.startedAt;
+            if (r.status === "succeeded" && !r.silent && r.output?.trim()) {
+                history.lastSuccessAt = r.startedAt;
+                history.lastResult = r.output;
+                break;
+            }
+        }
+        return history;
+    }
+    retryDelay(attempt) {
+        const base = (this.deps.retryBaseMs ?? JOB_RETRY_BASE_MS) * 2 ** Math.max(0, attempt - 1);
+        return Math.min(MAX_RETRY_DELAY_MS, Math.round(base * (0.75 + this.random() * 0.5)));
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    track(promise) {
+        this.inFlight.add(promise);
+        void promise.finally(() => this.inFlight.delete(promise));
+    }
+    async require(id) {
+        const job = await this.get(id);
+        if (!job)
+            throw new JobError(`No job "${id}" for this agent`, "not_found", id);
+        return job;
+    }
+    async requireRun(runId) {
+        const run = await this.getRun(runId);
+        if (!run)
+            throw new JobError(`No job run "${runId}" for this agent`, "not_found");
+        return run;
+    }
+    store() {
+        return this.deps.getStore();
+    }
+    iso(ms) {
+        return new Date(ms).toISOString();
+    }
+}
+/**
+ * The depth of an event a run causes. Only event and webhook jobs chain: an event
+ * from their run is one level deeper than the run, so with maxDepth 0 it wakes no
+ * event job. A schedule job's run (and run now) starts no chain: its events have
+ * depth 0, so "when my scheduled job fails, look into it" works.
+ */
+function eventDepthOf(job, run) {
+    return isScheduleWhen(job.when) ? 0 : run.depth + 1;
+}
+function viewOf(event) {
+    return { type: event.type, ...(event.subject !== undefined ? { subject: event.subject } : {}), source: event.source, data: event.data };
+}
+/** A-103: "45 seconds", "30 minutes", "2 hours" — for the time-limit error. */
+function describeDuration(ms) {
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)} seconds`;
+    if (ms < HOUR || ms % HOUR !== 0)
+        return `${Math.round(ms / 60_000)} minutes`;
+    return `${ms / HOUR} hour${ms === HOUR ? "" : "s"}`;
+}
+function clampLimit(limit) {
+    return Math.min(Math.max(1, Math.floor(Number(limit) || 50)), 200);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=job-manager.js.map