@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/widget-types/src/bridge-browser.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The bridge browser (#1332): a Chrome for Testing the daemon launches and owns, with the Claude
+ * web bridge extension installed, signed in to claude.ai once by the user and kept minimized.
+ *
+ * The bridge's far end is a browser signed in to claude.ai. Until now that was the user's own
+ * Chrome with the extension loaded, so a web run could only start — and a parked question could
+ * only be noticed — while that Chrome happened to be open. The spike on #1332 settled what a
+ * browser nobody attends has to be: headed, because claude.ai's Cloudflare gate never clears a
+ * headless one; Chrome for Testing, because branded Chrome stopped loading unpacked extensions
+ * from the command line; and installed over CDP with developer mode on, because an extension
+ * loaded any other way is disabled the first time it reloads itself (#1712).
+ *
+ * Nothing here talks to claude.ai. The daemon launches the browser, hands the extension the
+ * bridge token, and from then on the extension's Driver tab does exactly what it does in the
+ * user's own Chrome — the daemon only keeps the window out of the way and brings it up when the
+ * user has to sign in.
+ */
+/** The directory holding the bridge browser's profile and binary, next to the registry file. */
+export declare const BRIDGE_BROWSER_DIR = "the-framework-browser";
+/**
+ * Where the bridge browser lives: `$XDG_CONFIG_HOME/the-framework-browser` when set, else the
+ * dotted `$HOME/.the-framework-browser`. Beside the registry, so the same variable that isolates
+ * a test's registry isolates its browser, and a machine's real one is never touched from a test.
+ * The profile inside it is persistent on purpose: the user signs in once and the sign-in outlives
+ * every daemon restart.
+ */
+export declare function bridgeBrowserDir(env: NodeJS.ProcessEnv): string;
+/**
+ * The launch flags. Headed (no `--headless`): claude.ai's bot gate rejects a headless browser
+ * outright, and a headed one whose window is minimized passes. The unsafe-extension-debugging
+ * flag is what lets `Extensions.loadUnpacked` install the extension over CDP. The keychain flags
+ * keep the cookie-encryption key out of the OS keychain (macOS asks for the login password on
+ * every launch otherwise, and Linux for the wallet) — the same choice Puppeteer makes; the profile
+ * directory's own permissions are what guard the sign-in.
+ */
+export declare function bridgeBrowserLaunchArgs(port: number, profileDir: string): string[];
+/** Where the extension's files are, and whether that is a checkout, where they are edited in place. */
+export interface BridgeExtensionSource {
+    dir: string;
+    checkout: boolean;
+}
+/**
+ * The extension's files (#1720): the checkout's `packages/chrome-extension` next to this package,
+ * so an edit there reaches the browser through the extension's self-reload; else the copy the
+ * build puts in `dist/chrome-extension`, which is what an installed package has. A folder counts
+ * only when its manifest names the bridge extension. Undefined when neither is there.
+ * `moduleUrl` is this file's URL; tests point it elsewhere.
+ */
+export declare function bridgeExtensionSource(moduleUrl?: string): BridgeExtensionSource | undefined;
+/**
+ * The process holding a profile's singleton lock, or undefined when nothing does. Chrome leaves
+ * the lock behind as a symlink whose target is `<host>-<pid>`; a daemon that died without closing
+ * its browser leaves that browser running, and a second Chrome on the same profile would hand its
+ * command line to the first and exit at once.
+ */
+export declare function profileLockOwner(profileDir: string, readLink?: (path: string) => Promise<string>): Promise<number | undefined>;
+/** One page, worker or browser-internal target Chrome lists. */
+export interface CdpTarget {
+    id: string;
+    type: string;
+    url: string;
+    webSocketDebuggerUrl?: string;
+}
+/** A session on one target: the calls go to that page or worker rather than to the browser. */
+export interface CdpTargetSession {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    close(): void;
+}
+/** How the daemon talks to its browser. Injectable: the real one speaks WebSocket to Chrome. */
+export interface BridgeBrowserCdp {
+    /** A browser-level call: installing the extension, opening and closing targets, window bounds. */
+    call(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Every target Chrome lists — pages, the extension's worker, browser-internal pages. */
+    targets(): Promise<CdpTarget[]>;
+    /** Attach to one target. */
+    attach(target: CdpTarget): Promise<CdpTargetSession>;
+    /** Drop the browser-level connection. The browser keeps running. */
+    close(): void;
+}
+/** The real connection: the browser socket from `/json/version`, targets from `/json/list`. */
+export declare function connectBridgeBrowser(browserUrl: string): Promise<BridgeBrowserCdp>;
+/** Install the extension from its directory. Chrome answers with the extension's id. */
+export declare function installExtension(cdp: BridgeBrowserCdp, extensionDir: string): Promise<string>;
+/**
+ * The developer-mode switch on Chrome's extensions page, flipped on if it is off. Chrome (137
+ * and later) disables an unpacked extension on reload while the mode is off, and the extension
+ * reloads itself whenever its files change (#1712), so without this the bridge would die on the
+ * first edit or pull. The profile remembers the setting, but writing the preference into the
+ * profile directly does nothing — the switch is the one way that works.
+ */
+export declare const DEVELOPER_MODE_ON = "(() => {\n  const manager = document.querySelector('extensions-manager')?.shadowRoot\n  const toggle = manager?.querySelector('extensions-toolbar')?.shadowRoot?.querySelector('#devMode')\n  if (!toggle) return 'missing'\n  if (!toggle.checked) toggle.click()\n  return 'on'\n})()";
+/** Open Chrome's extensions page in the background, switch developer mode on, close the page. */
+export declare function enableDeveloperMode(cdp: BridgeBrowserCdp, sleep: (ms: number) => Promise<void>): Promise<void>;
+/**
+ * What the extension is told, run inside its own worker: the daemon's address and the bridge
+ * token go into the storage its options page would have written, and the Driver tab is opened
+ * as the one pinned claude.ai/code tab — the shape the extension adopts as its Driver — in place
+ * of the blank page the browser started on. Opened here rather than left to the extension
+ * because the extension opens no Driver tab while the daemon lists no cloud session, and the user
+ * signs in on that tab before any session exists.
+ */
+export declare function seedExpression(daemonUrl: string, token: string): string;
+/** Hand the freshly installed extension its daemon and token, in its service worker. */
+export declare function seedExtension(cdp: BridgeBrowserCdp, extensionId: string, daemonUrl: string, token: string, sleep: (ms: number) => Promise<void>): Promise<void>;
+/** The bridge browser once it runs. */
+export interface BridgeBrowser {
+    extensionId: string;
+    /** The path the claude.ai tab is on (`/login` while signed out), or undefined without such a tab. */
+    page(): Promise<string | undefined>;
+    /** Restore the window and bring the browser to the front, for the user to sign in. */
+    show(): Promise<void>;
+    /** Minimize the window again. */
+    hide(): Promise<void>;
+    /** Called once if Chrome exits on its own — the user quit it, or it crashed. */
+    onExit(listener: (detail: string) => void): void;
+    /** Close the browser. Safe to call twice. */
+    close(): Promise<void>;
+}
+/** The Chrome process, as much of it as this module needs. */
+export interface BridgeBrowserProcess {
+    pid?: number | undefined;
+    kill(signal?: NodeJS.Signals): unknown;
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+}
+/** Everything the launch touches outside its own logic. Injectable so the sequence is testable without a Chrome. */
+export interface BridgeBrowserDeps {
+    /** The Chrome for Testing binary, downloaded into `cacheDir` if none is there yet. */
+    binary(cacheDir: string, report: (detail: string) => void): Promise<string>;
+    /** The process holding the profile's lock, if any. */
+    lockOwner(profileDir: string): Promise<number | undefined>;
+    alive(pid: number): boolean;
+    kill(pid: number, signal: NodeJS.Signals): void;
+    port(): Promise<number>;
+    spawn(binary: string, args: string[]): BridgeBrowserProcess;
+    ready(browserUrl: string): Promise<boolean>;
+    connect(browserUrl: string): Promise<BridgeBrowserCdp>;
+    /** Bring the browser application to the front (macOS: activate the app bundle). */
+    activate(binary: string): void;
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * The Chrome for Testing binary in `cacheDir`, or the current stable one downloaded there (about
+ * 150 MB, once). Chrome for Testing rather than whatever Chrome the machine has: branded Chrome
+ * ignores an unpacked extension handed to it from outside, and the agent's own browser lookup
+ * would find exactly that.
+ */
+export declare function bridgeBrowserBinary(cacheDir: string, report: (detail: string) => void): Promise<string>;
+/** macOS: the `.app` bundle the binary lives in, which `open` activates. Undefined elsewhere. */
+export declare function appBundle(binary: string): string | undefined;
+/** The real dependencies. */
+export declare function bridgeBrowserDeps(): BridgeBrowserDeps;
+/**
+ * Make sure nothing else holds the profile: a browser a dead daemon left behind is stopped,
+ * gently first. It is the framework's own profile, so whatever holds it is the framework's own
+ * leftover; nothing the user runs shares it.
+ */
+export declare function freeProfile(profileDir: string, deps: BridgeBrowserDeps): Promise<boolean>;
+/** What a launch needs to know. */
+export interface BridgeBrowserOptions {
+    /** Where the daemon listens — what the extension is told to call. */
+    daemonUrl: string;
+    /** The bridge token the extension presents on every call. */
+    token: string;
+    /** The bridge browser's directory: the profile and the binary live under it. */
+    dir: string;
+    /** The extension's files. Default: `bridgeExtensionSource()`. */
+    extension?: BridgeExtensionSource | undefined;
+    /** Progress, one line at a time, for the dashboard to show while the launch runs. */
+    report?: ((detail: string) => void) | undefined;
+}
+/**
+ * Launch the bridge browser and get it ready: binary, profile, extension, developer mode, token,
+ * Driver tab, minimized. Throws with the step that failed; the browser is closed again on a
+ * failure after the spawn, so a half-set-up browser is never left running.
+ */
+export declare function startBridgeBrowser(opts: BridgeBrowserOptions, deps?: BridgeBrowserDeps): Promise<BridgeBrowser>;
+/** Where the bridge browser stands, for the dashboard. */
+export type BridgeBrowserStatus = {
+    state: 'off';
+} | {
+    state: 'starting';
+    detail: string;
+}
+/** `signIn`: the claude.ai tab is on the sign-in page, so a person has to sign in before anything is served. */
+ | {
+    state: 'running';
+    since: string;
+    visible: boolean;
+    signIn: boolean;
+} | {
+    state: 'stopped';
+    detail: string;
+};
+/** What the dashboard can ask of the bridge browser. */
+export type BridgeBrowserAction = 'show' | 'hide' | 'restart';
+/** The daemon's handle on its bridge browser: one at a time, started and stopped from the preference and the dashboard. */
+export interface BridgeBrowserOwner {
+    /** Where the browser stands; a running one is asked which page its claude.ai tab is on. */
+    status(): Promise<BridgeBrowserStatus>;
+    /** Launch it, unless it is running or on its way. Resolves once the launch is over, either way. */
+    start(): Promise<void>;
+    /** Close it, or cancel a launch under way. */
+    stop(): Promise<void>;
+    act(action: BridgeBrowserAction): Promise<void>;
+}
+/** How the owner launches a browser: the daemon's real launch, or a test's fake. */
+export type BridgeBrowserLauncher = (report: (detail: string) => void) => Promise<BridgeBrowser>;
+/**
+ * The one bridge browser a daemon runs. A launch is slow — the first one downloads Chrome — so
+ * the status carries the step it is on, and a stop that lands mid-launch closes the browser the
+ * launch then hands over rather than leaving it running unowned. A browser that exits on its own
+ * (the user quit it) is reported as stopped with the reason, and not relaunched: quitting it was
+ * an act, and the dashboard offers a restart.
+ */
+export declare function bridgeBrowserOwner(launch: BridgeBrowserLauncher, log?: (line: string) => void): BridgeBrowserOwner;

package/dist/widget-types/src/browser-stream.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The DevTools connection to a Chrome the daemon owns: the bridge browser's (#1332). Chrome
+ * refuses DevTools socket connections carrying an `Origin` header unless launched with
+ * `--remote-allow-origins`, and opening that up would let any page the user happens to visit
+ * drive the browser. So the debug port stays unreachable from the web, and this process is the
+ * only one that talks to it.
+ */
+/** What a caller needs from a CDP connection, so a test can stand in for Chrome. */
+export interface CdpSession {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    close(): void;
+}
+/** How a caller reaches a browser or a page. Injectable: the real one speaks WebSocket to Chrome. */
+export type CdpConnect = (webSocketDebuggerUrl: string) => Promise<CdpSession>;
+/**
+ * Talk CDP to Chrome over its debugger socket. Node's global WebSocket is enough, which is
+ * what keeps this dependency-free.
+ */
+export declare const connectCdp: CdpConnect;

package/dist/widget-types/src/browser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What launching a Chrome with its DevTools port open needs, whoever launches it: a port nobody
+ * holds, and a way to know the port answers. The bridge browser (#1332) is the one caller.
+ */
+/** A free localhost port, asked of the OS rather than guessed. */
+export declare function freePort(): Promise<number>;
+/**
+ * Poll `/json/version` until Chrome answers. Chrome opens the port a beat after the process
+ * starts, so connecting to a URL that is not listening yet is the obvious race.
+ */
+export declare function waitForDebugEndpoint(browserUrl: string, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<boolean>;

package/dist/widget-types/src/cli-exec.d.ts

@@ -0,0 +1,35 @@
+/**
+ * One `execFile`-backed CLI runner, configured per binary — `gh`'s reads and writes. Git runs
+ * through the `skill-branches` package's own runner, which budgets per subcommand.
+ */
+/** Runs a CLI binary in `cwd`, resolving its stdout. Rejects on a non-zero exit. */
+export type CliRunner = (args: string[], cwd: string) => Promise<string>;
+/**
+ * A CLI killed for outrunning its timeout, as opposed to one the tool itself rejected (#997).
+ *
+ * `execFile` SIGTERMs on timeout, and a killed `git push` usually writes nothing to stderr, so
+ * without this the failure surfaces as a bare "Command failed: git push ..." that reads like a
+ * rejected push.
+ */
+export declare class CliTimeoutError extends Error {
+    readonly bin: string;
+    readonly args: string[];
+    readonly timeoutMs: number;
+    /** Brand, so a value that crossed a module boundary is still recognisable. */
+    readonly timedOut = true;
+    constructor(bin: string, args: string[], timeoutMs: number);
+}
+/** How to invoke one binary. */
+export interface CliRunnerOptions {
+    bin: string;
+    /** Kill the process after this long, so a hung CLI cannot hang the caller. */
+    timeoutMs: number;
+    /**
+     * Reject with the CLI's own stderr rather than the generic exec message. `gh` puts the
+     * useful part there ("not logged in", "no default remote"), and that is exactly what the
+     * dashboard should show instead of a generic failure.
+     */
+    preferStderr?: boolean;
+}
+/** Build a {@link CliRunner} for one binary. */
+export declare function cliRunner(opts: CliRunnerOptions): CliRunner;

package/dist/widget-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/widget-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/widget-types/src/dashboard/agent-handoff.d.ts

@@ -0,0 +1,211 @@
+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';
+/** 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;
+    /** What the branch is measured against (the repo's default branch), 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 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` or `failed` on this
+ * machine, and has no pull request. Such a run's own tool recorded the branch's last name as it
+ * ended and then reclaimed the checkout, and the branches rule deletes a branch with the checkout
+ * only when it holds nothing. A run another machine ran, or one whose process died before its tool
+ * could record the end (the sweep marks that one `stopped`), leaves no such proof.
+ */
+export declare function leftNothing(agent: {
+    status?: string;
+    host?: string;
+    pr?: unknown;
+}, 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 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>;
+/**
+ * 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'>>;