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

package/dist/agents/readiness.controller.d.ts

@@ -0,0 +1,26 @@
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService } from "./agents.service.js";
+/**
+ * Whether the org can run (`/api/v1/orgs/:orgId/readiness`, web-order spec §3.8): the web app
+ * decides between the shell and the setup layout with it. `modelProvider` is `ready` when a
+ * model-provider extension is loaded (enabled and configured), from extension state only, never
+ * a vendor call; `agents` is the number of agents the caller can see (the agent list's
+ * visibility). Humans and service tokens (`org.read`).
+ *
+ * `modelProvider` is deployment-wide, not about this org: model providers are not org-scoped
+ * (an org's model purposes map onto the deployment's providers but cannot add one), so every org
+ * of the deployment reads the same value. It is read from this replica's provider registry, which
+ * follows the per-replica extension reconcile: right after a provider is enabled, a replica that
+ * has not reconciled yet may still answer `none` for a moment.
+ */
+export declare class ReadinessController {
+    private readonly registry;
+    private readonly agents;
+    constructor(registry: ProviderRegistry, agents: AgentsService);
+    get(principal: Principal, org: OrgContext): Promise<{
+        modelProvider: "ready" | "none";
+        agents: number;
+    }>;
+}

package/dist/agents/readiness.controller.js

@@ -0,0 +1,56 @@
+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, Inject } from "@nestjs/common";
+import { CurrentPrincipal } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService } from "./agents.service.js";
+/** Service tokens have no account: they see `visibility='org'` agents only (as the agent list). */
+const viewerOf = (p) => (p.kind === "user" ? p.account.id : null);
+/**
+ * Whether the org can run (`/api/v1/orgs/:orgId/readiness`, web-order spec §3.8): the web app
+ * decides between the shell and the setup layout with it. `modelProvider` is `ready` when a
+ * model-provider extension is loaded (enabled and configured), from extension state only, never
+ * a vendor call; `agents` is the number of agents the caller can see (the agent list's
+ * visibility). Humans and service tokens (`org.read`).
+ *
+ * `modelProvider` is deployment-wide, not about this org: model providers are not org-scoped
+ * (an org's model purposes map onto the deployment's providers but cannot add one), so every org
+ * of the deployment reads the same value. It is read from this replica's provider registry, which
+ * follows the per-replica extension reconcile: right after a provider is enabled, a replica that
+ * has not reconciled yet may still answer `none` for a moment.
+ */
+let ReadinessController = class ReadinessController {
+    registry;
+    agents;
+    constructor(registry, agents) {
+        this.registry = registry;
+        this.agents = agents;
+    }
+    async get(principal, org) {
+        const visible = await this.agents.listVisible(org.orgId, viewerOf(principal));
+        return {
+            modelProvider: this.registry.hasProvider() ? "ready" : "none",
+            agents: visible.length,
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], ReadinessController.prototype, "get", null);
+ReadinessController = __decorate([
+    Controller("api/v1/orgs/:orgId/readiness"),
+    __param(0, Inject(ProviderRegistry)),
+    __param(1, Inject(AgentsService))
+], ReadinessController);
+export { ReadinessController };

package/dist/agents/templates.js

@@ -10,7 +10,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
 import { KernelDb } from "../infra/database/kernel-db.js";
-import { canonicalJson } from "../tools/registry.js";
+import { canonicalJson } from "../tools/canonical-json.js";
+import { loadLegacyScope } from "../tools/legacy-data.js";
+import { needsLegacyScope, normalizeToolKeys } from "./definition.js";
 const baseQuery = (db, orgId) => db
     .selectFrom("agent_templates as t")
     .innerJoin("agent_template_versions as v", (j) => j.onRef("v.template_id", "=", "t.id").onRef("v.version", "=", "t.current_version"))
@@ -26,16 +28,27 @@ const baseQuery = (db, orgId) => db
 ])
     .where("t.org_id", "=", orgId)
     .where("t.deleted_at", "is", null);
-const rowOf = (r) => ({
+/**
+ * A stored template row; its tool keys read as current keys (tool naming spec §8.3): old builtin
+ * names always, rc `<x>__<tool>` keys with `scope` (see {@link scopedRows}).
+ */
+const rowOf = (r, scope) => ({
     id: r.id,
     name: r.name,
     plugin: r.plugin_name,
     version: r.current_version,
-    template: r.definition,
+    template: normalizeToolKeys(r.definition, scope),
     sourceFormat: r.source_format,
     catalogItemId: r.catalog_item_id,
     catalogVersion: r.catalog_version,
 });
+/** The rows of one org as {@link TemplateRow}s, reading the org's legacy scope once when needed. */
+async function scopedRows(db, orgId, rows) {
+    const scope = rows.some((r) => needsLegacyScope(r.definition))
+        ? await loadLegacyScope(db, orgId)
+        : undefined;
+    return rows.map((r) => rowOf(r, scope));
+}
 /** The live templates of `ids` in the org (deleted and foreign ids are left out), by id. */
 export async function loadTemplates(db, orgId, ids) {
     if (ids.length === 0)
@@ -43,7 +56,7 @@ export async function loadTemplates(db, orgId, ids) {
     const rows = await baseQuery(db, orgId)
         .where("t.id", "in", [...ids])
         .execute();
-    return new Map(rows.map((r) => [r.id, rowOf(r)]));
+    return new Map((await scopedRows(db, orgId, rows)).map((t) => [t.id, t]));
 }
 /** Reads the org's agent templates (consumed by the roster, the agent page and Task 19's API). */
 let AgentTemplatesService = class AgentTemplatesService {
@@ -84,7 +97,9 @@ let AgentTemplatesService = class AgentTemplatesService {
         const r = await q.executeTakeFirst();
         if (!r)
             return null;
-        const t = rowOf(r);
+        const [t] = await scopedRows(this.db.db, orgId, [r]);
+        if (!t)
+            return null;
         return { id: t.id, version: t.version, plugin: t.plugin, template: t.template };
     }
 };

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,87 @@
+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 { BackgroundTasks, OUTPUT_TAIL_MAX_BYTES, } from "./tasks.service.js";
+const ConversationParams = z.object({ id: z.string().min(1).max(100) });
+const TaskParams = z.object({ id: z.string().min(1).max(100), taskId: z.string().min(1).max(100) });
+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,32 @@
+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 { 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, EventLogModule, ConversationAccessModule],
+        providers: [BackgroundTaskFinisher, BackgroundTaskStopper, BackgroundTasks],
+        exports: [BackgroundStoreModule, BackgroundTaskFinisher, BackgroundTaskStopper, BackgroundTasks],
+    })
+], BackgroundModule);
+export { BackgroundModule };

package/dist/background/finish.d.ts

@@ -0,0 +1,43 @@
+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) or the deletion of the conversation.
+ */
+export type BackgroundStoppedBy = "person" | "deletion";
+/** 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,94 @@
+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 { 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: `/workspace/${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,14 @@
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { XactLock } from "../infra/database/xact-lock.js";
+/**
+ * The launch lock of one sandbox (decision R9: one provider per transaction-scoped lock):
+ * serializes background task reservations in a sandbox, so the count of running tasks checked
+ * against `sandbox.background.maxTasks` 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,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;
+};
+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 sandbox (decision R9: one provider per transaction-scoped lock):
+ * serializes background task reservations in a sandbox, so the count of running tasks checked
+ * against `sandbox.background.maxTasks` 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,36 @@
+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 `/workspace` (the launch exec's `cwd`), so a provider that maps
+ * `/workspace` needs no rewriting inside the script.
+ */
+/** 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 `/workspace`. */
+export declare const TASKS_DIR = ".capybara/tasks";
+/** A task's output file, relative to `/workspace` (`output_path`). */
+export declare const taskOutputPath: (id: string) => string;
+/** The file the launch writes the session id to, relative to `/workspace`. */
+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. A sandbox 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). */
+export declare function startedText(id: string, description: string): string;

package/dist/background/launch.js

@@ -0,0 +1,70 @@
+import { randomBytes } from "node:crypto";
+/**
+ * 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 `/workspace` (the launch exec's `cwd`), so a provider that maps
+ * `/workspace` needs no rewriting inside the script.
+ */
+/** 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 `/workspace`. */
+export const TASKS_DIR = ".capybara/tasks";
+/** A task's output file, relative to `/workspace` (`output_path`). */
+export const taskOutputPath = (id) => `${TASKS_DIR}/${id}.out`;
+/** The file the launch writes the session id to, relative to `/workspace`. */
+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 inside the sandbox. */
+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. A sandbox 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 the sandbox; $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). */
+export function startedText(id, description) {
+    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");
+}