@openagt/dashboard 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,178 @@
+import type { BridgeEvent, BridgeHello, BridgeQuestion, BridgeSessionStatus } from './bridge-endpoints.js';
+/**
+ * An answer picked in the dashboard, on its way back to the session (#1237).
+ *
+ * `queued` until the extension fetches it, delivers it into the composer and acknowledges;
+ * then `sent`, or `failed` with the extension's reason. The id is what the acknowledgement
+ * references, so a stale ack from a tab that died mid-delivery cannot resolve a newer answer.
+ */
+export interface BridgeAnswer {
+    id: string;
+    sessionId: string;
+    /** The label(s) picked — one, or a `multi` question's subset (possibly none). */
+    labels: string[];
+    /**
+     * What the extension types into the session (#1554): the same continuation a local gate
+     * re-prompts with, so a cloud session hears its answer exactly as a local one does — and, on a
+     * `stop` pick, that the user is taking over, since nothing of ours can end a session over there.
+     */
+    text: string;
+    queuedAt: string;
+    /**
+     * When a Driver collected it to type (#1332). Two Drivers can serve one daemon — the user's own
+     * Chrome and the daemon's bridge browser — and an answer handed to both would be typed twice.
+     */
+    claimedAt?: string;
+    state: 'queued' | 'sent' | 'failed';
+    note?: string;
+}
+/** How long a collected answer stays with the Driver that collected it before it is offered again. */
+export declare const ANSWER_CLAIM_TTL_MS = 90000;
+/**
+ * The questions a Claude web session is parked on, keyed by its cloud session id (#1237).
+ *
+ * A cloud agent has no live local session to hang a choice gate on: #1231 ends the agent at the
+ * hand-off, so by the time the agent asks anything the agent is already `done`. The join back to
+ * an agent is `AgentMeta.sessionId`, which a web agent already carries because `CloudSession` reports
+ * the cloud id on its result.
+ *
+ * In memory on purpose. A question is only answerable while the session that asked it is still
+ * parked, and the bridge that reported it re-reports on reconnect, so surviving a daemon restart
+ * would preserve a question that may already have been answered elsewhere.
+ */
+/** The last time anything spoke to the bridge, and how it went. */
+export interface BridgeContact {
+    at: string;
+    route: string;
+    status: number;
+}
+/** The extension's last version claim, and whether the doorway turned it away (#1519). */
+export interface BridgeVersion {
+    got: string;
+    expected: string;
+    blocked: boolean;
+    at: string;
+}
+/**
+ * What a cloud session is told when the user picks a `stop` option (#358, #1554). It lives on
+ * claude.ai where nothing of ours can end it, so the bridge types this instead of a continuation:
+ * the decision, and that the user is taking over from here.
+ */
+export declare function takeoverPrompt(question: string, answer: string): string;
+export declare class BridgeQuestions {
+    private readonly bySession;
+    private contact;
+    /**
+     * Note that something reached the bridge, whatever the outcome.
+     *
+     * Failures are recorded too, and that is the point: an extension that is misconfigured looks
+     * exactly like one that is not installed, because both leave no question behind. A refused
+     * request at least proves something is trying.
+     */
+    recordContact(route: string, status: number): void;
+    private versionState;
+    /**
+     * What version the extension last claimed and whether it was refused for it (#1519).
+     *
+     * The accepted claims are recorded too, which is what clears a blocked banner: the moment an
+     * updated extension gets through, the last word is no longer a refusal.
+     */
+    recordVersion(got: string, expected: string, blocked: boolean): void;
+    /** The last version claim, or undefined while nothing has stated one. */
+    version(): BridgeVersion | undefined;
+    private helloState;
+    /** What the injected page script last said about itself. */
+    recordHello(hello: BridgeHello): void;
+    /** The page script's last report, or undefined if none has ever arrived. */
+    hello(): BridgeHello | undefined;
+    /** The last contact, or undefined if nothing has ever reached the bridge. */
+    lastContact(): BridgeContact | undefined;
+    private readonly statusBySession;
+    /**
+     * What claude.ai's session list last said about a session (#1332), as the Driver tab read it.
+     *
+     * This is the read-back a web run's own record cannot give: the run ends at its hand-off, so
+     * the record says `done` whether the session is parked on its user or finished hours ago.
+     */
+    recordStatus(status: BridgeSessionStatus): void;
+    /** The session's last list status, or undefined while the Driver has never reported one. */
+    status(sessionId: string): BridgeSessionStatus | undefined;
+    /**
+     * Whether the session is waiting on a human: the bridge holds the question it is parked on, or
+     * claude.ai's list shows it awaiting input — a question asked in prose carries no block for
+     * the bridge to hold, and the list is the only thing that says the session stopped for it.
+     *
+     * A list status older than the session window no longer counts: the Driver stops reading a
+     * session past the window, so its last word would otherwise stand forever.
+     */
+    waiting(sessionId: string, now?: Date): boolean;
+    /**
+     * Whether an extension is around (#1328): something reached the bridge and was let in within
+     * the window. The worker polls every half minute while it lives, so a longer silence means
+     * there is nobody to drain a request.
+     */
+    extensionAlive(now?: Date, windowMs?: number): boolean;
+    private readonly eventsBySession;
+    /**
+     * Record one transcript entry, keyed by its position.
+     *
+     * Keyed rather than appended because the page is re-read on every DOM change, so the same
+     * message arrives repeatedly and a growing list would be mostly duplicates. Position also lets
+     * a later read replace an earlier one, which is what a message still being streamed needs.
+     */
+    recordEvent(event: BridgeEvent): void;
+    /** That session's transcript so far, in order. */
+    events(sessionId: string): BridgeEvent[];
+    private readonly answersBySession;
+    /** The fingerprint of the question each session's `sent` answer resolved. */
+    private readonly answeredBySession;
+    /**
+     * Record the question a session is parked on, replacing any earlier one for that session.
+     *
+     * A question identical to one an answer was already delivered for is dropped: the extension's
+     * worker forgets what it sent when it restarts, and the answered block stays in the page's DOM,
+     * so the same question would otherwise resurface as parked right after being answered.
+     */
+    record(question: BridgeQuestion): void;
+    /**
+     * Queue an answer picked in the dashboard (#1237). Refuses anything but labels of the question
+     * currently parked — exactly one unless the question is `multi` — so the only text this can
+     * ever put in a composer is composed from what the session itself offered.
+     */
+    queueAnswer(sessionId: string, labels: string[]): BridgeAnswer | string;
+    /** Withdraw a queued answer. Too late once a Driver has collected it or the extension has delivered it. */
+    cancelAnswer(sessionId: string, now?: number): boolean;
+    /** The answer waiting for the extension to deliver, if any — collected by a Driver or not. */
+    pendingAnswer(sessionId: string): BridgeAnswer | undefined;
+    /** Whether a Driver holds the answer: collected, and not so long ago that it is presumed lost. */
+    private claimed;
+    /**
+     * Hand the queued answer to the Driver asking, once (#1332): the next Driver asking within the
+     * claim's lifetime gets nothing, so a session served by two browsers is not answered twice. A
+     * claim nobody acknowledged — the Driver died mid-delivery — expires, and the answer is offered
+     * again.
+     */
+    claimAnswer(sessionId: string, now?: number): BridgeAnswer | undefined;
+    /**
+     * Every session with an answer waiting to be delivered. The Driver serves these whatever the
+     * session window says: the page reports whichever session the user is on, so a pick can be for
+     * a session no listed run carries, and one nothing serves would sit queued forever.
+     */
+    pendingAnswerSessions(): string[];
+    /** The session's answer in whatever state, for the dashboard to render. */
+    answer(sessionId: string): BridgeAnswer | undefined;
+    /**
+     * The extension's word on what happened to a delivery. On success the question is resolved:
+     * it is dropped, and re-reports of the same block are ignored (see {@link record}).
+     */
+    resolveAnswer(sessionId: string, id: string, ok: boolean, note?: string): void;
+    /** The question that session is parked on, if the bridge has reported one. */
+    get(sessionId: string): BridgeQuestion | undefined;
+    /** Every parked question, newest first. */
+    list(): BridgeQuestion[];
+    /** Drop a session's question, once it is answered or its agent is gone. */
+    clear(sessionId: string): void;
+}
+export declare function bridgeQuestions(): BridgeQuestions;
+/** Replace the store. Tests only: a module singleton would otherwise leak between them. */
+export declare function resetBridgeQuestions(): void;

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

@@ -0,0 +1,46 @@
+/**
+ * A read-through cache for the dashboard's slow reads (#1028).
+ *
+ * The dashboard polls. Every session view asks for its branch's PR, twice (the worktree bar and
+ * the handoff summary), on every navigation and again every ten seconds — and a git host read costs
+ * about 600ms against a local git read's ten. So the same answer was being bought over and over,
+ * and the panel waited for it each time.
+ *
+ * Three behaviours, and each one is load-bearing:
+ *   - **single flight** — concurrent asks for the same key share one call, so two panels and a
+ *     poll tick do not become three subprocesses
+ *   - **stale while revalidate** — once a value exists it is returned immediately, and refreshed
+ *     in the background when it is older than `ttlMs`; nobody waits twice for the same answer
+ *   - **a budget on the cold ask** — the first ask waits only `budgetMs` for the answer before
+ *     reporting `pending`, so a slow lookup delays one panel's extra detail rather than the page
+ *
+ * `pending` is not "failed": it means the answer is on its way and the next read will have it.
+ * A caller that must not act on a half-answer (offering to open a PR that may already exist)
+ * uses it to hold off.
+ */
+/** What a cached read answers with: the value, and whether it is still being fetched. */
+export interface Cached<T> {
+    value: T | undefined;
+    /** True when no value is known yet and a read is still running. */
+    pending: boolean;
+}
+/** Clock seam, so the tests do not sleep. */
+export type Now = () => number;
+export interface CacheOptions {
+    /** How old a value may be before a background refresh is started. */
+    ttlMs?: number;
+    /** How long a first, uncached ask waits before reporting `pending`. */
+    budgetMs?: number;
+    now?: Now;
+}
+/**
+ * Read `key` through the cache, calling `load` when it is missing or stale.
+ *
+ * A failed load is not cached: it leaves whatever was there (a panel keeps showing the last PR it
+ * knew about rather than dropping it because the git host hiccuped) and the next read tries again.
+ */
+export declare function cachedRead<T>(key: string, load: () => Promise<T>, options?: CacheOptions): Promise<Cached<T>>;
+/** Drop what is cached under `key`, so the next read is a fresh one. */
+export declare function invalidate(key: string): void;
+/** Test seam: forget everything. */
+export declare function clearCache(): void;

package/dist/module-types/src/dashboard/content-type.d.ts

@@ -0,0 +1,2 @@
+/** The content type for a file path (by its extension), or `application/octet-stream`. */
+export declare function contentTypeFor(path: string): string;

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

@@ -0,0 +1,37 @@
+import type { ProjectSummary } from './projects.js';
+import { type ProjectQueue } from './queue.js';
+import { type ActiveAgent, type OverviewDeps } from './overview.js';
+/** One project's rollup row. */
+export interface ProjectStat {
+    projectId: string;
+    /** Whether the repo has any ticket in `tickets/` (#958) — presence only, not a count. */
+    hasTickets: boolean;
+    /** Whether one of the project's packages provides tickets at all (#1774): without one, there is nothing to populate. */
+    providesTickets: boolean;
+}
+/** The dashboard page payload (#471). */
+export interface DashboardData {
+    totals: {
+        projects: number;
+        openTodos: number;
+    };
+    /** Agents going right now, most-recently-updated first (from {@link buildOverview}). */
+    active: ActiveAgent[];
+    /** Every registered project, most-recently-active first. */
+    projects: ProjectStat[];
+    /** The per-project agent queue (from {@link collectQueue}): the projects that have one, with their open entries. */
+    queue: ProjectQueue[];
+}
+/** Injectable readers so {@link buildDashboard} is unit-testable off disk. */
+export interface DashboardDeps extends OverviewDeps {
+    /** Whether a project has tickets (#958). Defaults to the provider's list being non-empty (false on any error). */
+    tickets?: (cwd: string) => Promise<boolean>;
+    /** Whether a project's packages provide tickets (#1774). Defaults to the provider lookup (false on any error). */
+    providesTickets?: (cwd: string) => Promise<boolean>;
+}
+/**
+ * Build the Overview dashboard: the {@link buildOverview} rollup (working now / queue) plus the
+ * per-project ticket presence the onboarding checklist reads. Forgiving — a project whose state
+ * cannot be read simply contributes nothing.
+ */
+export declare function buildDashboard(projects: ProjectSummary[], deps?: DashboardDeps): Promise<DashboardData>;

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

@@ -0,0 +1,38 @@
+/**
+ * The plan/backlog document categories the dashboard surfaces in its sidebar
+ * (#319, part of the MVP UI #309), so the human can read them beside the agent.
+ *
+ * These are written per session as `PLAN_<SESSION>.agent.md` (the plan for now) and
+ * `TODO_<SESSION>.agent.md` (the backlog), where SESSION is a git-branch slug — by
+ * OpenAgent's own system prompt back when it ran the agent (#323/#326), and by
+ * whatever a project's own skills tell an agent to write now. The flat fallback is `PLAN.md`
+ * at the root; the `TODO` category has no flat file: the agent queue is not a document of the
+ * checkout but a project package's data, and the dashboard shows it on that package's own page
+ * and the Overview's AI Queue card (#1774), not here. Scoped and flat-root names are matched
+ * against a flat readdir of the root, never taken from user input, so there is no path
+ * traversal to guard against.
+ */
+export declare const DOC_CATEGORIES: readonly [{
+    readonly flat: 'PLAN.md';
+    readonly scoped: RegExp;
+}, {
+    readonly scoped: RegExp;
+}];
+/** One surfaced document: its filename and current contents. */
+export interface WorkspaceDoc {
+    name: string;
+    content: string;
+}
+/**
+ * The workspace-root filenames to surface, in sidebar order: per category the flat
+ * file (if present) then its session-scoped files (sorted). Every name is a bare
+ * readdir entry matched against a fixed pattern, so none can traverse. Returns
+ * empty when the workspace is missing or unreadable.
+ */
+/**
+ * Read the surfaced plan/todo docs, in sidebar order: per category the flat file (if the
+ * category has one and it is present) then its session-scoped files (sorted), every one a
+ * workspace-root file. Missing or blank files are skipped; a file over the size cap is
+ * truncated. Never throws — a read error just omits that doc.
+ */
+export declare function readDocs(cwd: string): Promise<WorkspaceDoc[]>;

package/dist/module-types/src/dashboard/git-status.d.ts

@@ -0,0 +1,43 @@
+import { type GitRunner } from '@openagt/agent-data';
+import { type LinkedPr, type PrLookup } from './pull-requests.js';
+/** A project's git status for the panel. */
+export interface GitStatus {
+    branch: string;
+    /** Uncommitted changes present. */
+    dirty: boolean;
+    pr?: LinkedPr;
+    /** The PR is not known yet, rather than absent (#1028): the lookup is still running. */
+    prPending?: boolean;
+}
+/** Injectable seams so {@link readGitStatus} is unit-testable off disk. */
+export interface GitStatusDeps {
+    git?: GitRunner;
+    pr?: PrLookup;
+    /**
+     * The agent's start, when the status is read for an agent's checkout (#1255). The default lookup
+     * answers the newest PR for the branch *in any state* — so an agent on a reused pinned branch
+     * (`openagent/triage-quick`) wears a predecessor's merged PR as its own badge.
+     * With `since` set the PR is picked from the branch's whole history by {@link pickAgentPr}
+     * instead: an open PR, or a closed one no older than the agent itself.
+     */
+    since?: string;
+    /** The branch's full PR history, for the {@link GitStatusDeps.since} path (default {@link cachedPrsForBranch}). */
+    prs?: (cwd: string, branch: string) => Promise<LinkedPr[]>;
+    /**
+     * The project's folder, for a status read in a run's checkout: the branch's PR history is looked
+     * up and cached by it, as the run's handoff reads it, so the lookup the bar made while the run
+     * worked is warm once the run ends and its Open PR is asked about.
+     */
+    prRoot?: string;
+}
+/**
+ * The branch `cwd` has checked out, by its short name; `HEAD` when it is on no branch. Undefined
+ * when `cwd` is not a git repo, or git failed.
+ */
+export declare function currentBranch(cwd: string, git?: GitRunner): Promise<string | undefined>;
+/**
+ * Read a project's git status: the current branch and dirty flag (from git), plus the linked
+ * PR (best-effort). Returns undefined when the path is not a git repo. Forgiving — a failed
+ * `git status` reads as clean, and a failed PR lookup simply omits the PR.
+ */
+export declare function readGitStatus(cwd: string, deps?: GitStatusDeps): Promise<GitStatus | undefined>;

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

@@ -0,0 +1,28 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * The plumbing every one of the daemon's non-RPC HTTP surfaces shares: the browser bridge
+ * (`/_bridge`), the web-start queue (`/_web-start`) and the device relay (`/_relay`).
+ *
+ * All three answer plain-text statuses, JSON payloads, and read capped JSON request bodies, and
+ * each carried its own copy — two body readers that differed only in which message they rejected
+ * with, and three identical status responders.
+ */
+/** Answer with a plain-text status line. */
+export declare function end(res: ServerResponse, status: number, message: string, headers?: Record<string, string>): void;
+/** Answer with a JSON payload. */
+export declare function sendJson(res: ServerResponse, payload: unknown, status?: number): void;
+/**
+ * Read a JSON body, refusing anything past the cap rather than buffering it. Rejects with
+ * `body too large` on overflow and `body must be JSON` on anything unparseable — the messages the
+ * bridge and web-start routes answer 400 with, so a caller learns which of the two it hit.
+ */
+export declare function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<unknown>;
+/**
+ * The preamble every POST route runs: refuse a non-POST, then read the body. Answers the request
+ * itself on either failure and resolves `undefined`, so a caller's whole check is
+ * `const body = await readPost(...); if (body === undefined) return`. JSON has no `undefined`, so
+ * the sentinel cannot collide with a body that parsed.
+ */
+export declare function readPost(req: IncomingMessage, res: ServerResponse, maxBytes: number): Promise<unknown>;
+/** Refuse anything but a GET, answering 405 itself. `false` means the request is already answered. */
+export declare function requireGet(req: IncomingMessage, res: ServerResponse): boolean;

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

@@ -0,0 +1,66 @@
+import { type LiveAgent, type AgentMeta } from '../store/index.js';
+import type { OpenAgentEvent } from '../events.js';
+import type { ProjectSummary, ProjectionRead } from './projects.js';
+import { type BranchesFor } from '../store/branches.js';
+import { type PrLister } from './pull-requests.js';
+export { interventionKey } from './keys.js';
+/**
+ * One item awaiting the human. Two kinds: an open `pr` to review/merge or close, and an
+ * `awaiting` run paused on a choice gate. The card and the browser hook both iterate the flat
+ * list, branching on `kind` for the fields that differ.
+ */
+export interface Intervention {
+    projectId: string;
+    projectName: string;
+    /**
+     * `pr` = an open PR to review/merge or close; `awaiting` = a run waiting on the question it ended on (#636/#1774);
+     * `unpushed` = a finished agent whose branch has commits that were never pushed (#860).
+     */
+    kind: 'pr' | 'awaiting' | 'unpushed';
+    title: string;
+    /** The PR on the git host (`pr` only): where a click takes the user. */
+    url?: string;
+    /** The PR number (`pr` only). */
+    number?: number;
+    /** The question's id (`awaiting` only) — its stable identity, so it notifies exactly once. */
+    awaitId?: string;
+    /** Which run this is about (`awaiting` #738 / `unpushed`): a project has several agents. */
+    agentId?: string;
+    /** The branch the work is sitting on (`unpushed` only). */
+    branch?: string;
+    /** How many commits are waiting (`unpushed` only). */
+    commits?: number;
+    /** When the PR was opened (`pr`) or the agent last updated (the other two), ISO, for ordering. */
+    createdAt?: string;
+}
+/** Injectable seam so {@link buildInterventions} is unit-testable off disk. */
+export interface InterventionsDeps {
+    prs?: PrLister;
+    /** The reader of the runs that have a checkout (default {@link readLiveMetas}): a waiting run keeps its own; drives the `awaiting` source (#636). */
+    liveAgents?: (cwd: string) => Promise<LiveAgent[]>;
+    /** One run's events, by the project's path and the run's id (default {@link loadAgentEvents}): where a waiting run's question is read. */
+    events?: (cwd: string, agentId: string) => Promise<OpenAgentEvent[] | undefined>;
+    /** The finished-agent reader (default {@link listAgents}); drives the `unpushed` source (#860). */
+    agents?: (cwd: string) => Promise<AgentMeta[]>;
+    /** The project's checkouts and branches (default the project's provider, {@link projectBranches}): where a branch's state is read; drives the `unpushed` source (#860). */
+    branches?: BranchesFor;
+    /**
+     * How many of a project's most recent finished agents to inspect for unpushed work. Each one costs
+     * a handful of git reads, and this runs on a poll, so old history is not re-walked every minute:
+     * work that has sat unpushed for dozens of agents is not news, and the agent list stays the record.
+     */
+    handoffLimit?: number;
+}
+/**
+ * Build the cross-project interventions queue: every registered project's open PRs, plus any run
+ * currently paused on a choice gate (#636), newest first. Forgiving — a project with no remote
+ * (or an unreadable one) simply contributes nothing. Hand-opened draft PRs are excluded: they are
+ * not yet asking for review. A draft on an agent's branch is not (#1102): an agent publishes a
+ * draft when a person should look first, and cloud work adoption opens its PRs as drafts.
+ *
+ * Which projects were read whole comes back alongside the items (#1623): forgiveness here is what
+ * lets one unreachable project keep the queue useful, and it is also what would let that project's
+ * whole backlog announce itself as new the moment it came back. The queue's panels ignore this;
+ * the notification watcher is the caller that cannot.
+ */
+export declare function buildInterventions(projects: ProjectSummary[], deps?: InterventionsDeps): Promise<ProjectionRead<Intervention>>;

package/dist/module-types/src/dashboard/keyed-watcher.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tracks which items have been announced, so only new ones notify. Identity is the caller's
+ * (`keyOf`), since what makes two items "the same" is a property of what is being watched.
+ * Testable without timers.
+ *
+ * The baseline is kept per project (`scopeOf`), not once for the whole poll (#1623). A poll that
+ * reached three projects out of four knows what already existed on those three and knows nothing
+ * about the fourth, and announcing is a per-project decision anyway. Held globally, one project
+ * that can never be read — a registered repo with no remote is an ordinary case — would either
+ * silence every project's notifications or hand the whole set a baseline it had not earned.
+ */
+export declare class SeenTracker<T> {
+    private readonly keyOf;
+    private readonly scopeOf;
+    private readonly seen;
+    private readonly warmedUp;
+    constructor(keyOf: (item: T) => string, scopeOf: (item: T) => string);
+    /**
+     * Fold a poll's items into the baseline and return the ones worth announcing: the items not seen
+     * before, from projects this watcher has a real baseline for. `whole` names the projects the poll
+     * read completely, and only those earn a baseline — so whatever already existed at start-up is
+     * never announced, and a project that could not be read stays quiet until it can be.
+     *
+     * Items keep being folded in either way: a partial read can only under-report, never invent, so
+     * anything it did see is still something the user should not later hear about as new.
+     */
+    observe(items: T[], whole: Iterable<string>): T[];
+}

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

@@ -0,0 +1,30 @@
+import type { Activity } from './activity.js';
+import type { Intervention } from './interventions.js';
+/**
+ * The stable identity of a watched item, which the browser notifications dedupe on.
+ *
+ * A leaf module on purpose: `activity.ts` and `interventions.ts` build their items by reading the
+ * store, so they import `node:*` and cannot be reached from the browser bundle. These functions
+ * are pure and depend on nothing but the item, so they live here and are re-exported from
+ * `client.ts` — which is what lets the dashboard share them instead of keeping a copy that could
+ * drift from the item types.
+ *
+ * The type imports are erased at compile time, so they add no edge to the graph `client.test.ts`
+ * walks.
+ */
+/**
+ * The stable identity of an intervention. A PR is its url (survives title edits and re-sorts);
+ * the other two have no url and are keyed on the project plus the thing waiting — the agent and
+ * the gate it is parked on, or the agent whose branch is unpushed.
+ *
+ * The agent is part of the awaiting key because a gate id is only unique within its own agent:
+ * every agent's first gate is `await-choices`. Two agents running in one project (#736) and both
+ * parked would otherwise share one identity, and the dedupe would announce only one of them.
+ */
+export declare function interventionKey(item: Intervention): string;
+/**
+ * The stable identity of an activity item: its kind + project + run. The kind is part of the key
+ * so an agent's `started` and `finished` are two separate announcements (one when it kicks off, one
+ * when it lands), each firing exactly once.
+ */
+export declare function activityKey(item: Activity): string;

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

@@ -0,0 +1,24 @@
+import type { Driver, DriverModel } from '@openagt/agent-driver';
+import { type DriverName } from '../driver-names.js';
+/** What one coding agent offers: its models, or why it could not say. */
+export type DriverModels = {
+    models: DriverModel[];
+} | {
+    models: [];
+    error: string;
+};
+/** The models of every coding agent a person can pick, by driver. */
+export type ModelsView = Record<DriverName, DriverModels>;
+/** Where the dashboard reads which models each coding agent offers. */
+export interface ModelsSource {
+    read(): Promise<ModelsView>;
+}
+/**
+ * Ask each coding agent for its models, once: the first read asks, every later read answers from
+ * what it said, for the daemon's life. The list changes only with a new CLI version or a new
+ * login, and each question starts a CLI, so a menu opened again never waits on one. An agent that
+ * could not say is asked again at the next read, so a CLI installed or logged in since is found.
+ */
+export declare function cachedModelsSource(drivers: Record<DriverName, Pick<Driver, 'listModels'>>): ModelsSource;
+/** The daemon's own source: the coding agents on this machine, asked as the person's own login. */
+export declare function defaultModelsSource(): ModelsSource;

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

@@ -0,0 +1,43 @@
+import { type BranchesFor } from '../store/index.js';
+import { type LinkedPr } from './pull-requests.js';
+import type { Cached } from './cache.js';
+import type { ModuleServerHost } from '../module-server.js';
+/** What {@link serverHost} reads through; each defaults to the production reader. */
+export interface ServerHostDeps {
+    branches?: BranchesFor;
+    agent?: (root: string, agentId: string) => Promise<{
+        id: string;
+        status?: string;
+        host?: string;
+        branch?: string;
+        pr?: {
+            number: number;
+        };
+        base?: string;
+        baseCommit?: string;
+        landed?: string;
+    } | undefined>;
+    /** This machine's name, against a run's `host`. */
+    host?: string;
+    prs?: (root: string, branch: string) => Promise<Cached<LinkedPr[]>>;
+}
+/** The host a read of the project at `root` is given. */
+export declare function serverHost(root: string, deps?: ServerHostDeps): ModuleServerHost;
+/** How large the input of one read may be, as JSON: what a page asks with, never a payload. */
+export declare const MAX_READ_INPUT: number;
+/** How long one read may take before it answers an error instead. */
+export declare const READ_TIMEOUT_MS = 20000;
+/** What a read answered: its JSON, or why there is none. */
+export type ModuleReadResult = {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Call read `name` of the server part at `file` with `host` and `input`. Refused: a part that did
+ * not load, a read it does not have, an input that is not an object or is too large. A read that
+ * throws or runs past {@link READ_TIMEOUT_MS} answers an error; nothing a read does stops the daemon.
+ */
+export declare function callModuleRead(file: string, name: string, host: ModuleServerHost, input: unknown, timeoutMs?: number): Promise<ModuleReadResult>;

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

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ProjectsProvider } from './projects.js';
+import { type ProjectModule } from '../project-modules.js';
+/** Where module files are served: `/_modules/<project id>/<package>/<file>`, each segment encoded. */
+export declare const MODULES_PREFIX = "/_modules";
+/** The URL a module's browser part is served at from one project. */
+export declare function moduleUrl(projectId: string, module: Pick<ProjectModule, 'package' | 'entry'>): string;
+/**
+ * Serve one module file (#1774): the project must be registered, the package must be a module of
+ * that project, and the file must sit inside the module's browser part's own directory. Anything else is a
+ * 404, never a fallback: a module URL is asked for by the dashboard's loader, not typed by a person.
+ * Served as `no-cache`, since a module is rebuilt in place under the same name.
+ */
+export declare function serveModuleFile(req: IncomingMessage, res: ServerResponse, pathname: string, projects?: ProjectsProvider): Promise<void>;

package/dist/module-types/src/dashboard/open-in-app.d.ts

@@ -0,0 +1,42 @@
+/** Which app to open the project in. */
+export type OpenTarget = 'files' | 'editor';
+/** A known editor: its launcher CLI plus a human label for the picker (#727). */
+export interface EditorInfo {
+    bin: string;
+    label: string;
+}
+/**
+ * The editors the picker can offer (#727), probed by their CLI launcher on PATH. Order is the
+ * display order. `$OPENAGENT_EDITOR` and a hand-typed value stay valid beyond this list; this is
+ * only what auto-detection looks for.
+ */
+export declare const KNOWN_EDITORS: EditorInfo[];
+/** Whether an editor launcher is installed (on PATH). A seam so detection is unit-testable. */
+export type EditorProbe = (bin: string) => Promise<boolean>;
+/** The installed subset of {@link KNOWN_EDITORS}, in display order (#727). */
+export declare function detectEditors(probe?: EditorProbe): Promise<EditorInfo[]>;
+/** The outcome of an open attempt. */
+export type OpenResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Spawns a command, resolving once it launches (not on exit) and rejecting if it can't start. */
+export type SpawnRunner = (command: string, args: string[]) => Promise<void>;
+/** The OS command that reveals a path in the file manager. */
+export declare function fileManagerCommand(path: string, os?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/** The command to open a path in an editor: `$OPENAGENT_EDITOR` when set, else the VS Code CLI. */
+export declare function editorCommand(path: string, editor?: string | undefined): {
+    command: string;
+    args: string[];
+};
+/**
+ * Open the project at `cwd` in the file manager or an editor. Failures are values, never throws.
+ * `editor` (#727) is the stored preference; when unset {@link editorCommand} falls back to
+ * `$OPENAGENT_EDITOR`, then `code`.
+ */
+export declare function openInApp(cwd: string, target: OpenTarget, agent?: SpawnRunner, editor?: string): Promise<OpenResult>;