@openagt/dashboard 0.8.0 → 0.10.0

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

@@ -1,178 +0,0 @@
-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

@@ -1,46 +0,0 @@
-/**
- * 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

@@ -1,2 +0,0 @@
-/** 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

@@ -1,37 +0,0 @@
-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

@@ -1,16 +0,0 @@
-/** 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

@@ -1,38 +0,0 @@
-/**
- * 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[]>;

package/dist/widget-types/src/dashboard/file-diff.d.ts

@@ -1,66 +0,0 @@
-import { type GitRunner } from '@gemstack/agent-data';
-import type { FileGitStatus } from './file-status.js';
-import { safeRepoPath } from './file-read.js';
-export { safeRepoPath };
-/** One file's diff, capped so a hover card can render it. */
-export interface FileDiff {
-    /** The repo-relative path asked for. */
-    path: string;
-    status: FileGitStatus;
-    /** Unified diff body, hunks only (git's `diff --git` / index preamble is dropped). */
-    patch: string;
-    added: number;
-    removed: number;
-    /** The patch hit the preview cap and was cut. */
-    truncated: boolean;
-    /** Nothing textual to show (git reports a binary change, or the file is not UTF-8 text). */
-    binary: boolean;
-}
-/** One changed file in a session's Changes list (#817): what moved, and by how much. */
-export interface FileChange {
-    path: string;
-    status: FileGitStatus;
-    added: number;
-    removed: number;
-    /** Line counts are unavailable (a binary file, or an untracked one too large to count). */
-    binary: boolean;
-}
-/**
- * The diff for one changed file in the checkout at `cwd`, or, given a `range`, between two
- * commits of the repository at `cwd` (a run's committed change, `agent-tree.ts`).
- *
- * Tracked files diff against `HEAD`, not the index, so a change the agent staged still shows;
- * that also matches `git status --porcelain`, which is what dotted the file in the first place.
- * An untracked file is rendered as all-added from its contents, since `git diff --no-index`
- * exits non-zero on a difference and would read as a failure here.
- *
- * Returns null when the path is unsafe, unreadable, or has no diff to show.
- */
-export declare function readFileDiff(cwd: string, path: string, status: FileGitStatus, git?: GitRunner, range?: {
-    from: string;
-    to: string;
-}): Promise<FileDiff | null>;
-/** One `git diff --numstat` line, parsed. */
-export interface NumstatEntry {
-    path: string;
-    added: number;
-    removed: number;
-    binary: boolean;
-}
-/**
- * Parse `git diff --numstat` output: `added<TAB>removed<TAB>path`, with `-` for both counts
- * on a binary file. The one parser for the grammar — it was written here and in run-handoff,
- * and the copies had already drifted on a path containing a tab (this side rejoined it, the
- * other dropped the line).
- */
-export declare function parseNumstat(out: string): NumstatEntry[];
-/**
- * Every changed file in the checkout at `cwd`, with its line counts: the session's Changes list
- * (#817). One `git status` plus one `git diff --numstat`, not a diff per file, so a session that
- * touched forty files still costs two git calls.
- *
- * Untracked files have no numstat entry (they are not in the diff at all), so their added count
- * is their line count, read from disk. Sorted by path, so the list does not reshuffle as a live
- * session edits.
- */
-export declare function readFileChanges(cwd: string, statuses: Record<string, FileGitStatus>, git?: GitRunner): Promise<FileChange[]>;

package/dist/widget-types/src/dashboard/file-read.d.ts

@@ -1,41 +0,0 @@
-/** Cap what a hover card renders, whether it is a patch or a file. */
-export declare const MAX_PREVIEW_LINES = 500;
-/** One unchanged file's contents for the tree's hover card (#828). */
-export interface FileContent {
-    /** The repo-relative path asked for. */
-    path: string;
-    /** The file's text, cut at {@link MAX_PREVIEW_LINES}. Empty when binary. */
-    text: string;
-    /** The file was longer than the cap and was cut. */
-    truncated: boolean;
-    /** Not UTF-8 text, so there is nothing to render. */
-    binary: boolean;
-}
-/**
- * Whether a client-supplied path may be read: repo-relative, no traversal, no absolute path, no
- * leading `-` (git would read it as a flag), and never into `.git` (config and credentials live
- * there). Rejecting is the whole contract; the caller resolves it against a checkout it chose.
- */
-export declare function safeRepoPath(path: string): boolean;
-/**
- * Read a repo-relative file from `cwd`, or null when it is unsafe, outside the checkout, or
- * unreadable.
- *
- * The confinement check is a `realpath` on both sides, not a string compare on the resolved path.
- * `resolve` does not follow symlinks, so `src/link.txt -> /etc/passwd` resolves to a path that sits
- * happily under `cwd` and passes a textual check while the read leaves the repo. `realpath` is what
- * makes the containment real; it also normalizes the platform's own links (macOS `/tmp`), which is
- * why `cwd` goes through it too rather than being compared raw.
- */
-export declare function readConfinedFile(cwd: string, path: string): Promise<Buffer | null>;
-/** Cut a body to {@link MAX_PREVIEW_LINES}, reporting whether anything was dropped. */
-export declare function cutToPreview(body: string): {
-    body: string;
-    truncated: boolean;
-};
-/**
- * One unchanged file's contents (#828). Null when the path is unsafe, outside the checkout, or
- * unreadable. A file git has not touched still reads from the resolved checkout, so a session's
- * hover shows its worktree's copy rather than the project root's (#815).
- */
-export declare function readFileContent(cwd: string, path: string): Promise<FileContent | null>;

package/dist/widget-types/src/dashboard/file-status.d.ts

@@ -1,20 +0,0 @@
-import { type GitRunner } from '@gemstack/agent-data';
-/**
- * The tree's per-file git state. `added` is a file a commit created (a run's committed change,
- * `agent-tree.ts`); the working tree's status here never says it, a new file there is `untracked`.
- */
-export type FileGitStatus = 'untracked' | 'added' | 'modified' | 'deleted';
-/** One `git status --porcelain` line: the two status columns and the path they are about. */
-export interface PorcelainEntry {
-    code: string;
-    /** Repo-relative; a rename resolves to the new path. */
-    path: string;
-}
-/** Parse `git status --porcelain` output. Shared with the handoff's pending-files read (#1173). */
-export declare function parsePorcelain(out: string): PorcelainEntry[];
-/**
- * Read each changed file's status from `git status --porcelain`, keyed by repo-relative path.
- * `??` is untracked, a `D` in either column is deleted, anything else (M/A/R/C…) reads as
- * modified. Renames map to the new path. Returns `{}` when the path is not a git repo.
- */
-export declare function readFileStatuses(cwd: string, git?: GitRunner): Promise<Record<string, FileGitStatus>>;

package/dist/widget-types/src/dashboard/gh.d.ts

@@ -1,130 +0,0 @@
-import { type CliRunner } from '../cli-exec.js';
-import { type Cached } from './cache.js';
-/**
- * The `gh` CLI, in one place: the JSON reads the dashboard makes of pull requests. Reads only:
- * pushing, opening and merging are the project's branches provider's (`../store/branches.ts`).
- *
- * There were four separate `gh` adapters across three modules. Three were reads that each
- * hand-rolled `execFile` + `JSON.parse` + a swallowed failure and each spelled the 8s timeout
- * again, and two of those differed only in whether a branch positional was passed.
- */
-/** Runs `gh`, resolving stdout and rejecting with the CLI's own stderr on failure. */
-export type GhRunner = CliRunner;
-/** A forgiving `gh --json` read: resolves `empty` when gh is missing/unauthed, or its output is not JSON. */
-export declare function ghJson<T>(args: string[], cwd: string, empty: T, gh?: GhRunner): Promise<T>;
-/** The PR opened for a branch, when there is one. */
-export interface LinkedPr {
-    number: number;
-    url: string;
-    /** OPEN / MERGED / CLOSED (as gh reports it). */
-    state: string;
-    title: string;
-    /** ISO creation time, when the read included it: what tells one agent's PR from a predecessor's. */
-    createdAt?: string;
-    /**
-     * The head commit the PR covers, when the read included it (#1512): what tells "the branch's
-     * PR already landed everything" from "the session kept working after its PR merged".
-     */
-    headRefOid?: string;
-}
-/**
- * A best-effort PR lookup, for a named branch or for the checkout's current branch. One type for
- * both: the named-branch form is the general one, and "the current branch" is just omitting it.
- */
-export type PrLookup = (cwd: string, branch?: string) => Promise<LinkedPr | undefined>;
-/**
- * The branch-addressed form, for a caller that always names one (#799): a finished session's
- * worktree may be gone, so "the current branch" would silently be the project's, not the
- * session's. Narrower than {@link PrLookup} on purpose, so that invariant is in the type.
- */
-export type BranchPrLookup = (cwd: string, branch: string) => Promise<LinkedPr | undefined>;
-/**
- * The PR for `branch`, or for whatever branch `cwd` is on when none is named. Resolves undefined
- * when gh is missing/unauthed or there is no PR.
- *
- * The named-branch form is what a finished session needs (#799): its worktree may be gone, so the
- * checkout's current branch is the project's, not the session's. The fields are copied out rather
- * than passed through, so a future `--json` addition cannot leak into what callers store.
- *
- * Every optional field {@link LinkedPr} declares must be both asked for and copied out here, or it
- * is silently absent for every caller of this path. `createdAt` was once neither, and it is what
- * tells an agent's own PR from a predecessor's on the same branch name ({@link pickAgentPr}).
- */
-export declare function ghPrView(cwd: string, branch?: string, gh?: GhRunner): Promise<LinkedPr | undefined>;
-/**
- * The cached form of {@link ghPrView} (#1028), and what the dashboard's panels use.
- *
- * A PR lookup costs about 600ms where the git reads beside it cost ten, and the answer changes
- * about as often as someone opens a PR. Cached per checkout and branch, shared between the
- * worktree bar and the handoff summary, and refreshed behind whoever asks. `pending` says the
- * answer is not known yet rather than that there is no PR — the difference matters to a caller
- * deciding whether to offer "Open PR".
- */
-export declare function cachedPrView(cwd: string, branch?: string): Promise<Cached<LinkedPr | undefined>>;
-/** Forget a branch's PR, after an action that changes whether it has one. */
-export declare function forgetPr(cwd: string, branch?: string): void;
-/**
- * Every PR a branch name has ever had, newest first (#1251).
- *
- * `gh pr view <branch>` answers with the newest PR for that head *in any state*, so a session
- * whose prompt pins its branch name (`the-framework/triage-quick`) inherits a predecessor's
- * merged PR as its own. The list form keeps the whole history so {@link pickAgentPr} can decide
- * which entry, if any, belongs to the agent asking. Resolves `[]` when gh is missing/unauthed —
- * indistinguishable from "no PRs", which is what every caller would do with a failure anyway.
- */
-export declare function ghPrsForBranch(cwd: string, branch: string): Promise<LinkedPr[]>;
-/**
- * {@link ghPrsForBranch} for a caller about to *open* a PR (#1601): a listing that fails throws
- * instead of reading as "no PRs", because "none" and "could not tell" must not look alike there —
- * the difference is a second draft PR on a branch that already has one.
- */
-export declare function ghPrsForBranchOrThrow(cwd: string, branch: string): Promise<LinkedPr[]>;
-/** The cached form of {@link ghPrsForBranch}, shared through the same read-through cache (#1028). */
-export declare function cachedPrsForBranch(cwd: string, branch: string): Promise<Cached<LinkedPr[]>>;
-/** Forget a branch's PR history, after an action that changes it (opening one). */
-export declare function forgetBranchPrs(cwd: string, branch: string): void;
-/**
- * The PR that belongs to an agent, out of every PR its branch name has had (#1251/#1255).
- *
- * An OPEN PR always counts: GitHub allows one open PR per head branch, so whatever is open on the
- * run's branch is where its pushed commits land. A closed one counts only when it was created
- * after the agent started (`since`, the agent's `startedAt`) — the oldest such entry, which is the one
- * this agent's handoff opened. Anything older is a previous agent's PR wearing the same branch name,
- * which is exactly what showed a merged two-day-old PR as a fresh session's own. Without `since`
- * only an open PR is trusted.
- *
- * `order` exists for the one caller asking a different question (#1512). `'first'` answers
- * identity — which PR did *this agent* open, so a later agent's must not be the answer. `'latest'`
- * answers the handoff decision — which PR last saw the branch, so "did the session keep working
- * past it" is readable off that PR's `headRefOid`; there the oldest entry would call work that a
- * second PR already landed unlanded.
- */
-export declare function pickAgentPr(prs: LinkedPr[], since?: string, order?: 'first' | 'latest'): LinkedPr | undefined;
-/** An open PR on the interventions queue (#632). */
-export interface OpenPr {
-    number: number;
-    title: string;
-    url: string;
-    /**
-     * Draft PRs are generally left off the queue: a draft is not asking for review.
-     *
-     * The exception is a draft the framework opened for itself (#1102), which {@link headRefName}
-     * is what tells apart.
-     */
-    isDraft: boolean;
-    /** The branch the PR is from, so a session's own PR can be recognised as ours (#1102). */
-    headRefName?: string;
-    createdAt?: string;
-}
-/**
- * A checkout's open PRs. Unlike the other reads here it *rejects* when gh could not answer — no
- * remote, not authenticated, GitHub unreachable — instead of resolving `[]`.
- *
- * "No PRs are open" and "I could not look" are different answers, and its caller keeps a baseline
- * of what it has already announced (#1623): taking the second for the first makes the next
- * successful read announce every already-open PR as new. The caller decides what a failure costs;
- * it cannot decide what it never hears about.
- */
-export declare function ghPrList(cwd: string, gh?: GhRunner): Promise<OpenPr[]>;
-/** Lists a checkout's open PRs; rejects when there is no remote / gh is unavailable. */
-export type PrLister = (cwd: string) => Promise<OpenPr[]>;

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

@@ -1,32 +0,0 @@
-import { type GitRunner } from '@gemstack/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
-     * (`the-framework/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[]>;
-}
-/**
- * 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/widget-types/src/dashboard/github.d.ts

@@ -1,10 +0,0 @@
-import { type GitRunner } from '@gemstack/agent-data';
-/**
- * Normalize a git remote URL to an `https://github.com/<owner>/<repo>` URL, or undefined when
- * it is not a GitHub remote. Handles the scp-style (`git@github.com:o/r.git`), ssh
- * (`ssh://git@github.com/o/r.git`), and https (`https://github.com/o/r.git`) forms, dropping
- * a `.git` suffix, an embedded credential, and a trailing slash.
- */
-export declare function githubUrlFromRemote(remote: string): string | undefined;
-/** The repo's GitHub URL from its `origin` remote, or undefined (no remote / not GitHub). */
-export declare function githubUrlFor(cwd: string, git?: GitRunner): Promise<string | undefined>;