@aitne/daemon 0.1.10 → 0.1.11

package/dist/services/background-task/background-task-driver.js

@@ -0,0 +1,416 @@
+/**
+ * Background-task driver — generic Claude Agent SDK glue for the
+ * per-task worker loop. BACKGROUND_TASK_RUNNER_DESIGN.md §4.1.
+ *
+ * The browser-task driver's analogue, with the entire Playwright /
+ * managed-Chromium / allowlist / final-confirm plane removed. A worker
+ * is a plain `query()` session seeded with a SELF-CONTAINED brief and a
+ * three-tool MCP envelope (`read_memory`, `ask_user`, `finish`) plus the
+ * SDK's `WebSearch` / `WebFetch` for research-type work. It opts out of
+ * the `<user>` / `<management_rules>` injection (`settingSources:
+ * ["project"]`, as browser-task does) — the brief carries the context,
+ * the output-language directive, persona hints for the `draft`, and the
+ * notification policy / criteria.
+ *
+ * Responsibilities:
+ *   1. Resolve the `(model, maxTurns, maxBudgetUsd, executeTimeout)`
+ *      envelope from `process_backend_config` + the row's tier/budget
+ *      (`background-task-budget.ts`), pinned for the task's lifetime.
+ *   2. Render a per-task workdir (empty dir + CLAUDE.md agent profile).
+ *   3. Drive `query()` until terminal, honouring the AbortController
+ *      (cancel + timeout) — no Playwright resources to release.
+ *   4. Hand back a `DriverRunResult` the runner maps to terminal state /
+ *      park. On the death paths the artifact is NULL — the runner
+ *      synthesizes the fail-loud artifact (§4.3).
+ *
+ * Excluded from the 100% coverage gate — SDK stream consumer. The pure
+ * sub-pieces (budget envelope) live in the covered set.
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { getTaskFlow } from "../../core/prompts.js";
+import { ALWAYS_DISALLOWED_TOOLS } from "../../safety/always-disallowed.js";
+import { getBackgroundTask, setBackendSessionId, } from "../../db/background-task-store.js";
+import { createLogger } from "../../logging.js";
+import { resolveBackgroundTaskEnvelope, } from "./background-task-budget.js";
+import { BACKGROUND_TASK_MCP_SERVER_NAME, BACKGROUND_TASK_TOOL_FQNS, createBackgroundTaskMcpServer, createBackgroundTaskRuntime, } from "./background-task-tools.js";
+import { noopBackgroundTaskTransitionEmitter, } from "./background-task-transition-events.js";
+const logger = createLogger("background-task-driver");
+/** SDK tools the worker may use beyond its MCP envelope. Research-type
+ *  background tasks (the flagship category) need web access; everything
+ *  filesystem/shell is denied (the worker must not read arbitrary host
+ *  files or write shared memory — §10.4). */
+const BACKGROUND_TASK_WEB_TOOLS = ["WebSearch", "WebFetch"];
+/** Defence-in-depth deny list. These are NOT in `allowedTools`, so
+ *  `dontAsk` already denies them — listing them ensures a future
+ *  regression that widens `allowedTools` cannot unlock filesystem/shell
+ *  access. */
+const BACKGROUND_TASK_EXTRA_DISALLOWED = [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "NotebookEdit",
+    "Glob",
+    "Grep",
+];
+/** Read the operator-editable envelope row for `background_task`. */
+export function loadBackgroundTaskProcessConfig(db) {
+    try {
+        const row = db
+            .prepare(`SELECT main_backend, main_model, max_turns, max_budget_usd
+           FROM process_backend_config
+          WHERE process_key = 'background_task'`)
+            .get();
+        if (!row)
+            return null;
+        return {
+            mainBackend: row.main_backend,
+            mainModel: row.main_model,
+            maxTurns: row.max_turns,
+            maxBudgetUsd: row.max_budget_usd,
+        };
+    }
+    catch (err) {
+        logger.warn({ err }, "background-task: process_backend_config read failed; falling back to tier defaults");
+        return null;
+    }
+}
+/**
+ * Acquire a fresh workdir + runtime + binding for `row`. The runner
+ * calls this BEFORE `runDriver` so it can stash the handle in its parked
+ * map before any turn fires (an ask_user on the first turn must find the
+ * handle already there).
+ */
+export async function prepareDriverHandle(input) {
+    const { deps, row } = input;
+    // Pin the envelope BEFORE any work so a misconfigured backend fails
+    // fast AND the binding is frozen for the task's lifetime (no surprise
+    // model swap between yield and clarify resume).
+    const resolved = resolveBackgroundTaskEnvelope({
+        tier: row.tier,
+        maxBudgetUsd: row.maxBudgetUsd,
+        processConfig: loadBackgroundTaskProcessConfig(deps.db),
+    });
+    if (!resolved.ok) {
+        return { ok: false, reason: "backend_misconfigured", detail: resolved.detail };
+    }
+    const cwd = join(deps.paDataDir, "background-task-sessions", row.id);
+    await mkdir(cwd, { recursive: true });
+    try {
+        const profileBody = await readAgentProfileBody(deps.workspaceDir);
+        await writeFile(join(cwd, "CLAUDE.md"), profileBody, "utf-8");
+    }
+    catch (err) {
+        logger.warn({ err, taskId: row.id }, "background-task: agent profile read failed — proceeding with minimal CLAUDE.md");
+        await writeFile(join(cwd, "CLAUDE.md"), "# Background Task Worker\n", "utf-8");
+    }
+    const abortController = new AbortController();
+    const runtime = createBackgroundTaskRuntime({
+        taskId: row.id,
+        db: deps.db,
+        contextDir: deps.contextDir,
+        clarificationTtlMs: deps.clarificationTtlMs,
+        abortSignal: abortController.signal,
+        transitionEmitter: deps.transitionEmitter,
+        nowFn: deps.nowFn,
+    });
+    return {
+        ok: true,
+        handle: {
+            abortController,
+            cwd,
+            runtime,
+            sdkSessionId: row.backendSessionId,
+            binding: resolved.envelope,
+        },
+    };
+}
+/** Drive the initial turn — the worker reads the brief and works. */
+export async function runDriver(deps, row, handle) {
+    const startMs = (deps.nowFn ?? (() => Date.now()))();
+    return runQuery({
+        deps,
+        handle,
+        row,
+        prompt: renderTaskPrompt(row),
+        resume: null,
+        startMs,
+    });
+}
+/** Resume a parked task after `/clarify` lands the owner's answer. Uses
+ *  the persisted SDK session id so the prompt cache stays warm. Works both
+ *  in-process (warm parked handle) and across a daemon restart (the runner
+ *  reconstructs the handle from the persisted `backend_session_id`); in the
+ *  cross-restart case a session the SDK can no longer load surfaces as
+ *  `resume_unavailable`. */
+export async function resumeDriver(deps, row, handle, userAnswer) {
+    if (!handle.sdkSessionId) {
+        return {
+            outcome: "no_finish",
+            sdkSessionId: null,
+            detail: "no sdk session id captured — cannot resume",
+            costUsd: 0,
+            numTurns: 0,
+            durationMs: 0,
+        };
+    }
+    const startMs = (deps.nowFn ?? (() => Date.now()))();
+    return runQuery({
+        deps,
+        handle,
+        row,
+        prompt: `The owner answered your clarification:\n\n${userAnswer}\n\nContinue the task.`,
+        resume: handle.sdkSessionId,
+        isResume: true,
+        startMs,
+    });
+}
+/**
+ * BACKGROUND_TASK_RUNNER_DESIGN.md §10.2 / Phase 4 — resume a task that was
+ * mid-execution when the daemon restarted, using the persisted SDK session
+ * id (`backend_session_id`) so the warm transcript + prompt cache survive
+ * the restart instead of re-running the brief from scratch. The runner
+ * reconstructs the handle (`prepareDriverHandle` recreates the per-task
+ * workdir + sets `sdkSessionId` from the row). When the SDK can no longer
+ * load the session, this returns `resume_unavailable` and the runner falls
+ * back to re-dispatch-from-brief — so resume is a pure optimization with no
+ * regression.
+ */
+export async function resumeFromBootDriver(deps, row, handle) {
+    if (!handle.sdkSessionId) {
+        return {
+            outcome: "resume_unavailable",
+            sdkSessionId: null,
+            detail: "no persisted sdk session id — cannot resume across restart",
+            costUsd: 0,
+            numTurns: 0,
+            durationMs: 0,
+        };
+    }
+    const startMs = (deps.nowFn ?? (() => Date.now()))();
+    return runQuery({
+        deps,
+        handle,
+        row,
+        prompt: "The daemon restarted while you were working on this task. Pick up "
+            + "exactly where you left off and finish it. If you had already "
+            + "gathered enough, call finish() now.",
+        resume: handle.sdkSessionId,
+        isResume: true,
+        startMs,
+    });
+}
+async function runQuery(input) {
+    const { deps, handle, row, prompt, resume, isResume = false, startMs } = input;
+    const mcpServer = createBackgroundTaskMcpServer(handle.runtime);
+    const mcpServers = {
+        [BACKGROUND_TASK_MCP_SERVER_NAME]: mcpServer,
+    };
+    const binding = handle.binding;
+    let sessionId = handle.sdkSessionId;
+    let costUsd = 0;
+    let numTurns = 0;
+    let stopReason = null;
+    let isError = false;
+    let sawInit = false;
+    let outcome = "completed";
+    let detail = null;
+    const timeoutMs = binding.executeTimeoutMinutes * 60 * 1000;
+    const timeoutTimer = setTimeout(() => {
+        handle.abortController.abort(new Error("background_task_execute_timeout"));
+    }, timeoutMs);
+    try {
+        const stream = query({
+            prompt,
+            options: {
+                ...(resume ? { resume } : {}),
+                cwd: handle.cwd,
+                model: binding.modelId,
+                maxTurns: binding.maxTurns,
+                maxBudgetUsd: binding.maxBudgetUsd,
+                abortController: handle.abortController,
+                permissionMode: "dontAsk",
+                allowedTools: [
+                    ...BACKGROUND_TASK_TOOL_FQNS,
+                    ...BACKGROUND_TASK_WEB_TOOLS,
+                ],
+                disallowedTools: [
+                    ...ALWAYS_DISALLOWED_TOOLS,
+                    ...BACKGROUND_TASK_EXTRA_DISALLOWED,
+                ],
+                mcpServers,
+                // CLAUDE.md in cwd is the persona; settingSources includes
+                // "project" so the SDK auto-loads it but NOT the daemon's
+                // <user>/<management_rules> (the brief is self-contained).
+                settingSources: ["project"],
+                persistSession: true,
+                includePartialMessages: false,
+            },
+        });
+        try {
+            for await (const message of stream) {
+                if (message.type === "system"
+                    && message.subtype === "init") {
+                    sawInit = true;
+                    const sid = message.session_id ?? null;
+                    if (sid) {
+                        sessionId = sid;
+                        handle.sdkSessionId = sid;
+                        // Persist so a /clarify resume (and the boot path) can find it.
+                        try {
+                            setBackendSessionId(deps.db, row.id, sid);
+                        }
+                        catch (err) {
+                            /* c8 ignore next 3 -- defensive */
+                            logger.warn({ err, taskId: row.id }, "setBackendSessionId failed (continuing)");
+                        }
+                    }
+                }
+                else if (message.type === "result") {
+                    const result = message;
+                    stopReason = result.stop_reason ?? null;
+                    isError = !!result.is_error;
+                    costUsd += result.total_cost_usd ?? 0;
+                    numTurns = result.num_turns ?? numTurns;
+                }
+            }
+        }
+        finally {
+            try {
+                await stream.return?.(undefined);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const dbStateAfterStream = getBackgroundTask(deps.db, row.id)?.state ?? "running";
+        if (handle.abortController.signal.aborted) {
+            const reason = handle.abortController.signal.reason;
+            if (reason instanceof Error
+                && reason.message === "background_task_execute_timeout") {
+                outcome = "timeout";
+                detail = `executeTimeoutMinutes=${binding.executeTimeoutMinutes}`;
+            }
+            else {
+                outcome = "cancelled";
+                detail = reason instanceof Error ? reason.message : String(reason ?? "abort");
+            }
+        }
+        else if (isResume && !sawInit) {
+            // A resume attempt whose session never loaded — no `init` message
+            // ever arrived (e.g. the SDK can no longer find the persisted
+            // session after a restart). The runner falls back to re-dispatch
+            // rather than fail-loud. Comes after the abort check so a cancel /
+            // timeout during resume is still classified as such.
+            outcome = "resume_unavailable";
+            detail = "resume target session did not load (no init message)";
+        }
+        else if (isError && stopReason && /max_turns/i.test(stopReason)) {
+            outcome = "max_turns_exceeded";
+            detail = stopReason;
+        }
+        else if (isError && stopReason && /budget|cost/i.test(stopReason)) {
+            outcome = "budget_exceeded";
+            detail = stopReason;
+        }
+        else if (handle.runtime.finishFlag.current || dbStateAfterStream === "completed") {
+            outcome = "completed";
+        }
+        else if (dbStateAfterStream === "awaiting_user"
+            && handle.runtime.yieldFlag.current) {
+            outcome = "yielded_for_clarification";
+        }
+        else if (isError) {
+            outcome = "sdk_error";
+            detail = stopReason ?? "sdk_isError";
+        }
+        else {
+            // Clean SDK end but the worker never called finish/ask_user. The
+            // runner treats this as a fail-loud terminal.
+            outcome = "no_finish";
+            detail = "SDK stream ended without finish() or ask_user()";
+        }
+    }
+    catch (err) {
+        if (handle.abortController.signal.aborted) {
+            outcome = "cancelled";
+            detail = err instanceof Error ? err.message : String(err);
+        }
+        else if (isResume && !sawInit) {
+            // The resume query threw before the session loaded — treat as a
+            // recoverable "couldn't resume" rather than a hard SDK error so the
+            // runner re-dispatches from brief.
+            outcome = "resume_unavailable";
+            detail = err instanceof Error ? err.message : String(err);
+        }
+        else {
+            outcome = "sdk_error";
+            detail = err instanceof Error ? err.message : String(err);
+            logger.error({ err, taskId: row.id }, "background-task SDK query threw");
+        }
+    }
+    finally {
+        clearTimeout(timeoutTimer);
+    }
+    const durationMs = (deps.nowFn ?? (() => Date.now()))() - startMs;
+    return { outcome, sdkSessionId: sessionId, detail, costUsd, numTurns, durationMs };
+}
+/** Remove the per-task workdir. Idempotent. Parked tasks (awaiting_user)
+ *  do NOT call this — the runner keeps the handle in its parked map so
+ *  /clarify can resume the warm SDK session. */
+export async function releaseDriverHandle(deps, handle) {
+    try {
+        await rm(handle.cwd, { recursive: true, force: true });
+    }
+    catch (err) {
+        /* c8 ignore start -- defensive */
+        logger.warn({ err, cwd: handle.cwd }, "background-task workdir cleanup failed");
+        /* c8 ignore stop */
+    }
+    void deps;
+}
+async function readAgentProfileBody(workspaceDir) {
+    const candidate = join(workspaceDir, "agent-assets", "agent-profiles", "background-task.md");
+    return readFile(candidate, "utf-8");
+}
+/** Render the worker prompt: the `background_task` task-flow (tool
+ *  policy + notify-disposition rules + output-language reminder) with the
+ *  `{context}` block, then the self-contained brief. */
+function renderTaskPrompt(row) {
+    const flow = getTaskFlow("background_task");
+    const body = flow.length > 0 ? flow : "## Background Task\n\n{context}\n";
+    return body
+        .replace(/\{context\}/g, renderContextBlock(row))
+        .concat("\n\n## Your task (the brief)\n\n", row.brief, "\n");
+}
+function renderContextBlock(row) {
+    const lines = [
+        "<task>",
+        `<task_id>${row.id}</task_id>`,
+        `<title>${row.title ?? ""}</title>`,
+        `<notification_policy>${row.notificationPolicy}</notification_policy>`,
+    ];
+    // Phase 4 if_significant criteria DSL (§4.3): when the spawn carried
+    // structured criteria, render them as a numbered checklist so the
+    // worker's notify decision is a deterministic per-criterion evaluation
+    // rather than a free judgement. Only meaningful for `if_significant`;
+    // injected only when present (else the worker falls back to the brief's
+    // prose criteria).
+    if (row.notificationPolicy === "if_significant"
+        && row.significanceCriteria
+        && row.significanceCriteria.length > 0) {
+        lines.push("<significance_criteria>");
+        lines.push("Set notify=true if AT LEAST ONE of these is met by your result; "
+            + "otherwise notify=false. In `significance`, state which criteria "
+            + "were met / unmet.");
+        row.significanceCriteria.forEach((c, i) => {
+            lines.push(`${i + 1}. ${c}`);
+        });
+        lines.push("</significance_criteria>");
+    }
+    lines.push("</task>");
+    return lines.join("\n");
+}
+void noopBackgroundTaskTransitionEmitter;

package/dist/services/background-task/background-task-runner.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Background-task runner — BACKGROUND_TASK_RUNNER_DESIGN.md §4.1.
+ *
+ * The browser-task runner's lifecycle skeleton, generalized: it owns the
+ * per-task lifecycle from POST → terminal state, REUSING the pure slot
+ * manager (`browser-task-slots.ts`) with a synthetic per-task slot key so
+ * background tasks contend ONLY on the global concurrency cap (never on a
+ * per-key queue). The Playwright plane is gone; the worker is a generic
+ * SDK session (`background-task-driver.ts`).
+ *
+ * What this owns beyond browser-task's runner:
+ *   - DELIVERY ENQUEUE — the runner's `reconcileDriverOutcome` reads the
+ *     finished artifact and decides delivery in ONE place (the design's
+ *     "post-transition hook"): completed + notify=true ⇒ enqueue result;
+ *     parked ⇒ enqueue the open clarification; failed/timeout/no_finish ⇒
+ *     FAIL-LOUD synthesize a failure artifact (notify=true) + enqueue;
+ *     cancelled ⇒ no delivery (the owner cancelled). notify=false ⇒ file
+ *     only. The periodic recovery sweep re-enqueues any lost delivery.
+ *
+ * I/O-shaped. Excluded from the 100% coverage gate; the pure logic lives
+ * in the reused slot manager + the budget envelope.
+ */
+import type Database from "better-sqlite3";
+import { type BackgroundTaskRow } from "../../db/background-task-store.js";
+import { type DriverDeps } from "./background-task-driver.js";
+import { type SlotState } from "../browser-task/browser-task-slots.js";
+import { type BackgroundTaskTransitionEmitter } from "./background-task-transition-events.js";
+/** Shared mutable slot-state container — the runner and the route layer
+ *  hold the same instance (cancel-while-pending vs runner promote race). */
+export interface BackgroundTaskSlotStateRef {
+    state: SlotState;
+}
+export declare function createBackgroundTaskSlotStateRef(maxConcurrent: number): BackgroundTaskSlotStateRef;
+/**
+ * Delivery enqueuer — the runner hands the artifact to this so a
+ * `task.delivery` event lands on the bus. Wired in bootstrap from the
+ * `createBackgroundTask*DeliveryEvent` factories + the event bus (keeps
+ * the runner free of any core/messaging import).
+ */
+export interface BackgroundTaskDeliveryEnqueuer {
+    enqueueResult(input: {
+        taskId: string;
+        originatingChannel: string | null;
+        title: string;
+        draft: string;
+        report: string;
+    }): Promise<void>;
+    enqueueClarification(input: {
+        taskId: string;
+        originatingChannel: string | null;
+        title: string;
+        clarificationId: string;
+        question: string;
+        contextSummary: string | null;
+    }): Promise<void>;
+}
+export interface BackgroundTaskRunnerDeps {
+    db: Database.Database;
+    slotStateRef: BackgroundTaskSlotStateRef;
+    /** Drives the worker SDK session. Absent only in early-boot ordering
+     *  races / tests — when absent the runner fails the row fast. */
+    driver?: DriverDeps;
+    /** Enqueues `task.delivery` events. Optional — when absent (tests) the
+     *  artifact is still written + filed; only the push is skipped. */
+    deliveryEnqueuer?: BackgroundTaskDeliveryEnqueuer;
+    transitionEmitter?: BackgroundTaskTransitionEmitter;
+    /** BACKGROUND_TASK_RUNNER_DESIGN.md §10.2 / Phase 4 — when true, a task
+     *  with a captured SDK session id is resumed via `query({resume})` across
+     *  a daemon restart (boot) or a clarify-after-restart, falling back to
+     *  re-dispatch-from-brief when the session can't be loaded. Wired from
+     *  `backgroundTaskResumeAcrossRestart`; defaults to false (the v1
+     *  re-dispatch-only behaviour) when omitted. */
+    resumeAcrossRestart?: boolean;
+    nowFn?: () => number;
+}
+export interface RunResult {
+    ok: boolean;
+    reason: "completed" | "failed" | "timeout" | "cancelled" | "parked_awaiting_user" | "no_driver" | "queued" | "task_missing" | "already_terminal";
+    state: BackgroundTaskRow["state"] | null;
+}
+export interface BackgroundTaskRunner {
+    runFromPost(taskId: string): Promise<RunResult>;
+    runFromScheduleRow(taskId: string): Promise<RunResult>;
+    cancel(taskId: string, reason: string): Promise<boolean>;
+    resumeAfterClarification(input: {
+        taskId: string;
+        clarificationId: string;
+        answer: string;
+    }): Promise<RunResult>;
+    /** Phase 4 (§10.2) — boot recovery for ONE non-terminal task: resume the
+     *  warm SDK session when possible, else re-dispatch from brief. */
+    resumeFromBoot(taskId: string): Promise<RunResult>;
+    expireForDeadline(taskId: string, kind: "clarification_deadline" | "queue_timeout", waitedMs?: number): Promise<RunResult>;
+    __peekParkedIds(): readonly string[];
+}
+export declare function createBackgroundTaskRunner(deps: BackgroundTaskRunnerDeps): BackgroundTaskRunner;