@aitne/daemon 0.1.10 → 0.1.11

package/dist/db/background-task-clarifications-store.js

@@ -0,0 +1,152 @@
+/**
+ * Background-task clarifications — BACKGROUND_TASK_RUNNER_DESIGN.md §6.
+ *
+ * One row per `ask_user` round-trip. The worker writes the row when it
+ * calls `ask_user`, the runner transitions the task to `awaiting_user`,
+ * and the delivery boundary surfaces the question to the owner (active
+ * delivery turn or idle draft send). The owner replies via DM; the DM
+ * agent forwards the answer through `POST /api/background-task/:id/clarify`
+ * which calls `resolveClarification` here.
+ *
+ * Deadline enforcement: a daemon housekeeping tick sweeps
+ * `WHERE resolved = 0 AND deadline_at < now()` via
+ * `listOverdueClarifications` and transitions the parent task to
+ * `timeout` (releasing the slot). The TTL is CONFIGURABLE
+ * (`backgroundTaskClarificationTtlMinutes`) and longer than
+ * browser-task's fixed 5 min — no browser resource is held while parked.
+ *
+ * I/O-bound. Excluded from the coverage gate.
+ */
+const SELECT_COLUMNS = `id, task_id, question, context_summary,
+        asked_at, deadline_at, delivered_at, answer, answered_at, resolved`;
+function fromDbRow(row) {
+    return {
+        id: row.id,
+        taskId: row.task_id,
+        question: row.question,
+        contextSummary: row.context_summary,
+        askedAt: row.asked_at,
+        deadlineAt: row.deadline_at,
+        deliveredAt: row.delivered_at,
+        answer: row.answer,
+        answeredAt: row.answered_at,
+        resolved: row.resolved === 1,
+    };
+}
+export function createClarification(db, input) {
+    const deadline = input.askedAt + input.ttlMs;
+    db.prepare(`INSERT INTO background_task_clarifications
+       (id, task_id, question, context_summary,
+        asked_at, deadline_at, delivered_at, answer, answered_at, resolved)
+     VALUES (?, ?, ?, ?, ?, ?, NULL, NULL, NULL, 0)`).run(input.id, input.taskId, input.question, input.contextSummary, input.askedAt, deadline);
+    const row = getClarification(db, input.id);
+    if (!row) {
+        throw new Error(`createClarification: post-insert row for ${input.id} missing`);
+    }
+    return row;
+}
+export function getClarification(db, id) {
+    const row = db
+        .prepare(`SELECT ${SELECT_COLUMNS} FROM background_task_clarifications WHERE id = ?`)
+        .get(id);
+    return row ? fromDbRow(row) : null;
+}
+export function listClarificationsForTask(db, taskId) {
+    const rows = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM background_task_clarifications
+        WHERE task_id = ?
+        ORDER BY asked_at ASC`)
+        .all(taskId);
+    return rows.map(fromDbRow);
+}
+/** The most-recent unresolved clarification for a task — the one a
+ *  /clarify reply without an explicit id resolves against. */
+export function getOpenClarificationForTask(db, taskId) {
+    const row = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM background_task_clarifications
+        WHERE task_id = ? AND resolved = 0
+        ORDER BY asked_at DESC
+        LIMIT 1`)
+        .get(taskId);
+    return row ? fromDbRow(row) : null;
+}
+/** CAS-resolve a clarification with the owner's answer. Refuses if
+ *  already resolved (idempotent forwarding) or past deadline (the
+ *  deadline scanner owns the timeout transition). */
+export function resolveClarification(db, input) {
+    const existing = getClarification(db, input.id);
+    if (!existing)
+        return { ok: false, row: null, reason: "not_found" };
+    if (existing.resolved) {
+        return { ok: false, row: existing, reason: "already_resolved" };
+    }
+    if (input.answeredAt > existing.deadlineAt) {
+        return { ok: false, row: existing, reason: "expired" };
+    }
+    const result = db
+        .prepare(`UPDATE background_task_clarifications
+          SET answer = ?, answered_at = ?, resolved = 1
+        WHERE id = ? AND resolved = 0`)
+        .run(input.answer, input.answeredAt, input.id);
+    if (result.changes === 0) {
+        const after = getClarification(db, input.id);
+        return { ok: false, row: after, reason: "already_resolved" };
+    }
+    return { ok: true, row: getClarification(db, input.id) };
+}
+/** Sweep target — every unresolved clarification whose deadline has
+ *  passed. The scanner transitions each parent task to `timeout`. */
+export function listOverdueClarifications(db, nowMs) {
+    const rows = db
+        .prepare(`SELECT ${SELECT_COLUMNS}
+         FROM background_task_clarifications
+        WHERE resolved = 0 AND deadline_at < ?
+        ORDER BY deadline_at ASC`)
+        .all(nowMs);
+    return rows.map(fromDbRow);
+}
+/** Mark a clarification resolved without an answer (deadline path). */
+export function expireClarification(db, id, nowMs) {
+    const result = db
+        .prepare(`UPDATE background_task_clarifications
+          SET resolved = 1, answered_at = ?
+        WHERE id = ? AND resolved = 0`)
+        .run(nowMs, id);
+    if (result.changes === 0)
+        return null;
+    return getClarification(db, id);
+}
+export function markClarificationDelivered(db, id, deliveredAt) {
+    const result = db
+        .prepare(`UPDATE background_task_clarifications
+          SET delivered_at = COALESCE(delivered_at, ?)
+        WHERE id = ?`)
+        .run(deliveredAt, id);
+    return result.changes > 0 ? getClarification(db, id) : null;
+}
+/** Delivery recovery target — undelivered, still-open clarifications
+ *  whose parent task is parked, joined with that task's delivery fields. */
+export function listUndeliveredClarifications(db, nowMs, limit = 20) {
+    const rows = db
+        .prepare(`SELECT c.id, c.task_id, c.question, c.context_summary,
+              c.asked_at, c.deadline_at, c.delivered_at,
+              c.answer, c.answered_at, c.resolved,
+              t.originating_channel, t.title, t.brief
+         FROM background_task_clarifications c
+         JOIN background_task t ON t.id = c.task_id
+        WHERE c.resolved = 0
+          AND c.delivered_at IS NULL
+          AND c.deadline_at >= ?
+          AND t.state = 'awaiting_user'
+        ORDER BY c.asked_at ASC
+        LIMIT ?`)
+        .all(nowMs, limit);
+    return rows.map((row) => ({
+        ...fromDbRow(row),
+        taskOriginatingChannel: row.originating_channel,
+        taskTitle: row.title,
+        taskBrief: row.brief,
+    }));
+}

package/dist/db/background-task-store.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Background-task row store — BACKGROUND_TASK_RUNNER_DESIGN.md §6.
+ *
+ * I/O-bound CRUD over `background_task`. The state machine is enforced
+ * at this layer via the CHECK constraint on the `state` column (closed
+ * set) plus the per-transition CAS helpers below — `markRunning`,
+ * `markAwaitingUser`, `markRunningFromParked`, `markTerminal` — each
+ * one's WHERE clause refuses an out-of-order write so a race between two
+ * writers cannot flip a row backwards.
+ *
+ * The genuinely new shape vs `browser_task` is the ARTIFACT: `report`
+ * (verbatim result — the fidelity anchor), `draft` (worker-authored
+ * summary), `notify` (the worker's disposition vs the spawn-time policy),
+ * `significance`, and `artifact_path`. `markTerminal` writes them in the
+ * same transition as the terminal state so a worker's `finish` (or the
+ * runner's fail-loud synthesis) is atomic.
+ *
+ * Pure decision logic (slot arithmetic) is reused from
+ * `services/browser-task/browser-task-slots.ts`; this module is the SQL
+ * wrapper and is excluded from the coverage gate (same posture as
+ * `browser-task-store.ts`).
+ */
+import type Database from "better-sqlite3";
+export type BackgroundTaskState = "pending" | "running" | "awaiting_user" | "completed" | "failed" | "timeout" | "cancelled";
+export type BackgroundTaskNotificationPolicy = "always" | "if_significant" | "silent";
+export type BackgroundTaskTier = "lite" | "medium" | "high";
+export declare const BACKGROUND_TASK_TERMINAL_STATES: ReadonlySet<BackgroundTaskState>;
+export declare const BACKGROUND_TASK_NON_TERMINAL_STATES: ReadonlySet<BackgroundTaskState>;
+export interface BackgroundTaskRow {
+    id: string;
+    brief: string;
+    title: string | null;
+    state: BackgroundTaskState;
+    notificationPolicy: BackgroundTaskNotificationPolicy;
+    /** Phase 4 if_significant criteria DSL (§4.3) — concrete atomic
+     *  conditions the worker checks one-by-one. Empty/null ⇒ the worker
+     *  falls back to the prose criteria in the brief. */
+    significanceCriteria: string[] | null;
+    report: string | null;
+    draft: string | null;
+    /** null until finished; true ⇒ surface, false ⇒ file only. */
+    notify: boolean | null;
+    significance: string | null;
+    artifactPath: string | null;
+    outcomeDetail: string | null;
+    originatingChannel: string | null;
+    correlationId: string | null;
+    scheduleRowId: number | null;
+    tier: BackgroundTaskTier | null;
+    maxBudgetUsd: number | null;
+    backendSessionId: string | null;
+    createdAt: number;
+    startedAt: number | null;
+    finishedAt: number | null;
+    deliveredAt: number | null;
+}
+export interface CreateBackgroundTaskInput {
+    id: string;
+    brief: string;
+    title: string | null;
+    notificationPolicy: BackgroundTaskNotificationPolicy;
+    /** Phase 4 if_significant criteria DSL (§4.3) — optional structured
+     *  conditions. Persisted as a JSON array; null/empty stores SQL NULL. */
+    significanceCriteria?: readonly string[] | null;
+    originatingChannel: string | null;
+    correlationId: string | null;
+    scheduleRowId: number | null;
+    tier: BackgroundTaskTier | null;
+    maxBudgetUsd: number | null;
+    createdAt: number;
+}
+/** Insert a fresh row in state=pending. The slot manager promotes it to
+ *  `running` once a slot frees. */
+export declare function createBackgroundTask(db: Database.Database, input: CreateBackgroundTaskInput): BackgroundTaskRow;
+/**
+ * §10.3 brief-dedup — find a still-relevant task with an IDENTICAL brief
+ * spawned inside the dedup window, so a runaway fan-out (the
+ * RESEARCH_CLUSTER_COST_FIX_PLAN class: a replayed trigger POSTing the
+ * same brief many times in minutes) collapses onto the first task instead
+ * of spawning N workers. Matches on `brief` + `tier` (the two inputs that
+ * define "the same work" — `notificationPolicy` only affects delivery, not
+ * the work done) within `sinceMs`, and excludes the FAIL terminals
+ * (`failed`/`timeout`/`cancelled`) so a prior failure is retryable rather
+ * than sticky. A `completed` duplicate inside the window IS returned — the
+ * answer already exists, re-running would just re-spend. Newest first.
+ */
+export declare function findRecentDuplicateBackgroundTask(db: Database.Database, input: {
+    brief: string;
+    tier: BackgroundTaskTier | null;
+    sinceMs: number;
+}): BackgroundTaskRow | null;
+export declare function getBackgroundTask(db: Database.Database, id: string): BackgroundTaskRow | null;
+export interface ListBackgroundTasksOptions {
+    states?: readonly BackgroundTaskState[];
+    /** §10.5 — filter the worker disposition: `false` = the filed
+     *  (notify=false) digest pull, `true` = already-surfaced. Rows whose
+     *  `notify` is still NULL (unfinished) are excluded when this is set. */
+    notify?: boolean;
+    /** Keep only rows finished at/after this epoch-ms — the digest "since
+     *  yesterday" window. */
+    finishedSinceMs?: number;
+    limit?: number;
+    offset?: number;
+}
+export declare function listBackgroundTasks(db: Database.Database, options?: ListBackgroundTasksOptions): readonly BackgroundTaskRow[];
+export declare function countBackgroundTasks(db: Database.Database, options?: ListBackgroundTasksOptions): number;
+/** Pending → running. CAS on prior state so a concurrent terminal
+ *  transition (cancel-while-pending) does not get clobbered. */
+export declare function markRunning(db: Database.Database, id: string, startedAt: number): BackgroundTaskRow | null;
+/** Running → awaiting_user. Slot stays held; resume via /clarify. */
+export declare function markAwaitingUser(db: Database.Database, id: string): BackgroundTaskRow | null;
+/** awaiting_user → running. Used by /clarify resume. */
+export declare function markRunningFromParked(db: Database.Database, id: string): BackgroundTaskRow | null;
+export interface TerminalTransitionInput {
+    id: string;
+    state: "completed" | "failed" | "timeout" | "cancelled";
+    outcomeDetail: string | null;
+    finishedAt: number;
+    /** Artifact fields. Passing `undefined`/`null` leaves the existing
+     *  column unchanged (COALESCE). `finish` writes all of them on the
+     *  `completed` path; the runner's fail-loud synthesis writes
+     *  `report`/`draft`/`notify` on the `failed`/`timeout` path. */
+    report?: string | null;
+    draft?: string | null;
+    /** `true`/`false` set explicitly; `undefined` leaves it NULL. */
+    notify?: boolean;
+    significance?: string | null;
+    artifactPath?: string | null;
+}
+/** Any non-terminal state → terminal, writing the artifact atomically.
+ *  Idempotent — re-running on an already-terminal row CAS-misses and
+ *  returns null. */
+export declare function markTerminal(db: Database.Database, input: TerminalTransitionInput): BackgroundTaskRow | null;
+/** Capture the SDK session id once the first turn streams it, so a
+ *  /clarify resume can `query({resume})` the warm session. */
+export declare function setBackendSessionId(db: Database.Database, id: string, sessionId: string): void;
+export declare function markBackgroundTaskDelivered(db: Database.Database, id: string, deliveredAt: number): BackgroundTaskRow | null;
+/** Delivery recovery target — completed rows whose worker stored a
+ *  notify=true artifact but whose DM was never sent/recorded (§10.2). */
+export declare function listUndeliveredBackgroundTaskReports(db: Database.Database, limit?: number): readonly BackgroundTaskRow[];
+/** §10.5 — filed (notify=false) results, for the periodic digest +
+ *  owner pull ("did that monitor ever run?"). */
+export declare function listFiledBackgroundTaskResults(db: Database.Database, sinceMs: number, limit?: number): readonly BackgroundTaskRow[];
+/**
+ * §10.2 boot re-dispatch-from-brief — reset every non-terminal row to
+ * `pending` (clearing the lost in-memory session) so the event-pipeline
+ * boot hook can re-run each one's brief through the runner. Returns the
+ * ids reset so the caller can fan out the re-dispatch.
+ *
+ * Unlike browser_task's `sweepNonTerminalRowsForBootRecovery` (which
+ * force-fails), background tasks are re-dispatchable because the brief is
+ * self-contained. `backend_session_id` is cleared since the prior SDK
+ * session is unreachable after a restart.
+ *
+ * Open clarifications belonging to the reset tasks are resolved in the
+ * SAME transaction. The pre-restart run that raised an `ask_user` is
+ * gone, so its clarification row is orphaned: a surviving `resolved = 0`
+ * row would later trip the deadline scanner (`listOverdueClarifications`
+ * → `expireForDeadline`) into transitioning the FRESH re-dispatched run
+ * to `timeout` — and because re-dispatch makes the task ACTIVE again
+ * (pending→running), that `expireForDeadline` is NOT a no-op the way it
+ * is for a terminal row. Clearing them here closes that window.
+ */
+export declare function resetNonTerminalForBootRedispatch(db: Database.Database, nowMs?: number): readonly {
+    id: string;
+}[];
+/**
+ * Phase 4 resume-across-restart (§10.2) — the non-terminal rows the boot
+ * recovery path partitions into "resume the SDK session" vs "re-dispatch
+ * from brief". Returns just the discriminators (id, state, session id) so
+ * the caller can decide without loading the full artifact.
+ */
+export declare function listNonTerminalBackgroundTasks(db: Database.Database): readonly {
+    id: string;
+    state: BackgroundTaskState;
+    backendSessionId: string | null;
+}[];
+/**
+ * Phase 4 resume-across-restart (§10.2) — reset ONE non-terminal row back
+ * to `pending` for re-dispatch-from-brief, clearing its (now unreachable)
+ * SDK session id and resolving its orphaned open clarifications in the same
+ * transaction (same rationale as the bulk
+ * `resetNonTerminalForBootRedispatch`: a surviving `resolved = 0` row would
+ * trip the deadline scanner into timing out the FRESH re-dispatched run).
+ * Used by the boot path for the rows it re-dispatches and by the runner's
+ * resume-failure fallback. Returns the row id when it was non-terminal,
+ * else null (idempotent on an already-terminal / missing row).
+ */
+export declare function resetSingleForBootRedispatch(db: Database.Database, id: string, nowMs?: number): string | null;
+/**
+ * Fold a just-answered clarification into the task's brief so a COLD
+ * re-dispatch (when the warm SDK session can't be resumed across a restart,
+ * §10.2) still carries the owner's answer and doesn't re-ask the same
+ * question. The worker only ever sees the brief, so appending the resolved
+ * Q&A is the only way to thread the answer into a fresh run. Idempotency is
+ * not required — this runs at most once per clarification per re-dispatch,
+ * and the clarify route has already CAS-resolved the row.
+ */
+export declare function appendResolvedClarificationToBrief(db: Database.Database, id: string, question: string | null, answer: string): void;
+/**
+ * Retention prune for terminal rows older than `cutoffMs`. Children in
+ * `background_task_clarifications` go with the parent via ON DELETE
+ * CASCADE. Non-terminal rows are never deleted (the boot re-dispatch
+ * sweep owns them). `finished_at` is the lifetime anchor with a
+ * `created_at` fallback for the rare unset-finished_at terminal.
+ */
+export declare function deleteTerminalBackgroundTasksOlderThan(db: Database.Database, cutoffMs: number): number;