@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/background/store.js

@@ -0,0 +1,357 @@
+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 { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { BackgroundLaunchLock } from "./launch-lock.js";
+const toRow = (r) => ({
+    id: r.id,
+    orgId: r.org_id,
+    conversationId: r.conversation_id,
+    sandboxConversationId: r.sandbox_conversation_id,
+    environmentId: r.environment_id,
+    runId: r.run_id,
+    callId: r.call_id,
+    triggerAccountId: r.trigger_account_id,
+    description: r.description,
+    command: r.command,
+    sid: r.sid,
+    outputPath: r.output_path,
+    status: r.status,
+    lostReason: r.lost_reason,
+    exitCode: r.exit_code,
+    startedAt: new Date(r.started_at),
+    finishedAt: r.finished_at === null ? null : new Date(r.finished_at),
+    deadlineAt: new Date(r.deadline_at),
+    sandboxCreatedAt: r.sandbox_created_at === null ? null : new Date(r.sandbox_created_at),
+    killPending: r.kill_pending,
+    readOffset: Number(r.read_offset),
+    stoppingAt: r.stopping_at === null ? null : new Date(r.stopping_at),
+});
+/**
+ * How long a stop's claim holds: a claim older than this is abandoned (its stopper died), so the
+ * poller checks the task again and another stop may claim it. Longer than any stop takes (the
+ * lease wait, the SIGTERM grace, the kill and the tail).
+ */
+export const STOP_CLAIM_TTL_MS = 5 * 60_000;
+/** A condition: the row is not claimed by a live stop. */
+const unclaimed = sql `(stopping_at IS NULL OR stopping_at < now() - ${STOP_CLAIM_TTL_MS}::integer * interval '1 millisecond')`;
+/**
+ * Background Bash tasks (spec §4.1): one `capybara.background_tasks` row per command started with
+ * `run_in_background`. The store only reads and writes rows; the launch, the poller and the tools
+ * that drive them are other providers.
+ *
+ * A launch first reserves its row ({@link BackgroundTaskStore.reserve}: `running`, `sid` null),
+ * then starts the command and sets `sid` ({@link BackgroundTaskStore.markStarted}), or finishes
+ * the row as `failed` ({@link BackgroundTaskStore.failLaunch}). A running row with a null `sid`
+ * counts against `maxTasks` but has no process to check or stop: the poller and stops must skip
+ * it (the launch that reserved it settles it; one left over by a launch that died is failed by the
+ * poller, {@link BackgroundTaskStore.failAbandonedLaunches}).
+ */
+let BackgroundTaskStore = class BackgroundTaskStore {
+    db;
+    txHost;
+    launchLock;
+    constructor(db, txHost, launchLock) {
+        this.db = db;
+        this.txHost = txHost;
+        this.launchLock = launchLock;
+    }
+    /**
+     * Reserves a launch: under the root conversation's launch lock, counts the running tasks of
+     * `row.sandboxConversationId` and inserts `row` as `running` (no `sid`) when fewer than
+     * `maxTasks` run. False (nothing written) when that conversation tree already runs `maxTasks`.
+     */
+    async reserve(row, maxTasks) {
+        await this.launchLock.lock(row.sandboxConversationId);
+        if ((await this.countRunning(row.sandboxConversationId)) >= maxTasks)
+            return false;
+        await this.insert({ ...row, sid: null, sandboxCreatedAt: null });
+        return true;
+    }
+    /**
+     * Records the started command of a reserved row: `started`, or `stopping` when a stop claimed the
+     * reservation meanwhile (the launch then kills the command and finishes the row with
+     * {@link finishStoppedLaunch}); false when the row is no longer running.
+     */
+    async markStarted(id, to) {
+        const r = await this.db
+            .updateTable("background_tasks")
+            .set({ sid: to.sid, sandbox_created_at: to.sandboxCreatedAt })
+            .where("id", "=", id)
+            .where("status", "=", "running")
+            .where("sid", "is", null)
+            .returning("stopping_at")
+            .executeTakeFirst();
+        if (!r)
+            return false;
+        return r.stopping_at === null ? "started" : "stopping";
+    }
+    /**
+     * Finishes a launch whose reservation a stop claimed, once the launch killed what it started:
+     * `stopped`. No `background_task_finished` event: the launching call reports it itself.
+     */
+    async finishStoppedLaunch(id) {
+        await this.db
+            .updateTable("background_tasks")
+            .set({ status: "stopped", finished_at: sql `now()`, stopping_at: null })
+            .where("id", "=", id)
+            .where("status", "=", "running")
+            .execute();
+    }
+    /**
+     * Claims a running task for a stop (`stopping_at`): false when it is no longer running or another
+     * live stop claimed it ({@link STOP_CLAIM_TTL_MS}). While claimed the poller leaves it alone.
+     */
+    async claimStop(id) {
+        const r = await this.db
+            .updateTable("background_tasks")
+            .set({ stopping_at: sql `now()` })
+            .where("id", "=", id)
+            .where("status", "=", "running")
+            .where(unclaimed)
+            .executeTakeFirst();
+        return Number(r.numUpdatedRows) > 0;
+    }
+    /** Gives up a stop's claim (the stop failed while the sandbox runs: the task keeps running). */
+    async releaseStop(id) {
+        await this.db
+            .updateTable("background_tasks")
+            .set({ stopping_at: null })
+            .where("id", "=", id)
+            .where("status", "=", "running")
+            .execute();
+    }
+    /**
+     * Finishes a reserved row whose launch failed as `failed`, with `reason` in `lost_reason` (and a
+     * stop's claim cleared); a row that already has its sid (the command started and is tracked) is
+     * left as it is. No `background_task_finished` event: the launching call reports the failure
+     * itself.
+     */
+    async failLaunch(id, reason) {
+        await this.db
+            .updateTable("background_tasks")
+            .set({
+            status: "failed",
+            finished_at: sql `now()`,
+            lost_reason: reason,
+            stopping_at: null,
+        })
+            .where("id", "=", id)
+            .where("status", "=", "running")
+            // only a reservation that never started: a row with its sid is tracked by the poller
+            .where("sid", "is", null)
+            .execute();
+    }
+    /**
+     * Finishes as `failed` (`lost_reason` `launch_abandoned`) every reservation that started before
+     * `before`, never got its sid and is not claimed by a live stop: the launch that reserved it died
+     * (a crashed replica). A stop's claim older than {@link STOP_CLAIM_TTL_MS} does not hold it: a
+     * stop only claims a reservation and leaves the rest to the launch, so a dead launch would keep
+     * it (and its slot of `maxTasks`) forever. Conditional on `sid` still null, so a launch
+     * completing at that moment wins. No `background_task_finished` event: the command never
+     * started and the model never saw its id. Returns the rows it finished (their owner and sandbox
+     * conversations, for the caller's `changed: "background"` frames).
+     */
+    async failAbandonedLaunches(before) {
+        const r = await this.db
+            .updateTable("background_tasks")
+            .set({
+            status: "failed",
+            finished_at: sql `now()`,
+            lost_reason: "launch_abandoned",
+            stopping_at: null,
+        })
+            .where("status", "=", "running")
+            .where("sid", "is", null)
+            .where(unclaimed)
+            .where("started_at", "<", before)
+            .returning(["id", "conversation_id", "sandbox_conversation_id"])
+            .execute();
+        return r.map((x) => ({
+            id: x.id,
+            conversationId: x.conversation_id,
+            sandboxConversationId: x.sandbox_conversation_id,
+        }));
+    }
+    async insert(row) {
+        await this.db
+            .insertInto("background_tasks")
+            .values({
+            id: row.id,
+            org_id: row.orgId,
+            conversation_id: row.conversationId,
+            sandbox_conversation_id: row.sandboxConversationId,
+            environment_id: row.environmentId,
+            run_id: row.runId,
+            call_id: row.callId,
+            trigger_account_id: row.triggerAccountId,
+            description: row.description,
+            command: row.command,
+            sid: row.sid,
+            output_path: row.outputPath,
+            started_at: row.startedAt,
+            deadline_at: row.deadlineAt,
+            sandbox_created_at: row.sandboxCreatedAt,
+        })
+            .execute();
+    }
+    async get(id) {
+        const r = await this.db
+            .selectFrom("background_tasks")
+            .selectAll()
+            .where("id", "=", id)
+            .executeTakeFirst();
+        return r === undefined ? undefined : toRow(r);
+    }
+    /** The running tasks of one root conversation's tree, oldest first. */
+    async runningIn(sandboxConversationId) {
+        const rows = await this.db
+            .selectFrom("background_tasks")
+            .selectAll()
+            .where("sandbox_conversation_id", "=", sandboxConversationId)
+            .where("status", "=", "running")
+            .orderBy("started_at", "asc")
+            .orderBy("id", "asc")
+            .execute();
+        return rows.map(toRow);
+    }
+    /**
+     * Every running task that has started (its `sid` is set) and no live stop claimed, across
+     * sandboxes, oldest first: what the poller checks. A reservation still launching (`sid` null) is
+     * left to its launch, a claimed task to its stop.
+     */
+    async runningStarted() {
+        const rows = await this.db
+            .selectFrom("background_tasks")
+            .selectAll()
+            .where("status", "=", "running")
+            .where("sid", "is not", null)
+            .where(unclaimed)
+            .orderBy("started_at", "asc")
+            .orderBy("id", "asc")
+            .execute();
+        return rows.map(toRow);
+    }
+    /** The running tasks one conversation owns (not those of its sub-agents), oldest first. */
+    async runningOwnedBy(conversationId) {
+        const rows = await this.db
+            .selectFrom("background_tasks")
+            .selectAll()
+            .where("conversation_id", "=", conversationId)
+            .where("status", "=", "running")
+            .orderBy("started_at", "asc")
+            .orderBy("id", "asc")
+            .execute();
+        return rows.map(toRow);
+    }
+    /** The running tasks of one root conversation's tree (what `maxTasks` limits). */
+    async countRunning(sandboxConversationId) {
+        const r = await this.db
+            .selectFrom("background_tasks")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("sandbox_conversation_id", "=", sandboxConversationId)
+            .where("status", "=", "running")
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** The tasks owned by any of the conversations, newest first. */
+    async listFor(conversationIds) {
+        if (conversationIds.length === 0)
+            return [];
+        const rows = await this.db
+            .selectFrom("background_tasks")
+            .selectAll()
+            .where("conversation_id", "in", conversationIds)
+            .orderBy("started_at", "desc")
+            .orderBy("id", "desc")
+            .execute();
+        return rows.map(toRow);
+    }
+    /**
+     * Conditional `running` to a final status; false when the row was no longer running (another
+     * path finished it first), or, with `opts.unclaimed` (the poller), when a live stop claimed it.
+     * The caller's transaction also appends the finished event.
+     */
+    async finish(id, to, opts = {}) {
+        let q = this.db
+            .updateTable("background_tasks")
+            .set({
+            status: to.status,
+            finished_at: sql `now()`,
+            exit_code: to.exitCode ?? null,
+            lost_reason: to.lostReason ?? null,
+            stopping_at: null,
+            ...(to.killPending !== undefined && { kill_pending: to.killPending }),
+        })
+            .where("id", "=", id)
+            .where("status", "=", "running");
+        if (opts.unclaimed)
+            q = q.where(unclaimed);
+        const r = await q.executeTakeFirst();
+        return Number(r.numUpdatedRows) > 0;
+    }
+    /** Moves the read offset forward only (a concurrent reader never moves it back). */
+    async advanceOffset(id, to) {
+        await this.db
+            .updateTable("background_tasks")
+            .set({ read_offset: to })
+            .where("id", "=", id)
+            .where(sql `read_offset < ${to}`)
+            .execute();
+    }
+    /**
+     * Finished tasks of an environment whose process may still exist (any conversation's: they
+     * share the instance).
+     */
+    async pendingKills(environmentId) {
+        const rows = await this.db
+            .selectFrom("background_tasks")
+            .selectAll()
+            .where("environment_id", "=", environmentId)
+            .where("kill_pending", "=", true)
+            .orderBy("started_at", "asc")
+            .execute();
+        return rows.map(toRow);
+    }
+    async clearKill(ids) {
+        if (ids.length === 0)
+            return;
+        await this.db
+            .updateTable("background_tasks")
+            .set({ kill_pending: false })
+            .where("id", "in", ids)
+            .execute();
+    }
+    /** Deletes finished tasks that ended before `before`; a running one is never deleted. */
+    async pruneFinished(before) {
+        const r = await this.db
+            .deleteFrom("background_tasks")
+            .where("status", "<>", "running")
+            .where("finished_at", "<", before)
+            .executeTakeFirst();
+        return Number(r.numDeletedRows);
+    }
+};
+__decorate([
+    Transactional()
+], BackgroundTaskStore.prototype, "reserve", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], BackgroundTaskStore.prototype, "finish", null);
+BackgroundTaskStore = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(BackgroundLaunchLock))
+], BackgroundTaskStore);
+export { BackgroundTaskStore };

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

@@ -0,0 +1,6 @@
+/**
+ * The background task store alone, so `SandboxModule` (which kills lost tasks after a resume) can
+ * import it while `BackgroundModule`'s launch and poller import `SandboxModule`, without a cycle.
+ */
+export declare class BackgroundStoreModule {
+}

package/dist/background/store.module.js

@@ -0,0 +1,22 @@
+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 { BackgroundLaunchLock } from "./launch-lock.js";
+import { BackgroundTaskStore } from "./store.js";
+/**
+ * The background task store alone, so `SandboxModule` (which kills lost tasks after a resume) can
+ * import it while `BackgroundModule`'s launch and poller import `SandboxModule`, without a cycle.
+ */
+let BackgroundStoreModule = class BackgroundStoreModule {
+};
+BackgroundStoreModule = __decorate([
+    Module({
+        providers: [BackgroundTaskStore, BackgroundLaunchLock],
+        exports: [BackgroundTaskStore],
+    })
+], BackgroundStoreModule);
+export { BackgroundStoreModule };

package/dist/background/tasks.service.d.ts

@@ -0,0 +1,77 @@
+import { ConversationAccess } from "../conversations/access.js";
+import { EventLog } from "../conversations/event-log.js";
+import { ConversationEnvironments } from "../environments/conversation-environments.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { BackgroundTaskStopper } from "./stop.js";
+import { type BackgroundTaskStatus, BackgroundTaskStore } from "./store.js";
+/** The most bytes of output one read returns. */
+export declare const OUTPUT_TAIL_MAX_BYTES = 65536;
+/** A task as the API shows it. */
+export interface BackgroundTaskView {
+    id: string;
+    /** The conversation the task was asked for. */
+    conversationId: string;
+    /** The child conversation of a sub-agent's task; null for the conversation's own task. */
+    subagentId: string | null;
+    description: string;
+    command: string;
+    status: BackgroundTaskStatus;
+    exitCode: number | null;
+    lostReason: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    /** True while a stop has claimed the task and it is still running. */
+    stopping: boolean;
+}
+export interface BackgroundTaskOutput {
+    text: string;
+    /** True when `text` is only the end of the output (or, for `event`, the last lines). */
+    truncated: boolean;
+    /** `live`: read from the running sandbox; `event`: the last lines the finished event kept. */
+    source: "live" | "event";
+}
+/**
+ * The HTTP side of background tasks (spec 2026-11-05-background-bash-design §5): the tasks of a
+ * conversation and of its sub-agents, stopping one, reading its output. A task is reachable
+ * through the conversation that owns it or through any conversation above it, and only by a
+ * person who may see the conversation (`ConversationAccess`, the rule of `GET :id`, which is also
+ * what `POST :id/abort` checks: the owner).
+ */
+export declare class BackgroundTasks {
+    private readonly access;
+    private readonly store;
+    private readonly stopper;
+    private readonly sandbox;
+    private readonly eventLog;
+    private readonly db;
+    private readonly environments;
+    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "available" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb, environments: Pick<ConversationEnvironments, "forTool">);
+    /**
+     * The conversation and every sub-agent conversation below it (grandchildren too: their tasks run
+     * in the root's sandbox, agent map spec §6); `conversation.not_found` when not visible.
+     */
+    private scope;
+    private view;
+    private owned;
+    /** The tasks of the conversation and its sub-agents, newest first. */
+    list(orgId: string, conversationId: string, accountId: string): Promise<BackgroundTaskView[]>;
+    /**
+     * A person's stop. Returns the row after the stop: `running` with `stopping` true when another
+     * stop already claimed the task (or the task is a reservation still launching, which its launch
+     * then kills); a stop that fails throws. Writes the `background_task.stopped` audit event.
+     */
+    stop(orgId: string, conversationId: string, accountId: string, taskId: string, actorTokenId?: string): Promise<BackgroundTaskView>;
+    /**
+     * Whether the task's environment may still be used by its conversation's owner (the access
+     * re-check every sandbox tool call makes); when it may not, the live read is skipped.
+     */
+    private environmentUsable;
+    /**
+     * The end of the task's output, at most `tail` bytes. Read live when the task's environment
+     * instance runs (never resuming a suspended one); a finished task whose sandbox does not run answers
+     * with the last lines its finished event kept. Anything else is
+     * `background_task.output_unavailable` (409).
+     */
+    output(orgId: string, conversationId: string, accountId: string, taskId: string, tail: number): Promise<BackgroundTaskOutput>;
+}

package/dist/background/tasks.service.js

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