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

package/dist/background/background.controller.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type BackgroundTaskOutput, BackgroundTasks, type BackgroundTaskView } from "./tasks.service.js";
+declare const ConversationParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const TaskParams: z.ZodObject<{
+    id: z.ZodString;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+declare const OutputQuery: z.ZodObject<{
+    tail: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * Background Bash tasks of a conversation (spec 2026-11-05-background-bash-design §5). Visible to
+ * whoever sees the conversation, stoppable by whoever may abort its run (the owner): the same
+ * checks as `GET :id` and `POST :id/abort`.
+ */
+export declare class BackgroundController {
+    private readonly tasks;
+    constructor(tasks: BackgroundTasks);
+    /** The conversation's tasks and its sub-agents' (`subagentId`), newest first. */
+    list(principal: Principal, org: OrgContext, params: z.infer<typeof ConversationParams>): Promise<{
+        tasks: BackgroundTaskView[];
+    }>;
+    /**
+     * Stops a task like a person's stop: 200 `{ task }` with the row after the stop. A task that is
+     * still `running` with `stopping: true` is being stopped by another request (or is still
+     * launching); a stop that fails is an error and the task keeps running.
+     */
+    stop(principal: Principal, org: OrgContext, params: z.infer<typeof TaskParams>): Promise<{
+        task: BackgroundTaskView;
+    }>;
+    /** The end of the task's output (`tail` bytes, at most 65536); 409 when it cannot be read now. */
+    output(principal: Principal, org: OrgContext, params: z.infer<typeof TaskParams>, q: z.infer<typeof OutputQuery>): Promise<BackgroundTaskOutput>;
+}
+export {};

package/dist/background/background.controller.js

@@ -0,0 +1,88 @@
+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 { Controller, Get, HttpCode, Inject, Post } from "@nestjs/common";
+import { z } from "zod";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZParam, ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { BackgroundConversationParams, BackgroundTaskParams } from "./background.schemas.js";
+import { BackgroundTasks, OUTPUT_TAIL_MAX_BYTES, } from "./tasks.service.js";
+const ConversationParams = BackgroundConversationParams;
+const TaskParams = BackgroundTaskParams;
+const OutputQuery = z.object({
+    tail: z.coerce.number().int().min(1).max(OUTPUT_TAIL_MAX_BYTES).default(OUTPUT_TAIL_MAX_BYTES),
+});
+class BackgroundConversationParamsDto extends createZodDto(ConversationParams, "BackgroundConversationParams") {
+}
+class BackgroundTaskParamsDto extends createZodDto(TaskParams, "BackgroundTaskParams") {
+}
+class BackgroundOutputQueryDto extends createZodDto(OutputQuery, "BackgroundOutputQuery") {
+}
+/**
+ * Background Bash tasks of a conversation (spec 2026-11-05-background-bash-design §5). Visible to
+ * whoever sees the conversation, stoppable by whoever may abort its run (the owner): the same
+ * checks as `GET :id` and `POST :id/abort`.
+ */
+let BackgroundController = class BackgroundController {
+    tasks;
+    constructor(tasks) {
+        this.tasks = tasks;
+    }
+    /** The conversation's tasks and its sub-agents' (`subagentId`), newest first. */
+    async list(principal, org, params) {
+        const p = requireUser(principal);
+        return { tasks: await this.tasks.list(org.orgId, params.id, p.account.id) };
+    }
+    /**
+     * Stops a task like a person's stop: 200 `{ task }` with the row after the stop. A task that is
+     * still `running` with `stopping: true` is being stopped by another request (or is still
+     * launching); a stop that fails is an error and the task keeps running.
+     */
+    async stop(principal, org, params) {
+        const p = requireUser(principal);
+        return {
+            task: await this.tasks.stop(org.orgId, params.id, p.account.id, params.taskId, patTokenId(p)),
+        };
+    }
+    /** The end of the task's output (`tail` bytes, at most 65536); 409 when it cannot be read now. */
+    async output(principal, org, params, q) {
+        const p = requireUser(principal);
+        return this.tasks.output(org.orgId, params.id, p.account.id, params.taskId, q.tail);
+    }
+};
+__decorate([
+    Get(":orgId/conversations/:id/background-tasks"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(BackgroundConversationParamsDto))
+], BackgroundController.prototype, "list", null);
+__decorate([
+    Post(":orgId/conversations/:id/background-tasks/:taskId/stop"),
+    HttpCode(200),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(BackgroundTaskParamsDto))
+], BackgroundController.prototype, "stop", null);
+__decorate([
+    Get(":orgId/conversations/:id/background-tasks/:taskId/output"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(BackgroundTaskParamsDto)),
+    __param(3, ZQuery(BackgroundOutputQueryDto))
+], BackgroundController.prototype, "output", null);
+BackgroundController = __decorate([
+    Controller("api/v1/orgs"),
+    __param(0, Inject(BackgroundTasks))
+], BackgroundController);
+export { BackgroundController };

package/dist/background/background.module.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Background Bash (spec 2026-11-05-background-bash-design): the task store (from
+ * {@link BackgroundStoreModule}, which `SandboxModule` imports too), the finish of a task with its
+ * event ({@link BackgroundTaskFinisher}) and the stops ({@link BackgroundTaskStopper}). The wake of
+ * an idle conversation (`BackgroundWake`) is the runtime's (`RuntimeModule`): it needs the run
+ * queue, and the runtime imports this module. The poll and prune jobs
+ * (`BackgroundTaskPollJob`) are the worker role's (`WorkerModule`).
+ */
+export declare class BackgroundModule {
+}

package/dist/background/background.module.js

@@ -0,0 +1,39 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { ConversationAccessModule } from "../conversations/access.js";
+import { EventLogModule } from "../conversations/event-log.js";
+import { DevicesModule } from "../devices/devices.module.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { BackgroundTaskFinisher } from "./finish.js";
+import { BackgroundTaskStopper } from "./stop.js";
+import { BackgroundStoreModule } from "./store.module.js";
+import { BackgroundTasks } from "./tasks.service.js";
+/**
+ * Background Bash (spec 2026-11-05-background-bash-design): the task store (from
+ * {@link BackgroundStoreModule}, which `SandboxModule` imports too), the finish of a task with its
+ * event ({@link BackgroundTaskFinisher}) and the stops ({@link BackgroundTaskStopper}). The wake of
+ * an idle conversation (`BackgroundWake`) is the runtime's (`RuntimeModule`): it needs the run
+ * queue, and the runtime imports this module. The poll and prune jobs
+ * (`BackgroundTaskPollJob`) are the worker role's (`WorkerModule`).
+ */
+let BackgroundModule = class BackgroundModule {
+};
+BackgroundModule = __decorate([
+    Module({
+        imports: [
+            BackgroundStoreModule,
+            SandboxModule,
+            DevicesModule,
+            EventLogModule,
+            ConversationAccessModule,
+        ],
+        providers: [BackgroundTaskFinisher, BackgroundTaskStopper, BackgroundTasks],
+        exports: [BackgroundStoreModule, BackgroundTaskFinisher, BackgroundTaskStopper, BackgroundTasks],
+    })
+], BackgroundModule);
+export { BackgroundModule };

package/dist/background/background.schemas.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const BackgroundConversationParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const BackgroundTaskParams: z.ZodObject<{
+    id: z.ZodString;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+export declare const BACKGROUND_ROUTES: readonly RouteSchemas[];

package/dist/background/background.schemas.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export const BackgroundConversationParams = z.object({ id: z.string().min(1).max(100) });
+export const BackgroundTaskParams = z.object({
+    id: z.string().min(1).max(100),
+    taskId: z.string().min(1).max(100),
+});
+export const BACKGROUND_ROUTES = [
+    {
+        route: "GET /api/v1/orgs/:orgId/conversations/:id/background-tasks",
+        params: BackgroundConversationParams,
+    },
+    {
+        route: "POST /api/v1/orgs/:orgId/conversations/:id/background-tasks/:taskId/stop",
+        params: BackgroundTaskParams,
+    },
+];

package/dist/background/finish.d.ts

@@ -0,0 +1,44 @@
+import { EventLog } from "../conversations/event-log.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { type BackgroundTaskRow, BackgroundTaskStore } from "./store.js";
+/** Where a task ends (as {@link BackgroundTaskStore.finish} takes it). */
+export type BackgroundFinish = Parameters<BackgroundTaskStore["finish"]>[1];
+/**
+ * Who stopped a task, when its finish must never wake the conversation: a person (who is looking at
+ * it), the deletion of the conversation, or the end of the sub-agent that owns it (a fork's run, a
+ * stopped background sub-agent).
+ */
+export type BackgroundStoppedBy = "person" | "deletion" | "subagent_end";
+/** The idempotency key of a task's `background_task_finished` event. */
+export declare const finishedEventKey: (taskId: string) => string;
+/**
+ * Takes a task out of `running` (spec 2026-11-05-background-bash-design §4.3): one transaction holds
+ * the conditional status update and the `background_task_finished` event of the owning
+ * conversation, so a crash between them cannot lose the event, and of two paths finishing the same
+ * task (two pollers, a poll and a stop) exactly one writes it. After the commit: the log's notify,
+ * the `changed: "background"` frame (to the owner and, for a sub-agent's task, the conversation
+ * that owns the sandbox, whose panel lists it too) and the `background_task.finished` domain event
+ * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module).
+ *
+ * Holds no lock and runs no sandbox command: the caller reads `lastLines` before.
+ */
+export declare class BackgroundTaskFinisher {
+    private readonly store;
+    private readonly eventLog;
+    private readonly events;
+    readonly txHost: TransactionHost;
+    constructor(store: Pick<BackgroundTaskStore, "finish">, eventLog: EventLog, events: KernelEvents, txHost: TransactionHost);
+    /**
+     * Finishes `task` as `to` with its last output lines (cut to their last 4 000 characters);
+     * `reported` when a tool call already told the model in its run. False (nothing written) when the
+     * task was no longer running, or, with `opts.unclaimed` (the poller), when a live stop claimed it:
+     * the stop's finish is then the only one. `opts.stoppedBy` marks a stop that must never wake the
+     * conversation: `"person"` (a person stopped it) or `"deletion"` (its conversation is being
+     * deleted).
+     */
+    finish(task: BackgroundTaskRow, to: BackgroundFinish, lastLines: string, reported: boolean, opts?: {
+        unclaimed?: boolean;
+        stoppedBy?: BackgroundStoppedBy;
+    }): Promise<boolean>;
+}

package/dist/background/finish.js

@@ -0,0 +1,95 @@
+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 { EventLog } from "../conversations/event-log.js";
+import { afterCommit } from "../infra/database/after-commit.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { taskOutputFile } from "./launch.js";
+import { LAST_LINES_MAX_CHARS } from "./session.js";
+import { BackgroundTaskStore } from "./store.js";
+/** The idempotency key of a task's `background_task_finished` event. */
+export const finishedEventKey = (taskId) => `background_task_finished:${taskId}`;
+/**
+ * Takes a task out of `running` (spec 2026-11-05-background-bash-design §4.3): one transaction holds
+ * the conditional status update and the `background_task_finished` event of the owning
+ * conversation, so a crash between them cannot lose the event, and of two paths finishing the same
+ * task (two pollers, a poll and a stop) exactly one writes it. After the commit: the log's notify,
+ * the `changed: "background"` frame (to the owner and, for a sub-agent's task, the conversation
+ * that owns the sandbox, whose panel lists it too) and the `background_task.finished` domain event
+ * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module).
+ *
+ * Holds no lock and runs no sandbox command: the caller reads `lastLines` before.
+ */
+let BackgroundTaskFinisher = class BackgroundTaskFinisher {
+    store;
+    eventLog;
+    events;
+    txHost;
+    constructor(store, eventLog, events, txHost) {
+        this.store = store;
+        this.eventLog = eventLog;
+        this.events = events;
+        this.txHost = txHost;
+    }
+    /**
+     * Finishes `task` as `to` with its last output lines (cut to their last 4 000 characters);
+     * `reported` when a tool call already told the model in its run. False (nothing written) when the
+     * task was no longer running, or, with `opts.unclaimed` (the poller), when a live stop claimed it:
+     * the stop's finish is then the only one. `opts.stoppedBy` marks a stop that must never wake the
+     * conversation: `"person"` (a person stopped it) or `"deletion"` (its conversation is being
+     * deleted).
+     */
+    async finish(task, to, lastLines, reported, opts = {}) {
+        if (!(await this.store.finish(task.id, to, opts)))
+            return false;
+        const [event] = await this.eventLog.appendIn(task.conversationId, [
+            {
+                type: "background_task_finished",
+                idemKey: finishedEventKey(task.id),
+                payload: {
+                    taskId: task.id,
+                    description: task.description,
+                    status: to.status,
+                    exitCode: to.exitCode ?? null,
+                    elapsedMs: Math.max(0, Date.now() - task.startedAt.getTime()),
+                    lastLines: lastLines.length > LAST_LINES_MAX_CHARS
+                        ? lastLines.slice(-LAST_LINES_MAX_CHARS)
+                        : lastLines,
+                    outputPath: taskOutputFile(task.outputPath),
+                    reported,
+                    ...(to.lostReason !== undefined && { lostReason: to.lostReason }),
+                    ...(opts.stoppedBy !== undefined && { stoppedBy: opts.stoppedBy }),
+                },
+            },
+        ]);
+        const conversations = [...new Set([task.conversationId, task.sandboxConversationId])];
+        afterCommit(async () => {
+            if (event)
+                await this.eventLog.notify(task.conversationId, event.seq);
+            for (const c of conversations)
+                await this.eventLog.publishChanged(c, "background");
+            await this.events.emit("background_task.finished", { conversationId: task.conversationId });
+        });
+        return true;
+    }
+};
+__decorate([
+    Transactional()
+], BackgroundTaskFinisher.prototype, "finish", null);
+BackgroundTaskFinisher = __decorate([
+    Injectable(),
+    __param(0, Inject(BackgroundTaskStore)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(KernelEvents)),
+    __param(3, Inject(TransactionHost))
+], BackgroundTaskFinisher);
+export { BackgroundTaskFinisher };

package/dist/background/launch-lock.d.ts

@@ -0,0 +1,15 @@
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { XactLock } from "../infra/database/xact-lock.js";
+/**
+ * The launch lock of one root conversation (decision R9: one provider per transaction-scoped
+ * lock): serializes background task reservations in its tree, so the count of running tasks
+ * checked against `sandbox.background.maxTasks` (per root conversation, whatever device it
+ * works in) and the insert of the new row are one step. Joins the
+ * caller's transaction (`mandatory`), which holds it until it ends.
+ */
+export declare class BackgroundLaunchLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(sandboxConversationId: string): Promise<void>;
+}

package/dist/background/launch-lock.js

@@ -0,0 +1,40 @@
+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 { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { XactLock } from "../infra/database/xact-lock.js";
+/**
+ * The launch lock of one root conversation (decision R9: one provider per transaction-scoped
+ * lock): serializes background task reservations in its tree, so the count of running tasks
+ * checked against `sandbox.background.maxTasks` (per root conversation, whatever device it
+ * works in) and the insert of the new row are one step. Joins the
+ * caller's transaction (`mandatory`), which holds it until it ends.
+ */
+let BackgroundLaunchLock = class BackgroundLaunchLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(sandboxConversationId) {
+        await this.xactLock.lock(`capybara.background-launch:${sandboxConversationId}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], BackgroundLaunchLock.prototype, "lock", null);
+BackgroundLaunchLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], BackgroundLaunchLock);
+export { BackgroundLaunchLock };

package/dist/background/launch.d.ts

@@ -0,0 +1,42 @@
+import type { KernelConfig } from "../config/schema.js";
+/**
+ * Launching a background Bash task (spec 2026-11-05-background-bash-design §4.2): the task id, the
+ * one short exec that starts the command detached from the exec, and the model-visible result.
+ * Every path is relative to the instance's workspace root (the launch exec's `cwd`), so the
+ * script is the same whatever the instance's roots are.
+ */
+/** The launch exec's own time limit: it only writes a file and forks. */
+export declare const LAUNCH_EXEC_TIMEOUT_MS = 30000;
+/**
+ * The longest a background task may run, in seconds: `sandbox.background.maxSeconds`, at most
+ * `sandbox.limits.maxCommandSeconds`. It is also a task's default `timeout`.
+ */
+export declare const backgroundMaxSeconds: (cfg: Pick<KernelConfig, "sandbox">) => number;
+/** The directory of the task files, relative to the workspace root. */
+export declare const TASKS_DIR = ".capybara/tasks";
+/** A task's output file, relative to the workspace root (`output_path` while reserved). */
+export declare const taskOutputPath: (id: string) => string;
+/**
+ * The absolute output file of a task from its `output_path`: absolute once the task started (the
+ * launch records `<workspace>/.capybara/tasks/<id>.out` of its instance); a reservation's relative
+ * path is read under the default workspace.
+ */
+export declare const taskOutputFile: (outputPath: string) => string;
+/** The file the launch writes the session id to, relative to the workspace root. */
+export declare const taskSidPath: (id: string) => string;
+/** A new task id: `bt_` plus 6 lowercase base32 characters. */
+export declare function newTaskId(): string;
+/** A task id ({@link newTaskId}). */
+export declare const TASK_ID_RE: RegExp;
+/**
+ * The shell of the launch exec: writes `command` (base64 in the script, so nothing is quoted by
+ * hand) to `.capybara/tasks/<id>.sh` and starts it with bash (the shell a foreground `Bash` call
+ * runs its command in) in a session of its own under `timeout -s KILL <seconds>`, with its exit
+ * status written to `<id>.exit` and its output to `<id>.out`; writes the session id (`$!`, the pid
+ * `setsid` started) to `<id>.sid` and prints it. An environment without one of the needed programs fails with a readable error on
+ * stderr and exit code 127, before anything starts. `id` must be a task id and `seconds` a
+ * positive integer (both go into the script unquoted).
+ */
+export declare function launchScript(id: string, command: string, seconds: number): string;
+/** The model-visible result of a launch (spec §2.1); `workspace`: the instance's workspace root. */
+export declare function startedText(id: string, description: string, workspace?: string): string;

package/dist/background/launch.js

@@ -0,0 +1,77 @@
+import { randomBytes } from "node:crypto";
+import { DEFAULT_SANDBOX_ROOTS } from "@capybara-hq/plugin-sdk";
+/**
+ * Launching a background Bash task (spec 2026-11-05-background-bash-design §4.2): the task id, the
+ * one short exec that starts the command detached from the exec, and the model-visible result.
+ * Every path is relative to the instance's workspace root (the launch exec's `cwd`), so the
+ * script is the same whatever the instance's roots are.
+ */
+/** The launch exec's own time limit: it only writes a file and forks. */
+export const LAUNCH_EXEC_TIMEOUT_MS = 30_000;
+/**
+ * The longest a background task may run, in seconds: `sandbox.background.maxSeconds`, at most
+ * `sandbox.limits.maxCommandSeconds`. It is also a task's default `timeout`.
+ */
+export const backgroundMaxSeconds = (cfg) => Math.min(cfg.sandbox.background.maxSeconds, cfg.sandbox.limits.maxCommandSeconds);
+/** The directory of the task files, relative to the workspace root. */
+export const TASKS_DIR = ".capybara/tasks";
+/** A task's output file, relative to the workspace root (`output_path` while reserved). */
+export const taskOutputPath = (id) => `${TASKS_DIR}/${id}.out`;
+/**
+ * The absolute output file of a task from its `output_path`: absolute once the task started (the
+ * launch records `<workspace>/.capybara/tasks/<id>.out` of its instance); a reservation's relative
+ * path is read under the default workspace.
+ */
+export const taskOutputFile = (outputPath) => outputPath.startsWith("/") ? outputPath : `${DEFAULT_SANDBOX_ROOTS.workspace}/${outputPath}`;
+/** The file the launch writes the session id to, relative to the workspace root. */
+export const taskSidPath = (id) => `${TASKS_DIR}/${id}.sid`;
+const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
+/** A new task id: `bt_` plus 6 lowercase base32 characters. */
+export function newTaskId() {
+    const bytes = randomBytes(6);
+    let out = "bt_";
+    for (const b of bytes)
+        out += BASE32[b & 31];
+    return out;
+}
+/** The programs the launch and the later polls and stops need in the environment. */
+const REQUIRED = ["bash", "setsid", "nohup", "timeout", "pgrep", "pkill", "base64"];
+/** A task id ({@link newTaskId}). */
+export const TASK_ID_RE = /^bt_[a-z2-7]{6}$/;
+/**
+ * The shell of the launch exec: writes `command` (base64 in the script, so nothing is quoted by
+ * hand) to `.capybara/tasks/<id>.sh` and starts it with bash (the shell a foreground `Bash` call
+ * runs its command in) in a session of its own under `timeout -s KILL <seconds>`, with its exit
+ * status written to `<id>.exit` and its output to `<id>.out`; writes the session id (`$!`, the pid
+ * `setsid` started) to `<id>.sid` and prints it. An environment without one of the needed programs fails with a readable error on
+ * stderr and exit code 127, before anything starts. `id` must be a task id and `seconds` a
+ * positive integer (both go into the script unquoted).
+ */
+export function launchScript(id, command, seconds) {
+    if (!TASK_ID_RE.test(id))
+        throw new Error(`invalid background task id: ${JSON.stringify(id)}`);
+    if (!Number.isSafeInteger(seconds) || seconds < 1) {
+        throw new Error(`invalid background task seconds: ${seconds}`);
+    }
+    const b64 = Buffer.from(command, "utf8").toString("base64");
+    const t = `${TASKS_DIR}/${id}`;
+    return [
+        "set -e",
+        `for c in ${REQUIRED.join(" ")}; do command -v "$c" >/dev/null 2>&1 || { echo "Background tasks need ${REQUIRED.join(", ")} in this environment; $c is missing." >&2; exit 127; }; done`,
+        `mkdir -p ${TASKS_DIR}`,
+        `printf '%s' '${b64}' | base64 -d > ${t}.sh`,
+        `setsid nohup sh -c 'timeout -s KILL ${seconds} bash ${t}.sh; echo $? > ${t}.exit' > ${t}.out 2>&1 < /dev/null &`,
+        // the session id goes to a file first: a launch that ends before its output comes back
+        // (aborted, timed out) still leaves the id of what it started
+        `echo $! > ${t}.sid`,
+        `cat ${t}.sid`,
+    ].join("\n");
+}
+/** The model-visible result of a launch (spec §2.1); `workspace`: the instance's workspace root. */
+export function startedText(id, description, workspace = DEFAULT_SANDBOX_ROOTS.workspace) {
+    return [
+        `Started background task ${id} ("${description}").`,
+        `Output: ${workspace}/${taskOutputPath(id)}`,
+        "Read it with TaskOutput (or Read), stop it with TaskStop. You will be told when it finishes.",
+    ].join("\n");
+}

package/dist/background/poll.job.d.ts

@@ -0,0 +1,56 @@
+import type { KernelConfig } from "../config/schema.js";
+import { EventLog } from "../conversations/event-log.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { BackgroundTaskFinisher } from "./finish.js";
+import { BackgroundTaskStore } from "./store.js";
+/** The poll of the running background tasks (`@LockedInterval`, every `pollSeconds`). */
+export declare const BACKGROUND_POLL_JOB = "background-task-poll";
+/** The daily prune of finished background tasks older than `tools.outputRetentionDays`. */
+export declare const BACKGROUND_PRUNE_JOB = "background-task-prune";
+/**
+ * A reservation (`sid` null) older than this has lost its launch. The slowest legitimate launch
+ * is the pipeline's own limit for a background `Bash` call ({@link LAUNCH_EXEC_TIMEOUT_MS} plus
+ * {@link sandboxBaseTimeoutMs}: the tool timeout, `sandbox.lockWaitSeconds` and the setup margin),
+ * so twice that (never under 2 minutes) leaves a wide margin: only a launching process that died
+ * leaves a reservation this old.
+ */
+export declare const launchAbandonedAfterMs: (cfg: KernelConfig) => number;
+/**
+ * The worker's background task jobs (spec 2026-11-05-background-bash-design §4.3), each once per
+ * tick across replicas:
+ * - `background-task-poll` (every `sandbox.background.pollSeconds`): for every device
+ *   instance with running tasks (of any conversation using it), one exec through
+ *   `SandboxService.ifRunning` (which never creates or resumes an instance) reports each task's
+ *   exit file and liveness; ended tasks finish through {@link BackgroundTaskFinisher}. Each poll
+ *   takes and releases a lease, so `last_used_at` stays fresh and an instance with running tasks
+ *   is never idle-suspended;
+ * - `background-task-prune` (daily): deletes finished tasks older than `tools.outputRetentionDays`.
+ */
+export declare class BackgroundTaskPollJob {
+    private readonly store;
+    private readonly finisher;
+    private readonly eventLog;
+    private readonly sandbox;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(store: Pick<BackgroundTaskStore, "runningStarted" | "pruneFinished" | "failAbandonedLaunches">, finisher: BackgroundTaskFinisher, eventLog: Pick<EventLog, "publishChanged">, sandbox: Pick<SandboxService, "cloudAvailable" | "availableFor" | "ifRunning">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    poll(signal?: AbortSignal): Promise<void>;
+    /**
+     * One poll of every running task (the body of {@link poll}); returns how many tasks finished.
+     * A sandbox whose poll fails (busy, a provider error) is logged and tried again next tick.
+     * First, reservations abandoned by a launch that died ({@link launchAbandonedAfterMs}) are
+     * failed, so they stop holding a slot of `sandbox.background.maxTasks` (not counted in the
+     * result: they never started), with a `changed: "background"` frame to their conversations.
+     */
+    pollOnce(signal?: AbortSignal): Promise<number>;
+    /** Polls the tasks of one device instance; returns how many finished. */
+    private pollSandbox;
+    /** The poll exec of one instance: each task's report by id. */
+    private pollExec;
+    /** Deletes the finished tasks older than `tools.outputRetentionDays` (their rows only). */
+    prune(): Promise<void>;
+}