visionclaw 0.1.218 → 0.1.219-dev.codex-issue-2805-worker-runtime.1

package/dist/threads/thread-task-runtime.js

@@ -1,843 +0,0 @@
-/**
- * ThreadTaskRuntime (issue #1996, PR 3): the one object the live loop talks
- * to. It owns this process's {@link ThreadTaskStore} and
- * {@link ThreadTaskController} for the thread it serves — the default thread
- * in the main process, a business thread in its worker.
- *
- * Hot-path rule: every method is fail-safe. A store, controller or model
- * error is logged and swallowed; it must never break message handling, a
- * wake or a reply. The cost of a failure is a missed task update that the
- * next run can still recover from the persisted events, never a lost message.
- */
-import { randomUUID } from "node:crypto";
-import path from "node:path";
-import { getConfigDir } from "../config/index.js";
-import { DEFAULT_THREAD_ID } from "../channels/interface.js";
-import { getMessageDedupKey } from "../channels/message-dedup.js";
-import { EXTERNAL_WAKE_KIND } from "../channels/queue.js";
-import { logger } from "../logger.js";
-import { OPEN_TASK_STATUSES } from "./task-contracts.js";
-import { createSidecarModel } from "./task-sidecar.js";
-import { ThreadTaskStore, messageEventKey } from "./task-store.js";
-import { ThreadTaskController } from "./thread-task-controller.js";
-import { renderThreadTaskContext } from "./thread-task-context.js";
-import { taskContinuationRouting } from "../agent/reply-target.js";
-/** Execution events are batched harder than owner messages; each run is a model call. */
-const LIVE_CONTROLLER_DEFAULTS = {
-    batchDelayMs: 30_000,
-    maxBatchEvents: 40,
-    callTimeoutMs: 60_000,
-    budget: { maxCalls: 12, windowMs: 10 * 60_000 },
-    // Execution events alone never use the last 4 calls of the window, so an
-    // owner message still gets a run during a long busy wake.
-    ownerReserve: 4,
-};
-/**
- * How long a fast reply waits for the sidecar before it settles for
- * "received". Added in front of the fast responder's own 5 s budget.
- */
-export const REGISTRATION_WAIT_MS = 6_000;
-/**
- * How long a lifecycle boundary waits for the sidecar to catch up (#1996 PR 4).
- * Wake end is short because the next message waits behind it; compaction,
- * refresh and handoff are already slow.
- */
-export const RECONCILE_WAIT_MS = { wakeEnd: 5_000, handoff: 8_000, boundary: 10_000 };
-/** Newest unfolded events read for the context block. */
-const UNFOLDED_CONTEXT_EVENTS = 200;
-/** `meta.kind` of a queued resume (PR 5). A system row: no fast reply, watchdog or gate reply. */
-export const TASK_RESUME_KIND = "thread-task-resume";
-const RESUME_SENDER = "thread-task-resume";
-/**
- * At most this many resumes are queued per pass. One wake works one task at
- * a time; the next pass after it queues the next one.
- */
-const RESUMES_PER_PASS = 1;
-/** Unfolded events read at `/stop` to tell pre-stop tasks from later ones. */
-const STOP_EVENTS = 1_000;
-/** A resume pass waits for the sidecar to catch up; if it cannot, it retries after this. */
-export const RESUME_RETRY_MS = 60_000;
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-export class ThreadTaskRuntime {
-    threadId;
-    store;
-    controller;
-    /**
-     * Latest event seq when this process started. A task whose last committed
-     * change came from events up to here was moved by a previous process.
-     */
-    startSeq;
-    /** Resumes this process accepted, by task id: a resume runs once per task per process. Released when its message goes back on the queue. */
-    resumesAccepted = new Set();
-    closed = false;
-    resumeHooks = null;
-    resumeRetry = null;
-    resumeRunning = false;
-    constructor(threadId, store, controller, startSeq, inProgressAtStart) {
-        this.threadId = threadId;
-        this.store = store;
-        this.controller = controller;
-        this.startSeq = startSeq;
-        if (inProgressAtStart > 0) {
-            logger.system(`[thread-tasks] thread=${threadId}: ${inProgressAtStart} task(s) were in progress when the previous process stopped`);
-        }
-    }
-    /**
-     * Open the thread's store next to its queue.db, take the writer slot and
-     * start the controller (which picks up events a previous process left).
-     * Returns null instead of throwing: without a runtime the agent runs
-     * exactly as before.
-     */
-    static start(options) {
-        let store;
-        try {
-            store = new ThreadTaskStore({
-                threadId: options.threadId,
-                writerId: options.writerId,
-                // Same file the MessageQueue owner opens, whichever process this is.
-                dbPath: options.dbPath ?? path.join(getConfigDir(), "queue.db"),
-                claimWriter: true,
-            });
-            // Read before the controller starts: it may move these tasks on, and
-            // nothing after start() may throw and leave its timer running.
-            const startSeq = store.latestSeq();
-            const inProgressAtStart = store.listTasks(["in_progress"]).length;
-            const controller = new ThreadTaskController({
-                store,
-                model: options.model ?? createSidecarModel(options.config),
-                ...LIVE_CONTROLLER_DEFAULTS,
-                ...options.controller,
-            });
-            const runtime = new ThreadTaskRuntime(options.threadId, store, controller, startSeq, inProgressAtStart);
-            controller.start();
-            return runtime;
-        }
-        catch (error) {
-            logger.err(`[thread-tasks] disabled for thread=${options.threadId}: ${errorMessage(error)}`);
-            try {
-                store?.close();
-            }
-            catch {
-                // Already closed or never opened.
-            }
-            return null;
-        }
-    }
-    /**
-     * Persist owner messages as events. Idempotent per message (queue dedup
-     * key), so a redelivered message, the watchdog and the wake path can all
-     * call it. Returns false if any message could not be recorded.
-     */
-    recordMessages(messages, options = {}) {
-        if (this.closed || messages.length === 0)
-            return !this.closed;
-        let ok = true;
-        let appended = false;
-        for (const msg of messages) {
-            try {
-                appended = this.store.appendMessageEvent(msg).appended || appended;
-            }
-            catch (error) {
-                ok = false;
-                logger.err(`[thread-tasks] could not record message ${msg.id} thread=${this.threadId}: ${errorMessage(error)}`);
-            }
-        }
-        if (appended && options.notify !== false)
-            this.safeNotify(true);
-        return ok;
-    }
-    /** Persist an execution event (response, tool result, todo update, status report). */
-    recordExecution(input) {
-        if (this.closed)
-            return;
-        try {
-            if (this.store.appendEvent(input).appended)
-                this.safeNotify(false);
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] could not record ${input.kind} thread=${this.threadId}: ${errorMessage(error)}`);
-        }
-    }
-    /**
-     * Record the messages, then wait up to `waitMs` for the sidecar to consume
-     * them. `registered` lists the open tasks the commit tied to these messages;
-     * empty means a reply may only acknowledge receipt.
-     *
-     * A run that started before these events cannot commit them (it snapshotted
-     * its batch), and a batch is a contiguous prefix, so the message may need
-     * more than one run: an execution-event backlog in front of it is folded
-     * first. The loop therefore waits for this message's events to be consumed,
-     * not for a single run, and stops as soon as the deadline passes or a run
-     * fails (the controller keeps retrying those events on its own schedule).
-     */
-    async registerMessages(messages, waitMs = REGISTRATION_WAIT_MS) {
-        const recorded = this.recordMessages(messages, { notify: false });
-        if (!recorded || this.closed)
-            return { recorded, registered: [] };
-        try {
-            const target = this.store.latestSeq();
-            const deadline = Date.now() + waitMs;
-            while (!this.isClosed() && this.store.getPosition() < target) {
-                const remaining = deadline - Date.now();
-                if (remaining <= 0)
-                    break;
-                let timer;
-                const timeout = new Promise((resolve) => { timer = setTimeout(() => { resolve("timeout"); }, remaining); });
-                const outcome = await Promise.race([this.controller.runOnce(), timeout]).finally(() => { clearTimeout(timer); });
-                // Only a commit or a conflict re-read is worth another pass; anything
-                // else (deadline, budget, fence, failure) is retried by the controller.
-                if (outcome === "timeout" || (outcome.status !== "committed" && outcome.status !== "conflict"))
-                    break;
-            }
-            return { recorded, registered: this.tasksForMessages(messages) };
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] registration run failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return { recorded, registered: [] };
-        }
-    }
-    /** `close()` may run while a wait awaits; a method read is not narrowed away. */
-    isClosed() {
-        return this.closed;
-    }
-    /** Open tasks already tied to any of these messages (no model call). */
-    tasksForMessages(messages) {
-        try {
-            const eventIds = new Set();
-            for (const msg of messages) {
-                const event = this.store.getEventByKey(messageEventKey(getMessageDedupKey(msg)));
-                if (event)
-                    eventIds.add(event.id);
-            }
-            if (eventIds.size === 0)
-                return [];
-            return this.store.listOpenTasks().filter((task) => task.sourceEventIds.some((id) => eventIds.has(id)));
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] lookup failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return [];
-        }
-    }
-    /** Tasks of this thread for the query tool; `[]` on error. */
-    listTasks(statuses = OPEN_TASK_STATUSES) {
-        try {
-            return this.store.listTasks(statuses);
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] list failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return [];
-        }
-    }
-    /**
-     * Let the sidecar fold every event up to the latest one (the explicit
-     * position of this boundary), waiting at most `waitMs`. No events past the
-     * position means no model call. On timeout, budget exhaustion or failure
-     * the events simply stay unconsumed: the controller keeps retrying them,
-     * and {@link contextBlock} shows them raw to the next recovery.
-     */
-    async reconcile(phase, waitMs) {
-        let target = 0;
-        let position = 0;
-        try {
-            target = this.store.latestSeq();
-            position = this.store.getPosition();
-            const deadline = Date.now() + waitMs;
-            while (!this.closed && position < target) {
-                const remaining = deadline - Date.now();
-                if (remaining <= 0)
-                    break;
-                let timer;
-                const timeout = new Promise((resolve) => { timer = setTimeout(() => { resolve("timeout"); }, remaining); });
-                const outcome = await Promise.race([this.controller.runOnce(), timeout]).finally(() => { clearTimeout(timer); });
-                position = this.store.getPosition();
-                // Only a commit or a conflict re-read is worth another pass; anything
-                // else (timeout, budget, failure, fence) is retried by the controller.
-                if (outcome === "timeout" || (outcome.status !== "committed" && outcome.status !== "conflict"))
-                    break;
-            }
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] ${phase} reconcile failed thread=${this.threadId}: ${errorMessage(error)}`);
-        }
-        if (position < target) {
-            logger.info(`[thread-tasks] ${phase} reconcile left ${target - position} event seq(s) unfolded thread=${this.threadId}`);
-        }
-        return { reached: position >= target, target, position };
-    }
-    /**
-     * Tasks a previous process left `in_progress`: their last change came from
-     * events recorded before this process started. That includes a task those
-     * events only move to `in_progress` when this process folds them at
-     * startup (the sidecar batches, so a crash usually leaves some). Once this
-     * process's own events move the task, it is no longer interrupted.
-     * TODO: a startup fold whose batch also holds events of this process
-     * stamps the task with the later seq and drops the flag early.
-     */
-    interruptedTaskIds() {
-        return new Set(this.store.listTasks(["in_progress"])
-            .filter((task) => task.lastEventSeq <= this.startSeq)
-            .map((task) => task.id));
-    }
-    /** The recovery context for this thread, or null when it owes nothing. Never throws. */
-    contextBlock() {
-        try {
-            const position = this.store.getPosition();
-            return renderThreadTaskContext({
-                openTasks: this.store.listOpenTasks(),
-                unfoldedEvents: this.store.readLatestEventsAfter(position, UNFOLDED_CONTEXT_EVENTS),
-                unfoldedTotal: this.store.latestSeq() - position,
-                interruptedTaskIds: this.interruptedTaskIds(),
-            });
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] context unavailable thread=${this.threadId}: ${errorMessage(error)}`);
-            return null;
-        }
-    }
-    /**
-     * Queue a resume for the next runnable task (PR 5), so the thread keeps
-     * working without a new owner message. Crash-safe in three steps:
-     * reserve the delivery record (`recovery:<task>:v<version>`), enqueue a
-     * system message whose id is that key, then mark it delivered. A crash
-     * before the enqueue leaves a reservation that the next pass re-sends; a
-     * crash after it is harmless because the queue dedups the id. A resume
-     * that was already delivered is never queued again for the same version.
-     *
-     * Never throws. Returns what it queued.
-     */
-    deliverResumes(queue, now = Date.now()) {
-        if (this.closed)
-            return { queued: [] };
-        const queued = [];
-        try {
-            // Re-send reservations a previous pass made but did not deliver.
-            for (const record of this.store.listUndeliveredRecoveries()) {
-                const task = this.store.getTask(record.taskId);
-                if (this.enqueueResume(queue, record.idempotencyKey, task, record.taskVersion))
-                    queued.push(record.idempotencyKey);
-            }
-            if (queued.length < RESUMES_PER_PASS) {
-                // Work the previous process left in progress comes first. Its resume
-                // may have been replayed already (then it is accepted and skipped).
-                const interrupted = [...this.interruptedTaskIds()]
-                    .filter((id) => !this.resumesAccepted.has(id))
-                    .map((id) => this.store.getTask(id))
-                    .filter((task) => task !== undefined);
-                for (const task of [...interrupted, ...this.store.listRunnableTasks(now)]) {
-                    if (queued.length >= RESUMES_PER_PASS)
-                        break;
-                    const reservation = this.store.reserveRecoveryDelivery({ taskId: task.id, taskVersion: task.version });
-                    if (!reservation.ok) {
-                        logger.warn(`[thread-tasks] resume not reserved thread=${this.threadId}: ${reservation.reason}`);
-                        break;
-                    }
-                    // Already delivered for this version: a wake took it and made no
-                    // recorded progress. Do not loop on it; progress bumps the version.
-                    if (!reservation.value.reserved)
-                        continue;
-                    if (this.enqueueResume(queue, reservation.value.record.idempotencyKey, task, task.version)) {
-                        queued.push(reservation.value.record.idempotencyKey);
-                    }
-                }
-            }
-            return { queued };
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] resume pass failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return { queued };
-        }
-    }
-    /**
-     * Whether a dequeued resume may still run (the re-check before execution).
-     * Yes when its task is still pending at the version it was queued for and
-     * is due: a cancel, modification, wait or block since then makes it stale.
-     * Also yes, once per task per process, when a previous process left the
-     * task `in_progress` ({@link interruptedTaskIds}): that is a resume replayed
-     * after a crash, or one queued for the interrupted task. Its version is not
-     * compared, because folding the previous process's last events at startup
-     * bumps it.
-     *
-     * The "once" test is against {@link resumesAccepted}, which a requeue
-     * releases ({@link releaseResume}): an accepted resume whose message went
-     * back on the queue must still run when it is dequeued again, or the
-     * interrupted task keeps its only recovery row forever.
-     * Fail-closed: any error means no.
-     */
-    isResumeRunnable(msg, now = Date.now()) {
-        try {
-            const taskId = msg.meta?.taskId;
-            const taskVersion = msg.meta?.taskVersion;
-            if (typeof taskId !== "string" || typeof taskVersion !== "number")
-                return false;
-            const task = this.store.getTask(taskId);
-            if (!task)
-                return false;
-            // Left in progress by a previous process: once, whatever the version.
-            if (task.status === "in_progress" && this.interruptedTaskIds().has(task.id)) {
-                return !this.resumesAccepted.has(task.id);
-            }
-            // Pending, or unfinished by an earlier wake of this process: unchanged
-            // since it was queued. Any progress, wait, block or cancel bumps the version.
-            return (task.status === "pending" || task.status === "in_progress")
-                && task.version === taskVersion
-                && (task.runAfter === undefined || task.runAfter <= now);
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] resume check failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return false;
-        }
-    }
-    /**
-     * The re-check at dequeue: {@link isResumeRunnable}, and if yes, record
-     * that this process is now working on the task so a second copy of its
-     * resume is stale.
-     */
-    acceptResume(msg, now = Date.now()) {
-        if (!this.isResumeRunnable(msg, now))
-            return false;
-        this.resumesAccepted.add(msg.meta?.taskId);
-        return true;
-    }
-    /**
-     * The resume was accepted but its message went back on the queue (a failed
-     * inject, an orphaned injection, a failed wake). Takes the acceptance back
-     * so the next dequeue may run it. Safe for any message: not a resume, or
-     * never accepted, does nothing. #2664 review P1-B.
-     */
-    releaseResume(messages) {
-        for (const msg of messages) {
-            const taskId = msg.meta?.taskId;
-            if (!isTaskResumeMessage(msg) || typeof taskId !== "string")
-                continue;
-            if (this.resumesAccepted.delete(taskId)) {
-                logger.info(`[thread-tasks] resume released back to the queue thread=${this.threadId} task=${taskId}`);
-            }
-        }
-    }
-    /** Install the loop's hooks. Resumes are only queued once this is set. */
-    enableResumes(hooks) {
-        this.resumeHooks = hooks;
-    }
-    /**
-     * The owner sent `/stop` (option B, owner 10-04): cancel every unfinished
-     * task of this thread. Cancelled is a stored status, so nothing queued
-     * starts on its own, a restart cannot bring it back, and resumes already
-     * queued are retired at dequeue.
-     *
-     * The open tasks are cancelled at once. A message sent just before
-     * `/stop` may not be folded yet: the sidecar then folds up to the stop
-     * (bounded by `waitMs`) and the tasks those events created are cancelled
-     * too. Tasks from messages after the `/stop` are kept. Returns every
-     * cancelled task, for the reply. Never throws.
-     * TODO: a fold that misses `waitMs` (or more than {@link STOP_EVENTS}
-     * unfolded events) can still create a task from a pre-stop message later.
-     */
-    async cancelOpenTasks(waitMs = RECONCILE_WAIT_MS.wakeEnd, queue) {
-        if (this.closed)
-            return { cancelled: [], droppedQueued: 0 };
-        let beforeStop;
-        let cancelled;
-        let droppedQueued = 0;
-        try {
-            // Queue rows first, at this boundary: a message the interrupt debounce
-            // has not recorded yet is not an event and owns no task, so nothing
-            // below would ever see it. Left in place, the next wake reads it as a
-            // new request and runs it (#2664 review P1-A).
-            droppedQueued = this.dropQueuedMessages(queue);
-            beforeStop = new Set(this.store.readUnconsumedEvents(STOP_EVENTS).map((event) => event.id));
-            cancelled = this.cancelTasks(this.store.listOpenTasks());
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] /stop cancel failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return { cancelled: [], droppedQueued };
-        }
-        if (beforeStop.size === 0)
-            return { cancelled, droppedQueued };
-        await this.reconcile("stop", waitMs);
-        if (this.isClosed())
-            return { cancelled, droppedQueued };
-        try {
-            // A task's first source event is the one that created it.
-            const late = this.store.listOpenTasks().filter((task) => beforeStop.has(task.sourceEventIds[0] ?? ""));
-            return { cancelled: [...cancelled, ...this.cancelTasks(late)], droppedQueued };
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] /stop cancel failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return { cancelled, droppedQueued };
-        }
-    }
-    /**
-     * Drop queued owner messages: rows not claimed by a wake, that are not
-     * system rows (a resume, or the stop command itself) and that the task
-     * sidecar would read as owner input. Returns how many were dropped.
-     * Fail-safe: a row that cannot be read is left alone.
-     */
-    dropQueuedMessages(queue) {
-        if (!queue)
-            return 0;
-        let dropped = 0;
-        for (const msg of queue.snapshot()) {
-            if (msg.channel === "system" || !isTaskRelevantMessage(msg))
-                continue;
-            try {
-                // Handled, not just removed: a provider retry of the same message
-                // would otherwise be accepted again as a request after the stop.
-                if (queue.remove(msg.id)) {
-                    queue.markHandled(msg);
-                    dropped += 1;
-                }
-            }
-            catch (error) {
-                logger.warn(`[thread-tasks] could not drop queued message ${msg.id} thread=${this.threadId}: ${errorMessage(error)}`);
-            }
-        }
-        if (dropped > 0)
-            logger.system(`[thread-tasks] /stop dropped ${dropped} queued message(s) thread=${this.threadId}`);
-        return dropped;
-    }
-    /**
-     * Commit `cancelled` for these tasks without consuming any event, so the
-     * sidecar still folds everything. Read and commit run in one synchronous
-     * stretch, so no sidecar commit lands between them; a sidecar call in
-     * flight hits a version conflict and re-reads.
-     */
-    cancelTasks(tasks) {
-        if (tasks.length === 0)
-            return [];
-        const position = this.store.getPosition();
-        const result = this.store.commit({
-            expectedPosition: position,
-            throughSeq: position,
-            changes: tasks.map((task) => ({ op: "update", taskId: task.id, expectedVersion: task.version, patch: { status: "cancelled" } })),
-        });
-        if (!result.ok) {
-            logger.warn(`[thread-tasks] /stop cancel rejected thread=${this.threadId}: ${result.reason} ${result.detail}`);
-            return [];
-        }
-        logger.system(`[thread-tasks] /stop cancelled ${tasks.length} task(s) thread=${this.threadId}`);
-        return [...tasks];
-    }
-    /**
-     * Fold the events up to now, then queue the next runnable task. Called at
-     * wake end and at startup; never throws and never blocks the caller's
-     * loop. Without the fold a task the wake just finished could still look
-     * pending, so a pass that cannot catch up delivers nothing and retries
-     * after {@link RESUME_RETRY_MS} instead. A fold that needs a slow sidecar
-     * call therefore starts the next task about a minute later, not at once.
-     */
-    async requestResume(waitMs = RECONCILE_WAIT_MS.wakeEnd) {
-        const hooks = this.resumeHooks;
-        if (!hooks || this.closed || this.resumeRunning)
-            return { queued: [] };
-        this.resumeRunning = true;
-        this.clearResumeRetry();
-        try {
-            const reconciled = await this.reconcile("wake_end", waitMs);
-            if (this.isClosed())
-                return { queued: [] };
-            // Events that arrived during the fold (another wake ran and ended; its
-            // own pass was dropped because this one was running) may cancel or
-            // finish the task this pass would queue: fold them first.
-            if (!reconciled.reached || this.store.latestSeq() > reconciled.target) {
-                this.scheduleResumeRetry();
-                return { queued: [] };
-            }
-            // Busy: usually a wake, whose end starts the next pass; but nightly
-            // maintenance is busy too and has no wake end, so retry either way.
-            if (hooks.isBusy() || hooks.isGated()) {
-                this.scheduleResumeRetry();
-                return { queued: [] };
-            }
-            const outcome = this.deliverResumes(hooks.queue);
-            if (outcome.queued.length > 0)
-                hooks.wake();
-            // By design (owner 10-03): a not-yet-due task waits; its due or
-            // unblock wake comes from the existing calendar / event-trigger
-            // messages to this thread. Thread tasks never schedule wakes.
-            return outcome;
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] resume request failed thread=${this.threadId}: ${errorMessage(error)}`);
-            return { queued: [] };
-        }
-        finally {
-            this.resumeRunning = false;
-        }
-    }
-    scheduleResumeRetry() {
-        if (this.closed || this.resumeRetry)
-            return;
-        this.resumeRetry = setTimeout(() => {
-            this.resumeRetry = null;
-            void this.requestResume();
-        }, RESUME_RETRY_MS);
-        this.resumeRetry.unref();
-    }
-    clearResumeRetry() {
-        if (this.resumeRetry)
-            clearTimeout(this.resumeRetry);
-        this.resumeRetry = null;
-    }
-    /** Enqueue one reserved resume and mark it delivered. False when nothing was handed over. */
-    enqueueResume(queue, key, task, version) {
-        if (!task) {
-            // TODO: a reservation whose task row is gone stays reserved; harmless,
-            // the next pass skips it again.
-            return false;
-        }
-        // `enqueue` returns false for an id it already holds or handled: that
-        // resume reached the queue before a crash, so marking it is still right.
-        queue.enqueue(resumeMessage(this.threadId, key, task, version));
-        const marked = this.store.markRecoveryDelivered(key);
-        if (!marked.ok) {
-            logger.warn(`[thread-tasks] resume ${key} queued but not marked thread=${this.threadId}: ${marked.reason}`);
-            return false;
-        }
-        this.recordExecution({
-            idempotencyKey: key,
-            kind: "recovery",
-            payload: { text: `Resumed: ${task.title}`, data: { taskId: task.id, taskVersion: version } },
-        });
-        logger.system(`[thread-tasks] queued resume thread=${this.threadId} task=${task.id} v${version}`);
-        return true;
-    }
-    /** Events not yet folded into tasks (the sidecar is behind or failing). */
-    pendingEventCount() {
-        try {
-            return this.store.readUnconsumedEvents(1_000).length;
-        }
-        catch {
-            return 0;
-        }
-    }
-    async close(graceMs) {
-        if (this.closed)
-            return;
-        this.closed = true;
-        this.clearResumeRetry();
-        try {
-            await this.controller.close(graceMs);
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] controller close failed thread=${this.threadId}: ${errorMessage(error)}`);
-        }
-        try {
-            this.store.close();
-        }
-        catch {
-            // Closing twice or after a failed open is harmless.
-        }
-    }
-    safeNotify(immediate) {
-        try {
-            this.controller.notify({ immediate });
-        }
-        catch (error) {
-            logger.warn(`[thread-tasks] notify failed thread=${this.threadId}: ${errorMessage(error)}`);
-        }
-    }
-}
-/**
- * The queue row for a resume. Its id is the delivery key, so the queue's
- * own dedup refuses a second copy. `system` keeps it out of fast replies,
- * the watchdog, activity cards and gate replies; the reply target travels
- * with the task, not with this row.
- */
-function resumeMessage(threadId, key, task, version) {
-    // Replies go where the task came from, like any task continuation.
-    const routing = task.replyTarget
-        ? taskContinuationRouting({ sender: RESUME_SENDER, delivery: task.replyTarget })
-        : { meta: {} };
-    return {
-        id: key,
-        channel: "system",
-        sender: RESUME_SENDER,
-        text: `[Thread task resume] Continue the queued task "${task.title}" (id ${task.id}). ` +
-            "Its requirements and checkpoint are in the Thread Tasks block. Check the checkpoint and results first; never redo a step listed as done. " +
-            "If it is no longer wanted or cannot start yet, report that instead of doing it.",
-        attachments: [],
-        timestamp: new Date().toISOString(),
-        ...routing,
-        meta: { ...routing.meta, kind: TASK_RESUME_KIND, taskId: task.id, taskVersion: version },
-        ...(threadId !== DEFAULT_THREAD_ID ? { threadId } : {}),
-    };
-}
-/** True for a queued thread-task resume row. */
-export function isTaskResumeMessage(msg) {
-    return msg.channel === "system" && msg.meta?.kind === TASK_RESUME_KIND;
-}
-/**
- * The re-check before execution, at every place a wake takes rows off the
- * queue: a resume whose task was cancelled, changed, put on hold or already
- * started since it was queued is retired unexecuted. Without a runtime (the
- * switch was turned off) every resume is stale. Returns true when retired.
- */
-export function retireStaleResume(queue, runtime, msg) {
-    if (!isTaskResumeMessage(msg) || runtime?.acceptResume(msg) === true)
-        return false;
-    logger.system(`[thread-tasks] dropping stale resume ${msg.id}`);
-    queue.markHandled(msg);
-    return true;
-}
-/**
- * Messages the task store tracks: anything from a real channel. System
- * messages (heartbeats, internal continuations) and external-wake markers
- * carry no owner request. Email and group chats are included; the sidecar
- * decides whether they hold a request.
- */
-export function isTaskRelevantMessage(msg) {
-    return msg.channel !== "system" && msg.meta?.kind !== EXTERNAL_WAKE_KIND;
-}
-/**
- * The end-of-wake handoff (issue #1996 PR 1 rule): a claim is released as
- * handled only after its message is a durable task event, so the follow-up
- * belongs to the task store instead of vanishing with the queue row.
- *
- * Fail-safe: if recording fails the claims are still released. The agent
- * already processed them in this wake; replaying them would redo the work.
- * The error is logged. `handled` never means a task is completed.
- */
-export function releaseClaimsAfterRecording(queue, runtime) {
-    if (runtime) {
-        try {
-            runtime.recordMessages(queue.currentCycleClaims().filter(isTaskRelevantMessage));
-        }
-        catch (error) {
-            logger.err(`[thread-tasks] could not record claims before release: ${errorMessage(error)}`);
-        }
-    }
-    queue.markAllInFlightHandled();
-}
-/**
- * Wake end. A wake cut short by an engine failover restart leaves its claims
- * in flight for the replacement process (issue #2519) and folds nothing.
- * Otherwise release the claims, fold this wake's events into the
- * checkpoints and queue the next runnable task (PR 5). Not awaited: the
- * session keeps its transcript, so the loop need not hold the next message
- * for it. Bounded; leftovers stay unconsumed and the next wake's context
- * shows them raw.
- */
-export function endWakeThreadTasks(queue, runtime, options) {
-    if (options.failoverRestartPending)
-        return;
-    releaseClaimsAfterRecording(queue, runtime);
-    void runtime?.requestResume();
-}
-/** Per-event caps; the sidecar clips again, this keeps the event log small. */
-const EXECUTION_TEXT_CHARS = 1_500;
-const TOOL_OUTPUT_CHARS = 400;
-function clipText(text, max) {
-    return text.length <= max ? text : `${text.slice(0, max)}… [${text.length - max} more chars]`;
-}
-/**
- * Provider tool-call ids are not unique for the life of a thread: some
- * providers number them per response (`functions.notify_user:0`). A stream
- * emits each result once, so the key only has to be unique; a process nonce
- * plus a counter makes it so.
- */
-const EXECUTION_KEY_NONCE = randomUUID().slice(0, 8);
-let executionKeySeq = 0;
-function executionKey(prefix, toolUseId) {
-    executionKeySeq += 1;
-    return `${prefix}:${toolUseId}:${EXECUTION_KEY_NONCE}-${executionKeySeq}`;
-}
-/** Tools whose results say nothing about task progress. */
-const NOISE_TOOLS = new Set(["wait", "finish", "TodoWrite", "TaskCreate", "TaskUpdate", "TaskList", "TaskGet"]);
-function baseToolName(name) {
-    return name.replace(/^mcp__[^_]+(?:_[^_]+)*__/, "");
-}
-/**
- * Engine-neutral execution events. Both engines feed the same stream
- * handler, so these are called from there. Each id is unique per call, so
- * keys never collide across wakes or retries.
- */
-export const executionEvents = {
-    toolResult(toolUseId, toolName, output, isError) {
-        const name = baseToolName(toolName);
-        // Some providers stream tool calls without an id; a shared empty key
-        // would dedup every later one away, so those results are not recorded.
-        if (NOISE_TOOLS.has(name) || !toolUseId)
-            return null;
-        return {
-            idempotencyKey: executionKey("tool", toolUseId),
-            kind: "tool_result",
-            payload: { data: { tool: name, ok: !isError, output: clipText(output, TOOL_OUTPUT_CHARS) } },
-        };
-    },
-    todos(toolUseId, todos) {
-        if (!toolUseId)
-            return null;
-        return {
-            idempotencyKey: executionKey("todo", toolUseId),
-            kind: "todo_update",
-            payload: { data: { todos: todos.map((todo) => ({ content: clipText(todo.content, 200), status: todo.status })) } },
-        };
-    },
-    response(turnId, text) {
-        const trimmed = text.trim();
-        if (!trimmed)
-            return null;
-        return { idempotencyKey: `response:${turnId}`, kind: "assistant_response", payload: { text: clipText(trimmed, EXECUTION_TEXT_CHARS) } };
-    },
-    /** What the agent told the owner through notify_user: an explicit status report. */
-    statusReport(toolUseId, message) {
-        const trimmed = message.trim();
-        if (!trimmed || !toolUseId)
-            return null;
-        return { idempotencyKey: executionKey("report", toolUseId), kind: "status_report", payload: { text: clipText(trimmed, EXECUTION_TEXT_CHARS) } };
-    },
-};
-/**
- * The fast responder's reading of a batch, as one candidate event. It shares
- * the message's dedup key, so the sidecar's origin key matches the message's
- * and the same task is never created twice. Only for a single-message batch:
- * a brief over several messages cannot be keyed to the right one, and the
- * messages themselves are already events.
- */
-export function fastResponderCandidate(messages, brief) {
-    const relevant = messages.filter(isTaskRelevantMessage);
-    const first = relevant.length === 1 ? relevant[0] : undefined;
-    const text = typeof brief === "string" ? brief.trim() : "";
-    if (!first || !text)
-        return null;
-    const dedupKey = getMessageDedupKey(first);
-    return {
-        idempotencyKey: `candidate:${dedupKey}`,
-        kind: "fast_responder_candidate",
-        source: { channel: first.channel, sender: first.sender, messageId: first.id, dedupKey },
-        payload: { text: clipText(text, EXECUTION_TEXT_CHARS) },
-    };
-}
-/** Record the fast responder's brief as a candidate event. Never throws. */
-export function recordFastResponderCandidate(messages, brief) {
-    try {
-        recordExecutionEvent(fastResponderCandidate(messages, brief));
-    }
-    catch (error) {
-        logger.warn(`[thread-tasks] could not record fast-responder candidate: ${errorMessage(error)}`);
-    }
-}
-/** Record an execution event on the process runtime, if there is one. Never throws. */
-export function recordExecutionEvent(input) {
-    if (input)
-        current?.recordExecution(input);
-}
-/** The process runtime's recovery context, or null without a runtime (then nothing is injected). */
-export function buildThreadTaskContext() {
-    return current?.contextBlock() ?? null;
-}
-/** Bounded reconcile on the process runtime; resolves immediately without one. */
-export async function reconcileThreadTasks(phase, waitMs = RECONCILE_WAIT_MS.boundary) {
-    await current?.reconcile(phase, waitMs);
-}
-/** The runtime for this process, set once by the loop. Tools and hooks read it. */
-let current = null;
-export function setThreadTaskRuntime(runtime) {
-    current = runtime;
-}
-export function getThreadTaskRuntime() {
-    return current;
-}
-//# sourceMappingURL=thread-task-runtime.js.map