@aitne/daemon 0.1.8 → 0.1.9

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

@@ -0,0 +1,166 @@
+/**
+ * Browser-task runner — BROWSER_TASK_REDESIGN_PLAN.md §5 + §5.1.
+ *
+ * Owns the per-task lifecycle from POST → terminal state:
+ *
+ *  1. Slot acquisition (`browser-task-slots.ts` — pure decisions, the
+ *     runner mutates its `SlotStateRef`).
+ *  2. Playwright + SDK loop via `browser-task-driver.ts` — Phase 2's
+ *     real driver. Phase 1 shipped a `not_implemented` stub that flipped
+ *     every task straight to `failed (not_implemented)`; the driver
+ *     module replaces that body.
+ *  3. Post-execute hook — flips parked-without-yield tasks to
+ *     `failed (ask_user_without_yield)` (§5 hard rule defence).
+ *  4. Park map for clarify resume — `awaiting_user` / `final_confirm`
+ *     tasks keep their `DriverHandle` alive in `parkedHandles` so
+ *     `/clarify` can call `resumeAfterClarification` and re-enter the
+ *     SDK with the user's answer.
+ *  5. Cancellation — `cancel(taskId)` walks the park map and any
+ *     in-flight `AbortController`, signals abort, and lets the driver
+ *     unwind to a `cancelled` terminal.
+ *  6. Final-confirm token reply — `consumeFinalConfirmToken(taskId)`
+ *     is the hook the messaging adapter calls when a `!~xxxxxxxx`
+ *     token reply lands; the runner consults the parked handle to
+ *     resume the click that was waiting on the token. (The token
+ *     await happens INSIDE the tool body via
+ *     `finalConfirmHandler.awaitReply`, so there's no separate driver
+ *     entry-point for it.)
+ *
+ * I/O-shaped. Excluded from the 100% coverage gate; pure logic lives
+ * in the slot manager + deadline scanner + tool helpers under
+ * `browser-task-tools/`.
+ */
+import type Database from "better-sqlite3";
+import { type BrowserTaskRow } from "../../db/browser-task-store.js";
+import { type DriverDeps } from "./browser-task-driver.js";
+import { type SlotState } from "./browser-task-slots.js";
+import { type BrowserTaskTransitionEmitter } from "./browser-task-transition-events.js";
+/**
+ * Runner factory dependencies. Production wires `db`, an in-memory
+ * `SlotStateRef` shared with the API route layer (so cancel + slot
+ * acquisition see one state), the optional notifier for queue / DM
+ * events, and the driver deps the per-task runs need. The factory
+ * returns the singleton runner; the caller stashes it on
+ * `ApiDependencies` for the route layer.
+ */
+export interface BrowserTaskRunnerDeps {
+    db: Database.Database;
+    /** Mutable reference to the slot state. The runner reads and
+     *  replaces it on every acquire / release. The API route layer
+     *  shares the same ref so cancel-while-pending updates a queue the
+     *  runner is about to promote from. */
+    slotStateRef: SlotStateRef;
+    /** Optional notifier — when present, the runner fans queue-state /
+     *  DM intents through it. */
+    notifier?: BrowserTaskNotifier;
+    /** Optional driver-side deps. When absent (Phase 1 boot path that
+     *  has not yet wired the driver), the runner falls back to the
+     *  Phase 1 `not_implemented` synthetic transition so the row
+     *  doesn't hang in pending. Phase 2 callers wire this. */
+    driver?: DriverDeps;
+    /** BROWSER_TASK_REDESIGN_PLAN.md §9a.5 Shape B — emits a `browser_task`
+     *  named SSE event after every state-machine write so the dashboard
+     *  invalidates list / detail / awaiting-count caches without per-id
+     *  polling. Defaults to the no-op emitter when not wired (tests,
+     *  early-boot ordering races). Production wires it from
+     *  `bootstrap/event-pipeline.ts` over the global EventBroadcaster. */
+    transitionEmitter?: BrowserTaskTransitionEmitter;
+    /** Override for tests; production uses `Date.now`. */
+    nowFn?: () => number;
+}
+/** Shared mutable slot-state container. The runner and the route
+ *  layer hold the same instance so a cancel-while-pending and a
+ *  runner-side promote race on the same value. */
+export interface SlotStateRef {
+    state: SlotState;
+}
+export declare function createSlotStateRef(maxConcurrent: number): SlotStateRef;
+/** Surface the runner uses to DM the originating channel on
+ *  queue-state events. Production wires a wrapper around the messaging
+ *  adapter's `sendNotification`; tests pass null and rely on the
+ *  `agent_actions` log to assert intent. */
+export interface BrowserTaskNotifier {
+    notifyQueued(input: {
+        taskId: string;
+        originatingChannel: string | null;
+        blockedCount: number;
+    }): Promise<void>;
+    notifyTerminal(input: {
+        taskId: string;
+        originatingChannel: string | null;
+        state: BrowserTaskRow["state"];
+        outcomeDetail: string | null;
+    }): Promise<void>;
+}
+export interface RunResult {
+    ok: boolean;
+    /**
+     * - `completed` | `failed` | `timeout` | `cancelled` | `abandoned`:
+     *   the driver landed a terminal transition (Phase 2 real run).
+     * - `parked_awaiting_user`: the driver yielded for ask_user; the
+     *   runner kept the BrowserContext in its parked map.
+     * - `parked_final_confirm`: the driver yielded mid-flight on the
+     *   final-confirm gate (rare — usually completes inside the tool).
+     * - `not_implemented`: Phase 1 fallback (driver deps absent).
+     * - `queued`: the slot manager queued the task.
+     * - `task_missing`: row was deleted between insert and dispatch.
+     * - `already_terminal`: the row already reached a terminal state.
+     */
+    reason: "completed" | "failed" | "timeout" | "cancelled" | "abandoned" | "parked_awaiting_user" | "parked_final_confirm" | "not_implemented" | "queued" | "task_missing" | "already_terminal";
+    state: BrowserTaskRow["state"] | null;
+}
+export interface BrowserTaskRunner {
+    /**
+     * Entry point for `POST /api/browser-task` (immediate run) — the
+     * row was just inserted in state=pending and the route handler is
+     * deciding whether to fire-and-forget the runner. Acquires the
+     * slot (or queues), then runs the driver when promoted.
+     */
+    runFromPost(taskId: string): Promise<RunResult>;
+    /**
+     * Entry point for `scheduled.browser_task` — the scheduler is firing
+     * a row whose `agent_schedule.task_context` carries the original
+     * POST body. The Phase 3 scheduler branch creates a fresh
+     * `browser_task` row at fire time and calls this; identical body
+     * to `runFromPost`.
+     */
+    runFromScheduleRow(taskId: string): Promise<RunResult>;
+    /** §14.11 Q#4 cancellation. Aborts the in-flight SDK query via the
+     *  per-task AbortController, releases the parked BrowserContext if
+     *  any, and lets the driver unwind. Returns true when the cancel
+     *  reached a known task. */
+    cancel(taskId: string, reason: string): Promise<boolean>;
+    /** Clarify resume — called from `POST /api/browser-task/:id/clarify`
+     *  after the route layer has written the user's answer into the
+     *  clarification row. The runner re-enters the driver with the
+     *  parked handle + the user's answer threaded as a fresh user
+     *  message. */
+    resumeAfterClarification(input: {
+        taskId: string;
+        clarificationId: string;
+        answer: string;
+    }): Promise<RunResult>;
+    /**
+     * Deadline expiry hook called by the daemon-side deadline scanner
+     * (`bootstrap/event-pipeline.ts` 30 s tick). Two callers today —
+     * the overdue-clarification sweep (`kind: "clarification_deadline"`,
+     * target state `abandoned`) and the pending-queue-timeout sweep
+     * (`kind: "queue_timeout"`, target state `failed`).
+     *
+     * The runner owns this because both kinds may target a task whose
+     * `DriverHandle` is still alive in `parkedHandles` (clarification
+     * deadline) or `liveHandles` (race against a concurrent
+     * `markTerminal` write). Without runner involvement the deadline
+     * tick would write the terminal DB row directly + release the slot
+     * but leak the Playwright Chromium process + workdir for the
+     * clarification-deadline case (`Phase 2 hand-off` note in
+     * `event-pipeline.ts` § browser-task deadline scanner tick).
+     *
+     * Idempotent — re-running on an already-terminal row is a no-op.
+     */
+    expireForDeadline(taskId: string, kind: "clarification_deadline" | "queue_timeout", waitedMs?: number): Promise<RunResult>;
+    /** Test-only — read the parked-task ids so tests can assert the
+     *  parking lifecycle without mocking the driver internals. */
+    __peekParkedIds(): readonly string[];
+}
+export declare function createBrowserTaskRunner(deps: BrowserTaskRunnerDeps): BrowserTaskRunner;