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

package/dist/background/store.js

@@ -0,0 +1,361 @@
+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,
+    deviceId: r.device_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,
+            ...(to.outputPath !== undefined && { output_path: to.outputPath }),
+        })
+            .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,
+            device_id: row.deviceId,
+            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 a device whose process may still exist (any conversation's: they
+     * share the instance).
+     */
+    async pendingKills(deviceId) {
+        const rows = await this.db
+            .selectFrom("background_tasks")
+            .selectAll()
+            .where("device_id", "=", deviceId)
+            .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,109 @@
+import { ConversationAccess } from "../conversations/access.js";
+import { EventLog } from "../conversations/event-log.js";
+import { ConversationDevices } from "../devices/conversation-devices.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;
+}
+/**
+ * Why a task's output cannot be read live: `starting` (the launch has not recorded the task's
+ * session yet), `not_started` (the launch failed: the task never ran, its `lostReason` says why),
+ * `device_offline` (the local device's machine is not connected), `suspended` (the instance is
+ * suspended; reading never resumes it), `rebuilt` (the instance the task ran in is gone, and its
+ * files with it), `output_missing` (the instance runs but the output file is gone), `no_access`
+ * (the conversation's owner may no longer use the device), `unavailable` (the device's provider
+ * is not loaded), `read_failed` (the read command failed).
+ */
+export type OutputUnavailableReason = "starting" | "not_started" | "device_offline" | "suspended" | "rebuilt" | "output_missing" | "no_access" | "unavailable" | "read_failed";
+/** Why the live read failed, and where the task ran: a `local` device or a `cloud` sandbox. */
+export interface OutputUnavailable {
+    reason: OutputUnavailableReason;
+    environment: "local" | "cloud";
+}
+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";
+    /** With `event`: why the output was not read live. */
+    unavailable?: OutputUnavailable;
+}
+/**
+ * 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 devices;
+    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "availableFor" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb, devices: Pick<ConversationDevices, "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, auditDetail?: Record<string, unknown>): Promise<BackgroundTaskView>;
+    /**
+     * Whether the task's device may still be used by its conversation's owner (the access
+     * re-check every sandbox tool call makes); when it may not, the live read is skipped.
+     */
+    private deviceUsable;
+    /**
+     * The end of the task's output, at most `tail` bytes. Read live when the task's device
+     * instance runs (never resuming a suspended one); a finished task that cannot be read live
+     * answers with the last lines its finished event kept and why (`unavailable`). Anything else is
+     * `background_task.output_unavailable` (409) with `details: [{ reason, environment }]`.
+     */
+    output(orgId: string, conversationId: string, accountId: string, taskId: string, tail: number): Promise<BackgroundTaskOutput>;
+    /** Whether the task ran on a local device (its machine) or in a cloud sandbox. */
+    private environmentOf;
+    /** Reads the output from the task's running instance, or says why it cannot. */
+    private readLive;
+}
+/**
+ * Prints `size <bytes>` and `out <base64 of the last `tail` bytes>`, or `missing` when the output
+ * file is not there. Relative to the workspace root; POSIX tools only (`wc -c`, `tail -c`,
+ * `base64`, `tr`), so it reads the same on Linux and macOS.
+ */
+export declare function tailScript(id: string, tail: number): string;
+/**
+ * Decodes {@link tailScript}'s output (`missing`: no output file; null: unreadable); a cut that
+ * splits a UTF-8 character drops its tail bytes.
+ */
+export declare function parseTail(stdout: string, tail: number): Omit<BackgroundTaskOutput, "source"> | "missing" | null;