@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/app.d.ts

@@ -0,0 +1,93 @@
+import "reflect-metadata";
+import type { BootstrapManifest } from "@capybara-hq/plugin-sdk";
+import type { INestApplicationContext } from "@nestjs/common";
+import type { NestFastifyApplication } from "@nestjs/platform-fastify";
+import type { ConfigSource } from "./config/load.js";
+import type { KernelConfig } from "./config/schema.js";
+import type { ConfigSourceKind } from "./config/sources.js";
+import { type KernelHttp } from "./http/app.js";
+import { type ShutdownSignalOptions } from "./infra/lifecycle/shutdown-signals.js";
+import type { KernelLogger } from "./log.js";
+import type { KernelOverride } from "./overrides.js";
+/** What {@link createKernelApp} takes besides the config. */
+export interface KernelAppOptions {
+    /** 配置来源；提供 `watch` 时启用热更新。 */
+    source?: ConfigSource;
+    /** 解析插件裸包名的目录，默认 `process.cwd()`；相对路径按当前 cwd 解析。 */
+    resolveFrom?: string;
+    /** Defaults to a logger built from `config.log` and `config.roles` (createConfiguredLogger). */
+    logger?: KernelLogger;
+    /** 热更新时与来源原始值合并的环境变量，默认 `process.env`。 */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The bootstrap step (package ecosystem spec §7, startup bootstrap spec). When given, the start
+     * runs it (see `extensions/bootstrap.ts`) before loading extensions unless it is already done for
+     * the manifest, and refuses to start when it cannot complete a required entry. `dir`: the
+     * optional offline directory whose `*.tgz` files are matched to the entries by sha512 (a missing
+     * directory is an empty one); entries without a matching file are downloaded from
+     * `packages.npmRegistry`. Omitted: no bootstrap step (tests, unless they ask for it).
+     */
+    bootstrap?: {
+        dir?: string;
+    };
+    /** The bootstrap manifest; default the `bootstrap.json` shipped with the kernel package. */
+    bootstrapManifest?: BootstrapManifest;
+    /**
+     * Where each extension deployment config field of the startup config comes from (the
+     * `extensionConfigSources` returned by `loadConfigWithSources`); these fields are read-only in the
+     * admin console (D8). When omitted it is derived from `config.extensionConfig`: fields present in
+     * the environment are `env`, the rest take the `CAPYBARA_CONFIG_SOURCE` kind (file / nacos).
+     */
+    extensionConfigSources?: Record<string, Record<string, ConfigSourceKind>>;
+    /**
+     * The kernel's own tests' seams: values for the named seam tokens ({@link KernelOverride} lists
+     * every one), registered in a global module so the domain modules that resolve these optional
+     * tokens get them. Any other token is refused when the application is built.
+     */
+    overrides?: readonly KernelOverride[];
+}
+/**
+ * Builds the kernel application (one Nest application, root module {@link KernelModule}) and sets
+ * up its HTTP side, without initializing it: nothing connects and nothing starts. A failure
+ * releases what was created (Redis connections, the pool) before it is thrown. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start; everything else uses {@link createKernelApp}.
+ */
+export declare function buildKernelApp(config: KernelConfig, options?: KernelAppOptions): Promise<NestFastifyApplication>;
+/**
+ * Closes a kernel application once (later calls get the same promise): the stop phases begin at
+ * once (`KernelLifecycle.stop`: readiness 503, the start aborted at its next checkpoint), next to
+ * `app.close()`, which runs the shutdown hooks (the stop phases are the same promise, then Redis
+ * and the pool). Use it to stop an application from {@link createKernelApp} /
+ * {@link startKernelApp} (tests, `@capybara-hq/testing`), so the stop begins before Nest's
+ * `onModuleDestroy` hooks run.
+ */
+export declare function closeKernelApp(app: NestFastifyApplication): Promise<void>;
+/**
+ * Creates the kernel application and runs its start sequence (nest kernel spec §4): Redis,
+ * migrations, the official marketplace, the bootstrap step, the extension load, the role parts,
+ * extension routes, the lifecycle reconcile and the config watch. Does not listen and installs no
+ * process-wide handler.
+ */
+export declare function createKernelApp(config: KernelConfig, options?: KernelAppOptions): Promise<NestFastifyApplication>;
+/**
+ * Builds the kernel application, installs the SIGTERM / SIGINT handlers
+ * ({@link handleShutdownSignals}), runs the start sequence and listens on `config.http.port`:
+ * nothing is served before the start sequence finished. The handlers are installed before the
+ * start, so a signal during it aborts the start at its next checkpoint and closes the application
+ * cleanly; this function then rejects once the signal path has exited (with 0). A second signal
+ * exits with 1 at once. A failed build or start is logged (`kernel start failed`) before it is
+ * thrown.
+ */
+export declare function startKernelApp(config: KernelConfig, options?: KernelAppOptions, signalOptions?: ShutdownSignalOptions): Promise<NestFastifyApplication>;
+/**
+ * The start half of {@link startKernelApp} for an application from {@link buildKernelApp}: installs
+ * the signal handlers, runs the start sequence and listens on `config.http.port`. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start.
+ */
+export declare function startBuiltKernelApp(app: NestFastifyApplication, config: KernelConfig, signalOptions?: ShutdownSignalOptions): Promise<void>;
+/** The in-process HTTP of a kernel application (`inject`, the route list). */
+export declare function kernelAppHttp(app: INestApplicationContext): KernelHttp;
+/** The port a kernel application listens on; undefined before it listens and after the stop. */
+export declare function kernelAppPort(app: INestApplicationContext): number | undefined;

package/dist/app.js

@@ -0,0 +1,150 @@
+import "reflect-metadata";
+import { NestFactory } from "@nestjs/core";
+import { createKernelAdapter } from "./http/adapter.js";
+import { createHttpApp } from "./http/app.js";
+import { NestLogAdapter } from "./http/nest-logger.js";
+import { GracefulShutdown } from "./infra/lifecycle/graceful-shutdown.service.js";
+import { handleShutdownSignals, } from "./infra/lifecycle/shutdown-signals.js";
+import { setupSwagger } from "./infra/swagger/swagger.js";
+import { KernelModule } from "./kernel.module.js";
+import { KernelLifecycle } from "./lifecycle/kernel-lifecycle.js";
+import { createConfiguredLogger } from "./log-config.js";
+/**
+ * Builds the kernel application (one Nest application, root module {@link KernelModule}) and sets
+ * up its HTTP side, without initializing it: nothing connects and nothing starts. A failure
+ * releases what was created (Redis connections, the pool) before it is thrown. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start; everything else uses {@link createKernelApp}.
+ */
+export async function buildKernelApp(config, options = {}) {
+    const logger = options.logger ?? createConfiguredLogger(config);
+    const app = await NestFactory.create(KernelModule.forRoot(config, { ...options, logger }), createKernelAdapter(config.http.trustProxy), { logger: new NestLogAdapter(logger), abortOnError: false });
+    const lifecycle = app.get(KernelLifecycle);
+    const gateway = lifecycle.gatewayRoutes();
+    try {
+        lifecycle.attachHttp(await createHttpApp({
+            log: logger,
+            servePlugins: config.roles.includes("api") || config.roles.includes("gateway"),
+            ...(gateway !== undefined && { gateway }),
+            replicaId: config.http.replicaId === undefined ? undefined : String(config.http.replicaId),
+            packageMaxBytes: config.packages.maxBytes,
+        }, app));
+        setupSwagger(app, config.http.swagger);
+    }
+    catch (e) {
+        // Nothing started: only release the connections (the stop phases are skipped)
+        lifecycle.releaseOnly();
+        await app.close();
+        throw e;
+    }
+    return app;
+}
+const closing = new WeakMap();
+/**
+ * Closes a kernel application once (later calls get the same promise): the stop phases begin at
+ * once (`KernelLifecycle.stop`: readiness 503, the start aborted at its next checkpoint), next to
+ * `app.close()`, which runs the shutdown hooks (the stop phases are the same promise, then Redis
+ * and the pool). Use it to stop an application from {@link createKernelApp} /
+ * {@link startKernelApp} (tests, `@capybara-hq/testing`), so the stop begins before Nest's
+ * `onModuleDestroy` hooks run.
+ */
+export function closeKernelApp(app) {
+    let p = closing.get(app);
+    if (p === undefined) {
+        p = Promise.all([app.get(KernelLifecycle).stop(), app.close()]).then(() => { });
+        closing.set(app, p);
+    }
+    return p;
+}
+/**
+ * Initializes a built kernel application: `init()` runs the start sequence
+ * (`KernelLifecycle.onApplicationBootstrap`). A failure (unless the shutdown began meanwhile) is
+ * logged; either way the application is closed (the stop phases, then Redis and the pool) before
+ * the error is thrown.
+ */
+async function initKernelApp(app) {
+    try {
+        await app.init();
+    }
+    catch (e) {
+        if (!app.get(GracefulShutdown).isShuttingDown()) {
+            app.get(KernelLifecycle).log.error("kernel start failed", { err: e });
+        }
+        await closeKernelApp(app);
+        throw e;
+    }
+}
+/**
+ * Creates the kernel application and runs its start sequence (nest kernel spec §4): Redis,
+ * migrations, the official marketplace, the bootstrap step, the extension load, the role parts,
+ * extension routes, the lifecycle reconcile and the config watch. Does not listen and installs no
+ * process-wide handler.
+ */
+export async function createKernelApp(config, options = {}) {
+    const app = await buildKernelApp(config, options);
+    await initKernelApp(app);
+    return app;
+}
+/**
+ * Builds the kernel application, installs the SIGTERM / SIGINT handlers
+ * ({@link handleShutdownSignals}), runs the start sequence and listens on `config.http.port`:
+ * nothing is served before the start sequence finished. The handlers are installed before the
+ * start, so a signal during it aborts the start at its next checkpoint and closes the application
+ * cleanly; this function then rejects once the signal path has exited (with 0). A second signal
+ * exits with 1 at once. A failed build or start is logged (`kernel start failed`) before it is
+ * thrown.
+ */
+export async function startKernelApp(config, options = {}, signalOptions = {}) {
+    const logger = options.logger ?? createConfiguredLogger(config);
+    let app;
+    try {
+        app = await buildKernelApp(config, { ...options, logger });
+    }
+    catch (e) {
+        // Nothing to stop (the build released what it created); the process entry only sees the error
+        logger.error("kernel start failed", { err: e });
+        throw e;
+    }
+    await startBuiltKernelApp(app, config, signalOptions);
+    return app;
+}
+/**
+ * The start half of {@link startKernelApp} for an application from {@link buildKernelApp}: installs
+ * the signal handlers, runs the start sequence and listens on `config.http.port`. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start.
+ */
+export async function startBuiltKernelApp(app, config, signalOptions = {}) {
+    const lifecycle = app.get(KernelLifecycle);
+    const signals = handleShutdownSignals(() => closeKernelApp(app), lifecycle.log, signalOptions);
+    try {
+        await initKernelApp(app);
+        try {
+            await lifecycle.listen(config.http.port);
+        }
+        catch (e) {
+            if (!app.get(GracefulShutdown).isShuttingDown()) {
+                lifecycle.log.error("kernel start failed", { err: e });
+            }
+            await closeKernelApp(app);
+            throw e;
+        }
+    }
+    catch (e) {
+        // Stopped by a signal: the signal path closes and exits; otherwise nothing is left to stop
+        const exiting = signals.exiting();
+        if (exiting)
+            await exiting;
+        else
+            signals.dispose();
+        throw e;
+    }
+}
+/** The in-process HTTP of a kernel application (`inject`, the route list). */
+export function kernelAppHttp(app) {
+    return app.get(KernelLifecycle).http;
+}
+/** The port a kernel application listens on; undefined before it listens and after the stop. */
+export function kernelAppPort(app) {
+    return app.get(KernelLifecycle).port;
+}

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 { EnvironmentsModule } from "../environments/environments.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,
+            EnvironmentsModule,
+            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 environment 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 environment 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 };