@jobshimo/browser-link 0.26.0 → 0.27.1

package/dist/extension/flow-registry.d.ts

@@ -1,13 +1,16 @@
 /**
- * In-flight flow registry + per-tab flow history — the state behind the
- * popup's Flows panel and behind `deps.shouldCancel` (see `flow.ts`).
+ * In-flight flow registry + per-tab flow history + detached-flow records —
+ * the state behind the popup's Flows panel, behind `deps.shouldCancel` (see
+ * `flow.ts`), and behind the `flow_status` wire tool that backs
+ * `browser.flow_status`.
  *
  * Extracted out of `background.ts` for the same reason `idle-policy.ts`,
  * `reconnect-policy.ts` and `flow-recording-policy.ts` were: the service
  * worker itself is untestable (it reaches for `chrome.*` at import time),
  * while THIS is the part with rules worth pinning down — the lifecycle of a
  * running flow, what a cancel does to an id nobody recognises, the 20-entry
- * history cap, and above all WHAT A HISTORY ENTRY IS ALLOWED TO CONTAIN.
+ * history cap, the detached ceiling, and above all WHAT A HISTORY ENTRY IS
+ * ALLOWED TO CONTAIN.
  *
  * PRIVACY CONTRACT (same rule as the persistent map, enforced by
  * `toHistoryEntry` and asserted in the tests): a history entry holds UI
@@ -22,6 +25,18 @@
  * `background.ts`, read by the popup through the same runtime-message
  * channel) and therefore dies with the browser session BY DESIGN. This is
  * an operator view, not an audit log.
+ *
+ * DETACHED-FLOW RECORDS ARE A DIFFERENT ANIMAL and the distinction matters.
+ * A record (`DetachedFlowRecord`, keyed `detached-flow:<flow_id>`) carries
+ * the flow's ACTION MANIFEST — the very `results[]` a synchronous flow
+ * returns to its caller — plus the failure message, so the agent that
+ * launched a detached run can still answer "which things did you just
+ * delete?" after the fact. That is page-derived data at rest in
+ * `chrome.storage.session`, deliberately, because a detached flow has no
+ * open tool call to return it through. It is NEVER shown in the popup, it
+ * is only ever handed back over the bridge to an agent that can already
+ * read the page, and it dies with the browser session like everything else
+ * here.
  */
 import type { FlowProgress, FlowResult } from './flow.js';
 /** How many completed flows are kept per tab. Small on purpose — this is a
@@ -32,7 +47,40 @@ export declare const MAX_FLOW_HISTORY_PER_TAB = 20;
  * only ever knows the former, and a tab that reconnects under a new
  * browser-link id is still the same tab to the human looking at it. */
 export declare function flowHistoryKey(tabId: number): string;
-export type FlowOutcome = 'completed' | 'cancelled' | 'failed';
+/** Absolute wall-clock ceiling on a DETACHED flow, from the moment it is
+ * registered. Mirrors `MAX_DETACHED_FLOW_TIMEOUT_MS` in the server's
+ * `browser-dispatch.ts` (which rejects an over-ceiling flow up front) and
+ * `cdp/detached-flows.ts` (the cdp-direct runner's own copy); kept in sync
+ * manually, since the three packages share no module for it.
+ *
+ * A detached flow escapes `MAX_FLOW_TIMEOUT_MS` — nothing is parked on it,
+ * so the 60s "do not hold a tool call open longer than this" rule simply
+ * does not apply. What it must NOT escape is having an end: a flow that
+ * keeps acting with no agent attached and no upper bound is exactly the
+ * runaway this whole program exists to make impossible. Past the ceiling
+ * the flow self-cancels and reports `stopped_by: 'expired'` — a distinct
+ * outcome from a human pressing Stop, because "I ran out of time" and
+ * "someone stopped me" are different facts about the same partial work.
+ *
+ * Enforced as a DEADLINE checked at the same points as the cancel flag
+ * (see `shouldStop`), never as a timer: a timer would fire while the
+ * runner is mid-step and could not stop anything anyway, and a
+ * request-derived `setTimeout` duration is a resource-exhaustion finding
+ * waiting to happen. */
+export declare const MAX_DETACHED_FLOW_MS: number;
+export type FlowOutcome = 'completed' | 'cancelled' | 'failed' | 'expired';
+/** Why a flow was told to stop. A fixed vocabulary — it reaches both the
+ * popup (as a history label) and the agent (as `stopped_by`), so it can
+ * never carry free text. */
+export type FlowStopReason = 'cancelled' | 'expired' | 'worker-terminated';
+/** Lifecycle state of a flow as `browser.flow_status` reports it.
+ * `'unknown'` is the answer for an id this worker has no record of — a
+ * flow that finished before the last service-worker restart, a synchronous
+ * flow that already returned, or an id that never existed. Deliberately a
+ * state rather than an error, for the same reason cancelling an unknown id
+ * is a no-op: the caller asked "what is this doing?", and "nothing I know
+ * of" is a truthful answer, not a failure. */
+export type FlowState = 'running' | 'completed' | 'cancelled' | 'failed' | 'expired' | 'unknown';
 /** One live flow. Mutable on purpose: `cancelled` is what the runner's
  * `shouldCancel` reads on every step, and `progress` is overwritten in
  * place by its `onProgress`. */
@@ -49,6 +97,18 @@ export interface FlowRegistryEntry {
     steps: number;
     cancelled: boolean;
     progress: FlowProgress;
+    /** Started with `detach: true` — nothing is waiting on its result, so it
+     * keeps acting between agent turns and is the one thing here that
+     * outlives the call that launched it. */
+    detached: boolean;
+    /** Wall-clock instant past which a detached flow self-cancels as
+     * `'expired'`. Set only for detached flows (a synchronous one is already
+     * bounded by `MAX_FLOW_TIMEOUT_MS` on the server side). */
+    expiresAt?: number;
+    /** Set the moment the flow is told to stop, alongside `cancelled`. What
+     * turns an otherwise-identical `stopped_by: 'cancelled'` from the runner
+     * into `'expired'` in the record the agent reads. */
+    stopReason?: FlowStopReason;
 }
 /** A running flow as the popup renders it. Flat and pre-computed
  * (`elapsedMs` rather than a raw clock) so the popup does no arithmetic on
@@ -66,6 +126,10 @@ export interface RunningFlowView {
      * The button becomes "Stopping…" instead of vanishing, so the click is
      * visibly acknowledged during the up-to-one-step gap. */
     cancelling: boolean;
+    /** Rendered as a badge on the row. The human needs to know WHICH of the
+     * running flows is the one that will keep clicking after every agent has
+     * gone home — that is the whole reason the Stop button exists. */
+    detached: boolean;
 }
 /** A finished flow, as stored in `chrome.storage.session`. Every field is
  * a number, an id or a fixed enum — see the PRIVACY CONTRACT above. */
@@ -87,16 +151,28 @@ export interface FlowHistoryEntry {
     /** Step KIND of the failing step ('click', 'wait_for', …). A fixed
      * vocabulary, never page-derived text. */
     failedStepKind?: string;
+    /** The flow ran detached. Worth a badge in the panel: a detached entry is
+     * work the browser did with nobody watching. */
+    detached?: true;
+    /** Why it stopped, when that is not obvious from `outcome` alone — a
+     * `failed` entry reads very differently once you know the service worker
+     * was killed under it rather than a step going wrong. */
+    stoppedBy?: FlowStopReason;
 }
 export interface FlowRegistry {
-    /** Start tracking a flow. Returns the live entry so the caller can hand
-     * `shouldCancel` / `onProgress` closures straight over it. */
+    /** Start tracking a flow and hand back the live entry, so the caller can
+     * stamp late-arriving fields (the tab title) on it and close its
+     * `shouldCancel` / `onProgress` over the same object. */
     register(input: {
         flowId: string;
         tabId: number;
         steps: number;
         title?: string;
-    }): void;
+        detached?: boolean;
+        /** Wall-clock deadline for a detached flow. Ignored (and never set)
+         * for a synchronous one. */
+        expiresAt?: number;
+    }): FlowRegistryEntry;
     get(flowId: string): FlowRegistryEntry | undefined;
     /** Flip a running flow to cancelled. Returns whether this call is the
      * one that flipped it — `false` for an unknown id, an id that already
@@ -104,11 +180,23 @@ export interface FlowRegistry {
      * an agent and the flow's own completion race by nature, and every one
      * of those races ends with the flow not running, which is what the
      * caller asked for. */
-    cancel(flowId: string): boolean;
+    cancel(flowId: string, reason?: FlowStopReason): boolean;
     /** Cancel every flow running against one Chrome tab — the tab closed,
      * the debugger detached, or the bridge was disconnected. Returns how
      * many were flipped. */
     cancelForTab(tabId: number): number;
+    /** The single rule the whole "one detached flow per tab" contract rests
+     * on. Returns the entry so the rejection can NAME the flow already
+     * running — an error that just says "busy" leaves the caller with no way
+     * to find, inspect or stop the thing blocking it. */
+    detachedForTab(tabId: number): FlowRegistryEntry | undefined;
+    /** The one question the runner asks between steps: should I stop? True
+     * when the cancel flag is set OR a detached flow has outlived its
+     * deadline — and in that second case this call is also what RECORDS the
+     * reason, so the outcome comes out as `'expired'` rather than as an
+     * indistinguishable `'cancelled'`. Idempotent and cheap: it runs once
+     * per step. */
+    shouldStop(flowId: string, now: number): boolean;
     /** Stop tracking a finished flow and hand back its final entry (or
      * `undefined` if it was never registered). */
     finish(flowId: string): FlowRegistryEntry | undefined;
@@ -119,14 +207,47 @@ export interface FlowRegistry {
 }
 export declare function createFlowRegistry(): FlowRegistry;
 /**
- * Reduce a finished flow to a history entry — the ONE place a `FlowResult`
- * is allowed to turn into stored state, and therefore the one place the
- * privacy contract has to hold. Nothing is copied across by spread: every
- * field is named, typed and numeric/enum.
+ * What a finished flow amounted to, in fields that are the same whether
+ * the reader is the popup or an agent. Shared by `toHistoryEntry` and
+ * `finishedDetachedFlowRecord` precisely so the two can never disagree
+ * about the same run — a popup showing `cancelled` next to a
+ * `flow_status` reporting `expired` would be worse than either being
+ * wrong on its own.
+ *
+ * `error` is the one field with page-derived free text in it. It is
+ * produced here but consumed ONLY by the detached record (which the agent
+ * reads); `toHistoryEntry` drops it on the floor. See the privacy contract
+ * in the module header.
+ */
+export interface FlowOutcomeSummary {
+    outcome: FlowOutcome;
+    stepsCompleted: number;
+    iterationsCompleted?: number;
+    failedStep?: number;
+    failedStepKind?: string;
+    stoppedBy?: FlowStopReason;
+    error?: string;
+}
+/**
+ * Reduce a finished flow to its outcome. The ONE place a `FlowResult` is
+ * interpreted, so "what happened" has a single definition.
  *
  * `result === null` means the flow threw instead of returning (a detached
  * debugger, a closed tab). That is a `failed` outcome with no step
  * attribution, which is honest — the runner never got to report one.
+ *
+ * The runner only ever reports `stopped_by: 'cancelled'`: it flips when
+ * `shouldCancel` goes true and has no idea WHY it went true. The registry
+ * entry does (`stopReason`), which is what promotes a run that outlived
+ * its ceiling from `cancelled` to `expired` here.
+ */
+export declare function summarizeFlow(entry: FlowRegistryEntry, result: FlowResult | null): FlowOutcomeSummary;
+/**
+ * Reduce a finished flow to a history entry — the ONE place a summary is
+ * allowed to turn into POPUP-visible stored state, and therefore the one
+ * place the privacy contract has to hold. Nothing is copied across by
+ * spread: every field is named, typed and numeric/enum, and the summary's
+ * `error` is deliberately not among them.
  */
 export declare function toHistoryEntry(entry: FlowRegistryEntry, result: FlowResult | null, endedAt: number): FlowHistoryEntry;
 /** Prepend a finished flow to a tab's history and enforce the cap. Newest
@@ -155,8 +276,172 @@ export declare function flowTabLabel(view: {
 }): string;
 /** The progress line for one running flow: "step 2/5" outside a repeat,
  * "step 2/5 · iteration 12/50" inside one, "starting…" before the runner
- * has reported its first step. */
+ * has reported its first step. A detached flow is labelled as such: it is
+ * the one row where the human is the ONLY party still watching. */
 export declare function describeFlowProgress(view: RunningFlowView): string;
 /** The one-line summary for a finished flow: outcome, what it got through,
  * and how long it took. Structure and counts only. */
 export declare function describeFlowHistoryEntry(entry: FlowHistoryEntry): string;
+/** `chrome.storage.session` key holding ONE detached flow's record. Keyed
+ * by `flow_id` (not by tab): the id is what `browser.flow_status` and
+ * `browser.flow_cancel` address, and it stays valid across a tab
+ * reconnecting under a new browser-link id. */
+export declare function detachedFlowKey(flowId: string): string;
+/** Inverse of `detachedFlowKey`, for the worker-start sweep over
+ * `chrome.storage.session.get(null)`. Returns null for every other key. */
+export declare function flowIdFromDetachedFlowKey(key: string): string | null;
+/** How many detached-flow records are kept at once, across every tab.
+ * Small on purpose: each terminal record carries a full action manifest,
+ * `chrome.storage.session` is a shared, quota-bounded store, and the
+ * realistic access pattern is "the agent that launched it polls it, reads
+ * the manifest once, and moves on". Oldest-first eviction. */
+export declare const MAX_DETACHED_FLOW_RECORDS = 10;
+/** Byte ceiling on ONE stored record's serialized manifest. A 500-iteration
+ * repeat over a 20-step body can produce a manifest far larger than
+ * anything a session store should hold, and losing the whole record to a
+ * quota rejection would be strictly worse than losing the manifest: the
+ * counts, the outcome and the failing step all still fit. Over the ceiling
+ * the manifest is dropped and `manifestTruncated` says so out loud, rather
+ * than a silently short array the agent would read as "that's all that
+ * happened". */
+export declare const MAX_DETACHED_MANIFEST_BYTES = 128000;
+/**
+ * The durable record of one detached flow — what `browser.flow_status`
+ * answers from once the flow is no longer in the live registry, and what
+ * makes MV3 service-worker termination detectable at all.
+ *
+ * Written twice per flow and no more: once at launch (`state: 'running'`)
+ * and once when it ends. There is deliberately NO per-step write — a
+ * 200-iteration flow would otherwise hammer `chrome.storage.session`
+ * hundreds of times to keep a progress counter warm that the live registry
+ * already holds for free.
+ */
+export interface DetachedFlowRecord {
+    flowId: string;
+    /** Chrome tab id. The server stamps the browser-link `tab_id` onto the
+     * status payload itself — the extension only ever knows this one. */
+    tabId: number;
+    state: Exclude<FlowState, 'unknown'>;
+    startedAt: number;
+    endedAt?: number;
+    /** Top-level step count the flow was launched with. */
+    steps: number;
+    stepsCompleted: number;
+    iterationsCompleted?: number;
+    stoppedBy?: FlowStopReason;
+    /** The flow failure message. Page-derived free text — agent-facing only,
+     * never rendered in the popup. */
+    error?: string;
+    /** The action manifest: `runFlow`'s `results[]`, verbatim. Absent while
+     * the flow is still running (the runner holds them until it returns) and
+     * when `manifestTruncated` is set. */
+    manifest?: unknown[];
+    manifestTruncated?: true;
+    /** The one-per-flow summary `bridge.event` has not reached the server
+     * yet — either the socket was closed when the flow ended, or the record
+     * was only reconciled at worker start, when no tab is connected. Flushed
+     * on that tab's next registration. */
+    eventPending?: true;
+}
+/** The record written the instant a detached flow is launched. Its whole
+ * job is to exist: a `running` record with no live registry entry behind it
+ * is the ONLY evidence that Chrome killed the service worker mid-flow. */
+export declare function startedDetachedFlowRecord(entry: FlowRegistryEntry): DetachedFlowRecord;
+/** The terminal record, manifest included. `endedAt` is passed in rather
+ * than read off the clock so the caller can use the same instant for the
+ * record, the history entry and the audit event. */
+export declare function finishedDetachedFlowRecord(entry: FlowRegistryEntry, result: FlowResult | null, endedAt: number): DetachedFlowRecord;
+/**
+ * Reconcile a persisted record against the fact that this service worker
+ * has no live registry entry for it — i.e. Chrome terminated the worker
+ * while the flow was mid-run.
+ *
+ * THE RULE, and it is not negotiable: mark it `failed` /
+ * `'worker-terminated'` and NEVER resume. A detached flow exists to do
+ * irreversible bulk work; a resume that could not know how far the dead run
+ * actually got would double-act on some prefix of it. A loud, honest
+ * failure is strictly better than a silent second pass, and a phantom
+ * `running` state — a flow that looks alive while nothing is executing it —
+ * is worse than both.
+ *
+ * The manifest of the dead run is genuinely unrecoverable: it lived in the
+ * runner's closure, and there was never a per-step write that could have
+ * saved it. `manifestTruncated` says so rather than presenting an empty
+ * array as "nothing happened".
+ *
+ * Returns `null` for a record that is already terminal — a second worker
+ * restart must not rewrite an outcome, nor re-fire its audit event.
+ */
+export declare function terminatedDetachedFlowRecord(record: DetachedFlowRecord, endedAt: number): DetachedFlowRecord | null;
+/** Character ceiling on the error string of a MINIMAL record. The normal
+ * terminal record keeps the failure message whole — it is the answer to
+ * "why did it stop". This bound applies only where the full write already
+ * came back refused, and a flow error is page-derived free text with no
+ * upper bound of its own (a `find: multiple-matches` over a huge table
+ * quotes every candidate), so it is the one remaining field that could
+ * still be what breaches the quota. */
+export declare const MAX_MINIMAL_RECORD_ERROR_CHARS = 1024;
+/** The same terminal record without its manifest — what gets written when
+ * storage refuses the full one. The manifest is the only part large enough
+ * to be refused under normal conditions; state, `stoppedBy` and the
+ * counters are a few hundred bytes. Losing the manifest is a documented
+ * outcome; losing the write is not: the stale `running` record becomes
+ * `worker-terminated`. The error is trimmed to
+ * `MAX_MINIMAL_RECORD_ERROR_CHARS` with a visible ellipsis, so a
+ * pathological message cannot be what sinks the retry too. */
+export declare function minimalDetachedFlowRecord(record: DetachedFlowRecord): DetachedFlowRecord;
+/** The history entry for a flow the service worker was killed under. The
+ * live entry is gone, so this is reconstructed from the persisted record —
+ * counts and enums only, same privacy contract as every other entry. */
+export declare function terminatedFlowHistoryEntry(record: DetachedFlowRecord): FlowHistoryEntry;
+/** Narrow whatever `chrome.storage.session` hands back into a record.
+ * Same posture as `parseFlowHistory`: storage is not a typed channel, and a
+ * record written by an older extension version must be dropped rather than
+ * rendered as a half-`undefined` status payload. */
+export declare function parseDetachedFlowRecord(raw: unknown): DetachedFlowRecord | null;
+/** Which stored records to evict so `MAX_DETACHED_FLOW_RECORDS` holds,
+ * oldest-start first. RUNNING records are never evicted regardless of age:
+ * dropping one would erase the only evidence that a flow was in flight, and
+ * a worker restart would then have nothing to mark `worker-terminated`.
+ * Records still owing their summary event (`eventPending`) go LAST, reached
+ * only when nothing else is left: evicting one destroys an audit event no
+ * one has received, but a cap that can never be enforced would block every
+ * new record. The exemption lapses when the flush clears the flag. */
+export declare function detachedFlowRecordsToEvict(records: readonly DetachedFlowRecord[]): DetachedFlowRecord[];
+/** The wire shape `browser.flow_status` returns (the server additionally
+ * stamps `tab_id` onto it — the extension does not know the browser-link
+ * id). snake_case because this one crosses the bridge to an agent, unlike
+ * every other type in this module. */
+export interface FlowStatusPayload {
+    flow_id: string;
+    state: FlowState;
+    detached: boolean;
+    started_at?: number;
+    ended_at?: number;
+    steps?: number;
+    steps_completed?: number;
+    iterations_completed?: number;
+    stopped_by?: FlowStopReason;
+    error?: string;
+    /** A stop has been requested and the runner has not reached its next
+     * check yet — the up-to-one-step gap. Distinguishes "asked to stop" from
+     * "stopped", which is exactly the ambiguity an agent polling right after
+     * `browser.flow_cancel` needs resolved. */
+    cancelling?: true;
+    /** When a detached flow will self-cancel as `expired`. */
+    expires_at?: number;
+    /** `runFlow`'s `results[]`. Present only in a terminal state: while a
+     * flow runs, the runner is still holding them. */
+    manifest?: unknown[];
+    /** The manifest existed but is not retrievable — over the storage
+     * ceiling, or lost with the service worker that was running the flow. */
+    manifest_truncated?: true;
+}
+/**
+ * Build the status payload for a flow id, from whichever source knows
+ * about it. The live registry entry wins for a running flow (it has
+ * up-to-the-step progress the twice-written record cannot), the persisted
+ * record answers for everything that already ended, and an id neither
+ * knows about comes back as `state: 'unknown'` rather than as an error.
+ */
+export declare function toFlowStatus(flowId: string, entry: FlowRegistryEntry | undefined, record: DetachedFlowRecord | undefined): FlowStatusPayload;