@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/module-types/src/built-in.d.ts

@@ -0,0 +1,28 @@
+import { type ProjectPackage, type ProvidedCommand, type ProvidedCommandLookup } from '@openagt/agent-data';
+/**
+ * The packages the framework ships for every project, by name: dependencies of the framework
+ * itself, resolved from its own install, so a project installs nothing for them and an empty
+ * folder starts an agent and shows it. Each comes through the same contract as a project's own
+ * package: a module by its `./dashboard` export, a provider of a kind of data and the writer of
+ * its hook lines by its `framework` key. This list is the one place the framework names a
+ * package, and a project's own copy of any of them wins.
+ */
+export declare const BUILT_IN_PACKAGES: readonly string[];
+/** The built-in packages, resolved from the framework's own install, once; one that is not installed is skipped. */
+export declare function builtInPackages(): Promise<ProjectPackage[]>;
+/** The directories the built-in packages' commands sit in: what a hook line's PATH gains after the project's own installed tools. */
+export declare function builtInBinDirs(): Promise<string[]>;
+/** What provides `kind` in the project at `root`: one of the project's own packages, else a built-in one. */
+export declare function lookupProvided(root: string, kind: string): Promise<ProvidedCommandLookup>;
+/** {@link lookupProvided}'s command, for a caller that only needs to run it. */
+export declare function providedCommand(root: string, kind: string): Promise<ProvidedCommand | undefined>;
+/** Whether `command` comes from a built-in package the project has no copy of: one the project did not choose. */
+export declare function isBuiltIn(root: string, command: ProvidedCommand): Promise<boolean>;
+/**
+ * Have every package that writes hook lines write its own into the project at `root`: a package
+ * declares `"framework": { "hooks": "<command>" }`, and `<command> init`, run in the project,
+ * writes its lines into the project's hooks file, keeping every line already there. The project's
+ * own packages are asked, then the built-in ones the project has no copy of. Answers one line per
+ * package that could not write, in words.
+ */
+export declare function writeHookLines(root: string): Promise<string[]>;

package/dist/module-types/src/client.d.ts

@@ -0,0 +1,15 @@
+export { DRIVERS, DRIVER_LABELS, isDriverName, driverFromImpl, type DriverName } from './driver-names.js';
+export { PUBLISH_LABELS, isPublishPick, offeredPublishPicks, publishPickIn, type PublishPick } from './publish-levels.js';
+export { formatFrameworkEvent } from './terminal.js';
+export { formatBytes } from './format-bytes.js';
+export { errorMessage } from './error-message.js';
+export { pickedIds } from './events.js';
+export { sessionInfo, agentErrors, type SessionInfo, type AgentError, } from './agent-view.js';
+export { pendingChoices } from './open-choices.js';
+export { interventionKey, activityKey } from './dashboard/keys.js';
+export { SeenTracker } from './dashboard/keyed-watcher.js';
+export type { ProjectionRead } from './dashboard/projects.js';
+export { NOTIFICATION_DEFAULTS, MAX_SPEND_OFFSET, notifies, browserNotifyEnabled, notifyCategoryEnabled, type NotifyCategory } from './preference-defaults.js';
+export { isLoopbackHost } from './loopback-host.js';
+export { bridgeChoiceRequest } from './dashboard/bridge-question.js';
+export { cloudRunState, cloudRunActive, CLOUD_SESSION_WINDOW_MS, type CloudRunState } from './cloud-run-state.js';

package/dist/module-types/src/cloud-run-state.d.ts

@@ -0,0 +1,26 @@
+import type { AgentMeta } from './store/agent-store.js';
+/**
+ * How long after its start a run's cloud session is still assumed to be alive. The same window
+ * the browser bridge watches a session for (`bridge-sessions`): past it nothing could learn the
+ * session is parked, so "in cloud" would be a guess nobody can correct — hence "done".
+ */
+export declare const CLOUD_SESSION_WINDOW_MS: number;
+/**
+ * What the cloud side of a web run is doing.
+ *
+ * - `waiting`: the browser bridge holds a question the session is parked on
+ * - `merged`: the session's work was adopted (#1601) and its pull request merged by the framework
+ * - `in-cloud`: no pull request yet and the run is inside the session window, so it may still be working
+ * - `done`: its pull request exists — the work landed, and the PR badge carries its live state — or the
+ *   window passed with nothing adopted: the session finished or never pushed
+ */
+export type CloudRunState = 'waiting' | 'merged' | 'in-cloud' | 'done';
+/** The fields of a run's record the projection reads. */
+export type CloudRunFacts = Pick<AgentMeta, 'target' | 'status' | 'startedAt' | 'pr' | 'mergeOutcome' | 'cloudWaiting'>;
+/**
+ * The cloud state of a web run whose local half is over, or undefined for any other run — a
+ * local run, or a web run still handing off, stopped or failed — whose stored status is the word.
+ */
+export declare function cloudRunState(meta: CloudRunFacts, now: number): CloudRunState | undefined;
+/** Whether the cloud side still counts as an agent at work: in its session, or waiting on a human. */
+export declare function cloudRunActive(state: CloudRunState | undefined): boolean;

package/dist/module-types/src/dashboard/activity.d.ts

@@ -0,0 +1,40 @@
+import { type AgentMeta, type AgentStatus } from '../store/index.js';
+import type { ProjectSummary, ProjectionRead } from './projects.js';
+export { activityKey } from './keys.js';
+/**
+ * One agent lifecycle event worth a passing mention. Two kinds: an agent `started` (entered
+ * `running`) or `finished` (reached a terminal status). The card is not shown for these — they
+ * only drive notifications — so the fields are just what a notification line needs.
+ */
+export interface Activity {
+    projectId: string;
+    projectName: string;
+    /** The agent this is about. */
+    agentId: string;
+    /** `started` = the agent entered `running`; `finished` = it reached a terminal status. */
+    kind: 'started' | 'finished';
+    /** What the agent is building (its `intent`), for the notification body; may be absent. */
+    title?: string;
+    /** The finished agent's terminal status (`finished` only), so a stop reads differently from a done. */
+    status?: AgentStatus;
+    /** When the agent last changed, ISO, for ordering and the baseline diff. */
+    updatedAt?: string;
+}
+/** Injectable seam so {@link buildActivity} is unit-testable off disk. */
+export interface ActivityDeps {
+    /** A project's runs, live prepended to the archived history, newest-first. Defaults to disk. */
+    readAgents?: (cwd: string) => Promise<AgentMeta[]>;
+}
+/**
+ * Build the cross-project activity feed: for each registered project's most recent agents, one
+ * item per agent reflecting where it is now (`started` while it runs, `finished` once it lands),
+ * newest first. Forgiving — a project whose agents cannot be read simply contributes nothing, and
+ * comes back named as one that was *not* read whole (#1623), since "nothing happened there" and
+ * "I could not look" are the same empty list to everyone but the notification watcher.
+ *
+ * The `started` and `finished` items for one agent carry distinct keys ({@link activityKey}), so a
+ * run that is still going notifies once (started) and again when it lands (finished). An agent that
+ * both starts and finishes between two polls is only ever seen terminal, so it notifies once
+ * (finished) — one quick agent, one line.
+ */
+export declare function buildActivity(projects: ProjectSummary[], deps?: ActivityDeps): Promise<ProjectionRead<Activity>>;

package/dist/module-types/src/dashboard/agent-handoff.d.ts

@@ -0,0 +1,243 @@
+import { type LinkedPr, type BranchPrLookup } from './pull-requests.js';
+import type { Cached } from './cache.js';
+import type { AgentMeta } from '../store/index.js';
+import { type BranchesFor } from '../store/branches.js';
+import { type GitHostFor } from '../store/git-host.js';
+import { type RunsFor } from '../store/runs.js';
+/** One commit a session put on its branch. */
+export interface HandoffCommit {
+    sha: string;
+    /** Short sha, for display. */
+    short: string;
+    subject: string;
+}
+/** One file the session changed, against the branch point. */
+export interface HandoffFile {
+    path: string;
+    insertions: number;
+    deletions: number;
+    /** True for a binary file, where line counts are meaningless. */
+    binary: boolean;
+}
+/** What a finished session produced and what can still be done with it. */
+export interface AgentHandoff {
+    /** The branch the work is on. */
+    branch: string;
+    /** The name the agent gave its work, as the branches provider answers it; absent while the run has not named it. */
+    name?: string;
+    /** The branch still exists in the repo (a deleted or never-created one does not). */
+    exists: boolean;
+    /** The branch is gone because the run changed nothing ({@link leftNothing}), not because work went. */
+    unchanged?: boolean;
+    /**
+     * The run's work was landed: merged into its main agent's branch by that agent, or into the
+     * project's default branch by the person, on this machine. The run's own branch went with that,
+     * and what is read here is what it held, by the last commit its record kept.
+     */
+    landed?: boolean;
+    /** What the branch is measured against: the repo's default branch, or the commit the run's own work begins at (a run started from another branch, or one already merged), when one was found. */
+    base?: string;
+    commits: HandoffCommit[];
+    files: HandoffFile[];
+    insertions: number;
+    deletions: number;
+    /**
+     * The session produced nothing to hand off: the branch exists but carries no commit the base
+     * does not already have — or nothing beyond the framework's own bookkeeping (#1291), which is
+     * committed for provenance, never as publishable work. Said out loud, rather than shown as an
+     * empty branch.
+     */
+    empty: boolean;
+    /** The repo has a remote to push to at all. */
+    hasRemote: boolean;
+    /** The branch is on the remote and the remote is at the same commit. */
+    pushed: boolean;
+    /** The branch is already merged into the base. */
+    merged: boolean;
+    /** The project has a git host package (#1820): a pull request is a next step at all. Without one, the last step is the push. */
+    gitHost: boolean;
+    /** The PR opened for this branch, when there is one. */
+    pr?: LinkedPr;
+    /** The PR is not known yet, rather than absent (#1028): the lookup is still running. */
+    prPending?: boolean;
+    /**
+     * The files the session changed and never committed, read from its own checkout (#1173).
+     *
+     * The agent is told to commit its work, but one that ended without doing so holds its whole
+     * output in an uncommitted tree, and nothing commits it on the agent's behalf (#1638). That work
+     * is not on the branch yet, so it is
+     * not in {@link commits} and it does not make {@link empty} false. Paths rather than a count,
+     * because a no-diff branch must *name* what is waiting instead of offering an Open PR that
+     * the git host can only refuse. Absent when no checkout is on the branch any more — "no checkout"
+     * and "a checkout, tree clean" are different answers.
+     */
+    pendingFiles?: string[];
+}
+/** Injectable seams so the reader is unit-testable off disk and off the provider. */
+export interface AgentHandoffDeps {
+    pr?: BranchPrLookup;
+    /** The project's checkouts and branches (default the project's provider, {@link projectBranches}). */
+    branches?: BranchesFor;
+    /** The project's git host (default the project's provider, {@link projectGitHost}). */
+    gitHost?: GitHostFor;
+    /**
+     * When the agent started (ISO), so the PR lookup can tell the agent's own PR from an earlier agent's
+     * on the same branch name (#1251). Without it, only an open PR is trusted.
+     */
+    since?: string;
+    /**
+     * Which of the run's own PRs answers, when it has more than one (#1512). Identity questions want
+     * the first; a handoff decision comparing the branch tip against a PR's head wants the last one
+     * that saw the branch, or work a later PR already landed reads as unlanded. See {@link pickAgentPr}.
+     */
+    order?: 'first' | 'latest';
+    /** The commit the run's own work begins at ({@link AgentMeta.baseCommit}): what the branch is measured from. */
+    from?: string;
+}
+/**
+ * The branch an agent's work is on: what was recorded while the checkout existed (#799/#1277).
+ * The agent renames its branch itself (#1725), so anything but the record is a guess, and a run
+ * whose record carries no branch has none to hand off.
+ */
+export declare function agentBranchFor(agent: {
+    id: string;
+    branch?: string;
+}): string | undefined;
+/**
+ * Whether a run whose branch is gone changed nothing (#1850): it ended `done`, `failed` or
+ * `stopped` on this machine, has no pull request, and was not landed by a main agent (a landed
+ * run's branch went because its work moved on, not for holding nothing). Such a run's own tool recorded the branch's
+ * last name as it ended, a Stop included, and then reclaimed the checkout, and the branches rule
+ * deletes a branch with the checkout only when it holds nothing. A run whose process died is marked
+ * `stopped` by the sweep only when it left no checkout, so it had nowhere to keep a change. A run
+ * another machine ran leaves no such proof here, and one `waiting` keeps its checkout.
+ */
+export declare function leftNothing(agent: {
+    status?: string;
+    host?: string;
+    pr?: unknown;
+    landed?: string;
+}, host?: string): boolean;
+/** The cached single-PR read {@link resolveAgentPr} asks for the recorded PR's current state. */
+export type CachedBranchPrLookup = (cwd: string, branch?: string) => Promise<Cached<LinkedPr | undefined>>;
+/** What {@link resolveAgentPr} needs to know about an agent: structurally satisfied by {@link AgentMeta}. */
+export interface PrAgent {
+    id: string;
+    branch?: string;
+    /** The pull request the agent recorded when one was opened for it (E6). */
+    pr?: {
+        number: number;
+        url: string;
+    };
+}
+/**
+ * The pull request that belongs to an agent: the one it recorded (E6), read live for its state.
+ *
+ * The number is a fact about the agent, so the agent writes it down — at the moment its handoff opens
+ * the PR, or when the dashboard's button does after the process is gone. Every surface then reads
+ * the same integer instead of re-deriving it.
+ *
+ * What that replaced: a three-way branch-name ladder (the recorded branch, then a branch built from
+ * the session name, then the run-id branch, because a hands-off web agent's checkout is gone and its
+ * session name may be a reused pin) plus a timestamp heuristic on top of it, so that a predecessor's PR on
+ * a shared branch name was not mistaken for this agent's. Three sources and a guess, standing in for
+ * one integer nobody had written down — the same lesson the `branch` event (#1277) already learned.
+ *
+ * The *state* is still read live, because it changes without this agent doing anything: a PR merges,
+ * a human closes it. That read rides the PR-lookup cache (#1028), and `pending` while it is warming means the
+ * caller can ask again rather than render "no PR".
+ */
+export declare function resolveAgentPr(cwd: string, agent: PrAgent, prs?: CachedBranchPrLookup): Promise<Cached<LinkedPr | undefined>>;
+/**
+ * Merge a finished session's open PR (#1391): the Merge action, pressed by a human saying "it's
+ * good, land it". The landing itself is the git host provider's (`merge <number>`): armed to merge on
+ * green, merged at once where it is already green, or watched by the provider where the
+ * repository allows no auto-merge; a draft is marked ready on the way. Refuses when the agent has
+ * no PR or it is no longer open — "already merged" is an answer, not an action.
+ */
+export declare function mergeAgentPr(cwd: string, agent: PrAgent, deps?: {
+    gitHost?: GitHostFor;
+    prs?: CachedBranchPrLookup;
+}): Promise<HandoffResult>;
+/**
+ * Read what a finished session left behind, for `branch`: the branch's git facts from the
+ * project's branches provider, and the run's own pull request from the framework's lookup.
+ *
+ * Returns undefined only when the project has no branches provider, or the provider did not
+ * answer for the branch. A branch that no longer exists still returns a handoff (with
+ * `exists: false`), because "that branch is gone" is itself the answer the dashboard needs to
+ * show — and its PR is a remote question, still answerable (#1255).
+ */
+export declare function readAgentHandoff(cwd: string, branch: string, deps?: AgentHandoffDeps): Promise<AgentHandoff | undefined>;
+/**
+ * What a finished run left behind, off its record: {@link readAgentHandoff} for the branch the
+ * record names, measured from the commit the run's own work begins at when the record names one
+ * (a run started from another branch holds, beyond the default branch, that branch's work too).
+ *
+ * A run its main agent landed has no branch left: what it held is read by the last commit its
+ * record kept, and the answer says landed. A branch gone because the run changed nothing is said
+ * as that, not as lost work. Undefined for a run with neither a branch nor a landed commit.
+ */
+export declare function readRunHandoff(cwd: string, agent: Pick<AgentMeta, 'id' | 'startedAt' | 'branch' | 'baseCommit' | 'landed' | 'status' | 'host' | 'pr'>, deps?: AgentHandoffDeps): Promise<AgentHandoff | undefined>;
+/**
+ * What a handoff action did. The PR's `number` rides along with its `url` (E6), because the number
+ * is the fact worth *recording* — every surface that wants an agent's PR then reads it off the agent
+ * rather than re-deriving it later.
+ */
+export type HandoffResult = {
+    ok: true;
+    url?: string;
+    number?: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Push a finished session's branch (#1820): the last step where the project has no git host, or the
+ * step a person wants on its own. The branches provider pushes it under its clean rule; a branch
+ * only the remote has is already there. Refuses a session that recorded no branch.
+ */
+export declare function pushAgentBranch(cwd: string, agent: Pick<AgentMeta, 'id' | 'branch'>, deps?: {
+    branches?: BranchesFor;
+}): Promise<HandoffResult>;
+/**
+ * Merge a finished session's branch into the project's default branch, on this machine: how the
+ * work reaches the project's own folder where there is no remote to push to. The branches provider
+ * merges and deletes the branch; the session's record then keeps the branch's last commit and the
+ * commit its work began at, so what it changed is still read once the branch is gone.
+ */
+export declare function mergeAgentBranch(cwd: string, agent: Pick<AgentMeta, 'id' | 'branch'>, deps?: {
+    branches?: BranchesFor;
+    runs?: RunsFor;
+}): Promise<HandoffResult>;
+/**
+ * Open a draft PR for a branch that exists only on the remote (#1601): a cloud session's own
+ * `claude/*` branch was pushed from a VM this machine never sees, so there is nothing to push
+ * here — the provider publishes the branch as the remote has it. Draft because a PR the
+ * framework opens by itself must not put a review request in anyone's inbox, and the
+ * interventions queue keeps listing a session's draft.
+ */
+export declare function openRemoteBranchPullRequest(cwd: string, agent: HandoffAgent, branch: string, deps?: {
+    branches?: BranchesFor;
+    gitHost?: GitHostFor;
+}): Promise<HandoffResult>;
+/**
+ * Open a PR for a finished session, deciding from what the agent recorded which cases should not
+ * open one. Reads the branch's handoff first: a branch that no longer exists, or a session that
+ * changed nothing, is a clear error rather than an empty PR, and a branch that already has a PR
+ * returns that one. Title is its branch, else the id; body is the intent, plus which session did it. This is the handoff decision the
+ * dashboard's open-PR button offers; the RPC layer only resolves which run it is about, and the
+ * two providers do the pushing and the opening.
+ */
+export declare function openAgentPullRequest(cwd: string, agent: AgentMeta, options?: {
+    draft?: boolean;
+    branches?: BranchesFor;
+    gitHost?: GitHostFor;
+    pr?: BranchPrLookup;
+}): Promise<HandoffResult>;
+/**
+ * The little a handoff needs to know about the agent it is for: which branch, and what to say on
+ * the PR. Narrower than {@link AgentMeta} so a caller cannot quietly start depending on the rest
+ * of the agent's state.
+ */
+export type HandoffAgent = Pick<AgentMeta, 'id' | 'branch' | 'intent'> & Partial<Pick<AgentMeta, 'startedAt'>>;

package/dist/module-types/src/dashboard/agent-tree.d.ts

@@ -0,0 +1,105 @@
+import { type GitRunner } from '@gemstack/agent-data';
+import { type BranchesFor } from '../store/index.js';
+import type { Cached } from './cache.js';
+import { type FileGitStatus } from './file-status.js';
+import { type FileDiff } from './file-diff.js';
+import { type FileContent } from './file-read.js';
+import { type LinkedPr } from './pull-requests.js';
+/** Where a run's files are read from, and the commit its changes are measured from (`base`). */
+export type AgentFilesAt = {
+    source: 'checkout';
+    path: string;
+    base?: string;
+} | {
+    source: 'branch';
+    branch: string;
+    ref: string;
+    base?: string;
+} | {
+    source: 'merge';
+    number: number;
+    ref: string;
+    base?: string;
+}
+/** The run changed nothing: the project's default branch, where no path is marked. */
+ | {
+    source: 'unchanged';
+    ref: string;
+}
+/** The run's pull request is still being looked up: the next read knows. */
+ | {
+    source: 'pending';
+} | {
+    source: 'gone';
+};
+/** One changed path: what changed, and whether it is committed or only on disk in the checkout. */
+export interface FileMark {
+    status: FileGitStatus;
+    committed: boolean;
+}
+/** What the Files tab shows for a run: the tree at its last state, the paths it changed marked. */
+export type AgentTree = {
+    source: 'checkout';
+    files: string[];
+    changes: Record<string, FileMark>;
+} | {
+    source: 'branch';
+    branch: string;
+    files: string[];
+    changes: Record<string, FileMark>;
+} | {
+    source: 'merge';
+    number: number;
+    files: string[];
+    changes: Record<string, FileMark>;
+} | {
+    source: 'unchanged';
+    files: string[];
+    changes: Record<string, FileMark>;
+} | {
+    source: 'pending';
+} | {
+    source: 'gone';
+};
+/** What {@link resolveAgentFiles} reads through; each defaults to the production reader. */
+export interface AgentFilesDeps {
+    git?: GitRunner;
+    branches?: BranchesFor;
+    agent?: (root: string, agentId: string) => Promise<{
+        id: string;
+        status?: string;
+        host?: string;
+        branch?: string;
+        pr?: {
+            number: number;
+        };
+    } | undefined>;
+    /** This machine's name, against the run's `host`. */
+    host?: string;
+    prs?: (root: string, branch: string) => Promise<Cached<LinkedPr[]>>;
+}
+/**
+ * Where the run `agentId` of the project at `root` has its files: its checkout, else its recorded
+ * branch (local, then origin's copy), else the commit its recorded pull request merged as, else,
+ * for a run that finished `done` on this machine with no pull request, the default branch as a
+ * run that changed nothing, else gone. A branch the default branch already contains (a true merge) shows no change, so there
+ * the merge commit is preferred when this machine has it.
+ */
+export declare function resolveAgentFiles(root: string, agentId: string, deps?: AgentFilesDeps): Promise<AgentFilesAt>;
+/**
+ * The Files tab's answer for a resolved source. A checkout lists every file git sees in it and
+ * marks both what the run committed since it forked and what is on disk uncommitted, the
+ * uncommitted mark winning a path marked both: it is what the file is now. A branch or a merge
+ * lists the commit's tree and marks what it changed, all committed. A run that changed nothing
+ * lists the default branch's tree and marks nothing.
+ */
+export declare function readAgentTree(root: string, at: AgentFilesAt, git?: GitRunner): Promise<AgentTree>;
+/**
+ * One changed file's diff, from the same source the tree was read from. In a checkout an
+ * uncommitted file diffs as it always has (against its last commit); a committed one diffs from
+ * the fork point to the checkout's last commit. On a branch or a merge it is the commit's own
+ * change. Null for a path that is unsafe or not changed there.
+ */
+export declare function readAgentFileDiff(root: string, at: AgentFilesAt, path: string, git?: GitRunner): Promise<FileDiff | null>;
+/** One unchanged file's contents, from the same source the tree was read from. */
+export declare function readAgentFileContent(root: string, at: AgentFilesAt, path: string, git?: GitRunner): Promise<FileContent | null>;

package/dist/module-types/src/dashboard/bridge-endpoints.d.ts

@@ -0,0 +1,157 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { BridgeQuestion } from './bridge-question.js';
+export type { BridgeOption, BridgeQuestion } from './bridge-question.js';
+/**
+ * The browser bridge (#1237): the one endpoint an extension running in the user's own Claude
+ * session posts to, so a question a cloud agent is parked on becomes visible in the dashboard.
+ *
+ * **Why this route carries its own token, unlike every other one.** The #1051 guard in
+ * `startDashboard` only exists on a non-loopback bind, and what protects a loopback daemon is
+ * the same-origin check on `/_rpc`: a page on another origin is refused outright. This
+ * route is the first that is *meant* to be reached from another origin, so neither of those
+ * protects it, and it demands `Authorization: Bearer <daemonToken>` unconditionally instead.
+ *
+ * **No CORS headers, on purpose.** An extension's service worker holding `host_permissions`
+ * fetches without a preflight, so the bridge does not need `Access-Control-Allow-Origin` and
+ * must not have it: a wildcard here would let any page the user visits post to their daemon.
+ * The cost is that the extension has to post from its background worker rather than from the
+ * content script, which is a line in the extension and a much better trade.
+ *
+ * **What it accepts is deliberately tiny.** One shape, fully validated, with no path, command,
+ * prompt or free text anywhere in it. The worst a stolen token buys is a bogus question card in
+ * someone's dashboard, which is the point: this is attached to a daemon that spawns processes.
+ */
+export declare const BRIDGE_PREFIX = "/_bridge";
+/**
+ * The extension version this daemon speaks (#1519). The extension states its own version on
+ * every call, in this header, and a daemon expecting another refuses outright: a version-skewed
+ * extension does not fail loudly, it half-works — missed messages, silently ignored fields —
+ * which reads as a framework bug and burns a debugging session. The extension's manifest must
+ * carry the same number; a test keeps the two in lockstep.
+ */
+export declare const EXPECTED_EXTENSION_VERSION = "0.12.0";
+/** The header the extension states its version in. Lowercase, as node presents all headers. */
+export declare const EXTENSION_VERSION_HEADER = "x-tf-extension-version";
+/**
+ * One thing a cloud session did, as scraped from its page (#1237).
+ *
+ * `seq` is the message's position in the transcript, assigned by the extension, and it is what
+ * makes this idempotent: the page is re-read on every DOM change, so the same message arrives
+ * many times and the daemon keeps one copy per position rather than a growing pile of repeats.
+ */
+export interface BridgeEvent {
+    sessionId: string;
+    seq: number;
+    role: 'agent' | 'user';
+    text: string;
+    receivedAt: string;
+}
+/** What the page half of the bridge reports about itself, for diagnosis. */
+export interface BridgeHello {
+    version: string;
+    sessionId?: string | undefined;
+    note: string;
+    at: string;
+}
+/** A cloud session the extension's Driver tab should be serving (#1237, #1332). */
+export interface BridgeSession {
+    id: string;
+    url: string;
+    /**
+     * Whether the dashboard holds an answer for it waiting to be typed. Such a session is visited
+     * whatever the session list says about it.
+     */
+    answerQueued: boolean;
+}
+/**
+ * What claude.ai's own session list says a session is doing, as the Driver tab reads it (#1332).
+ *
+ * The list's status icon carries a text label, and these are its words: `awaiting` ("Awaiting
+ * input": the session stopped to ask its user), `unread` ("Unread response": it finished a turn
+ * nobody has read), `idle`, `running`, `landed` (the label is the session's pull request and
+ * its state), `missing` (the list does not show the session at all) and `unknown` — a label
+ * the extension does not know, carried verbatim so it can be named rather than guessed at.
+ */
+export type BridgeListStatus = 'awaiting' | 'unread' | 'idle' | 'running' | 'landed' | 'missing' | 'unknown';
+/** One session's list status, stamped when the daemon took it. */
+export interface BridgeSessionStatus {
+    sessionId: string;
+    status: BridgeListStatus;
+    /** The list's own label, kept only for `unknown`. */
+    label?: string | undefined;
+    at: string;
+}
+/**
+ * A session the daemon wants the extension to create on claude.ai (#1328).
+ *
+ * The one shape that travels *out* of the bridge carrying free text, and that direction is what
+ * keeps the "deliberately tiny input" rule intact: the daemon writes it, the extension reads it,
+ * and what comes back is only an id, a boolean and a session id.
+ */
+export interface BridgeStart {
+    id: string;
+    /** `owner/name`, as the repo picker lists it. */
+    repo: string;
+    branch: string;
+    prompt: string;
+    /** The model to pick in claude.ai's model menu before sending (#1697); absent leaves the page's own. */
+    model?: string;
+}
+/** What the daemon wires behind the bridge. Absent when the feature is off, which 404s it. */
+export interface BridgeHandlers {
+    /** The shared secret every bridge call must present. */
+    token: string;
+    /**
+     * The extension version to insist on (#1519). When set, every route past the token demands a
+     * matching {@link EXTENSION_VERSION_HEADER} and answers 426 otherwise — no degraded mode,
+     * ping included, so the only path forward from a stale extension is updating it.
+     */
+    expectedExtensionVersion?: string;
+    /** What version the caller claimed and whether it was turned away, for the dashboard. */
+    extensionVersion?: (got: string, blocked: boolean) => void;
+    record: (question: BridgeQuestion) => void;
+    /** Record what the session said, keyed by its position in the transcript. */
+    recordEvent?: (event: BridgeEvent) => void;
+    /** Note that something reached the bridge, including when it was refused. */
+    contact?: (route: string, status: number) => void;
+    /** What the injected page script reports about itself. */
+    hello?: (hello: BridgeHello) => void;
+    /**
+     * The cloud sessions worth watching, newest first. The extension cannot know an agent started:
+     * it only sees pages the user is already on, so without this the bridge works only when
+     * somebody happens to be looking at claude.ai. This is how a tab gets opened for them.
+     */
+    sessions?: () => Promise<BridgeSession[]>;
+    /**
+     * What the Driver tab read off claude.ai's session list for the watched sessions (#1332): the
+     * read-back a web run's own record cannot give, since the run ends at its hand-off.
+     */
+    statuses?: (statuses: BridgeSessionStatus[]) => void;
+    /**
+     * The answer queued in the dashboard for that session, waiting to be delivered (#1237): `text`
+     * is exactly what the extension types into the composer, composed by the daemon from labels the
+     * session itself offered (#1554).
+     */
+    answer?: (sessionId: string) => {
+        id: string;
+        text: string;
+    } | undefined;
+    /** The extension's word on what a delivery attempt did. */
+    answered?: (sessionId: string, id: string, ok: boolean, note?: string) => void;
+    /**
+     * The next session the daemon wants created, claimed for whoever is asking (#1328). Claiming is
+     * the callee's job: two tabs polling must not both be handed the same request, because a
+     * duplicate here is a duplicate cloud session on the user's account.
+     */
+    start?: () => BridgeStart | undefined;
+    /** The extension's word on what a creation attempt did (#1328). */
+    started?: (id: string, ok: boolean, sessionId?: string, note?: string) => void;
+    now?: () => Date;
+}
+/** Route a `/_bridge/*` request. A daemon with the bridge off 404s every route. */
+export declare function handleBridgeRequest(req: IncomingMessage, res: ServerResponse, pathname: string, handlers: BridgeHandlers | undefined): Promise<void>;
+/**
+ * `Authorization: Bearer <token>`, compared in constant time. Rejects before the body is read,
+ * so an unauthenticated caller cannot make the daemon buffer anything.
+ */
+export declare function bearerAuthorized(req: IncomingMessage, token: string): boolean;

package/dist/module-types/src/dashboard/bridge-question.d.ts

@@ -0,0 +1,32 @@
+import type { ChoiceRequest } from '../events.js';
+/** One answer a bridged question offers: the same fields an `await-choices` option carries. */
+export interface BridgeOption {
+    label: string;
+    detail?: string;
+    /** Starts checked, on a `multi` question. */
+    default?: boolean;
+    /** Picking it hands the session back to the user instead of continuing it (#358). */
+    stop?: boolean;
+}
+/**
+ * A question a cloud session is parked on, as reported by the bridge. The shape of the session's
+ * own `await-choices` block (#1554), keyed by label rather than id: the page shows labels, and a
+ * label is what the extension can type back.
+ */
+export interface BridgeQuestion {
+    /** The cloud session that asked, which joins back to an agent through `AgentMeta.sessionId`. */
+    sessionId: string;
+    title: string;
+    options: BridgeOption[];
+    recommended?: string;
+    /** Several answers at once (#332): the pick is a subset of labels rather than one. */
+    multi?: boolean;
+    /** When the daemon accepted it. Set by the daemon, never by the caller. */
+    receivedAt: string;
+}
+/**
+ * A bridged question as the gate panel renders it (#1554): the same `ChoiceRequest` a local
+ * agent's `choice` event carries, with the labels standing in for ids — a claude.ai page has no
+ * ids, and the label is what can be typed back into it.
+ */
+export declare function bridgeChoiceRequest(question: BridgeQuestion): ChoiceRequest;