@openagt/dashboard 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,163 @@
+/**
+ * The checkouts and the branches, as OpenAgent reads and acts on them (#1774). OpenAgent
+ * keeps no checkout and imports no branches package: a project's checkouts come from whichever of
+ * its packages declares that it provides them — `"openagent": { "branches": "<command>" }` in the
+ * package's own package.json — and OpenAgent 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: OpenAgent 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). OpenAgent 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 OpenAgent. */
+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;
+/** OpenAgent'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 OpenAgent reads and acts on it (#1820): the pull requests of the
+ * project, opening one, landing one, and the project's page there. OpenAgent 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 — `"openagent": { "git-host": "<command>" }` in the package's own package.json — and
+ * OpenAgent 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 OpenAgent 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 OpenAgent. */
+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;
+/** OpenAgent'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 OpenAgent's provided readers caches: every provided reader
+ * forgets that project, so its next read runs the provider again. OpenAgent 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 OpenAgent'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[]>;

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

@@ -0,0 +1,45 @@
+/**
+ * The agent queue, as OpenAgent reads it (#1774). OpenAgent keeps no queue and imports no
+ * queue package: a project's queue comes from whichever of its packages declares that it provides
+ * it — `"openagent": { "queue": "<command>" }` in the package's own package.json — and
+ * OpenAgent reads it by running that command. Swap the package for another that answers the same
+ * command line and prints the same shape, and nothing here changes. No package declares it: the
+ * project has no queue, and the dashboard shows it none.
+ *
+ * The command line a provider answers, printing one JSON document and exiting 0:
+ *   `<command> --local`   the open entries, in order of work, as an array of strings
+ * `--local` reads the copy on this machine, no network: OpenAgent polls.
+ *
+ * That is the whole contract. Writing the queue is not OpenAgent's: a module the queue package
+ * brings acts on it through its own command (`@openagt/dashboard/module`'s link actions), and OpenAgent
+ * only re-reads.
+ *
+ * The shape, owned here: an entry is one string, the task a future agent is started with, as the
+ * queue's own command prints it. A markdown link at its start names the work and where it points;
+ * how a dashboard reads that is the queue package's module's.
+ */
+/** A project's queue: what a provider answers, read by OpenAgent. */
+export interface QueueSource {
+    /** The open entries, in order of work; `[]` when none can be read. */
+    list(): Promise<string[]>;
+}
+/** The queue of the project at `root`, or `undefined` when none of its packages provides one. */
+export type QueueFor = (root: string) => Promise<QueueSource | undefined>;
+/** A {@link QueueFor} that also forgets what it read of one project, for when a module just wrote there. */
+export type QueueReader = QueueFor & {
+    changed(root: string): void;
+};
+/** Entries read back from a provider's output: the non-empty strings of an array, trimmed; anything else is no entries. */
+export declare function parseQueueEntries(output: unknown): string[];
+/**
+ * The production {@link QueueReader}: 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 read, so the next read runs the
+ * command again: a module's command just ran there, and may have written.
+ */
+export declare function providedQueue(now?: () => number): QueueReader;
+/** OpenAgent's one reader of the queue, shared by every caller so they share its cache. */
+export declare const projectQueue: QueueReader;
+/** A {@link QueueFor} for a project with no provider: no queue. */
+export declare const noQueue: QueueFor;

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

@@ -0,0 +1,32 @@
+/**
+ * Creating a project's repository on a host, for a project that lives on this machine only. Like
+ * every provided kind, OpenAgent names no host: the package that declares
+ * `"openagent": { "repository": "<command>" }` creates it, and OpenAgent asks by running that
+ * command.
+ *
+ * The command line a provider answers, each printing one JSON document and exiting 0 (a refusal
+ * exits 1 with its reason on stderr):
+ *   `<command> create --check`   the repository the project would become, `{ repository, name }`
+ *                                (`name` is the host's), creating nothing; refused when the
+ *                                project has a remote already or the host cannot be reached
+ *   `<command> create`           create it private, set it as the project's origin and push;
+ *                                `{ repository, url, name }`
+ */
+/** The repository a project would become, and the host it would be on. */
+export interface RepositoryOffer {
+    /** `<account>/<name>`, as the host names it. */
+    repository: string;
+    /** The host's name, for a button: `GitHub`. */
+    name: string;
+}
+export type CreateRepositoryResult = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** What the project's repository provider offers to create, or undefined: no provider, a remote already there, or a host that cannot be reached. */
+export declare function repositoryOffer(root: string): Promise<RepositoryOffer | undefined>;
+/** Create the project's repository through its provider; a refusal is the provider's own line. */
+export declare function createRepository(root: string): Promise<CreateRepositoryResult>;

package/dist/module-types/src/store/run-record.d.ts

@@ -0,0 +1,21 @@
+import type { AnyDiaryLine, RunCard } from './runs.js';
+import type { OpenAgentEvent } from '../events.js';
+import type { AgentMeta } from './agent-store.js';
+/**
+ * A run's card and diary (`runs.ts`), read as OpenAgent's own shapes (#1769): the card as the
+ * meta every list shows, the diary as the events the run page replays and tails. The card's
+ * eleven plain fields and four kinds of diary line are the shape; whoever ran the agent keeps the
+ * rest of what it knows under one key, `caller`, and writes its other lines as they are.
+ * OpenAgent records no run of its own (#1774), so there is no writing half.
+ */
+/** A card as OpenAgent's meta: `caller` unfolded, the card's own fields winning. */
+export declare function fromRunCard(card: RunCard): AgentMeta;
+/**
+ * One diary line as one OpenAgent event: what the agent said, its result, the run's end and its
+ * cost are the shape's four kinds; a line of any other kind is an OpenAgent event as written, and
+ * one whose kind is no longer an event (the kinds of runs recorded before OpenAgent stopped
+ * running agents) reads as nothing. The line's time, `at`, is the event's, whatever the kind.
+ */
+export declare function fromDiaryLine(line: AnyDiaryLine): OpenAgentEvent | undefined;
+/** A diary as the run's events, for a reader that replays them. */
+export declare function eventsOf(lines: readonly AnyDiaryLine[]): OpenAgentEvent[];

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

@@ -0,0 +1,107 @@
+/**
+ * Finished runs, as OpenAgent reads them (#1774). OpenAgent keeps no run and imports no
+ * records package: a project's finished runs come from whichever of its packages declares that it
+ * provides them — `"openagent": { "runs": "<command>" }` in the package's own package.json — and
+ * OpenAgent reads 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 finished runs, only the ones still running in a checkout.
+ *
+ * The command line a provider answers, each printing one JSON document and exiting 0:
+ *   `<command> --local --full --limit N`   the runs, newest first, whole cards
+ *   `<command> show <id> --local --full`   one run: the whole card plus `diary`, every line
+ *   `<command> delete <id>`                remove a run
+ *   `<command> patch <id> [--branch <b>] [--pr <n> --pr-url <url>] [--landed <commit> --from <commit>]`   the late facts
+ * `--local` reads the copy on this machine, no network: OpenAgent polls.
+ *
+ * The shapes, owned here: {@link RunCard} and {@link AnyDiaryLine}. A running agent's own card in
+ * its checkout is the same shape, written by the tool that runs it.
+ */
+/** How a run stands: still going, or how it ended. */
+export type RunStatus = 'running' | 'done' | 'stopped' | 'failed' | 'waiting';
+/**
+ * A run's card: what was asked, where the work went, how it ended, what it cost. `caller` is the
+ * bookkeeping of the program that ran the agent (its pid, host, session id, …), one key.
+ */
+export interface RunCard {
+    id: string;
+    startedAt: string;
+    endedAt?: string;
+    status: RunStatus;
+    intent?: string;
+    driver?: string;
+    model?: string;
+    branch?: string;
+    pr?: {
+        number: number;
+        url: string;
+    };
+    ticket?: string;
+    cost?: number;
+    caller?: Record<string, unknown>;
+}
+/** The two late facts a finished run's card may still learn: the branch its work landed on, its pull request. */
+export type RunPatch = Partial<Pick<RunCard, 'branch' | 'pr'>> & {
+    /** The run's work was merged and its branch deleted: its last commit, and the commit its work began at. */
+    landed?: {
+        commit: string;
+        from: string;
+    };
+};
+/** One line of a run's diary: a JSON object with a `kind`. */
+export type AnyDiaryLine = {
+    kind: string;
+} & Record<string, unknown>;
+/** A finished run: its card and its whole diary. */
+export interface FinishedRun {
+    card: RunCard;
+    diary: AnyDiaryLine[];
+}
+/** A project's finished runs: what a provider answers, read by OpenAgent. */
+export interface RunsSource {
+    /**
+     * Every finished run's card, newest first; `[]` when none can be read. `fresh` skips a list read
+     * a moment ago: the caller knows the runs changed since.
+     */
+    list(opts?: {
+        fresh?: boolean;
+    }): Promise<RunCard[]>;
+    /** One run with its diary; `undefined` for no such run, or none readable. */
+    show(id: string): Promise<FinishedRun | undefined>;
+    /** Remove a run, or why it could not be. */
+    remove(id: string): Promise<RunsWrite>;
+    /** Set a run's late facts, or why they could not be. */
+    patch(id: string, patch: RunPatch): Promise<RunsWrite>;
+}
+/** What a change to the runs did: done, or the provider's reason it was not. */
+export type RunsWrite = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** The finished runs of the project at `root`, or `undefined` when none of its packages provides them. */
+export type RunsFor = (root: string) => Promise<RunsSource | undefined>;
+/** A {@link RunsFor} that also forgets what it read of one project, for when a module just wrote there. */
+export type RunsReader = RunsFor & {
+    changed(root: string): void;
+};
+/** Whether a string can name a run: letters, digits, `-` and `_`, nothing a path can climb out with. */
+export declare function isRunId(id: string): boolean;
+/**
+ * A card read back: the fields of the shape, each kept only when it has the right type, plus
+ * `caller` as it is. `undefined` for anything that is not a card — not an object, or missing an
+ * id, a start or a status. Takes a card's JSON text or an already-parsed value.
+ */
+export declare function parseRunCard(input: unknown): RunCard | undefined;
+/**
+ * The production {@link RunsFor}: 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 module's command just ran there, and may have written.
+ */
+export declare function providedRuns(now?: () => number): RunsReader;
+/** OpenAgent's one reader of finished runs, shared by every caller so they share its cache. */
+export declare const projectRuns: RunsReader;
+/** A {@link RunsFor} for a project with no provider: no finished runs. */
+export declare const noRuns: RunsFor;

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

@@ -0,0 +1,72 @@
+/**
+ * The tickets, as OpenAgent reads them (#1774). OpenAgent keeps no ticket and imports no
+ * tickets package: a project's tickets come from whichever of its packages declares that it
+ * provides them — `"openagent": { "tickets": "<command>" }` in the package's own package.json —
+ * and OpenAgent reads them by running that command. Swap the package for another that answers
+ * the same command line and prints the same shape, and nothing here changes. No package declares
+ * it: the project has no tickets, and the dashboard shows it none.
+ *
+ * The command line a provider answers, printing one JSON document and exiting 0:
+ *   `<command> list --local`   every open ticket, as an array of {@link Ticket}
+ * `--local` reads the copy on this machine, no network: OpenAgent polls.
+ *
+ * That is the whole contract. OpenAgent reads tickets for what it composes across skills: the
+ * onboarding step, a queued link's title. Showing them, planning them, claiming and releasing them,
+ * and the Overview's hot-tickets card, are the tickets package's own module, through its own command.
+ *
+ * The shape, owned here: {@link Ticket}, the row a ticket lists as.
+ */
+/** A ticket's row, as a provider prints it. Everything but the five plain facts is optional. */
+export interface Ticket {
+    /** The ticket's file name, its identity: `tickets/<file>` is the path a link to it carries. */
+    file: string;
+    title: string;
+    /** One line of what it is about; empty when the ticket says nothing beyond its title. */
+    summary: string;
+    /** `0`–`10` as written, `10` acting at once; absent when unset, and not checked here. */
+    priority?: string;
+    topics?: string[];
+    /** The issue it tracks in the project's tracker, and the pull request that closes it: a label and where it points. */
+    issue?: {
+        label: string;
+        url: string;
+    };
+    pr?: {
+        label: string;
+        url: string;
+    };
+    /** ISO 8601: the file's date. */
+    date: string;
+    /** Whether a plan sits beside it. */
+    planned: boolean;
+    /** Whether someone holds it, and who: a run's id, or a branch. */
+    locked?: boolean;
+    lockedBy?: string;
+    effort?: number;
+    uncertainty?: number;
+}
+/** A project's tickets: what a provider answers, read by OpenAgent. */
+export interface TicketsSource {
+    /** Every open ticket; `[]` when none can be read. */
+    list(): Promise<Ticket[]>;
+}
+/** The tickets of the project at `root`, or `undefined` when none of its packages provides them. */
+export type TicketsFor = (root: string) => Promise<TicketsSource | undefined>;
+/** A {@link TicketsFor} that also forgets what it read of one project, for when a module just wrote there. */
+export type TicketsReader = TicketsFor & {
+    changed(root: string): void;
+};
+/** The rows read back from a provider's output: the objects with the five plain facts, everything else as printed; anything else is no ticket. */
+export declare function parseTickets(output: unknown): Ticket[];
+/**
+ * The production {@link TicketsReader}: 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 read, so the next read runs the
+ * command again: a module's command just ran there, and may have written.
+ */
+export declare function providedTickets(now?: () => number): TicketsReader;
+/** OpenAgent's one reader of the tickets, shared by every caller so they share its cache. */
+export declare const projectTickets: TicketsReader;
+/** A {@link TicketsFor} for a project with no provider: no tickets. */
+export declare const noTickets: TicketsFor;

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

@@ -0,0 +1,3 @@
+import { type OpenAgentEvent } from './events.js';
+/** Render a {@link OpenAgentEvent} as one human-readable line (terminal surface). */
+export declare function formatOpenAgentEvent(event: OpenAgentEvent): string;