@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/widget-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/widget-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/widget-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;

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

@@ -0,0 +1,16 @@
+/** Discord rejects a message over 2000 characters outright, so a long reply is trimmed. */
+export declare const MAX_CONTENT = 2000;
+/**
+ * The one Discord *webhook* transport (#627): a single POST of one message. The two
+ * notification posters (activity, interventions) each carried their own copy of this fetch;
+ * their line formatters rightly stay beside the types they switch on, but the transport is
+ * not per-feed. Deliberately not in discord/rest.ts — that module is the bot-token API
+ * (channels, replies), and a webhook needs no token and reaches one fixed channel — though
+ * it shares that module's clamp: Discord rejects a message over 2000 chars outright, so an
+ * unclamped "needs you" batch would silently post nothing (#940).
+ *
+ * Resolves whether Discord accepted the post. A failed delivery must never throw out of a
+ * daemon watcher, so a non-ok response and a network error both resolve `false` for the
+ * caller to log.
+ */
+export declare function postDiscordWebhook(webhook: string, content: string, fetchImpl?: typeof fetch): Promise<boolean>;

package/dist/widget-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
+ * The Framework'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[]>;