@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/widget-types/src/dashboard-rpc/reads.d.ts

@@ -0,0 +1,227 @@
+import type { BridgeBrowserStatus } from '../bridge-browser.js';
+import { type AgentMeta } from '../store/index.js';
+import { type GitHostHome } from '../store/git-host.js';
+import { type WorkspaceDoc } from '../dashboard/docs.js';
+import { type ProjectQueue } from '../dashboard/queue.js';
+import { type ProjectScheduler } from '../dashboard/scheduler-state.js';
+import { type Overview, type RecentAgent } from '../dashboard/overview.js';
+import { type Intervention } from '../dashboard/interventions.js';
+import type { ProjectionRead } from '../dashboard/projects.js';
+import { type OpenQuestion } from '../dashboard/open-questions.js';
+import { type Activity } from '../dashboard/activity.js';
+import { type DashboardData } from '../dashboard/dashboard.js';
+import { type GitStatus } from '../dashboard/git-status.js';
+import { type AgentHandoff } from '../dashboard/agent-handoff.js';
+import type { AgentWorktree } from '../dashboard/types.js';
+import { type FileGitStatus } from '../dashboard/file-status.js';
+import { type FileDiff, type FileChange } from '../dashboard/file-diff.js';
+import { type FileContent } from '../dashboard/file-read.js';
+import { type AgentTree } from '../dashboard/agent-tree.js';
+import type { FrameworkEvent } from '../events.js';
+import type { BridgeEvent, BridgeHello, BridgeQuestion } from '../dashboard/bridge-endpoints.js';
+import type { BridgeAnswer, BridgeContact, BridgeVersion } from '../dashboard/bridge-store.js';
+/**
+ * The project's runs, most-recent first (or `[]`). The archived (finished) runs
+ * from `agents/`, plus every live agent prepended — so the sidebar shows an in-progress
+ * run with a `running` status the moment it starts, not only after it closes.
+ *
+ * Since #736 a project has any number of live agents, each in its own worktree, so this reads
+ * them all (#738) instead of the single one that used to sit at the project path. They come
+ * back as {@link LiveAgent}s, carrying the `cwd` of the checkout that agent is editing.
+ *
+ * One row per id, and where both a live and an archived copy exist the live one wins (#768): a
+ * continued run (#762) has an archive from its first leg while being live again, and the archive
+ * would otherwise show a running agent as finished. The status is not filtered on: `readLiveMeta`
+ * may have just self-healed a dead agent to `stopped` (#716), and that freshly-archived row can
+ * lag `listAgents` by a poll — keeping it regardless leaves the row visible with no flicker.
+ *
+ * An agent relayed to a connected device (#1067) lives only in the daemon's memory, never on disk, so
+ * its in-memory stub is merged in too (#1077): that is what re-opens it after a dashboard reload
+ * instead of losing it.
+ */
+export declare function onAgents(projectId: string): Promise<AgentMeta[]>;
+/**
+ * A web run whose cloud session is waiting on a human — the bridge holds its parked question, or
+ * claude.ai's session list shows it awaiting input (#1332) — is marked waiting (#1668), so its row
+ * says so instead of "in cloud": the archive on disk cannot know, only the daemon's bridge store
+ * does. Every other run passes through untouched.
+ */
+export declare function markCloudWaiting(agent: AgentMeta): AgentMeta;
+/**
+ * A run another machine's daemon started is marked as from another host (#1648): the data branch
+ * is shared precisely so other machines' runs show up here, and a row that looked exactly like
+ * one of this daemon's own sent the user reading the archive by hand to learn whose it was. A run
+ * with no recorded host predates the field and passes through untouched.
+ */
+export declare function markOtherHost(agent: AgentMeta, thisHost?: string): AgentMeta;
+/**
+ * A run that ended clean while the process its card names is still alive on this host is marked
+ * saving: the tool that runs it saves the run's record and cleans up its checkout after the card says
+ * done, and a row that said "done" through that window read as finished with nothing coming. A
+ * run of another host, or with no recorded process, passes through untouched.
+ */
+export declare function markSaving(agent: AgentMeta, thisHost?: string, alive?: (pid: number) => boolean): AgentMeta;
+/**
+ * The agent ids that still have a worktree on disk (#737). An agent that failed or was stopped keeps
+ * its checkout so you can go look at what it was holding; this is how the dashboard knows which
+ * finished run has one to offer removing. Live agents are excluded — their worktree is in use.
+ */
+export declare function onRetainedWorktrees(projectId: string): Promise<string[]>;
+/**
+ * Where a session is working (#798): the checkout it has, its branch, whether it is holding
+ * uncommitted changes, and — once it is no longer live — what that checkout costs on disk.
+ *
+ * The dashboard could not answer "where is this session working". The git status bar reads the
+ * *project*, so a session's own branch was visible nowhere, and a worktree an agent kept (#737) was
+ * a name in a list with no size and no way in.
+ *
+ * Every run works in a checkout of its own, so once that checkout is gone there is no tree left to
+ * be clean or dirty: the answer is then only what the run recorded, its branch and its pull
+ * request. It used to fall back to the project's root and report the user's own checkout (their
+ * branch, their "clean") as the run's.
+ */
+export declare function onAgentWorktree(projectId: string, agentId: string): Promise<AgentWorktree | null>;
+/** One archived agent's event log for replay (or `[]` when the agent or project is gone). */
+export declare function onAgent(projectId: string, agentId: string): Promise<FrameworkEvent[]>;
+/** The surfaced PLAN/TODO docs at the workspace root, in sidebar order (or `[]`). */
+export declare function onDocs(projectId: string): Promise<WorkspaceDoc[]>;
+/** The aggregated open TODO queue across every registered project (#438), most-open first. */
+export declare function onQueue(): Promise<ProjectQueue[]>;
+/** Every project's scheduler (#1774): a projection of each project's `.agent-scheduler/state.json`, one row per project. */
+export declare function onSchedulers(): Promise<ProjectScheduler[]>;
+/** The cross-project Overview (#437): what is running now, the queue size, and recent projects. */
+export declare function onOverview(): Promise<Overview>;
+/** Recent sessions pooled across every project (#shared-shell), newest first, for the home rail. */
+export declare function onRecentAgents(): Promise<RecentAgent[]>;
+/**
+ * The cross-project interventions queue (#632, Queue #624): open PRs that need review, newest first,
+ * plus which projects were read whole (#1625).
+ *
+ * The panels render `items` and ignore the rest. The browser's notifier is the caller that cannot:
+ * it keeps a baseline of what was already waiting when the page opened, and a queue that came back
+ * empty because the git host was unreachable is not a baseline — taking it for one announces the whole
+ * backlog the moment the git host answers.
+ */
+export declare function onInterventions(): Promise<ProjectionRead<Intervention>>;
+/** Every session's open question with its full gate (#1455), longest-waiting first: the launcher's hub. */
+export declare function onOpenQuestions(): Promise<OpenQuestion[]>;
+/**
+ * The cross-project "New activity" feed (#627): recent run started/finished transitions, newest
+ * first, with the projects that were read whole beside them (#1625) — see {@link onInterventions}.
+ */
+export declare function onActivity(): Promise<ProjectionRead<Activity>>;
+/** The Overview dashboard page (#471): the {@link onOverview} rollup plus agent counts, run-status totals, and activity. */
+export declare function onDashboard(): Promise<DashboardData>;
+/**
+ * The project's files for the `#` context picker (#504) and the project's file tree (#492): every
+ * file git sees (tracked + untracked, honoring .gitignore), repo-relative and sorted, via
+ * `git ls-files`. Localhost-only by nature — the relay has no checkout, so it resolves `[]`.
+ * Pass a live `agentId` to list that agent's worktree instead of the project root (#738); a run's
+ * own tree is {@link onAgentTree}.
+ */
+export declare function onProjectFiles(projectId: string, agentId?: string): Promise<string[]>;
+/**
+ * Per-file git status for the project's file tree (#492): repo-relative path -> untracked/
+ * modified/deleted, from `git status --porcelain` in the project root. `{}` when not a repo. A
+ * run's own marks come with its tree, {@link onAgentTree}.
+ */
+export declare function onProjectFileStatus(projectId: string): Promise<Record<string, FileGitStatus>>;
+/**
+ * A run's files for the agent page's Files tab (`agent-tree.ts`): the tree with the paths the run
+ * changed marked, read from its checkout while it exists, then from its branch, then from the
+ * commit its pull request merged as. `gone` when none is left on this machine, `pending` while
+ * the pull request is still being looked up.
+ */
+export declare function onAgentTree(projectId: string, agentId: string): Promise<AgentTree>;
+/**
+ * One changed file's diff, for the tree's hover card (#816). Null when the path is not a changed
+ * file, is unsafe (see `safeRepoPath`), or there is no checkout. For a run it reads the same
+ * source its tree does ({@link onAgentTree}), so it shows the same change the tree marked (#815).
+ *
+ * The status comes from the same git read the marks do, rather than from the caller: a client
+ * that thinks a file is untracked must not be able to make the server read it as one.
+ */
+export declare function onFileDiff(projectId: string, path: string, agentId?: string): Promise<FileDiff | null>;
+/**
+ * What the session changed (#817): every changed file in its worktree with line counts, newest
+ * state each poll. `[]` when nothing changed or there is no checkout.
+ *
+ * Derived from the worktree rather than from the agent's tool calls on purpose. The driver
+ * surfaces a tool's name and not its arguments (#165) — we verify by outcome, not by watching
+ * which tool the agent reached for — so reading git is both the honest source and the one that
+ * works for every agent, not just the ones whose stream carries an edit payload.
+ */
+export declare function onAgentChanges(projectId: string, agentId?: string): Promise<FileChange[]>;
+/**
+ * One unchanged file's contents, for the tree's hover card (#828). Null when the path is unsafe
+ * (see `safeRepoPath`), outside the checkout, or unreadable. For a run it reads the same source
+ * its tree does ({@link onAgentTree}), so it shows the copy the tree is listing (#815).
+ *
+ * The caller picks this or {@link onFileDiff} from the status the tree already holds; a changed
+ * file has a diff worth seeing, an unchanged one has only itself.
+ */
+export declare function onFileContent(projectId: string, path: string, agentId?: string): Promise<FileContent | null>;
+/** The project's page on its git host and the git host's name (#489, #1820), or null: no git host package, no remote there, or the relay. */
+export declare function onGitHostHome(projectId: string): Promise<GitHostHome | null>;
+/**
+ * The project's git status (#491): active branch, dirty flag, linked PR. Null when not a repo /
+ * relay. Pass a live `agentId` to read that agent's worktree, which is the branch and the dirty
+ * state that actually belong to it (#738). A run-scoped read is since-filtered (#1255): an agent on
+ * a reused pinned branch must not wear a predecessor's merged PR as its own badge.
+ */
+export declare function onGitStatus(projectId: string, agentId?: string): Promise<GitStatus | null>;
+/**
+ * The end-of-session handoff (#799): the branch a finished session left its work on, what it
+ * committed, what it changed, and whether that has been pushed or opened as a PR.
+ *
+ * Read from the *project* checkout against the session's branch, not from the session's worktree.
+ * A clean agent's worktree is removed when it finishes, and `resolveAgentPath` then falls back to the
+ * project root — so a worktree-addressed read reports the project's own branch and the user's own
+ * uncommitted changes as though they were the session's. The branch is what outlives the agent, so
+ * the branch is what this asks about.
+ */
+export declare function onAgentHandoff(projectId: string, agentId: string): Promise<AgentHandoff | null>;
+/**
+ * The question a Claude web session is parked on, as reported by the browser bridge (#1237).
+ *
+ * Keyed by cloud session id rather than agent id because that is what the bridge can see: it reads
+ * a claude.ai page, which knows its session and nothing about our runs. The agent view already
+ * derives that id from the agent's own `cloud <url>` event, so the join happens on the client
+ * without the daemon having to index runs by session.
+ *
+ * Returns null for anything unrecognised, so an agent with no bridge, no question, or a target that
+ * is not `web` renders exactly as it did before.
+ */
+export declare function onBridgeQuestion(sessionId: string): Promise<BridgeQuestion | null>;
+/**
+ * Whether anything has reached the browser bridge, and how it went (#1237).
+ *
+ * A misconfigured extension and an uninstalled one both leave no question behind, so "nothing is
+ * showing" cannot be diagnosed from the questions alone. A refused request at least proves
+ * something is trying, and its status says which half is wrong.
+ */
+export declare function onBridgeStatus(): Promise<{
+    lastContact: BridgeContact | null;
+    questions: number;
+    page: BridgeHello | null;
+    version: BridgeVersion | null;
+}>;
+/**
+ * The bridge token, for the setup step where a user pastes it into the extension (#1237).
+ *
+ * Only while the bridge is on, so a daemon with the feature off never hands the secret to a
+ * page. Revealing it here is not a new exposure: anyone who can load this dashboard can already
+ * start runs on this machine, and on a non-loopback bind their browser is holding the same token
+ * as a cookie. What it replaces is the alternative, which was telling people to open
+ * `~/.the-framework.json` and copy a field out of it.
+ */
+export declare function onBridgeToken(): Promise<string | null>;
+/**
+ * Where the answer picked for that session's question stands (#1237): queued for the
+ * extension, delivered, or failed with the extension's reason. Null when nothing was picked.
+ */
+export declare function onBridgeAnswer(sessionId: string): Promise<BridgeAnswer | null>;
+/** What a Claude web session has said so far, as scraped by the browser bridge (#1237). */
+export declare function onBridgeEvents(sessionId: string): Promise<BridgeEvent[]>;
+/** Where the daemon's own bridge browser stands (#1332): off, starting (and on which step), running, or stopped and why. */
+export declare function onBridgeBrowser(): Promise<BridgeBrowserStatus>;

package/dist/widget-types/src/dashboard-rpc/relay-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Run a run-scoped RPC locally, or relay it to the device when `agentId` names an agent this daemon is
+ * relaying to a connected one (#1067 slice 2). For an ordinary local agent the remote lookup is empty and
+ * `local()` runs unchanged. For a remote agent there is no local checkout, so the call is forwarded to the
+ * device over the token; if the device is unreachable, `unreachable` is returned - the same empty/error
+ * shape `local()` gives on a failed read - so the caller never special-cases a remote agent.
+ */
+export declare function relayOr<T>(agentId: string | undefined, fn: string, args: unknown[], local: () => Promise<T>, unreachable: T): Promise<T>;

package/dist/widget-types/src/dashboard-rpc/stream-forward.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Forward an async-iterable of events to a `send` sink until the source is exhausted or
+ * the returned stop function is called (#426). This is the bridge behind a relayed
+ * run's live feed: the agent is an `AsyncIterable` that replays its buffered history then follows
+ * live, and each value becomes one `send(event)`. Transport-agnostic on purpose — a plain
+ * callback, so the pump is driven and tested on its own, and the mount decides what a value
+ * becomes on the wire.
+ *
+ * `onDone` fires when the source runs out on its own — a relayed agent that finished. Without it a
+ * consumer cannot tell "nothing more is coming" from "nothing has happened yet", so an SSE
+ * response would stay open forever on a stream that was already over.
+ *
+ * Returns a stop function that halts forwarding and cancels the iterator, releasing the
+ * follower waiting on the next event. Idempotent. An absent source is a no-op.
+ */
+export declare function forwardStream<T>(iterable: AsyncIterable<T> | undefined, send: (value: T) => void, onDone?: () => void): () => void;

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

@@ -0,0 +1,32 @@
+import { type WidgetCommandResult } from '../project-widgets.js';
+export type { WidgetCommandResult } from '../project-widgets.js';
+/** One widget as the dashboard loads it: where its module is, and which projects have it. */
+export interface DashboardWidget {
+    /** The package that brings it. */
+    package: string;
+    /** The URL of its browser module, served from the first project that has it. */
+    url: string;
+    /** The registered projects whose packages include it, in the registry's order. */
+    projects: string[];
+}
+/**
+ * Every widget any registered project brings (#1774), one per package: the sidebar and the pages
+ * are cross-project, like the Overview. A package several projects install is loaded once, from
+ * the first of them in the registry's order; its page then reads each project through that
+ * project's own command. A project that cannot be read contributes nothing.
+ */
+export declare function onWidgets(): Promise<DashboardWidget[]>;
+/**
+ * Run one of a widget package's commands in one project and answer its JSON output: how a widget
+ * reads (and changes) its own data. Refused for an unknown project and for a package that is not a
+ * widget of that project, so a page can run only its own package's commands, never an arbitrary
+ * program. Once the command has run, the framework forgets what it had read of that project's
+ * provided data (its queue, its runs): the command may have written it, and the next read sees
+ * that at once instead of a cached copy.
+ *
+ * `acts` says the command is a widget's action on the project (a link action), not a page's read:
+ * the framework then also converges the project's data branch with origin, as its clock does
+ * every minute, before forgetting — a package's command writes as a remote writer, straight to
+ * origin, and this machine's copy would otherwise show the write only at the next sync.
+ */
+export declare function runWidgetCommand(projectId: string, pkg: string, args: string[], command?: string, acts?: boolean): Promise<WidgetCommandResult>;

package/dist/widget-types/src/discord-credentials.d.ts

@@ -0,0 +1,79 @@
+import type { RegistrySecrets } from './registry.js';
+/**
+ * Where the daemon's Discord credential — the notifications webhook — comes from (#1095).
+ *
+ * It used to be an environment variable and nothing else, which made "enable Discord" the one
+ * onboarding step you could not finish from the dashboard: you had to edit the daemon's
+ * environment and restart it. It is now also settable from the UI, stored in the registry file
+ * beside the daemon token, and picked up without a restart.
+ *
+ * The values only ever move daemon-side. This module is the rules — resolution, precedence,
+ * validation — and holds no credential itself, which is what lets the dashboard share the same
+ * validation the daemon enforces; reading and writing them is `discord-credentials-store.ts`,
+ * deliberately a separate file so the home-file edge stays out of the browser bundle.
+ *
+ * What the dashboard is told is {@link DiscordCredentialStatus}: which credential exists and where
+ * it came from, never what it is. That is the presence-only contract `onNotifyChannels` has had
+ * since #948, kept on purpose — a stored credential is not a credential you can read back.
+ */
+/** The resolved credentials a daemon runs with. Absent means Discord notifications are off. */
+export interface DiscordCredentials {
+    /** Where notifications are posted (#627). */
+    webhook?: string;
+}
+/**
+ * Which of the two places a credential came from. `env` wins, and the dashboard says so rather
+ * than offering an edit that would not take effect: an environment variable is how a deployment
+ * (a container, a systemd unit, a shared box) configures the daemon, and a value typed into a
+ * browser must not quietly override the machine it is running on.
+ */
+export type CredentialSource = 'env' | 'stored';
+/** Which credentials the daemon holds and where each came from. Presence, never values. */
+export interface DiscordCredentialStatus {
+    webhook?: CredentialSource;
+}
+/** An edit to the stored credentials: a string sets, `null` clears, absent leaves alone. */
+export interface DiscordCredentialsPatch {
+    webhook?: string | null;
+}
+/** The outcome of a {@link DiscordCredentialsStore.save}. */
+export type SaveCredentialsResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** The env var behind each credential, so the two tables below cannot drift apart. */
+export declare const ENV_KEYS: {
+    readonly webhook: 'DISCORD_WEBHOOK';
+};
+/** The registry key behind each credential. */
+export declare const SECRET_KEYS: {
+    readonly webhook: 'discordWebhook';
+};
+/** The credential names, once, so every loop over them covers both by construction. */
+export declare const CREDENTIALS: Array<keyof DiscordCredentials>;
+/** The environment variable a credential is read from, for the UI's "set on the daemon" copy. */
+export declare function credentialEnvVar(credential: keyof DiscordCredentials): string;
+/** The credentials to run with: the environment first, the stored value as the fallback. */
+export declare function resolveDiscordCredentials(env: NodeJS.ProcessEnv, secrets: RegistrySecrets): DiscordCredentials;
+/** The same resolution, reported as presence + origin. The browser-facing half of the pair above. */
+export declare function discordCredentialStatus(env: NodeJS.ProcessEnv, secrets: RegistrySecrets): DiscordCredentialStatus;
+/**
+ * Reject what cannot possibly work, before it is stored and silently does nothing.
+ *
+ * Deliberately shallow: a token is only checked for the shape of a token (one opaque word), and a
+ * webhook for being an http(s) URL rather than for being on discord.com — people front webhooks
+ * with their own proxies, and the daemon has no business refusing a URL it was told to post to.
+ * Whether the credential actually authenticates is Discord's answer to give, and the daemon logs it.
+ */
+export declare function validateCredential(credential: keyof DiscordCredentials, value: string): string | undefined;
+/**
+ * The store the dashboard's context carries (#1095): status out, edits in. The daemon
+ * wires one; a public host (the relay) leaves it unset, so the RPCs report nothing configured and
+ * refuse the write, the same way the preferences store degrades.
+ */
+export interface DiscordCredentialsStore {
+    status(): Promise<DiscordCredentialStatus>;
+    save(patch: DiscordCredentialsPatch): Promise<SaveCredentialsResult>;
+}

package/dist/widget-types/src/driver-names.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The driver vocabulary (#542), node-free so every surface shares one copy: the registry's
+ * preference sanitizer and the dashboard bundle. The names are agent-driver's own, the ones a
+ * run's card carries, so the pick handed to a project's start hook as `DRIVER` and the record
+ * that comes back say the same word. The dashboard's per-driver UI table is keyed by
+ * {@link DriverName}, so a missing entry there is a compile error, not a silent gap.
+ */
+/** The coding agents a person can pick for a run, in the order surfaces list them. */
+export declare const DRIVERS: readonly ['claude-code', 'codex'];
+/** A driver the user can pick. */
+export type DriverName = (typeof DRIVERS)[number];
+/** Whether `value` names a driver we can run. */
+export declare function isDriverName(value: string | undefined): value is DriverName;
+/** How each driver reads in a sentence or on a button. */
+export declare const DRIVER_LABELS: Record<DriverName, string>;
+/**
+ * The pick behind the driver a run's record names (#831). Every surface Claude ran on is still
+ * Claude (#1263): older records name its cloud session and its Actions runner. `undefined` for a
+ * driver no pick claims (a fake one, or a record from a newer version).
+ */
+export declare function driverFromImpl(impl: string | undefined): DriverName | undefined;

package/dist/widget-types/src/error-message.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The message of an unknown caught value. `catch` hands back `unknown`, and this ternary was
+ * spelled out at over twenty call sites; the next variation in one of them would be a bug (a
+ * dropped `String()` turns a thrown string into `[object Object]`'s sibling problems), so the
+ * idiom gets one home. Node-free, exported through /client for the dashboard's use too.
+ */
+export declare function errorMessage(err: unknown): string;

package/dist/widget-types/src/event-stream.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A replayable, multi-consumer stream of events: buffer every event, hand out live async
+ * iterators, and replay history from an offset (tail=N replay).
+ *
+ * Absorbed from `@gemstack/ai-autopilot` when that package was deleted (A2). Its element type
+ * used to default to the supervisor's event; the only caller here passes `FrameworkEvent`, so
+ * the parameter is now required.
+ */
+export declare class EventStream<E> {
+    private readonly buffer;
+    private readonly waiters;
+    private closed;
+    /** Append an event. Wire this in as an `onEvent` sink. Ignored once closed. */
+    readonly push: (event: E) => void;
+    /** Alias for {@link push}, reads well at the `onEvent:` call site. */
+    get sink(): (event: E) => void;
+    /** Events buffered so far, from `fromOffset` (default 0) — Flue-style tail replay. */
+    history(fromOffset?: number): E[];
+    /** Number of events buffered. */
+    get length(): number;
+    /** True once {@link close} has run. */
+    get isClosed(): boolean;
+    /** End the stream: live iterators drain their backlog, then finish. Idempotent. */
+    close(): void;
+    /**
+     * A fresh async iterator that replays every buffered event, then yields new
+     * ones as they arrive, and finishes once the stream is closed and drained.
+     * Independent iterators each keep their own cursor, so late consumers still
+     * see the full history.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<E>;
+}