@alisio/core 0.1.0-alpha.8 → 0.1.0

package/dist/background/mirror.js

@@ -0,0 +1,41 @@
+const STATUS = {
+    queued: "queued",
+    running: "running",
+    waiting: "running",
+    completed: "succeeded",
+    failed: "failed",
+    cancelled: "cancelled",
+    interrupted: "lost",
+};
+/** Maps one panel node to a task (an unknown status is shown as `lost`, never as running). */
+export function nodeToTask(node, rootSession) {
+    return {
+        id: node.id,
+        kind: "subagent",
+        label: node.label,
+        status: STATUS[node.status] ?? "lost",
+        ...(node.detail ? { command: node.detail } : {}),
+        sessionId: node.sessionId ?? rootSession,
+        ...(node.parentId ? { parentId: node.parentId } : {}),
+        bytes: 0,
+        createdAt: node.startedAt ?? 0,
+        ...(node.startedAt ? { startedAt: node.startedAt } : {}),
+        ...(node.endedAt ? { endedAt: node.endedAt } : {}),
+    };
+}
+/** The subagent tasks of a root session, from the panels the plugin registered. */
+export function subagentTasks(panels, rootSession) {
+    const tasks = [];
+    for (const entry of panels.values()) {
+        if (entry.plugin !== "subagents")
+            continue;
+        try {
+            for (const node of entry.provider.nodes({ sessionId: rootSession }))
+                tasks.push(nodeToTask(node, rootSession));
+        }
+        catch {
+            /* a failing panel never breaks the task list */
+        }
+    }
+    return tasks;
+}

package/dist/background/notify.d.ts

@@ -0,0 +1,58 @@
+import type { BackgroundTaskStore, TaskRow } from "./store.ts";
+export type WakeOutcome = 
+/** A run that carries the notification has started. */
+"started"
+/** The session cannot take a run right now (a run, an approval, another surface): retry. */
+ | "busy"
+/** The session can never take it (missing, archived, finished): give up without delivering. */
+ | "skip";
+export interface TaskWakeRequest {
+    /** The ROOT session to wake. */
+    sessionId: string;
+    /** The message the run starts from (persisted as the user message of the run). */
+    text: string;
+    /** What the UIs show instead of `text`. */
+    display: string;
+    /** Idempotency key of the batch (the host uses it as the run's request id). */
+    requestId: string;
+    taskIds: string[];
+}
+export type TaskWake = (request: TaskWakeRequest) => WakeOutcome | Promise<WakeOutcome>;
+export interface NotifierTiming {
+    batchMs: number;
+    minIntervalMs: number;
+    retryMs: number;
+    burstMax: number;
+    burstWindowMs: number;
+}
+export declare const DEFAULT_NOTIFIER_TIMING: NotifierTiming;
+/** The bounded message of one batch: ids, status and how to read the output, nothing else. */
+export declare function buildTaskNotification(rows: TaskRow[]): {
+    text: string;
+    display: string;
+};
+export declare class TaskNotifier {
+    private options;
+    private sessions;
+    private readonly timing;
+    private disposed;
+    constructor(options: {
+        store: BackgroundTaskStore;
+        wake: TaskWake;
+        timing?: Partial<NotifierTiming>;
+        now?: () => number;
+        /** Errors of the wake callback (it never throws into the caller). */
+        onError?: (error: unknown) => void;
+    });
+    private now;
+    private state;
+    /** Number of finished tasks of a session waiting to be announced. */
+    pending(session: string): number;
+    /** A task ended and may be announced to its root session. */
+    note(row: TaskRow): void;
+    /** The host says the session is idle now: try again without waiting for the retry timer. */
+    poke(session: string): void;
+    dispose(): void;
+    private schedule;
+    private attempt;
+}

package/dist/background/notify.js

@@ -0,0 +1,172 @@
+export const DEFAULT_NOTIFIER_TIMING = {
+    batchMs: 2_000,
+    minIntervalMs: 10_000,
+    retryMs: 2_000,
+    burstMax: 6,
+    burstWindowMs: 10 * 60_000,
+};
+const MAX_LISTED = 10;
+const oneLine = (text, max) => {
+    const flat = text
+        .replace(/[\u0000-\u001f\u007f]+/g, " ")
+        .replace(/[<>]/g, "")
+        .trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+/** Statuses a notification can report. */
+const ENDED = ["succeeded", "failed"];
+/** The bounded message of one batch: ids, status and how to read the output, nothing else. */
+export function buildTaskNotification(rows) {
+    const listed = rows.slice(0, MAX_LISTED).map((row) => {
+        const detail = [
+            `status=${row.status}`,
+            ...(row.exitCode !== undefined ? [`exit_code=${row.exitCode}`] : []),
+            ...(row.errorCode ? [`error=${row.errorCode}`] : []),
+            `output_bytes=${row.bytes}`,
+        ].join(" ");
+        return `- id=${row.id} label="${oneLine(row.label, 80)}" ${detail}`;
+    });
+    const more = rows.length - listed.length;
+    const text = [
+        "<background-task-notification>",
+        `${rows.length} background task${rows.length === 1 ? "" : "s"} finished:`,
+        ...listed,
+        ...(more > 0 ? [`- and ${more} more (use bg_list)`] : []),
+        'Read the output with bg_output {"id": "<id>"}; pass next_offset as offset to continue.',
+        "This is an automatic notification, not a message from the user.",
+        "</background-task-notification>",
+    ].join("\n");
+    const first = rows[0];
+    const display = rows.length === 1
+        ? `Background task finished: ${oneLine(first.label, 60)} (${first.status})`
+        : `${rows.length} background tasks finished`;
+    return { text, display };
+}
+export class TaskNotifier {
+    options;
+    sessions = new Map();
+    timing;
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+        this.timing = { ...DEFAULT_NOTIFIER_TIMING, ...options.timing };
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    state(session) {
+        let state = this.sessions.get(session);
+        if (!state) {
+            state = { ids: new Set(), wakes: [], attempting: false };
+            this.sessions.set(session, state);
+        }
+        return state;
+    }
+    /** Number of finished tasks of a session waiting to be announced. */
+    pending(session) {
+        return this.sessions.get(session)?.ids.size ?? 0;
+    }
+    /** A task ended and may be announced to its root session. */
+    note(row) {
+        if (this.disposed || !ENDED.includes(row.status))
+            return;
+        const state = this.state(row.rootSession);
+        state.ids.add(row.id);
+        this.schedule(row.rootSession, state, this.timing.batchMs);
+    }
+    /** The host says the session is idle now: try again without waiting for the retry timer. */
+    poke(session) {
+        const state = this.sessions.get(session);
+        if (this.disposed || !state?.ids.size)
+            return;
+        this.schedule(session, state, 0);
+    }
+    dispose() {
+        this.disposed = true;
+        for (const state of this.sessions.values())
+            if (state.timer)
+                clearTimeout(state.timer);
+        this.sessions.clear();
+    }
+    schedule(session, state, delay) {
+        const due = this.now() + Math.max(0, delay);
+        // A sooner timer wins; a later request never postpones an armed one.
+        if (state.timer && state.dueAt !== undefined && state.dueAt <= due)
+            return;
+        if (state.timer)
+            clearTimeout(state.timer);
+        state.dueAt = due;
+        state.timer = setTimeout(() => {
+            state.timer = undefined;
+            state.dueAt = undefined;
+            void this.attempt(session, state);
+        }, Math.max(0, delay));
+        state.timer.unref?.();
+    }
+    async attempt(session, state) {
+        if (this.disposed || state.attempting || !state.ids.size)
+            return;
+        const now = this.now();
+        const { minIntervalMs, burstMax, burstWindowMs, retryMs, batchMs } = this.timing;
+        state.wakes = state.wakes.filter((at) => now - at < burstWindowMs);
+        const earliest = Math.max(state.lastWakeAt !== undefined ? state.lastWakeAt + minIntervalMs : 0, state.wakes.length >= burstMax ? state.wakes[0] + burstWindowMs : 0);
+        if (earliest > now)
+            return this.schedule(session, state, earliest - now);
+        const { store } = this.options;
+        const claimed = [];
+        for (const id of [...state.ids]) {
+            const row = store.get(id);
+            state.ids.delete(id);
+            // Read after it finished (delivered_at set by `bg_output`) or removed: nothing to announce.
+            if (!row || row.deliveredAt !== undefined)
+                continue;
+            if (store.claimDelivery(id, now))
+                claimed.push(row);
+        }
+        if (!claimed.length)
+            return;
+        state.attempting = true;
+        const release = () => {
+            for (const row of claimed) {
+                store.releaseDelivery(row.id, now);
+                state.ids.add(row.id);
+            }
+        };
+        try {
+            const { text, display } = buildTaskNotification(claimed.map((row) => store.get(row.id) ?? row));
+            const outcome = await this.options.wake({
+                sessionId: session,
+                text,
+                display,
+                requestId: `bg-${claimed[0]?.id}`,
+                taskIds: claimed.map((row) => row.id),
+            });
+            if (outcome === "started") {
+                state.lastWakeAt = now;
+                state.wakes.push(now);
+                if (state.ids.size)
+                    this.schedule(session, state, batchMs);
+            }
+            else if (outcome === "busy") {
+                release();
+                this.schedule(session, state, retryMs);
+            }
+            else {
+                // `skip`: the session cannot be woken at all; stop retrying, deliver nothing.
+                for (const row of claimed)
+                    store.releaseDelivery(row.id, now);
+            }
+        }
+        catch (error) {
+            this.options.onError?.(error);
+            release();
+            this.schedule(session, state, retryMs);
+        }
+        finally {
+            state.attempting = false;
+            // Tasks that finished while the wake-up was in flight must not wait for another `note`.
+            if (!this.disposed && state.ids.size && !state.timer)
+                this.schedule(session, state, retryMs);
+        }
+    }
+}

package/dist/background/output.d.ts

@@ -0,0 +1,46 @@
+export declare const TAIL_BYTES: number;
+/** Default size of one `bg_output` read and its hard maximum. */
+export declare const DEFAULT_READ_BYTES: number;
+export declare const MAX_READ_BYTES: number;
+/** The folder and relative path of a task log under the state root. */
+export declare const taskLogPath: (rootSession: string, id: string) => string;
+/** Absolute path of a stored (relative) log path; refuses anything that escapes the state root. */
+export declare function resolveLogPath(stateRoot: string, relativePath: string): string;
+/** Length of the longest prefix of `bytes` that does not end in the middle of a UTF-8 sequence. */
+export declare function completeUtf8Length(bytes: Uint8Array): number;
+/** The writing side of one task log. */
+export declare class TaskLogWriter {
+    readonly path: string;
+    private readonly maxBytes;
+    private fd;
+    private written;
+    private cut;
+    private received;
+    private tail;
+    private tailBytes;
+    private closed;
+    constructor(path: string, maxBytes: number);
+    /** Bytes in the file so far. */
+    get bytes(): number;
+    /** Whether output was left out of the stored log. */
+    get truncated(): boolean;
+    append(chunk: string | Buffer): void;
+    private keepTail;
+    private write;
+    /** Appends the tail of a truncated log and closes the file. Idempotent. */
+    finish(): void;
+}
+export interface LogRead {
+    text: string;
+    nextOffset: number;
+    /** Size of the file at the time of the read. */
+    size: number;
+}
+/**
+ * Reads at most `limit` bytes of a log from `offset`. The text ends at a character boundary:
+ * `nextOffset` is where the next read must start. A missing file reads as empty.
+ */
+export declare function readLog(path: string, offset: number, limit: number): Promise<LogRead>;
+/** Appends a note to a finished log file (used for spawn errors); best effort. */
+export declare function appendNote(path: string, note: string): void;
+export declare function removeLog(path: string): Promise<void>;

package/dist/background/output.js

@@ -0,0 +1,179 @@
+/**
+ * Task logs: one append-only file per task under `<state>/tasks/<root session>/<task id>.log`,
+ * written with synchronous appends (chunks are small) so a reader never sees less than what the
+ * writer reported. Readers address the file by byte offset: nothing is ever rewritten, so an offset
+ * stays valid for the life of the task.
+ *
+ * Size limit: the first `maxBytes` of output are kept, then ONE marker line. The rest is not
+ * stored, except for a rolling tail of the last `TAIL_BYTES` which is appended when the task ends,
+ * so the error at the end of a very long build is still readable.
+ */
+import { appendFileSync, closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { open, rm, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { inside } from "../runtime/paths.js";
+export const TAIL_BYTES = 32 * 1024;
+/** Default size of one `bg_output` read and its hard maximum. */
+export const DEFAULT_READ_BYTES = 16 * 1024;
+export const MAX_READ_BYTES = 64 * 1024;
+/** The folder and relative path of a task log under the state root. */
+export const taskLogPath = (rootSession, id) => join("tasks", rootSession, `${id}.log`);
+/** Absolute path of a stored (relative) log path; refuses anything that escapes the state root. */
+export function resolveLogPath(stateRoot, relativePath) {
+    const absolute = resolve(stateRoot, relativePath);
+    if (isAbsolute(relativePath) || !inside(resolve(stateRoot), absolute))
+        throw new Error("Invalid task log path");
+    return absolute;
+}
+/** Length of the longest prefix of `bytes` that does not end in the middle of a UTF-8 sequence. */
+export function completeUtf8Length(bytes) {
+    let end = bytes.length;
+    // Walk back over at most 3 continuation bytes to the lead byte of the last character.
+    for (let back = 1; back <= 4 && end - back >= 0; back++) {
+        const byte = bytes[end - back];
+        if ((byte & 0xc0) === 0x80)
+            continue; // continuation byte
+        const needed = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+        return back < needed ? end - back : end;
+    }
+    return end;
+}
+/** The writing side of one task log. */
+export class TaskLogWriter {
+    path;
+    maxBytes;
+    fd;
+    written = 0;
+    cut = false;
+    received = 0;
+    tail = [];
+    tailBytes = 0;
+    closed = false;
+    constructor(path, maxBytes) {
+        this.path = path;
+        this.maxBytes = maxBytes;
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        this.fd = openSync(path, "a", 0o600);
+    }
+    /** Bytes in the file so far. */
+    get bytes() {
+        return this.written;
+    }
+    /** Whether output was left out of the stored log. */
+    get truncated() {
+        return this.cut;
+    }
+    append(chunk) {
+        if (this.closed || this.fd === undefined)
+            return;
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        if (!buffer.length)
+            return;
+        this.received += buffer.length;
+        if (this.cut)
+            return this.keepTail(buffer);
+        const room = this.maxBytes - this.written;
+        if (buffer.length <= room)
+            return this.write(buffer);
+        const head = buffer.subarray(0, Math.max(0, room));
+        // Never end the stored head in the middle of a character.
+        const whole = head.subarray(0, completeUtf8Length(head));
+        if (whole.length)
+            this.write(whole);
+        this.write(Buffer.from(`\n[output truncated: the log limit of ${this.maxBytes} bytes was reached; the last ${TAIL_BYTES} bytes are appended when the task ends]\n`));
+        this.cut = true;
+        this.keepTail(buffer.subarray(whole.length));
+    }
+    keepTail(buffer) {
+        this.tail.push(buffer);
+        this.tailBytes += buffer.length;
+        while (this.tailBytes - (this.tail[0]?.length ?? 0) >= TAIL_BYTES) {
+            this.tailBytes -= this.tail.shift().length;
+        }
+    }
+    write(buffer) {
+        if (this.fd === undefined)
+            return;
+        try {
+            writeSync(this.fd, buffer);
+            this.written += buffer.length;
+        }
+        catch {
+            /* A full disk never fails the task itself. */
+        }
+    }
+    /** Appends the tail of a truncated log and closes the file. Idempotent. */
+    finish() {
+        if (this.closed)
+            return;
+        if (this.cut && this.tailBytes > 0) {
+            let tail = Buffer.concat(this.tail);
+            if (tail.length > TAIL_BYTES)
+                tail = tail.subarray(tail.length - TAIL_BYTES);
+            // The cut may split a character at the start of the tail.
+            let start = 0;
+            while (start < tail.length && start < 4 && (tail[start] & 0xc0) === 0x80)
+                start++;
+            tail = tail.subarray(start);
+            const omitted = this.received - this.written - tail.length;
+            if (omitted > 0)
+                this.write(Buffer.from(`\n[... ${omitted} bytes omitted; the end of the output follows ...]\n`));
+            this.write(tail);
+        }
+        this.closed = true;
+        if (this.fd !== undefined) {
+            try {
+                closeSync(this.fd);
+            }
+            catch {
+                /* already closed */
+            }
+            this.fd = undefined;
+        }
+    }
+}
+/**
+ * Reads at most `limit` bytes of a log from `offset`. The text ends at a character boundary:
+ * `nextOffset` is where the next read must start. A missing file reads as empty.
+ */
+export async function readLog(path, offset, limit) {
+    const start = Math.max(0, Math.floor(offset));
+    const want = Math.max(1, Math.min(Math.floor(limit), MAX_READ_BYTES));
+    let size = 0;
+    try {
+        size = (await stat(path)).size;
+    }
+    catch {
+        return { text: "", nextOffset: start, size: 0 };
+    }
+    if (start >= size)
+        return { text: "", nextOffset: start, size };
+    const handle = await open(path, "r");
+    try {
+        const buffer = Buffer.alloc(Math.min(want, size - start));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
+        let slice = buffer.subarray(0, bytesRead);
+        // Hold back an incomplete trailing character (the next read completes it); if that leaves
+        // nothing (a lone broken byte), return the raw bytes so a reader always makes progress.
+        slice = slice.subarray(0, completeUtf8Length(slice));
+        if (!slice.length && bytesRead)
+            slice = buffer.subarray(0, bytesRead);
+        return { text: new TextDecoder().decode(slice), nextOffset: start + slice.length, size };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Appends a note to a finished log file (used for spawn errors); best effort. */
+export function appendNote(path, note) {
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        appendFileSync(path, note, { mode: 0o600 });
+    }
+    catch {
+        /* best effort */
+    }
+}
+export async function removeLog(path) {
+    await rm(path, { force: true });
+}

package/dist/background/service.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `BackgroundTasks`: the runtime behind `bg_run`, `bg_list`, `bg_output` and `bg_stop`, and behind
+ * the `/tasks` panels of the TUI and the web.
+ *
+ * A task is an ordinary child process of Alisio started through the shared process runner
+ * (`runProcess`: same shell, same environment allowlist, process-group kill, `taskkill /T /F` on
+ * Windows). It is NOT detached and NOT sandboxed: it dies with Alisio. The process group of every
+ * live task is killed on an orderly `close()` and, as a last resort, from a synchronous `exit`
+ * handler; after an abrupt death of Alisio (SIGKILL, power loss) nothing can run, so the next start
+ * marks the leftovers `lost` (by owner pid) without touching them.
+ *
+ * Every state change is a compare-and-set in the database (see `store.ts`). The origin of an abort
+ * is kept apart from its effect: a stop by the user or the model, or a shutdown, ends `cancelled`
+ * (never `failed`); the watchdog ends `failed` with the code `timeout`.
+ */
+import type { BackgroundTaskInfo, BackgroundTaskOutput, BackgroundTaskStatus, SqlDatabase } from "@alisio/sdk";
+import { type NotifierTiming, type TaskWake } from "./notify.ts";
+import { BackgroundTaskStore } from "./store.ts";
+/** Why a task could not be started. */
+export type TaskAdmissionCode = "disabled" | "read_only" | "shutting_down" | "session_limit" | "process_limit";
+export declare class TaskAdmissionError extends Error {
+    readonly code: TaskAdmissionCode;
+    constructor(code: TaskAdmissionCode, message: string);
+}
+/** An unknown task id, or one that belongs to another session tree. */
+export declare class TaskNotFoundError extends Error {
+    constructor(id: string);
+}
+/** The task belongs to another live Alisio process: only that process can stop it. */
+export declare class TaskForeignError extends Error {
+    readonly ownerPid: number;
+    constructor(ownerPid: number);
+}
+export interface TaskLimits {
+    enabled: boolean;
+    maxPerSession: number;
+    maxRunMs: number;
+    maxOutputBytes: number;
+}
+export interface BackgroundTasksOptions {
+    db: SqlDatabase;
+    /** State root: logs live under `<stateRoot>/tasks/<root session>/`. */
+    stateRoot: string;
+    /** The root of a session (a child session shares its root's tasks). */
+    rootOf: (session: string) => string;
+    /** Read live on every call, so a changed setting applies to the next task. */
+    limits: () => TaskLimits;
+    /** `--read-only`: no task can be started. */
+    readOnly?: boolean;
+    /** Host hook that starts a run to tell the owner about finished tasks (absent: no wake-ups). */
+    wake?: TaskWake;
+    /** Whether the session may still be woken (default: always). */
+    timing?: Partial<NotifierTiming>;
+    /** Live tasks across every application of this process (default 16). */
+    maxPerProcess?: number;
+    /** SIGTERM → SIGKILL grace of a stop (default 3 s). */
+    killGraceMs?: number;
+    /** How long `close()` waits for processes to end before killing their groups (default 1.5 s). */
+    closeGraceMs?: number;
+    /** A task appeared or changed state. */
+    onChange?: (task: BackgroundTaskInfo, rootSession: string) => void;
+    /** Read-only mirror of other task sources (subagents) for the unified list. */
+    mirror?: (rootSession: string) => BackgroundTaskInfo[];
+    onError?: (error: unknown) => void;
+    now?: () => number;
+    /** Owner pid recorded on new rows (tests simulate another process). */
+    pid?: number;
+}
+export declare class BackgroundTasks {
+    private options;
+    readonly store: BackgroundTaskStore;
+    private live;
+    private closing;
+    private notifier;
+    private readonly pid;
+    constructor(options: BackgroundTasksOptions);
+    private now;
+    /** Whether finished tasks wake the owner agent in this host (tools say so in their result). */
+    get notifies(): boolean;
+    /** Startup recovery: tasks of a dead owner process become `lost`. */
+    recover(): BackgroundTaskInfo[];
+    private emit;
+    private info;
+    /** Starts `command` in the background. Throws `TaskAdmissionError` when it cannot be admitted. */
+    start(input: {
+        session: string;
+        workspace: string;
+        command: string;
+        /** Absolute working directory (already resolved through the path policy). */
+        cwd: string;
+        label?: string;
+        timeoutMs?: number;
+    }): BackgroundTaskInfo;
+    private run;
+    /** Final state of a task, exactly once (compare-and-set), then the notification decision. */
+    private settle;
+    /** Moves a live task to `stopping` (compare-and-set) and aborts it. Idempotent. */
+    private requestStop;
+    private ownRow;
+    /** One task of a root session (its tree), or `TaskNotFoundError`. */
+    get(rootSession: string, id: string): BackgroundTaskInfo;
+    /** Tasks of a root session, newest first (shell tasks, plus the read-only subagent mirror). */
+    list(rootSession: string, options?: {
+        status?: BackgroundTaskStatus[];
+        limit?: number;
+        mirror?: boolean;
+    }): BackgroundTaskInfo[];
+    /** Live (queued, running, stopping) tasks of this service, optionally of one root session. */
+    liveCount(rootSession?: string): number;
+    /**
+     * Reads the log from `offset`. `reader: "model"` (the `bg_output` tool) also marks a finished
+     * task as consumed: the agent has seen that it ended, so it is never announced afterwards.
+     */
+    read(rootSession: string, id: string, options?: {
+        offset?: number;
+        limit?: number;
+        reader?: "model" | "user";
+    }): Promise<BackgroundTaskOutput>;
+    /** The agent saw that these tasks finished (read or listed them): nothing to announce. */
+    markSeen(ids: string[]): void;
+    /**
+     * Stops a task. The origin (`user` from a UI, `model` from `bg_stop`) is kept: the task ends
+     * `cancelled`, never `failed`. Resolves with the task as it is after the process ended (or after
+     * the grace period when it is slow to die). A finished task is returned unchanged.
+     */
+    stop(rootSession: string, id: string, origin: "user" | "model"): Promise<BackgroundTaskInfo>;
+    /** The host reports that a session is idle again: a notification held back may go now. */
+    sessionIdle(rootSession: string): void;
+    /** Tasks announced as finished but not yet delivered (tests and diagnostics). */
+    pendingNotifications(rootSession: string): number;
+    /**
+     * Orderly shutdown: refuse new tasks, stop announcing, abort every live task (origin
+     * `shutdown`, so they end `cancelled`), wait for the processes and kill the groups of any that
+     * ignore SIGTERM. Nothing is left running when it resolves.
+     */
+    close(): Promise<void>;
+}