@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/background/tasks.service.js

@@ -0,0 +1,271 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { isSandboxGoneError, rootsOf } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { ConversationAccess } from "../conversations/access.js";
+import { EventLog } from "../conversations/event-log.js";
+import { conversationTree } from "../conversations/tree.js";
+import { ConversationDevices } from "../devices/conversation-devices.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { UUID_RE } from "../ui/registry.js";
+import { finishedEventKey } from "./finish.js";
+import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
+import { actingAs } from "./session.js";
+import { BackgroundTaskStopper } from "./stop.js";
+import { BackgroundTaskStore } from "./store.js";
+/** The most bytes of output one read returns. */
+export const OUTPUT_TAIL_MAX_BYTES = 65_536;
+/** The time limit of reading an output (the exec and the wait for the sandbox's lease). */
+const OUTPUT_READ_TIMEOUT_MS = 30_000;
+const conversationNotFound = () => new ApiError("conversation.not_found", "Conversation not found");
+const taskNotFound = () => new ApiError("background_task.not_found", "Background task not found");
+/**
+ * The HTTP side of background tasks (spec 2026-11-05-background-bash-design §5): the tasks of a
+ * conversation and of its sub-agents, stopping one, reading its output. A task is reachable
+ * through the conversation that owns it or through any conversation above it, and only by a
+ * person who may see the conversation (`ConversationAccess`, the rule of `GET :id`, which is also
+ * what `POST :id/abort` checks: the owner).
+ */
+let BackgroundTasks = class BackgroundTasks {
+    access;
+    store;
+    stopper;
+    sandbox;
+    eventLog;
+    db;
+    devices;
+    constructor(access, store, stopper, sandbox, eventLog, db, devices) {
+        this.access = access;
+        this.store = store;
+        this.stopper = stopper;
+        this.sandbox = sandbox;
+        this.eventLog = eventLog;
+        this.db = db;
+        this.devices = devices;
+    }
+    /**
+     * The conversation and every sub-agent conversation below it (grandchildren too: their tasks run
+     * in the root's sandbox, agent map spec §6); `conversation.not_found` when not visible.
+     */
+    async scope(orgId, conversationId, accountId) {
+        if (!UUID_RE.test(conversationId) ||
+            !(await this.access.isAccessible(orgId, conversationId, accountId))) {
+            throw conversationNotFound();
+        }
+        // the conversation is the org's (isAccessible), and so is every sub-agent conversation below it
+        return (await conversationTree(this.db.db, conversationId)).map((c) => c.id);
+    }
+    view(task, conversationId) {
+        return {
+            id: task.id,
+            conversationId,
+            subagentId: task.conversationId === conversationId ? null : task.conversationId,
+            description: task.description,
+            command: task.command,
+            status: task.status,
+            exitCode: task.exitCode,
+            lostReason: task.lostReason,
+            startedAt: task.startedAt.toISOString(),
+            finishedAt: task.finishedAt === null ? null : task.finishedAt.toISOString(),
+            stopping: task.status === "running" && task.stoppingAt !== null,
+        };
+    }
+    async owned(orgId, conversationId, accountId, taskId) {
+        const ids = await this.scope(orgId, conversationId, accountId);
+        if (!TASK_ID_RE.test(taskId))
+            throw taskNotFound();
+        const task = await this.store.get(taskId);
+        if (!task || task.orgId !== orgId || !ids.includes(task.conversationId))
+            throw taskNotFound();
+        return task;
+    }
+    /** The tasks of the conversation and its sub-agents, newest first. */
+    async list(orgId, conversationId, accountId) {
+        const ids = await this.scope(orgId, conversationId, accountId);
+        return (await this.store.listFor(ids)).map((t) => this.view(t, conversationId));
+    }
+    /**
+     * A person's stop. Returns the row after the stop: `running` with `stopping` true when another
+     * stop already claimed the task (or the task is a reservation still launching, which its launch
+     * then kills); a stop that fails throws. Writes the `background_task.stopped` audit event.
+     */
+    async stop(orgId, conversationId, accountId, taskId, actorTokenId, auditDetail) {
+        const task = await this.owned(orgId, conversationId, accountId, taskId);
+        const after = await this.stopper.stop(task, "person");
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "background_task.stopped",
+            target: task.id,
+            detail: {
+                taskId: task.id,
+                conversationId: task.conversationId,
+                status: after.status,
+                ...auditDetail,
+            },
+        });
+        return this.view(after, conversationId);
+    }
+    /**
+     * Whether the task's device may still be used by its conversation's owner (the access
+     * re-check every sandbox tool call makes); when it may not, the live read is skipped.
+     */
+    async deviceUsable(orgId, taskConversationId) {
+        try {
+            await this.devices.forTool(orgId, await rootConversationOf(this.db.db, taskConversationId));
+            return true;
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * The end of the task's output, at most `tail` bytes. Read live when the task's device
+     * instance runs (never resuming a suspended one); a finished task that cannot be read live
+     * answers with the last lines its finished event kept and why (`unavailable`). Anything else is
+     * `background_task.output_unavailable` (409) with `details: [{ reason, environment }]`.
+     */
+    async output(orgId, conversationId, accountId, taskId, tail) {
+        const task = await this.owned(orgId, conversationId, accountId, taskId);
+        const read = await this.readLive(orgId, accountId, task, tail);
+        if (read.kind === "ok")
+            return { ...read.value, source: "live" };
+        const unavailable = {
+            reason: read.reason,
+            environment: await this.environmentOf(task.deviceId),
+        };
+        if (task.status !== "running") {
+            const ev = await this.eventLog.findByIdem(task.conversationId, finishedEventKey(task.id));
+            if (ev?.type === "background_task_finished") {
+                return { text: ev.payload.lastLines, truncated: true, source: "event", unavailable };
+            }
+        }
+        throw new ApiError("background_task.output_unavailable", `The task's output cannot be read now (${unavailable.reason})`, [unavailable]);
+    }
+    /** Whether the task ran on a local device (its machine) or in a cloud sandbox. */
+    async environmentOf(deviceId) {
+        if (deviceId === null)
+            return "cloud";
+        const row = await this.db.db
+            .selectFrom("devices")
+            .select("source")
+            .where("id", "=", deviceId)
+            .executeTakeFirst();
+        return row?.source === "local" ? "local" : "cloud";
+    }
+    /** Reads the output from the task's running instance, or says why it cannot. */
+    async readLive(orgId, accountId, task, tail) {
+        if (task.sid === null || task.sandboxCreatedAt === null || task.deviceId === null) {
+            // a reservation the launch has not finished, or a launch that failed
+            return {
+                kind: "unavailable",
+                reason: task.status === "running" ? "starting" : "not_started",
+            };
+        }
+        if (!(await this.sandbox.availableFor(task.deviceId))) {
+            return { kind: "unavailable", reason: "unavailable" };
+        }
+        if (!(await this.deviceUsable(orgId, task.conversationId))) {
+            return { kind: "unavailable", reason: "no_access" };
+        }
+        const createdAt = task.sandboxCreatedAt;
+        // the person reading it acts in the task's conversation
+        const actor = { accountId, conversationId: task.conversationId };
+        try {
+            const r = await this.sandbox.ifRunning(task.deviceId, { createdAt }, async (p, h, signal) => {
+                const res = await actingAs(p, actor).exec(h, {
+                    command: tailScript(task.id, tail),
+                    cwd: rootsOf(h).workspace,
+                    timeoutMs: OUTPUT_READ_TIMEOUT_MS,
+                    maxOutputBytes: 2 * OUTPUT_TAIL_MAX_BYTES + 4096,
+                    signal,
+                });
+                return res.exitCode === 0 ? parseTail(res.stdout, tail) : null;
+            }, AbortSignal.timeout(OUTPUT_READ_TIMEOUT_MS));
+            if (r.kind === "other_instance")
+                return { kind: "unavailable", reason: "rebuilt" };
+            if (r.kind === "not_running") {
+                // a suspended instance keeps its files; any other state means they went with it
+                return { kind: "unavailable", reason: r.status === "suspended" ? "suspended" : "rebuilt" };
+            }
+            if (r.value === null)
+                return { kind: "unavailable", reason: "read_failed" };
+            if (r.value === "missing")
+                return { kind: "unavailable", reason: "output_missing" };
+            return { kind: "ok", value: r.value };
+        }
+        catch (e) {
+            if (isSandboxGoneError(e))
+                return { kind: "unavailable", reason: "rebuilt" };
+            // a local device's machine: offline, or no longer the owner's (revoked, deleted)
+            if (e instanceof ApiError && e.code.startsWith("device.")) {
+                return {
+                    kind: "unavailable",
+                    reason: e.code === "device.offline" ? "device_offline" : "no_access",
+                };
+            }
+            throw e;
+        }
+    }
+};
+BackgroundTasks = __decorate([
+    Injectable(),
+    __param(0, Inject(ConversationAccess)),
+    __param(1, Inject(BackgroundTaskStore)),
+    __param(2, Inject(BackgroundTaskStopper)),
+    __param(3, Inject(SandboxService)),
+    __param(4, Inject(EventLog)),
+    __param(5, Inject(KernelDb)),
+    __param(6, Inject(ConversationDevices))
+], BackgroundTasks);
+export { BackgroundTasks };
+/**
+ * Prints `size <bytes>` and `out <base64 of the last `tail` bytes>`, or `missing` when the output
+ * file is not there. Relative to the workspace root; POSIX tools only (`wc -c`, `tail -c`,
+ * `base64`, `tr`), so it reads the same on Linux and macOS.
+ */
+export function tailScript(id, tail) {
+    if (!TASK_ID_RE.test(id))
+        throw new Error(`invalid background task id: ${id}`);
+    const f = `${TASKS_DIR}/${id}.out`;
+    return [
+        `if [ ! -f ${f} ]; then echo missing; exit 0; fi`,
+        `s=$({ wc -c < ${f}; } 2>/dev/null | tr -d ' '); echo "size \${s:-0}"`,
+        `printf 'out '; { tail -c ${Math.floor(tail)} ${f} 2>/dev/null | base64 | tr -d '\\n'; }; echo`,
+    ].join("\n");
+}
+/**
+ * Decodes {@link tailScript}'s output (`missing`: no output file; null: unreadable); a cut that
+ * splits a UTF-8 character drops its tail bytes.
+ */
+export function parseTail(stdout, tail) {
+    if (/^missing$/m.test(stdout))
+        return "missing";
+    const size = /^size ([0-9]+)$/m.exec(stdout);
+    const out = /^out (\S*)$/m.exec(stdout);
+    if (!size || !out)
+        return null;
+    let bytes = Buffer.from(out[1], "base64");
+    const truncated = Number(size[1]) > tail;
+    if (truncated) {
+        let i = 0;
+        while (i < bytes.length && i < 3 && (bytes[i] & 0xc0) === 0x80)
+            i++;
+        bytes = bytes.subarray(i);
+    }
+    return { text: bytes.toString("utf8"), truncated };
+}

package/dist/background/wake-rules.d.ts

@@ -0,0 +1,66 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * The wake rules of an idle conversation (spec 2026-11-05-background-bash-design §3, generalized
+ * by agent map spec §5.3 to a second event kind): a finished background task or a sub-agent's
+ * delivery starts a run. Read by `RunQueue.ensureRun` in its transaction: every path that may start
+ * a run (a finish, a delivery, the end of a run, the delayed wake job, a page opening) applies the
+ * same rules. `BackgroundWake` is what calls `ensureRun` when a task finishes or a delivery lands.
+ */
+/** No two wakes of one conversation start within this window. */
+export declare const WAKE_WINDOW_MS = 60000;
+/** The delayed job that wakes a conversation at the end of its window (`cap-kernel-maintenance`). */
+export declare const BG_WAKE_JOB = "bg-wake";
+/**
+ * Its job id: one job per conversation and window end (no `:`). `retry` > 0 is a job that fired
+ * before the window ended on the database's clock and scheduled itself again: a distinct id, since
+ * BullMQ ignores an add under the id of the job still running.
+ */
+export declare const bgWakeJobId: (conversationId: string, windowEnd: number, retry?: number) => string;
+export interface BgWakeJobData {
+    conversationId: string;
+    /** How many times this window's wake fired early (absent: none). */
+    retry?: number;
+}
+/**
+ * What a conversation's unconsumed wake events decide:
+ * - `wake`: start a run whose boundary is the event at `seq`, as `triggerAccountId`;
+ * - `later`: a wake started less than {@link WAKE_WINDOW_MS} ago; the window ends at `windowEnd`
+ *   (epoch ms, the database's clock), `delayMs` from now;
+ * - null: nothing wakes the conversation.
+ */
+export type WakeDecision = {
+    kind: "wake";
+    seq: number;
+    triggerAccountId: string;
+} | {
+    kind: "later";
+    windowEnd: number;
+    delayMs: number;
+} | null;
+/**
+ * The wake decision for a conversation that is idle and has no unconsumed message (the caller
+ * checked these under the conversation's row lock): a chat conversation (`rootId` = its own id) or
+ * a sub-agent's (`rootId` = the root of its tree). An event wakes it when:
+ * - it is after `consumed` and is either
+ *   - a `background_task_finished` of a task of this conversation (the join on `conversation_id`
+ *     reads the task's trigger account) that is not `reported` (a tool call already told the model)
+ *     and has no `stoppedBy` (`"person"`: that person is looking at the conversation;
+ *     `"deletion"`: the conversation is being deleted), or
+ *   - a `subagent_delivery` (its own `triggerAccountId`: the trigger account of the child run that
+ *     delivered it, agent map spec §7), except the finish of a child that was stopped
+ *     (`status: "aborted"`: a person's stop of it or of a sub-agent above it, a tree stop, the
+ *     deletion of the root), for the same reason as a person's task stop; a tree stop thus never
+ *     wakes the stopped ancestors through their descendants' finishes, which land after them;
+ * - the wake setting is on (the org's override, else `deploymentOn`);
+ * - the root's queue is not paused and the root is not deleted (a paused root holds the wakes of
+ *   the whole tree, agent map spec §5.3);
+ * - the event's trigger account can still send to the root (`canSend`, which the caller binds to
+ *   the root);
+ * - no other wake of this conversation started in the last {@link WAKE_WINDOW_MS} (else `later`).
+ * The boundary is the newest event whose trigger account can send.
+ */
+export declare function wakeDecisionIn(t: KernelSchemaDb, conv: {
+    id: string;
+    orgId: string;
+    rootId: string;
+}, consumed: number, deploymentOn: boolean, canSend: (accountId: string) => Promise<boolean>): Promise<WakeDecision>;

package/dist/background/wake-rules.js

@@ -0,0 +1,113 @@
+import { sql } from "kysely";
+import { effectiveWakeOnBackgroundTask, readOrgSettings } from "../orgs/settings.service.js";
+/**
+ * The wake rules of an idle conversation (spec 2026-11-05-background-bash-design §3, generalized
+ * by agent map spec §5.3 to a second event kind): a finished background task or a sub-agent's
+ * delivery starts a run. Read by `RunQueue.ensureRun` in its transaction: every path that may start
+ * a run (a finish, a delivery, the end of a run, the delayed wake job, a page opening) applies the
+ * same rules. `BackgroundWake` is what calls `ensureRun` when a task finishes or a delivery lands.
+ */
+/** No two wakes of one conversation start within this window. */
+export const WAKE_WINDOW_MS = 60_000;
+/** The delayed job that wakes a conversation at the end of its window (`cap-kernel-maintenance`). */
+export const BG_WAKE_JOB = "bg-wake";
+/**
+ * Its job id: one job per conversation and window end (no `:`). `retry` > 0 is a job that fired
+ * before the window ended on the database's clock and scheduled itself again: a distinct id, since
+ * BullMQ ignores an add under the id of the job still running.
+ */
+export const bgWakeJobId = (conversationId, windowEnd, retry = 0) => `bg-wake-${conversationId}-${windowEnd}${retry > 0 ? `-r${retry}` : ""}`;
+/** How many unconsumed events are tried for a trigger account that can still send. */
+const CANDIDATES = 20;
+/** The event types whose run is a wake run (its boundary, `runs.trigger_seq`, is one of them). */
+const WAKE_EVENT_TYPES = ["background_task_finished", "subagent_delivery"];
+/**
+ * The wake decision for a conversation that is idle and has no unconsumed message (the caller
+ * checked these under the conversation's row lock): a chat conversation (`rootId` = its own id) or
+ * a sub-agent's (`rootId` = the root of its tree). An event wakes it when:
+ * - it is after `consumed` and is either
+ *   - a `background_task_finished` of a task of this conversation (the join on `conversation_id`
+ *     reads the task's trigger account) that is not `reported` (a tool call already told the model)
+ *     and has no `stoppedBy` (`"person"`: that person is looking at the conversation;
+ *     `"deletion"`: the conversation is being deleted), or
+ *   - a `subagent_delivery` (its own `triggerAccountId`: the trigger account of the child run that
+ *     delivered it, agent map spec §7), except the finish of a child that was stopped
+ *     (`status: "aborted"`: a person's stop of it or of a sub-agent above it, a tree stop, the
+ *     deletion of the root), for the same reason as a person's task stop; a tree stop thus never
+ *     wakes the stopped ancestors through their descendants' finishes, which land after them;
+ * - the wake setting is on (the org's override, else `deploymentOn`);
+ * - the root's queue is not paused and the root is not deleted (a paused root holds the wakes of
+ *   the whole tree, agent map spec §5.3);
+ * - the event's trigger account can still send to the root (`canSend`, which the caller binds to
+ *   the root);
+ * - no other wake of this conversation started in the last {@link WAKE_WINDOW_MS} (else `later`).
+ * The boundary is the newest event whose trigger account can send.
+ */
+export async function wakeDecisionIn(t, conv, consumed, deploymentOn, canSend) {
+    const finishes = await t
+        .selectFrom("conversation_events as e")
+        .innerJoin("background_tasks as b", (j) => j
+        .on(sql `b.id = e.payload ->> 'taskId'`)
+        .onRef("b.conversation_id", "=", "e.conversation_id"))
+        .select(["e.seq", "b.trigger_account_id as account"])
+        .where("e.conversation_id", "=", conv.id)
+        .where("e.type", "=", "background_task_finished")
+        .where("e.seq", ">", String(consumed))
+        .where(sql `(e.payload ->> 'reported')::boolean = false`)
+        .where(sql `e.payload ->> 'stoppedBy' IS NULL`)
+        .orderBy("e.seq", "desc")
+        .limit(CANDIDATES)
+        .execute();
+    const deliveries = await t
+        .selectFrom("conversation_events as e")
+        .select(["e.seq", sql `e.payload ->> 'triggerAccountId'`.as("account")])
+        .where("e.conversation_id", "=", conv.id)
+        .where("e.type", "=", "subagent_delivery")
+        .where("e.seq", ">", String(consumed))
+        .where(sql `e.payload ->> 'status' IS DISTINCT FROM 'aborted'`)
+        .orderBy("e.seq", "desc")
+        .limit(CANDIDATES)
+        .execute();
+    const candidates = [...finishes, ...deliveries]
+        .sort((a, b) => Number(b.seq) - Number(a.seq))
+        .slice(0, CANDIDATES);
+    if (candidates.length === 0)
+        return null;
+    const org = (await readOrgSettings(t, conv.orgId)).wakeOnBackgroundTask;
+    if (!effectiveWakeOnBackgroundTask(deploymentOn, org))
+        return null;
+    const root = await t
+        .selectFrom("conversations")
+        .select(["queue_paused", "deleted_at"])
+        .where("id", "=", conv.rootId)
+        .executeTakeFirst();
+    if (!root || root.queue_paused || root.deleted_at !== null)
+        return null;
+    let boundary;
+    for (const c of candidates) {
+        if (await canSend(c.account)) {
+            boundary = { seq: Number(c.seq), triggerAccountId: c.account };
+            break;
+        }
+    }
+    if (boundary === undefined)
+        return null;
+    // the window starts when the last wake run was created (PG, so every replica reads the same)
+    const last = await t
+        .selectFrom("runs as r")
+        .innerJoin("conversation_events as w", (j) => j.onRef("w.conversation_id", "=", "r.conversation_id").onRef("w.seq", "=", "r.trigger_seq"))
+        .select([
+        sql `floor(extract(epoch from max(r.created_at)) * 1000)::bigint`.as("started"),
+        sql `floor(extract(epoch from now()) * 1000)::bigint`.as("now"),
+    ])
+        .where("r.conversation_id", "=", conv.id)
+        .where("w.type", "in", WAKE_EVENT_TYPES)
+        .executeTakeFirst();
+    if (last?.started != null) {
+        const windowEnd = Number(last.started) + WAKE_WINDOW_MS;
+        const now = Number(last.now);
+        if (windowEnd > now)
+            return { kind: "later", windowEnd, delayMs: windowEnd - now };
+    }
+    return { kind: "wake", ...boundary };
+}

package/dist/background/wake.d.ts

@@ -0,0 +1,30 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type OnApplicationShutdown } from "@nestjs/common";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { RunQueue } from "../runtime/run-queue.js";
+/**
+ * Wakes an idle conversation when one of its background tasks finished (spec
+ * 2026-11-05-background-bash-design §3) or a sub-agent delivered to it (agent map spec §5.3).
+ * {@link BackgroundTaskFinisher} announces the committed finish (`background_task.finished`) and
+ * `SubagentDeliveries` the committed delivery (`subagent.delivered`), both in-process domain
+ * events emitted after the commit; {@link onFinished} asks the run queue for a run. The wake rules
+ * themselves (own task, not reported, the wake setting, the root's queue not paused, the trigger
+ * account can still send to the root, the 60 s window and its delayed `bg-wake` job) are applied
+ * by `RunQueue.ensureRun` in its transaction (`wakeDecisionIn`, ./wake-rules.ts), so a run's end,
+ * the delayed job and a page opening apply the same rules; a lost event is re-derived by the next
+ * of them. Provided by `RuntimeModule`.
+ */
+export declare class BackgroundWake implements OnApplicationShutdown {
+    private readonly runs;
+    private readonly log;
+    /** Drops the subscriptions (the events may outlive this instance). */
+    private readonly unsubscribe;
+    constructor(runs: Pick<RunQueue, "ensureRun">, events: KernelEvents, log: Pick<Logger, "warn">);
+    /**
+     * A task of `conversationId` finished, or a sub-agent delivered to it (after the commit): starts
+     * a wake run when the rules allow it, or schedules one at the end of the wake window. A run in
+     * progress absorbs the event at its next step instead, or its end starts the wake. Never throws.
+     */
+    onFinished(conversationId: string): Promise<void>;
+    onApplicationShutdown(): void;
+}

package/dist/background/wake.js

@@ -0,0 +1,63 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { RunQueue } from "../runtime/run-queue.js";
+/**
+ * Wakes an idle conversation when one of its background tasks finished (spec
+ * 2026-11-05-background-bash-design §3) or a sub-agent delivered to it (agent map spec §5.3).
+ * {@link BackgroundTaskFinisher} announces the committed finish (`background_task.finished`) and
+ * `SubagentDeliveries` the committed delivery (`subagent.delivered`), both in-process domain
+ * events emitted after the commit; {@link onFinished} asks the run queue for a run. The wake rules
+ * themselves (own task, not reported, the wake setting, the root's queue not paused, the trigger
+ * account can still send to the root, the 60 s window and its delayed `bg-wake` job) are applied
+ * by `RunQueue.ensureRun` in its transaction (`wakeDecisionIn`, ./wake-rules.ts), so a run's end,
+ * the delayed job and a page opening apply the same rules; a lost event is re-derived by the next
+ * of them. Provided by `RuntimeModule`.
+ */
+let BackgroundWake = class BackgroundWake {
+    runs;
+    log;
+    /** Drops the subscriptions (the events may outlive this instance). */
+    unsubscribe;
+    constructor(runs, events, log) {
+        this.runs = runs;
+        this.log = log;
+        this.unsubscribe = [
+            events.on("background_task.finished", ({ conversationId }) => this.onFinished(conversationId)),
+            events.on("subagent.delivered", ({ conversationId }) => this.onFinished(conversationId)),
+        ];
+    }
+    /**
+     * A task of `conversationId` finished, or a sub-agent delivered to it (after the commit): starts
+     * a wake run when the rules allow it, or schedules one at the end of the wake window. A run in
+     * progress absorbs the event at its next step instead, or its end starts the wake. Never throws.
+     */
+    async onFinished(conversationId) {
+        try {
+            await this.runs.ensureRun(conversationId);
+        }
+        catch (err) {
+            this.log.warn("background wake failed", { conversationId, err });
+        }
+    }
+    onApplicationShutdown() {
+        for (const off of this.unsubscribe)
+            off();
+    }
+};
+BackgroundWake = __decorate([
+    Injectable(),
+    __param(0, Inject(RunQueue)),
+    __param(1, Inject(KernelEvents)),
+    __param(2, Inject(KERNEL_LOGGER))
+], BackgroundWake);
+export { BackgroundWake };