@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/widget-types/dashboard/lib/draft-handoff.d.ts

@@ -0,0 +1,15 @@
+/** At SPA boot: move `?draft=` out of the URL into sessionStorage and strip it from the address bar
+ * (and so from history and any Referer). Idempotent and a no-op when there is no draft param. */
+export declare function stashDraftFromUrl(): void;
+/**
+ * Carry a draft across an in-app navigation (#1139): the same stash the device hop uses, written
+ * directly rather than through the URL. For a click that knows what the next session should be
+ * about but lands on the launcher, where that knowledge would otherwise be dropped — a hot ticket
+ * with no run of its own.
+ *
+ * Deliberately not a `?draft=` param like the device hop: this navigation never leaves the tab, so
+ * there is nothing to hand another device and no reason to put the prompt in the address bar.
+ */
+export declare function stashPendingDraft(draft: string): void;
+/** The carried draft, if any, cleared as it is read so a reload does not re-seed it. */
+export declare function takePendingDraft(): string | null;

package/dist/widget-types/dashboard/lib/format-date.d.ts

@@ -0,0 +1,51 @@
+/** A timestamp as local date + time, e.g. a project's last activity. */
+export declare function formatDateTime(value: string | undefined, fallback?: string): string;
+/**
+ * A short local date + time, e.g. "Jul 18, 10:35 PM". For places where the timestamp is standing
+ * in as a name (an unnamed session in the rail), where seconds are noise on the line that has to
+ * identify the row.
+ */
+export declare function formatDateTimeShort(value: string | undefined, fallback?: string): string;
+/** A timestamp as a local date alone, for the denser table columns. */
+export declare function formatDate(value: string | undefined, fallback?: string): string;
+/**
+ * A compact age (#1139): "22s ago" / "30m ago" / "5d ago" / "2w ago", the units the Agents list
+ * dates its rows in. Finer than {@link formatRelative} at both ends — it names seconds (a session
+ * that ended moments ago) and never falls back to a bare date (weeks, then years, stay relative) —
+ * so a row reads the same whether it finished this minute or last month. Pair it with
+ * {@link formatDateTime} in a `title` for the exact moment.
+ *
+ * Floored, not rounded: "1m ago" should mean at least a minute has passed, not "closer to a minute
+ * than to two".
+ */
+export declare function formatAge(value: string | undefined, fallback?: string): string;
+/**
+ * A timestamp as freshness (#948): "just now" / "12m ago" / "3h ago" / "2d ago", falling back
+ * to the local date past a week. An at-a-glance board wants "2m ago", not today's date.
+ */
+export declare function formatRelative(value: string | undefined, fallback?: string): string;
+/**
+ * A plain duration, floored to its largest whole unit: "2s" / "10m" / "2h" / "1d" (#960 Edit) — no
+ * "ago", and no weeks: this backs the pace-deviation figure, which can never exceed the week
+ * itself. Floored for the reason {@link formatAge} is: "1d" should mean a full day has passed, not
+ * "close enough to one".
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * The same duration spelled out — "1 day" / "2 hours" / "10 minutes" / "2 seconds" (#960 Edit) —
+ * for a sentence (a tooltip explaining the figure {@link formatDuration} renders as "1d"), where an
+ * abbreviation reads as a label rather than as prose.
+ */
+export declare function formatDurationLong(ms: number): string;
+/**
+ * A quota reset, as the week it sits under already places it: "Tuesday 8:59pm" (#960 Edit), not a
+ * date — the bar above says which day of the week it is; naming the date again would be the
+ * calendar repeating itself. Pair with {@link formatResetTooltip} for the exact moment.
+ */
+export declare function formatResetDay(at: number): string;
+/**
+ * The same moment in full, for a tooltip: "Quota resets on Jul 28, 8:59pm (Europe/Berlin)". Names
+ * the zone rather than leaving it implicit, since the reset is the account's own clock, and a
+ * viewer working from a different one should not have to guess whether the two agree.
+ */
+export declare function formatResetTooltip(at: number): string;

package/dist/widget-types/dashboard/lib/host-services.d.ts

@@ -0,0 +1,12 @@
+import type { WidgetHostBase } from '../widget/index.js';
+/** The services, minus the package they are bound to: what the shell has, before a widget is known. */
+export type HostServices = Omit<WidgetHostBase, 'package'>;
+/**
+ * Services for a shell that provides none (a unit test renders a page or a slot alone): nothing
+ * navigates, a start answers that there is no dashboard, no project has runs.
+ */
+export declare const INERT_HOST_SERVICES: HostServices;
+/** Set by the shell around the whole dashboard: the services every widget's host is built from. */
+export declare const HostServicesContext: import("react").Context<HostServices | null>;
+/** The shell's services bound to one widget package: the base of that widget's host. */
+export declare function useHostServices(pkg: string): WidgetHostBase;

package/dist/widget-types/dashboard/lib/route.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether a first segment names a page a widget adds (#1774) rather than a project: a lowercase
+ * letter, then lowercase letters and digits. Never a project's id, which always carries a
+ * `-<hash>` suffix, so the router reserves no widget's word: whichever widget claims the segment
+ * gets it, and the shell says "no such page" when none does.
+ */
+export declare function isPageSegment(segment: string): boolean;
+/** What the dashboard is looking at, as carried by the URL. */
+export interface Route {
+    /** A top-level view belonging to no project (#958). */
+    view?: 'settings';
+    /** The selected project, or null for the Overview. */
+    projectId: string | null;
+    /** The selected session (agent id), or null for the project's home/launcher. */
+    agentId: string | null;
+    /** A widget's page (#1774), by its segment; no project and no agent is selected there. */
+    page?: string;
+    /** The segments after a widget page's own, decoded: `/logs/a` carries `['a']`. */
+    pagePath?: string[];
+}
+/** Read the route out of a path. Anything unparseable is the Overview, and extra segments are ignored. */
+export declare function parseRoute(pathname: string): Route;
+/** The path for a route — the inverse of {@link parseRoute}. */
+export declare function formatRoute({ view, projectId, agentId, page, pagePath }: Route): string;

package/dist/widget-types/dashboard/lib/rpc.d.ts

@@ -0,0 +1,31 @@
+import type { LiveFeedEvent } from '../../src/dashboard-rpc/index.js';
+/**
+ * A typed stub for one RPC. `F` is the implementation's own signature, so the call is checked
+ * against the real thing and a rename that misses a caller is a type error rather than a 404.
+ *
+ * Arguments and return value go through JSON, which is what they always did — the wire has no
+ * opinion about `Date` or `Map` here because none of these RPCs pass one.
+ */
+export declare function rpc<F extends (...args: never[]) => unknown>(name: string): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+/**
+ * A live feed of one agent's events.
+ *
+ * The contract the dashboard relies on, unchanged from the Channel it replaced: `listen` per
+ * event, and `onClose` telling a clean end (the server is done — an unknown project, a finished
+ * relay stream) apart from a dropped one (retry with backoff). That distinction is the whole
+ * reason the feed can say "the daemon is not answering" instead of looking like a quiet agent.
+ */
+export interface EventChannel {
+    listen(onEvent: (event: LiveFeedEvent) => void): void;
+    onClose(onClosed: (err?: Error) => void): void;
+    close(): void;
+}
+/**
+ * Subscribe to an agent's events over SSE. Rejects when the subscription itself fails, which the
+ * caller retries; a stream that opens and later dies closes with an error instead.
+ *
+ * Read with `fetch` rather than `EventSource` because `EventSource` reconnects on its own
+ * schedule, which would fight the caller's backoff and erase the clean-vs-dropped distinction —
+ * it reports every end as an error and retries even the ones that meant "done".
+ */
+export declare function openEvents(projectId: string, agentId?: string): Promise<EventChannel>;

package/dist/widget-types/dashboard/lib/use-action.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What an action did: `ok` says whether it succeeded, and only then is there a `value`.
+ *
+ * Said as a pair rather than as "the value, or `undefined` when it did not succeed", because an
+ * action that succeeds with nothing to report is not a failure: with the value alone, a `sendStop`
+ * that resolves void was indistinguishable from one that threw, and every such caller had to map
+ * its success to a stand-in value to tell the two apart.
+ */
+export type ActionOutcome<T> = {
+    ok: true;
+    value: Succeeded<T>;
+} | {
+    ok: false;
+};
+/** What is left of an action's result once its own refusal branch is ruled out. */
+type Succeeded<T> = Exclude<T, {
+    ok: false;
+}>;
+export declare function useAction(): {
+    busy: boolean;
+    error: string | null;
+    reset: () => void;
+    run: <T>(fn: () => Promise<T>, fallback?: string) => Promise<ActionOutcome<T>>;
+};
+export {};

package/dist/widget-types/dashboard/lib/use-async.d.ts

@@ -0,0 +1,39 @@
+import { type DependencyList } from 'react';
+/**
+ * What a read shows when its deps change, until the new answer lands. By default, nothing: the
+ * `initial` value, so one target's data is never shown as another's.
+ *
+ * - `'previous'`: the last answer, whatever it was for. For a read whose target barely matters
+ *   to the eye (the git host page of a project), where blanking would only flicker.
+ * - `{ remember: key }`: the last answer read under this key, marked loaded, or nothing when no
+ *   answer was. For a page a person goes back and forth between (a run's facts): going back shows
+ *   what was read last time at once, and the read is made again all the same, so it is replaced
+ *   the moment the fresh answer lands. The key names the target, so no other target's answer is
+ *   ever shown.
+ */
+export type Keep = 'previous' | {
+    remember: string;
+};
+/** Forget every remembered answer. For tests. */
+export declare function forgetRemembered(): void;
+/**
+ * Read once, and again whenever `deps` change.
+ *
+ * Pass `null` for `load` when there is nothing to read yet (no project selected): the
+ * value stays `initial` and no read is made. `load` must close over exactly `deps`.
+ */
+export declare function useLoaded<T>(load: (() => Promise<T>) | null, initial: T, deps: DependencyList, keep?: Keep): T;
+/**
+ * Read now, again every `everyMs`, and again whenever `deps` change. Polling stops on
+ * unmount. `reload` reads immediately, for when a local action means the next tick is
+ * too late to wait for.
+ *
+ * Pass `null` for `load` when there is nothing to read yet. `load` must close over
+ * exactly `deps`. `loaded` is false until the first successful read, and again after
+ * a dep change — for callers that must tell "not there" from "not read yet".
+ */
+export declare function usePolled<T>(load: (() => Promise<T>) | null, initial: T, everyMs: number, deps: DependencyList, keep?: Keep): {
+    value: T;
+    reload: () => void;
+    loaded: boolean;
+};

package/dist/widget-types/dashboard/lib/use-widgets.d.ts

@@ -0,0 +1,42 @@
+import type { LinkAction, WidgetCard, WidgetPage } from '../widget/index.js';
+/** A widget page as the shell mounts it: the page, plus the package it came from and the projects that have it. */
+export interface MountedPage extends WidgetPage {
+    package: string;
+    projects: string[];
+}
+/** A link action as the shell mounts it (#1774): the action, plus the package it came from and the projects that have it. */
+export interface MountedLinkAction extends LinkAction {
+    package: string;
+    projects: string[];
+}
+/** A card as the shell mounts it (#1818): the card, plus the package it came from and the projects that have it. */
+export interface MountedCard extends WidgetCard {
+    package: string;
+    projects: string[];
+}
+/** What the installed widgets bring, once loaded: their pages, their cards and their link actions. */
+export interface MountedWidgets {
+    pages: MountedPage[];
+    /** The Overview's cards, in the order they are drawn: by `order`, then by package name. */
+    cards: MountedCard[];
+    linkActions: MountedLinkAction[];
+    /** True once the widget list was read and every module in it imported or skipped. */
+    loaded: boolean;
+}
+/**
+ * What the registered projects' widgets add (#1774), in package order: the pages, a segment two
+ * widgets claim going to the first, the cards (#1818), sorted by their order then their package, and the link actions, every one of them, each carrying the
+ * package it came from and the projects that have it. `loaded` is false until the widget list has
+ * been read and every module in it imported, so the shell can tell "no such page" from "not
+ * loaded yet".
+ */
+export declare function useWidgets(): MountedWidgets;
+/**
+ * The mounted widgets, for any component in the shell (#1774): the shell reads them once with
+ * {@link useWidgets} and provides them here, so a page deep in the tree finds the link actions
+ * without the shell threading them through every prop. Outside the provider: nothing mounted,
+ * not loaded.
+ */
+export declare const WidgetsContext: import("react").Context<MountedWidgets>;
+/** The installed widgets' pages and link actions, as the shell mounted them. */
+export declare function useMountedWidgets(): MountedWidgets;

package/dist/widget-types/dashboard/lib/utils.d.ts

@@ -0,0 +1,3 @@
+import { type ClassValue } from 'clsx';
+/** shadcn's class combiner: merge conditional classes, de-duping Tailwind conflicts. */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/widget-types/dashboard/rpc/widgets.d.ts

@@ -0,0 +1,4 @@
+import type * as impl from '../../src/dashboard-rpc/widgets.js';
+export type * from '../../src/dashboard-rpc/widgets.js';
+export declare const onWidgets: () => Promise<impl.DashboardWidget[]>;
+export declare const runWidgetCommand: (projectId: string, pkg: string, args: string[], command?: string | undefined, acts?: boolean | undefined) => Promise<import("@gemstack/agent-data").PackageCommandResult>;

package/dist/widget-types/dashboard/widget/index.d.ts

@@ -0,0 +1,207 @@
+import { type ComponentType } from 'react';
+import type { AgentStatus } from '../../src/index.js';
+import type { WidgetCommandResult } from '../rpc/widgets.js';
+export type { WidgetCommandResult, AgentStatus };
+/** A registered project that has the widget's package, as a page gets it. */
+export interface WidgetProject {
+    id: string;
+    name: string;
+}
+/**
+ * What a widget page is rendered with. A page reads its sub-path and navigates within itself
+ * through {@link WidgetHost.openPage}; the dashboard's own pages reach it the same way, by the
+ * link convention below.
+ *
+ * A link into a project's files (`WidgetLink.href` such as `tickets/2026-01-01_x.md`) opens the
+ * mounted page named by its first segment, at `/<segment>/<projectId>/<rest…>`: the path a page
+ * gets for it is `[projectId, ...rest]`. So a page that shows one project's file under its own
+ * segment is where every such link in the dashboard lands, and the dashboard names no page.
+ */
+export interface WidgetPageProps {
+    /** The registered projects whose dependencies include the widget's package, in the registry's order. */
+    projects: WidgetProject[];
+    /** The URL's segments after the page's own, decoded: `/logs/a` gives `['a']`. */
+    path: string[];
+}
+/** A page a widget adds: its own URL segment and its row in the sidebar. */
+export interface WidgetPage {
+    /** The page's URL, `/<segment>`: a lowercase letter, then lowercase letters and digits (never a project's id, which always has a dash). */
+    segment: string;
+    /** The sidebar row's label. */
+    label: string;
+    /** The sidebar row's icon; a generic one when absent. */
+    icon?: ComponentType<{
+        className?: string;
+        'aria-hidden'?: boolean;
+    }>;
+    /** The page itself. */
+    Page: ComponentType<WidgetPageProps>;
+}
+/**
+ * A link a dashboard page shows (#1774): the name of some work and where it points. What a
+ * {@link LinkAction} is given. The dashboard knows nothing of what the link names; the page that
+ * shows it does, and says so in these three fields.
+ */
+export interface WidgetLink {
+    /** The link's text: the name of the work. */
+    text: string;
+    /**
+     * Where the link points: a path inside the project's repository (`tickets/2026-01-01_x.md`) or an
+     * absolute URL. Absent for plain text that names work without pointing anywhere.
+     */
+    href?: string;
+    /** How urgent the page says the work is, 0 (only if capacity) to 10 (critical); absent when the page does not say. */
+    priority?: number;
+}
+/** What a link action did: done, or stopped, with the reason the action or its command gave. */
+export type LinkActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * An action a widget offers on the links dashboard pages show (#1774): one verb, done by the
+ * widget package's own command. The dashboard shows it as a button beside any link whose project
+ * has the widget's package, with no page naming the widget: the page shows links, the widget acts
+ * on links, the dashboard puts the two together.
+ */
+export interface LinkAction {
+    /** The button's label, a short verb phrase: "Add to queue". */
+    label: string;
+    /** What the button says once the action is done: "Queued". The label with a check mark otherwise. */
+    doneLabel?: string;
+    /** The button's icon; none otherwise. */
+    icon?: ComponentType<{
+        className?: string;
+        'aria-hidden'?: boolean;
+    }>;
+    /**
+     * Act on the links, in the order given, all in one project. `host` runs the widget package's
+     * own commands in that project. A batch stops at its first failure and says why.
+     */
+    run(host: WidgetHost, projectId: string, links: WidgetLink[]): Promise<LinkActionResult>;
+}
+/** What a widget card is rendered with: the projects that have its package. A card has no URL and no sub-path. */
+export interface WidgetCardProps {
+    /** The registered projects whose dependencies include the widget's package, in the registry's order. */
+    projects: WidgetProject[];
+}
+/**
+ * A card a widget adds to the Overview (#1818): the package's own summary of its data across the
+ * projects that have it, drawn beside the dashboard's own cards. A project none of whose packages
+ * declares a card sees none.
+ */
+export interface WidgetCard {
+    /** Which card this is, for the shell's key and its error line; never shown as a title. */
+    id: string;
+    /** Its place among every installed package's cards, lower first; 50 when unsaid, ties by package name. */
+    order?: number;
+    /** The card itself. */
+    Card: ComponentType<WidgetCardProps>;
+}
+/** What a widget module default-exports. */
+export interface WidgetDefinition {
+    /** The pages the widget adds, each with a sidebar row. */
+    pages?: WidgetPage[];
+    /** The cards the widget adds to the Overview. */
+    cards?: WidgetCard[];
+    /** The actions the widget offers on the links dashboard pages show, wherever the link's project has the widget's package. */
+    linkActions?: LinkAction[];
+    /** A stylesheet to load with the widget, relative to the widget module's own URL. */
+    stylesheet?: string;
+}
+/** Type the default export: `export default defineWidget({ ... })`. */
+export declare function defineWidget(definition: WidgetDefinition): WidgetDefinition;
+/** A run of a project as the dashboard knows it (#1774): enough for a page to name one and link to it. */
+export interface WidgetAgent {
+    /** The run's id, the one {@link WidgetHost.openAgent} takes. */
+    id: string;
+    /** The run's branch, the name the agent gave its work, when its record carries one. */
+    name?: string;
+    /** What the run was asked, as typed or as queued; absent when its record carries none. */
+    ask?: string;
+    status: AgentStatus;
+    /** ISO 8601. */
+    startedAt: string;
+}
+/** What starting a run answered: the run's id, or in words why there is none. */
+export type StartRunResult = {
+    ok: true;
+    agentId: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * What the dashboard gives the widget it is rendering. Every service is generic — a project, a
+ * run, a page, a command — and none names a skill: what a widget composes out of them is its own.
+ */
+export interface WidgetHost {
+    /** The package the widget came from: the one whose commands {@link runCommand} runs. */
+    package: string;
+    /**
+     * Run one of the widget package's own commands in one project and get its JSON output: the
+     * same command an agent runs (`npx <command> …`). `command` names one when the package has several.
+     */
+    runCommand(projectId: string, args: string[], command?: string): Promise<WidgetCommandResult>;
+    /**
+     * The same, for a command that changes the project's data (a claim released, an entry added):
+     * the dashboard then syncs the project's data with origin and forgets what it had read, so the
+     * change shows at once instead of at the next sync. A link action's host runs every command so.
+     */
+    act(projectId: string, args: string[], command?: string): Promise<WidgetCommandResult>;
+    /** Open one agent's page in the dashboard: its live feed while it runs, its record after. */
+    openAgent(projectId: string, agentId: string): void;
+    /** Open a page a widget adds (this one's or another's), at a sub-path: `openPage('tickets', [projectId, file])`. */
+    openPage(segment: string, path?: string[]): void;
+    /**
+     * Start a run in one project with this prompt, with the person's own picks (which tool, which
+     * model, where it runs), and land on it, unless `land` is false: then the dashboard stays where
+     * it is, for a widget that starts several runs in a row. Answers the run's id, or why there is none.
+     */
+    startRun(projectId: string, prompt: string, opts?: {
+        land?: boolean;
+    }): Promise<StartRunResult>;
+    /** Open the project's launcher with this prompt drafted in, to set it up before sending: "Configure first, then run". */
+    configureRun(projectId: string, prompt: string): void;
+    /** The project's runs the dashboard knows: the ones running, and the recorded ones when the project records them. */
+    agents(projectId: string): Promise<WidgetAgent[]>;
+}
+/** What the dashboard knows about the widget it is serving: every service but the commands, which it binds to the package. */
+export type WidgetHostBase = Omit<WidgetHost, 'runCommand' | 'act'>;
+/**
+ * The host for one widget: the dashboard's services, and its commands bound to the widget's own
+ * package. `acts` marks every command as an action on the project rather than a page's read: the
+ * dashboard builds a link action's host with it, so what the action wrote is read back at once.
+ */
+export declare function widgetHost(base: WidgetHostBase, opts?: {
+    acts?: boolean;
+}): WidgetHost;
+/**
+ * Set by the dashboard around every widget page it renders: the widget's package and the
+ * dashboard's services. A test of a widget page provides a whole host here, commands included,
+ * and {@link useWidgetHost} hands it over as it is.
+ */
+export declare const WidgetHostContext: import("react").Context<WidgetHost | WidgetHostBase | null>;
+/** The dashboard's services for the widget being rendered. Only valid inside a widget page. */
+export declare function useWidgetHost(): WidgetHost;
+export { Button, buttonVariants, type ButtonProps } from '../components/ui/button.js';
+export { Badge } from '../components/ui/badge.js';
+export { Card, CardHeader, CardTitle, CardContent } from '../components/ui/card.js';
+export { Skeleton } from '../components/ui/skeleton.js';
+export { Checkbox } from '../components/ui/checkbox.js';
+export { Input } from '../components/ui/input.js';
+export { Popover, PopoverContent, PopoverTrigger } from '../components/ui/popover.js';
+export { RangeSlider } from '../components/ui/slider.js';
+export { Separator } from '../components/ui/separator.js';
+export { ScrollArea } from '../components/ui/scroll-area.js';
+export { Tooltip, TooltipTrigger, TooltipContent } from '../components/ui/tooltip.js';
+export { DropdownMenu, DropdownMenuContent, DropdownMenuCheckboxItem, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from '../components/ui/dropdown-menu.js';
+export { Markdown } from '../components/Markdown.js';
+export { StartAgentButton } from '../components/StartAgentButton.js';
+export { LinkActions, type ProjectLinks, type LinkTargets } from '../components/LinkActions.js';
+export { cn } from '../lib/utils.js';
+export { formatRelative, formatDateTime, formatDuration, formatAge } from '../lib/format-date.js';
+export { usePolled, useLoaded } from '../lib/use-async.js';
+export { useAction } from '../lib/use-action.js';

package/dist/widget-types/src/agent-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An agent's id, derived from the moment it starts. Pure — no node imports — because the sweep
+ * that mints ids ahead of a claim (#1748) is reachable from the dashboard's browser bundle.
+ */
+/** Filesystem-safe, lexicographically-sortable agent id from an ISO start time. */
+export declare function agentIdFromStartedAt(startedAt: string): string;
+/**
+ * The inverse of {@link agentIdFromStartedAt}, for a caller that has the id but not the meta
+ * (#1251): picking which PR is the agent's needs the start time to tell the agent's own PR from a
+ * predecessor's on the same branch name. Undefined for an id that is not one of ours.
+ */
+export declare function startedAtFromAgentId(id: string): string | undefined;

package/dist/widget-types/src/agent-locks.d.ts

@@ -0,0 +1,2 @@
+/** Run `fn` once every earlier holder of `checkout`'s lock has settled. */
+export declare function withAgentLock<T>(checkout: string, fn: () => Promise<T>): Promise<T>;

package/dist/widget-types/src/agent-view.d.ts

@@ -0,0 +1,38 @@
+import type { FrameworkEvent } from './events.js';
+/** One error of a run: one the agent reported through an `error` block (#1500), or one its tool wrote in the diary. */
+export interface AgentError {
+    /** What is wrong, in one line. */
+    headline: string;
+    /** What it ran and what that said, when the agent wrote any. */
+    detail?: string;
+}
+/**
+ * Every error of the run (#1500), oldest first — the count the dashboard shows on the session, and
+ * the latest headline it shows beside it. Two sources: the `error` lines the run's tool writes in
+ * the diary when the coding agent or its transport fails (the message's first line is the
+ * headline, the rest the detail), and the `error` blocks of runs recorded before the daemon
+ * stopped running agents.
+ *
+ * A fold over the log rather than state of its own: an error is an event that happened, so the
+ * list only ever grows, and reopening a finished agent shows exactly what it showed while it ran.
+ */
+export declare function agentErrors(events: readonly FrameworkEvent[]): AgentError[];
+/** The wrapped agent session (#431): its id and a deep link, when one is known. */
+export interface SessionInfo {
+    sessionId?: string;
+    sessionLink?: string;
+    /**
+     * The directory the agent ran in (#1195), from the opening `session` event.
+     *
+     * Taken from the event rather than the filesystem on purpose: an agent that finishes cleanly has
+     * its worktree removed (`tearDownWorktree`), so the event is the only surviving record of where
+     * the session lived — and that path is exactly what `claude --resume` needs to find it again.
+     */
+    workspace?: string;
+}
+/**
+ * The session behind the agent (#431): the workspace from the opening `session`
+ * event, then the id and any deep link from the latest `session-update`. Null before the
+ * session opens. The link is what the old dashboard surfaced as "open session".
+ */
+export declare function sessionInfo(events: readonly FrameworkEvent[]): SessionInfo | null;