@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/module-types/src/store/agent-checkout.d.ts

@@ -0,0 +1,53 @@
+import { type BranchesFor, type Checkout } from './branches.js';
+import { type AnyDiaryLine, type RunsFor } from './runs.js';
+/**
+ * A run's checkout, as the project's branches provider lists it, or `undefined` when it lists
+ * none for the id. The provider's list is shared for a few seconds; a run that is not in it may
+ * have started a moment ago, so a miss asks once more, fresh (`branches.ts` bounds how fresh).
+ */
+export declare function findCheckout(projectCwd: string, agentId: string, branches: BranchesFor, opts?: {
+    cached?: boolean;
+}): Promise<Checkout | undefined>;
+/**
+ * The checkout an agent id resolves to (#738/#797): the agent's own checkout while the project's
+ * branches provider lists one for it, else the project root. The list is asked fresh on a miss:
+ * a run that just started has its checkout before its tool has written the card (#766), and the
+ * event stream resolves its path once, when the browser opens it.
+ *
+ * An unknown or finished `agentId` falls back to the project root rather than failing: the
+ * run's checkout may already be gone, and the project's own state is still the sane thing to
+ * act on. This is the one resolution every run-addressed surface shares — the daemon's serve
+ * targets and previews, and each dashboard RPC — so the fallback rules cannot drift apart.
+ */
+export declare function resolveAgentCheckout(projectCwd: string, agentId: string | undefined, branches?: BranchesFor): Promise<string>;
+/**
+ * Where a run's diary is, for a reader that follows it: a file while the run has a checkout, the
+ * finished run's lines once it has none, or nowhere yet (`pending`): the run was started a moment
+ * ago and its tool has not made the checkout, so the reader asks again shortly.
+ */
+export type AgentDiarySource = {
+    file: string;
+} | {
+    finished: AnyDiaryLine[];
+} | {
+    pending: true;
+};
+/**
+ * The diary a run-scoped subscribe should follow (#1472, #1774): the run's own `<id>.jsonl`.
+ * While the run has a checkout it is a file there, under the checkout's `.the-framework/`,
+ * written by the run's tool as the agent works. Once the run is recorded and its checkout
+ * reclaimed, it is the finished run's diary, whole, from the project's runs provider. A run that
+ * has neither yet was started a moment ago: its tool has not made the checkout, so the diary is
+ * nowhere yet, and the tail asks again (`../dashboard-rpc/events-tail.ts`). A project with no
+ * runs provider answers the same for a finished run: nowhere, where nothing more comes.
+ *
+ * `cached` answers from the shared lists only, never asking the checkouts fresh on a miss: for a
+ * reader that asks about a finished run for as long as it is open, in case it is resumed.
+ *
+ * Only the events tails resolve here; every other run-addressed surface keeps
+ * {@link resolveAgentCheckout}'s root fallback, where the project's own state is the sane
+ * thing to act on.
+ */
+export declare function resolveAgentDiary(projectCwd: string, agentId: string | undefined, runs?: RunsFor, branches?: BranchesFor, opts?: {
+    cached?: boolean;
+}): Promise<AgentDiarySource | undefined>;

package/dist/module-types/src/store/agent-store.d.ts

@@ -0,0 +1,266 @@
+import type { FrameworkEvent } from '../events.js';
+import { type BranchesFor, type Checkout } from './branches.js';
+import { type AnyDiaryLine, type RunsFor } from './runs.js';
+/**
+ * The read side of a project's runs (#1774). The daemon runs no agent and writes no run: a run's
+ * tool keeps the run's card (`<id>.json`) and diary (`<id>.jsonl`) under the `.the-framework/`
+ * of the run's own checkout while it works, and a finished run is whatever the project's runs
+ * provider answers (`runs.ts`), when one of its packages provides them. The dashboard is a
+ * projection of those files and that answer.
+ */
+export type AgentStatus = 'running' | 'done' | 'stopped' | 'failed' | 'waiting';
+/**
+ * A queryable snapshot of the agent, derived entirely from the event log. Lets the
+ * dashboard render a header (and a future agent list) without parsing every line.
+ */
+export interface AgentMeta {
+    status: AgentStatus;
+    /** Stable, path-safe id for this agent (derived from {@link startedAt}). */
+    id: string;
+    /** ISO timestamp the store was opened (run start). */
+    startedAt: string;
+    /** ISO timestamp of the last event written. */
+    updatedAt: string;
+    /** ISO timestamp the run ended (the `end` event), absent while it is going. The skill's card field. */
+    endedAt?: string;
+    /** What the run cost so far in US dollars, summed over its `usage` events; absent until one says. The skill's card field. */
+    cost?: number;
+    /**
+     * The OS pid of the process running this run, on {@link host} — whatever process the project's
+     * start hook began. Recorded on the card so Stop has something to signal, and so a reader can
+     * tell a run that is working from one whose process died without recording an ending (#716).
+     */
+    pid?: number;
+    /** The host the owning {@link pid} lives on, so a pid probe only trusts a match (#716). */
+    host?: string;
+    /** What this session was asked for (from the `intent` event). */
+    intent?: string;
+    /**
+     * The run this one was started for, by its id: this run is that run's subagent. Written on the
+     * card by the tool that started it; absent on a run a person or a schedule started.
+     */
+    parent?: string;
+    /**
+     * The branch the run was told to start from, by its name: a person's local branch picked in the
+     * launcher, or, for a subagent, its main agent's branch. Written on the card by the tool that
+     * started it; absent on a run that started from origin's default branch.
+     */
+    base?: string;
+    /**
+     * The commit the run's own work begins at: where its branch was made, for a run started from a
+     * branch other than the default one (a subagent starts from its main agent's). Its changes are
+     * measured from it; absent, from the default branch. Written on the card by the tool that
+     * started it.
+     */
+    baseCommit?: string;
+    /**
+     * The last commit of the run's work, written on the card when its main agent landed it: its
+     * branch is gone, and its changes are read from this commit. Absent on a run that is not landed.
+     */
+    landed?: string;
+    /** The wrapped agent (from the `session` event). */
+    driver?: string;
+    /** The workspace the agent builds in (from the `session` event). */
+    workspace?: string;
+    /** The wrapped agent's real session id, once it reports one. */
+    sessionId?: string;
+    /** The link shown to jump into the live agent session. */
+    sessionLink?: string;
+    /**
+     * The branch the agent's work is on: the card's, and for a run with a checkout the branch that
+     * checkout has checked out right now (the branches provider reads it), since the agent renames
+     * its branch itself while the card learns the new name only when the run ends.
+     *
+     * Recorded, not derived: a clean agent loses its checkout, and the agent renames its branch
+     * itself (#1725), so no name built from the run's id is guaranteed to be the one holding the
+     * commits.
+     */
+    branch?: string;
+    /**
+     * The hand-off anchor a cloud run pushed for its session to clone at (#1601): an empty commit
+     * unique to this run, folded from the `cloud-anchor` event. The session works on a `claude/*`
+     * branch of the cloud's own naming, and this is the ancestor by which the daemon's adoption
+     * pass recognizes which of origin's `claude/*` heads is this run's. Absent on non-web runs
+     * and on web runs whose pre-hand-off push failed.
+     */
+    cloudAnchor?: string;
+    /**
+     * The pull request this session's work is on (E6), recorded when one is opened rather than
+     * re-derived from branch names and timestamps by every surface that wants it.
+     */
+    pr?: {
+        number: number;
+        url: string;
+    };
+    /**
+     * What this session's end-of-session handoff is armed to do (#1102): push its branch, and open
+     * a draft PR for it. Both start on.
+     *
+     * On the meta because the checkboxes that show it live in a different process from the agent that
+     * obeys it, and a tab opened after the agent started has no event history to fold — the same
+     * reason {@link browserStreamPort} is here. Absent means an older agent, which the reader treats
+     * as armed, matching what that agent will actually do.
+     *
+     * `merge` mirrors the auto-merge arming (#1216, #1382) — display-only, like the rest of this
+     * field: the agent merges off its own config, never off the meta. Absent on records from before
+     * #1382, which the reader treats as off.
+     */
+    handoff?: {
+        push: boolean;
+        pr: boolean;
+        merge?: boolean;
+    };
+    /**
+     * How the handoff's merge half went (#1418), folded from the `handoff` event's `merge` field.
+     *
+     * What the daemon's CI watch scans for: `watched` is a PR waiting for green that *this* side
+     * must merge (the repo could not arm the git host's auto-merge), `auto-armed` one the git host will land by
+     * itself but whose checks going red is still ours to notice. On the meta because the watch
+     * reads metas, not event logs, and must survive both the agent's process and the daemon's.
+     * Absent on runs from before this field, and on every agent whose handoff had no merge to report.
+     */
+    mergeOutcome?: 'auto-armed' | 'merged' | 'watched' | 'withheld' | 'failed';
+    /**
+     * The choice gate the agent is currently parked on (#636): set when a `choice` event fires and
+     * cleared when its `choice-resolved` (or the agent's `end`) arrives. Present means the agent is
+     * paused waiting for the user's answer — the second "needs you" source after open PRs (#624).
+     */
+    pendingChoice?: {
+        id: string;
+        title: string;
+    };
+    /**
+     * The browser bridge holds a question this run's cloud session is parked on (#1668). Not stored:
+     * the daemon annotates a web run's record on the way to the dashboard, the way a relayed run's
+     * label is, because the bridge store is in memory and the archive on disk knows nothing of it.
+     */
+    cloudWaiting?: boolean;
+    /**
+     * The run was started by another machine's daemon (#1648): its {@link host} is not this one.
+     * Not stored either — annotated on the way to the dashboard like {@link cloudWaiting}, since
+     * the shared data branch shows every machine's runs here and only this daemon knows which host
+     * it is.
+     */
+    otherHost?: boolean;
+    /**
+     * The run ended clean and its process is still alive on this host: the tool that runs it is
+     * still saving its record and cleaning up its checkout, the window every surface says "saving…" for.
+     * Not stored: annotated on the way to the dashboard like {@link otherHost}, since only this
+     * machine can ask whether the process is alive.
+     */
+    saving?: boolean;
+    /**
+     * The loopback port the agent's browser preview is listening on (#813), or absent when the agent
+     * has no browser. What lets the daemon proxy the pane: the port is allocated per agent and the
+     * dashboard is a different process, so meta is the only place it can learn it.
+     */
+    browserStreamPort?: number;
+    /**
+     * Where this run executes (#1050/#1053/#610): `actions` for a GitHub Actions run, `web` for a
+     * Claude Code cloud session, `remote` when relayed to a connected device (#1067), absent for a
+     * local run. Persisted so the agent view can tell a burst-mode Actions run from a stalled live
+     * feed, show a cloud agent's session link after a reload, and gate the browser pane off (#1053).
+     */
+    target?: 'local' | 'actions' | 'remote' | 'web';
+    /** The connected device a remote agent (#1067) executes on, for the session list + notice after a reload. */
+    remoteLabel?: string;
+    /**
+     * The flow this agent started under (#1467): `build` for the scope→build orchestration, `prompt`
+     * for the direct-prompt path (research and transparent runs record `prompt` too). Persisted so a
+     * continuation (#762) can re-enter the flow its first leg ran — the composer's Resume always
+     * arrives as a `prompt` start, and without this record a resumed build agent ended as a bare
+     * prompt session (no synthesize framing, no backlog offer). Absent on records from before this
+     * field, which a reader treats as unknown (the continuation then keeps the prompt path).
+     */
+    kind?: 'build' | 'prompt';
+    /**
+     * The model id the current leg's agent was started with (#1438), folded from each leg's
+     * `session` event — a continuation (#762) may run a different model than the first leg, so
+     * the latest leg wins rather than the first pinning it. Absent when the leg left the agent
+     * on its own default (and on records from before this field).
+     */
+    model?: string;
+}
+/**
+ * The slice of a filesystem the store's reads need: the logic is testable with an in-memory fs,
+ * and only {@link nodeStoreFs} touches disk.
+ */
+export interface StoreFs {
+    read(path: string): Promise<string>;
+    write(path: string, contents: string): Promise<void>;
+    append(path: string, contents: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string): Promise<void>;
+    /** List a directory's entries (names only). Missing dir yields `[]`. */
+    readdir(path: string): Promise<string[]>;
+}
+/**
+ * A project's finished runs, most-recent first: what its runs provider answers, unfolded into the
+ * framework's meta. No provider, or one that cannot be read, is no runs, never a throw.
+ *
+ * `since` (epoch ms) is for a caller that only wants recent runs — a poll on a cadence, not the
+ * history list. `fresh` asks the provider past its last answer: the caller knows a run just finished.
+ */
+export declare function listAgents(cwd: string, runs?: RunsFor, opts?: {
+    since?: number;
+    fresh?: boolean;
+}): Promise<AgentMeta[]>;
+/**
+ * One finished run's whole diary, from the project's runs provider: for a reader that follows a
+ * run past its checkout. `undefined` for an unknown or unsafe id, a project with no provider, and
+ * a record that still says `running` — the marker a run's tool may leave as it starts, before its
+ * checkout exists: that run is not finished, its diary is still to come in the checkout.
+ */
+export declare function readFinishedDiary(cwd: string, agentId: string, runs?: RunsFor): Promise<AnyDiaryLine[] | undefined>;
+/**
+ * Whether `pid` is a live process on this host. `process.kill(pid, 0)` sends no signal but
+ * throws `ESRCH` once the process is gone; `EPERM` means it exists under another user (still
+ * alive). A pid on a *different* host is unknowable here, so callers guard on {@link AgentMeta.host}
+ * before trusting a result. A recycled pid (another process reusing a dead agent's number) reads as
+ * alive — an accepted, vanishingly rare miss on a single dev box.
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * The run a checkout holds, off its live card, `<id>.json` under the checkout's `.the-framework/`:
+ * the shape agent-driver's log writes, read as the meta the card unfolds to, `running` or not (a
+ * run that ended waiting on a question keeps its checkout), on the branch the checkout is on now
+ * (the provider read it), since the agent renames its branch itself while its card learns the new
+ * name only when the run ends. `undefined` when there is no card.
+ * Never healed here: the tool that started the run sweeps its own dead runs.
+ */
+export declare function readLiveMeta(checkout: Checkout, fs?: StoreFs): Promise<AgentMeta | undefined>;
+/** A run with a checkout, plus that checkout (#738): where to read the run's git and file status from. */
+export interface LiveAgent extends AgentMeta {
+    /** The run's own checkout, a worktree under `.branches/`. */
+    cwd: string;
+}
+/**
+ * Every run of a project that has a checkout (#738): each checkout the project's branches
+ * provider lists, its card through {@link readLiveMeta}. Newest first, by id. Never throws: a
+ * project with no provider has no checkouts, and an unreadable checkout is skipped.
+ */
+export declare function readLiveMetas(cwd: string, fs?: StoreFs, branches?: BranchesFor): Promise<LiveAgent[]>;
+/**
+ * One run's events, for a reader that replays them: the diary in the run's checkout while it has
+ * one (it is the newer of the two), else the finished run's diary from the runs provider.
+ * `undefined` for an unknown or unsafe id.
+ */
+export declare function loadAgentEvents(cwd: string, id: string, fs?: StoreFs, runs?: RunsFor, branches?: BranchesFor): Promise<FrameworkEvent[] | undefined>;
+/**
+ * What each of the named runs is doing now, by id: the last thing its diary says it did (a tool
+ * it used, with what) or said, on one line. Only a run with a checkout whose card says `running`
+ * has an entry: an ended run is doing nothing, and its row says how it ended.
+ */
+export declare function readDoing(cwd: string, ids: readonly string[], fs?: StoreFs, branches?: BranchesFor): Promise<Record<string, string>>;
+/** A {@link StoreFs} backed by `node:fs/promises`. See {@link nodeFs}. */
+export declare function nodeStoreFs(): StoreFs;
+/**
+ * A project's runs: the ones with a checkout prepended to the finished ones, newest-first.
+ * Forgiving — a side that cannot be read simply contributes nothing.
+ *
+ * The checkout's card wins over the recorded one (#768): a resumed run has a record from its
+ * first leg AND is going again, and the record alone would show a running agent as finished.
+ */
+export declare function readAllAgents(cwd: string, fs?: StoreFs, runs?: RunsFor, branches?: BranchesFor): Promise<AgentMeta[]>;
+/** One run's meta by id, the checkout's card winning over the record: {@link readAllAgents}'s rule for a single row. */
+export declare function findAgent(cwd: string, agentId: string, fs?: StoreFs, runs?: RunsFor, branches?: BranchesFor): Promise<AgentMeta | undefined>;

package/dist/module-types/src/store/branches.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The checkouts and the branches, as the framework reads and acts on them (#1774). The framework
+ * keeps no checkout and imports no branches package: a project's checkouts come from whichever of
+ * its packages declares that it provides them — `"framework": { "branches": "<command>" }` in the
+ * package's own package.json — and the framework reads and moves them by running that command.
+ * Swap the package for another that answers the same command line and prints the same shapes,
+ * and nothing here changes. No package declares it: the project has no checkouts, so no run with
+ * one, no branch to hand off, nothing to remove.
+ *
+ * The command line a provider answers, each printing one JSON document and exiting 0 (a refusal
+ * exits 1 with its reason on stderr):
+ *   `<command> list [--sizes]`                          every checkout, as an array of {@link Checkout}
+ *   `<command> show [--from <commit>] <branch>...`      what each branch holds and where it stands, as an array of {@link BranchState}, in the order asked;
+ *                                                       measured from `<commit>`, where the branches started, in place of the default branch;
+ *                                                       a full commit id in place of a branch is read as a branch that ends there
+ *   `<command> merge <b>`                               merge the branch into the default branch, on this machine, then delete it
+ *   `<command> push --branch <b>`                       push the branch to the remote; a branch only the remote has is answered as it is
+ *   `<command> remove <id> [--from <commit>] [--discard]`  reclaim a run's checkout once its branch holds everything, pushing nothing, its branch measured from the commit it started from; `--discard` drops uncommitted work
+ * `list` and `show` read this machine, no network: the framework polls. `show` answers the branch's
+ * git facts only; its pull request is the git host provider's (`git-host.ts`), as every pull request is.
+ *
+ * That is the whole contract: git, and nothing beyond it (#1820). The framework reads checkouts to
+ * find the runs that have one, and a branch's state for what it composes: the run page's handoff,
+ * the Human Queue's unpushed rows. Opening a pull request is the push here, then the git host
+ * provider's `open`. What a checkout is, where it lives, how a branch is pushed is the package's.
+ *
+ * The shapes, owned here: {@link Checkout}, {@link BranchState}.
+ */
+/** A run's checkout: where it works, as a provider lists it. */
+export interface Checkout {
+    /** The run's id. */
+    id: string;
+    /** The checkout's directory, absolute. */
+    path: string;
+    /** The branch it is on; absent for a checkout on none, or one git no longer knows. */
+    branch?: string;
+    /** The name the agent gave its work, as the provider answers it; absent while the run has not named it. Drawn where a branch would be drawn as a name. */
+    name?: string;
+    /** Its size on disk, when sizes were asked for. */
+    sizeBytes?: number;
+}
+/** One commit a branch holds beyond its base. */
+export interface BranchCommit {
+    sha: string;
+    subject: string;
+}
+/** One file a branch changed against its base. */
+export interface BranchFile {
+    path: string;
+    insertions: number;
+    deletions: number;
+    /** A binary file, where line counts mean nothing. */
+    binary: boolean;
+}
+/** What a branch holds and where it stands, as a provider answers `show`: git facts, no pull request. */
+export interface BranchState {
+    branch: string;
+    /** The name the agent gave its work, as the provider answers it; absent while the run has not named it. */
+    name?: string;
+    /** The branch exists on this machine. Gone: every list below is empty, and only the remote can say more. */
+    exists: boolean;
+    /** What it is measured against: the commit asked with `--from`, else the project's default branch, when one was found. */
+    base?: string;
+    /** The branch's own commits beyond the base, newest first. */
+    commits: BranchCommit[];
+    /** What it changed since it left the base. */
+    files: BranchFile[];
+    /** The project has a remote to push to. */
+    hasRemote: boolean;
+    /** The remote has the branch at this same tip. */
+    pushed: boolean;
+    /** The base already contains it. */
+    merged: boolean;
+    /** The uncommitted paths in the checkout that is on this branch; absent when no checkout is. */
+    pendingFiles?: string[];
+}
+/** What pushing a branch did: `pushed` is false when only the remote had it, so there was nothing here to push. */
+export type PushOutcome = {
+    ok: true;
+    pushed: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * What merging a branch into the project's default branch did: `into` names that branch, `commit`
+ * is the merged branch's last commit and `from` the commit its work began at, and `deleted` says
+ * the branch went once its work was in.
+ */
+export type MergeOutcome = {
+    ok: true;
+    into: string;
+    commit: string;
+    from: string;
+    deleted: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/** What reclaiming a checkout did: done, with the branches that went with it when any did, or the provider's reason it stayed. */
+export type RemoveOutcome = {
+    ok: true;
+    branchesDeleted?: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** A project's checkouts and branches: what a provider answers, read and moved by the framework. */
+export interface BranchesSource {
+    /**
+     * Every checkout; `[]` when none can be read. `fresh` asks past a list read within the window:
+     * the caller is looking for a checkout that may have just appeared. A list read less than
+     * {@link FRESH_MS} ago still answers, so a caller asking every second for a run that has no
+     * checkout is not a process every second.
+     */
+    list(opts?: {
+        sizes?: boolean;
+        fresh?: boolean;
+    }): Promise<Checkout[]>;
+    /**
+     * Each branch's state, in the order asked; a branch the provider did not answer for is missing.
+     * `[]` when nothing can be read. `from` is the commit the branches started from, which their
+     * commits and files are then measured from. A full commit id in place of a branch reads what a
+     * branch that ended there held.
+     */
+    show(branches: readonly string[], from?: string): Promise<BranchState[]>;
+    /** Push a branch to the remote: the checkout on it under its clean rule, else the branch itself. */
+    push(branch: string): Promise<PushOutcome>;
+    /** Merge a branch into the project's default branch, on this machine, then delete it; a merge that conflicts changes nothing. */
+    merge(branch: string): Promise<MergeOutcome>;
+    /**
+     * Reclaim a run's checkout, or why it stayed. `from` is the commit the run's branch started
+     * from, when that is not the default branch: what tells a branch with nothing of its own.
+     * `discard` drops its uncommitted work instead of refusing over it.
+     */
+    remove(id: string, opts?: {
+        discard?: boolean;
+        from?: string;
+    }): Promise<RemoveOutcome>;
+}
+/** The checkouts of the project at `root`, or `undefined` when none of its packages provides them. */
+export type BranchesFor = (root: string) => Promise<BranchesSource | undefined>;
+/** A {@link BranchesFor} that also forgets what it read of one project, for when a module or a run just wrote there. */
+export type BranchesReader = BranchesFor & {
+    changed(root: string): void;
+};
+/** The rows read back from a provider's `list`: the objects with an id and a path, everything else as printed; anything else is no checkout. */
+export declare function parseCheckouts(output: unknown): Checkout[];
+/** The states read back from a provider's `show`: the objects with a branch and the three verdicts, lists cleaned; anything else is no state. */
+export declare function parseBranchStates(output: unknown): BranchState[];
+/**
+ * The production {@link BranchesReader}: the project's provider, looked up by its package.json,
+ * one source per project kept while the same command provides — so the cache holds across the
+ * many reads of one poll, and a project that installs, swaps or drops its provider is read the new
+ * way within {@link CACHE_MS}. `changed(root)` forgets that project's reads, so the next read runs
+ * the command again: a run just started there, or a module's command just ran, and a checkout may
+ * have come or gone.
+ */
+export declare function providedBranches(now?: () => number): BranchesReader;
+/** The framework's one reader of the checkouts, shared by every caller so they share its cache. */
+export declare const projectBranches: BranchesReader;
+/** A {@link BranchesFor} for a project with no provider: no checkouts. */
+export declare const noBranches: BranchesFor;

package/dist/module-types/src/store/git-host.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The project's git host, as the framework reads and acts on it (#1820): the pull requests of the
+ * project, opening one, landing one, and the project's page there. The framework names no git host
+ * and runs no git host tool: a project's git host comes from whichever of its packages declares that it
+ * provides it — `"framework": { "git-host": "<command>" }` in the package's own package.json — and
+ * the framework asks by running that command. Swap the package for another that answers the same
+ * command line and prints the same shapes, and nothing here changes. No package declares it: the
+ * project has no git host, so no pull requests, and a finished run's last step is the push. A
+ * built-in package's git host is the project's only when it answers the project's page there: a
+ * project whose remote is on another host, or that has no remote, has none.
+ *
+ * The command line a provider answers, each printing one JSON document and exiting 0 (a refusal
+ * exits 1 with its reason on stderr):
+ *   `<command> requests [--branch <b>] [--state open|merged|all] [--since <iso>]`
+ *                                                       the project's pull requests, newest first, as an array of {@link GitHostRequest}
+ *   `<command> open --branch <b> --title <t> [--body <text>] [--draft]`
+ *                                                       open the branch's pull request; an open one is answered as it is (`existing`)
+ *   `<command> merge <number>`                          land the pull request: armed to merge on green, or merged at once
+ *   `<command> home`                                    the project's page on the git host, and the git host's name
+ * The branch `open` is asked for must already be on the remote: pushing is the branches
+ * provider's step, and the framework runs it first.
+ *
+ * The shapes, owned here: {@link GitHostRequest}, {@link GitHostHome}.
+ */
+/** A pull request, as a provider lists it. */
+export interface GitHostRequest {
+    number: number;
+    url: string;
+    state: 'open' | 'merged' | 'closed';
+    title: string;
+    draft: boolean;
+    /** The branch the request is from. */
+    branch: string;
+    /** The commit the request's head is at. */
+    head: string;
+    /** ISO creation time. */
+    createdAt: string;
+    /** ISO merge time, for a merged request. */
+    mergedAt?: string;
+    /** The commit a merged request landed as on the base branch. */
+    mergeCommit?: string;
+}
+/** The project's page on the git host, and what the git host is called: what a link is drawn from. */
+export interface GitHostHome {
+    url: string;
+    name: string;
+}
+/** What asking for requests answered: the list, or why there is none: "none" and "could not tell" are different answers. */
+export type RequestsOutcome = {
+    ok: true;
+    requests: GitHostRequest[];
+} | {
+    ok: false;
+    error: string;
+};
+/** What opening a pull request left: the request, and whether it was open already. */
+export type OpenOutcome = {
+    ok: true;
+    request: {
+        number: number;
+        url: string;
+    };
+    existing: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/** What landing a pull request did: armed to merge on green, merged at once, or the provider watching its checks. */
+export type MergeOutcome = {
+    ok: true;
+    outcome: 'auto-armed' | 'merged' | 'watching';
+} | {
+    ok: false;
+    error: string;
+};
+/** A project's git host: what a provider answers, read and moved by the framework. */
+export interface GitHostSource {
+    /** The project's pull requests, newest first: all, or one branch's, or by state, or since a time. */
+    requests(opts?: {
+        branch?: string;
+        state?: 'open' | 'merged' | 'all';
+        since?: string;
+    }): Promise<RequestsOutcome>;
+    /** Open a branch's pull request, or answer the open one. */
+    open(branch: string, opts: {
+        title: string;
+        body?: string;
+        draft?: boolean;
+    }): Promise<OpenOutcome>;
+    /** Land a pull request. */
+    merge(number: number): Promise<MergeOutcome>;
+    /** The project's page on the git host; `undefined` when the provider cannot tell (no remote there). */
+    home(): Promise<GitHostHome | undefined>;
+}
+/** The git host of the project at `root`, or `undefined` when none of its packages provides one. */
+export type GitHostFor = (root: string) => Promise<GitHostSource | undefined>;
+/** A {@link GitHostFor} that also forgets what it knows of one project. */
+export type GitHostReader = GitHostFor & {
+    changed(root: string): void;
+};
+/** The rows read back from a provider's `requests`: the objects with the facts a request needs; anything else is no request. */
+export declare function parseRequests(output: unknown): GitHostRequest[];
+/**
+ * The production {@link GitHostReader}: the project's provider, looked up by its package.json, one
+ * source per project kept while the same command provides, so a project that installs, swaps or
+ * drops its git host is read the new way within {@link CACHE_MS}. `changed(root)` forgets the
+ * project, so the next ask looks its provider up again.
+ */
+export declare function providedGitHost(now?: () => number): GitHostReader;
+/** The framework's one reader of the git host, shared by every caller. */
+export declare const projectGitHost: GitHostReader;
+/** A {@link GitHostFor} for a project with no git host package. */
+export declare const noGitHost: GitHostFor;

package/dist/module-types/src/store/index.d.ts

@@ -0,0 +1,9 @@
+export { nodeStoreFs, listAgents, readAllAgents, findAgent, isPidAlive, readLiveMeta, loadAgentEvents, readLiveMetas, readDoing, readFinishedDiary, type StoreFs, type AgentMeta, type LiveAgent, type AgentStatus, } from './agent-store.js';
+export { findCheckout, resolveAgentCheckout, resolveAgentDiary, type AgentDiarySource } from './agent-checkout.js';
+export { projectRuns, providedRuns, noRuns, parseRunCard, isRunId, type RunsFor, type RunsReader, type RunsSource, type RunsWrite, type RunCard, type RunPatch, type RunStatus, type AnyDiaryLine, type FinishedRun } from './runs.js';
+export { projectBranches, providedBranches, noBranches, parseCheckouts, parseBranchStates, type BranchesFor, type BranchesReader, type BranchesSource, type RemoveOutcome as BranchRemoveOutcome, type Checkout, type BranchState, type BranchCommit, type BranchFile, type PushOutcome as BranchPushOutcome } from './branches.js';
+export { projectGitHost, providedGitHost, noGitHost, parseRequests, type GitHostFor, type GitHostReader, type GitHostSource, type GitHostRequest, type GitHostHome, type RequestsOutcome as GitHostRequestsOutcome, type OpenOutcome as GitHostOpenOutcome, type MergeOutcome as GitHostMergeOutcome } from './git-host.js';
+export { projectQueue, providedQueue, noQueue, parseQueueEntries, type QueueFor, type QueueReader, type QueueSource } from './queue.js';
+export { providedDataChanged } from './provided.js';
+export { fromRunCard, fromDiaryLine, eventsOf } from './run-record.js';
+export { agentIdFromStartedAt, startedAtFromAgentId } from '../agent-id.js';

package/dist/module-types/src/store/provided.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A package's command just ran in the project at `root` (a module's, through the dashboard), and
+ * may have written what one of the framework's provided readers caches: every provided reader
+ * forgets that project, so its next read runs the provider again. The framework never knows which
+ * command writes what; forgetting is cheap and re-reading is what it does anyway.
+ */
+export declare function providedDataChanged(root: string): void;
+/** The kinds of the framework's data a project's package may provide, one reader each (`git-host` is `git-host.ts`). */
+export declare const PROVIDED_KINDS: readonly ['tickets', 'queue', 'runs', 'branches', 'git-host', 'repository'];
+/**
+ * Why a kind of the project's data has no provider although packages declare it (#1820): two or
+ * more declare the kind and the project's package.json names none, or names one that does not
+ * declare it. One sentence per such kind, for the project's error banner; none when every kind is
+ * settled. Nobody declaring a kind is not a problem: the project has none of that data.
+ */
+export declare function providerProblems(root: string): Promise<string[]>;