@openagt/dashboard 0.0.0-stage → 0.8.0

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

@@ -0,0 +1,89 @@
+import { type ProjectRecord } from '../registry.js';
+import { type AgentMeta } from '../store/index.js';
+import type { ProjectError } from '../project-errors.js';
+/**
+ * The multi-project read side (#392): projects the daemon serves come from the registry (#390),
+ * and every read resolves a project id to that project's path before running the per-cwd reader
+ * underneath. One daemon serves them all, running as many agents per project as their own
+ * concurrency allows (#736), each in its own checkout.
+ */
+/** One project's summary for the Projects sidebar (#314). */
+export interface ProjectSummary {
+    /** Registry id (stable, URL-safe). */
+    id: string;
+    /** Absolute repo path. */
+    path: string;
+    /** Display name (the path's basename). */
+    name: string;
+    /** True when the repo still has its `.the-framework/` marker. */
+    activated: boolean;
+    /** ISO timestamp of the project's newest activity: its most recent session. */
+    lastActivityAt?: string;
+    /**
+     * What the daemon's background jobs currently find wrong with the project (#1500), oldest
+     * first — absent when nothing is. Not part of the summary itself: the dashboard's project
+     * list attaches it from the daemon's error state.
+     */
+    errors?: ProjectError[];
+}
+/**
+ * A projection over the registered projects, together with the projects it could actually see.
+ *
+ * A project whose sources cannot be read contributes no items — which is exactly what a project
+ * with nothing waiting contributes. `whole` is what tells the two apart (#1623). Only a caller
+ * that keeps a baseline of what it has already announced needs the distinction; the panels that
+ * simply render the list read `items` and ignore it.
+ */
+export interface ProjectionRead<T> {
+    /** What was found. Possibly only part of it, when some project could not be read. */
+    items: T[];
+    /** The ids of the projects every source answered for, so their share of `items` is all of it. */
+    whole: string[];
+}
+/** Injectable readers so {@link summarizeProject} is unit-testable off disk. */
+export interface SummarizeDeps {
+    isActivated?: (path: string) => Promise<boolean>;
+    /** The project's runs (live + archived), newest-first. Defaults to {@link readAllAgents}. */
+    readAgents?: (path: string) => Promise<AgentMeta[]>;
+}
+/** A project's runs, live prepended to the archived history. Forgiving: a failed read is `[]`. */
+/**
+ * Derive a {@link ProjectSummary} from a registry record: its display name, whether
+ * it is still activated, and its last activity. Forgiving: a failed read reads as an
+ * inactive project with no activity, never a throw.
+ *
+ * Activity is the sessions themselves (B3). It used to be the newest of those and the latest
+ * `LOGS.md` entry — a committed markdown re-narration of the same sessions, which could only ever
+ * be older than the agent it described.
+ */
+export declare function summarizeProject(record: ProjectRecord, deps?: SummarizeDeps): Promise<ProjectSummary>;
+/**
+ * Reads the registry to serve the multi-project endpoints. The dashboard server
+ * holds one of these; the daemon uses the default (the real registry), tests pass
+ * a fake so the server is exercised without touching the user's registry.
+ */
+export interface ProjectsProvider {
+    /** Every registered project, summarized, for the projects read. */
+    list(): Promise<ProjectSummary[]>;
+    /** The absolute path for a registry id, or `undefined` when unknown. */
+    resolvePath(id: string): Promise<string | undefined>;
+}
+/** Injectable readers so {@link defaultProjectsProvider} is unit-testable off the user's registry. */
+export interface ProviderDeps {
+    /** The registry's records. Defaults to {@link listProjects}, forgiving. */
+    listRecords?: () => Promise<ProjectRecord[]>;
+    /** Whether a project's directory is on disk. Defaults to a directory stat. */
+    isDirectory?: (path: string) => Promise<boolean>;
+    /** Defaults to {@link summarizeProject}. */
+    summarize?: (record: ProjectRecord) => Promise<ProjectSummary>;
+}
+/**
+ * A {@link ProjectsProvider} backed by the global registry (#390).
+ *
+ * Only projects whose directory is still on disk are served (#1140): a repo the user renamed or
+ * deleted used to stay in the sidebar as a grey "not activated" entry with no files (#1142),
+ * indistinguishable from a repo that merely lost its marker, and with nothing to click to make it
+ * go away. The registry itself is left alone — the record is skipped, not pruned — so a directory
+ * that comes back (renamed back, a volume remounted) is a project again on the next read.
+ */
+export declare function defaultProjectsProvider(deps?: ProviderDeps): ProjectsProvider;

package/dist/widget-types/src/dashboard/pull-requests.d.ts

@@ -0,0 +1,126 @@
+import { type GitHostFor, type GitHostRequest } from '../store/git-host.js';
+import { type Cached } from './cache.js';
+/**
+ * The pull requests the dashboard reads (#1820), in one place, all through the project's git host
+ * provider (`../store/git-host.ts`): a branch's request, a branch's whole request history, and the
+ * project's open requests. Reads only: opening and landing are `agent-handoff.ts`'s, through the
+ * same provider. The framework runs no git host tool; a project with no git host package has no pull
+ * requests, and every read here answers "none" for it.
+ *
+ * The shapes are the framework's own ({@link LinkedPr}, {@link OpenPr}), copied out of what the
+ * provider answers rather than passed through, so a field a provider adds cannot leak into what
+ * callers store.
+ */
+/** The PR opened for a branch, when there is one. */
+export interface LinkedPr {
+    number: number;
+    url: string;
+    /** OPEN / MERGED / CLOSED, as the git host reports it; UNKNOWN for a recorded request no live read confirmed. */
+    state: string;
+    title: string;
+    /** ISO creation time, when the read included it: what tells one agent's PR from a predecessor's. */
+    createdAt?: string;
+    /**
+     * The head commit the PR covers, when the read included it (#1512): what tells "the branch's
+     * PR already landed everything" from "the session kept working after its PR merged".
+     */
+    headRefOid?: string;
+    /** The commit a merged PR landed as on the base branch, when the git host said. */
+    mergeCommit?: string;
+}
+/** An open PR on the interventions queue (#632). */
+export interface OpenPr {
+    number: number;
+    title: string;
+    url: string;
+    /**
+     * Draft PRs are generally left off the queue: a draft is not asking for review.
+     *
+     * The exception is a draft the framework opened for itself (#1102), which {@link headRefName}
+     * is what tells apart.
+     */
+    isDraft: boolean;
+    /** The branch the PR is from, so a session's own PR can be recognised as ours (#1102). */
+    headRefName?: string;
+    createdAt?: string;
+}
+/**
+ * A best-effort PR lookup, for a named branch or for the checkout's current branch. One type for
+ * both: the named-branch form is the general one, and "the current branch" is just omitting it.
+ */
+export type PrLookup = (cwd: string, branch?: string) => Promise<LinkedPr | undefined>;
+/**
+ * The branch-addressed form, for a caller that always names one (#799): a finished session's
+ * worktree may be gone, so "the current branch" would silently be the project's, not the
+ * session's. Narrower than {@link PrLookup} on purpose, so that invariant is in the type.
+ */
+export type BranchPrLookup = (cwd: string, branch: string) => Promise<LinkedPr | undefined>;
+/** Lists a checkout's open PRs; rejects when the git host could not answer. */
+export type PrLister = (cwd: string) => Promise<OpenPr[]>;
+/** A provider's request as the framework keeps it: the state upper-cased, the head as the request's commit. */
+export declare function linkedPrOf(request: GitHostRequest): LinkedPr;
+/** A provider's open request as the interventions queue keeps it. */
+export declare function openPrOf(request: GitHostRequest): OpenPr;
+/**
+ * Every PR a branch name has ever had, newest first (#1251).
+ *
+ * The newest request for a head *in any state* is what a single view would answer, so a session
+ * whose prompt pins its branch name (`the-framework/triage-quick`) inherits a predecessor's
+ * merged PR as its own. The list form keeps the whole history so {@link pickAgentPr} can decide
+ * which entry, if any, belongs to the agent asking. Resolves `[]` when the project has no git host or
+ * the git host could not answer — indistinguishable from "no PRs", which is what every caller would do
+ * with a failure anyway.
+ */
+export declare function prsForBranch(cwd: string, branch: string, gitHost?: GitHostFor): Promise<LinkedPr[]>;
+/**
+ * {@link prsForBranch} for a caller about to *open* a PR (#1601): a listing the git host could not
+ * answer throws instead of reading as "no PRs", because "none" and "could not tell" must not look
+ * alike there — the difference is a second draft PR on a branch that already has one. A project
+ * with no git host has none, truthfully.
+ */
+export declare function prsForBranchOrThrow(cwd: string, branch: string, gitHost?: GitHostFor): Promise<LinkedPr[]>;
+/** The newest PR of `branch`, in any state, or undefined when it has none or the git host cannot tell. */
+export declare function prView(cwd: string, branch: string, gitHost?: GitHostFor): Promise<LinkedPr | undefined>;
+/**
+ * The cached form of {@link prView} (#1028), and what the dashboard's panels use.
+ *
+ * A PR lookup costs a process where the git reads beside it cost ten milliseconds, and the answer
+ * changes about as often as someone opens a PR. Cached per checkout and branch, shared between
+ * the worktree bar and the handoff summary, and refreshed behind whoever asks. `pending` says the
+ * answer is not known yet rather than that there is no PR — the difference matters to a caller
+ * deciding whether to offer "Open PR". A read with no branch to ask about answers nothing at once.
+ */
+export declare function cachedPrView(cwd: string, branch?: string): Promise<Cached<LinkedPr | undefined>>;
+/** Forget a branch's PR, after an action that changes whether it has one. */
+export declare function forgetPr(cwd: string, branch?: string): void;
+/** The cached form of {@link prsForBranch}, shared through the same read-through cache (#1028). */
+export declare function cachedPrsForBranch(cwd: string, branch: string): Promise<Cached<LinkedPr[]>>;
+/** Forget a branch's PR history, after an action that changes it (opening one). */
+export declare function forgetBranchPrs(cwd: string, branch: string): void;
+/**
+ * The PR that belongs to an agent, out of every PR its branch name has had (#1251/#1255).
+ *
+ * An OPEN PR always counts: a git host allows one open PR per head branch, so whatever is open on the
+ * run's branch is where its pushed commits land. A closed one counts only when it was created
+ * after the agent started (`since`, the agent's `startedAt`) — the oldest such entry, which is the one
+ * this agent's handoff opened. Anything older is a previous agent's PR wearing the same branch name,
+ * which is exactly what showed a merged two-day-old PR as a fresh session's own. Without `since`
+ * only an open PR is trusted.
+ *
+ * `order` exists for the one caller asking a different question (#1512). `'first'` answers
+ * identity — which PR did *this agent* open, so a later agent's must not be the answer. `'latest'`
+ * answers the handoff decision — which PR last saw the branch, so "did the session keep working
+ * past it" is readable off that PR's `headRefOid`; there the oldest entry would call work that a
+ * second PR already landed unlanded.
+ */
+export declare function pickAgentPr(prs: LinkedPr[], since?: string, order?: 'first' | 'latest'): LinkedPr | undefined;
+/**
+ * A project's open PRs, through its git host. Unlike the other reads here it *rejects* when the git host
+ * could not answer — no remote, not logged in, the git host unreachable — instead of resolving `[]`.
+ *
+ * "No PRs are open" and "I could not look" are different answers, and its caller keeps a baseline
+ * of what it has already announced (#1623): taking the second for the first makes the next
+ * successful read announce every already-open PR as new. The caller decides what a failure costs;
+ * it cannot decide what it never hears about. A project with no git host package has none open.
+ */
+export declare function openPrs(cwd: string, gitHost?: GitHostFor): Promise<OpenPr[]>;

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

@@ -0,0 +1,16 @@
+import type { ProjectSummary } from './projects.js';
+import { type QueueFor } from '../store/queue.js';
+/** One project's queue, as the dashboard reads it. */
+export interface ProjectQueue {
+    projectId: string;
+    projectName: string;
+    /** The open entries, in order of work: each the task a future agent is started with. */
+    entries: string[];
+}
+/**
+ * The queue of every project that has one, most entries first: a project one of whose packages
+ * provides the queue is listed even with nothing queued (the card shows the projects it can speak
+ * for), and a project with no provider is left out (it has no queue, so nothing is said about it).
+ * `queueFor` is injectable so this is unit-testable off disk and processes.
+ */
+export declare function collectQueue(projects: ProjectSummary[], queueFor?: QueueFor): Promise<ProjectQueue[]>;

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

@@ -0,0 +1,59 @@
+import { QuotaPoller } from '../quota-poller.js';
+import { type QuotaBoundaryStatus } from '../quota-boundary.js';
+import type { DriverQuotaUnavailableReason, DriverQuotaWindow } from 'agent-driver';
+/**
+ * Everything the dashboard needs to draw the usage panel (#533): the account's
+ * own windows, and where they stand against the quota boundary (#879).
+ */
+export interface QuotaView {
+    /**
+     * The account's quota windows as the agent reported them (session, week, and
+     * a week per model). Empty when we have no reading at all — check
+     * {@link unavailable} before reading that as "nothing used".
+     */
+    windows: DriverQuotaWindow[];
+    /** When the reading was taken, epoch ms. Absent when there has never been one. */
+    readAt?: number;
+    /**
+     * Why there is no reading, when there isn't one. Present alongside stale
+     * `windows` too: the last good reading is kept through a blip, and this says
+     * the newest attempt failed, so the UI can mark it stale rather than blank it.
+     */
+    unavailable?: DriverQuotaUnavailableReason;
+    /**
+     * Where the account stands against its boundary (#879). Absent when there is no
+     * reading, or when the week's reset could not be placed — which is "we don't
+     * know", not "nothing is allowed".
+     */
+    boundary?: QuotaBoundaryStatus;
+}
+/** Where a dashboard reads the quota from. */
+export interface QuotaSource {
+    read(): Promise<QuotaView>;
+    /** Stop any polling behind it. */
+    stop(): void;
+}
+/**
+ * A {@link QuotaSource} backed by a live poller.
+ *
+ * The boundary is measured per read rather than captured: it moves with the clock, so a cached
+ * one would be stale the moment the week's day rolls over. A read costs no reading of the
+ * account: the poller's last good windows are measured again.
+ *
+ * The panel's boundary names no model on purpose: the bar is about the account (#879/#1619).
+ */
+export declare function pollerQuotaSource(poller: QuotaPoller, now?: () => number, 
+/** The slider's position, read per call so moving it shows without a restart (#960). */
+limitOffset?: () => number | Promise<number>): QuotaSource;
+/**
+ * The daemon's own quota source: it polls for the whole life of the dashboard,
+ * not just during an agent, because the panel has to show where the account stands
+ * even when nothing is running.
+ *
+ * Separate from the reading an agent takes for itself: that one dies with the agent, and
+ * nothing stops a running agent over quota anyway. This one exists to draw the bar and the line
+ * unattended work stops at. That line is the schedulers' own spend offset, which `spendOffset`
+ * reads off their state files (#960): the scheduler is what obeys it, so the bar draws what it
+ * obeys. None named, or none readable, is the default cushion, which is the schedulers' default too.
+ */
+export declare function defaultQuotaSource(spendOffset: () => Promise<number | undefined>): QuotaSource;

package/dist/widget-types/src/dashboard/remote-run.d.ts

@@ -0,0 +1,94 @@
+import { EventStream } from '../event-stream.js';
+import type { FrameworkEvent } from '../events.js';
+import type { AgentMeta } from '../store/index.js';
+import type { StartAgentOptions, StartAgentResult } from './types.js';
+/**
+ * The server-side half of "run on a connected device" (#1067). The local daemon holds the saved
+ * device's token, so it - not the browser - drives the remote daemon: it POSTs the agent to the
+ * remote's `/_relay/start` and then fetch-streams the remote's `/_relay/events` back into a local
+ * {@link EventStream}, which the dashboard reads over its normal same-origin `onEvents` channel. So
+ * the browser never talks cross-origin and the token never leaves the two daemons (issue #1067 (b)).
+ *
+ * Authentication is the shared-token cookie (#1051), sent daemon-to-daemon: `Cookie: fw_daemon=<token>` with no
+ * `Origin` header. The remote's guard admits a matching cookie without the browser-only `?token=`
+ * 302, and its `/_rpc` CSRF check (absent Origin passes) is not even on these raw routes.
+ */
+/** Where a relayed agent executes: the remote daemon's origin and its #1051 token. Memory-only. */
+export interface RemoteTarget {
+    url: string;
+    token: string;
+}
+/** The body a relay start forwards to the remote's `/_relay/start`. */
+export interface RelayStartBody {
+    prompt: string;
+    options: StartAgentOptions;
+}
+/**
+ * Health-check a saved device (#1072): a cookie'd `GET /_relay/ping`, true on any 2xx, false on a
+ * non-2xx, an unreachable host, or the timeout. The token stays in memory for the check only, never
+ * persisted, same as {@link startRemoteAgent}. This is how the browser's status dots learn reachable
+ * from not: it has the tokens, the daemon does the cross-origin request.
+ */
+export declare function pingRemote(target: RemoteTarget): Promise<boolean>;
+/**
+ * Start an agent on the remote daemon and return its {@link StartAgentResult} (with the remote's own run
+ * id). A non-2xx or a transport failure surfaces as an `ok: false` result the dashboard shows, the
+ * same shape a local refusal has, so the caller does not special-case remote errors.
+ */
+export declare function startRemoteAgent(target: RemoteTarget, body: RelayStartBody): Promise<StartAgentResult>;
+/**
+ * Relay one run-scoped RPC to the device that owns a remote agent (#1067 slice 2). The local daemon
+ * holds the device token, so a read/diff/handoff/push/PR for a relayed agent runs ON the device: POST
+ * {fn, args} to the remote's /_relay/rpc over the shared-token cookie (#1051) (no Origin), returning the device's
+ * result. Throws on an unreachable device or a non-2xx so the caller falls back to its own empty/error
+ * shape, the same way a failed local read does.
+ */
+export declare function relayRpc(target: RemoteTarget, fn: string, args: unknown[]): Promise<unknown>;
+/**
+ * Fetch-stream a remote agent's newline-delimited events into `onEvent` until the remote closes the
+ * body, the agent ends, or `cancel()` is called. A 401 (the token was rotated) ends the stream
+ * cleanly rather than as an error, so the dashboard sees a normal `done`, not a lost connection.
+ * Returns a cancel function; calling it aborts the fetch and releases the reader.
+ */
+export declare function streamRemoteEvents(target: RemoteTarget, agentId: string, onEvent: (event: FrameworkEvent) => void, onEnd?: () => void): () => void;
+/**
+ * The local daemon's live relayed runs (#1067), keyed by the remote agent id. Registering an agent opens
+ * an {@link EventStream} the dashboard reads through `onEvents`, fed by {@link streamRemoteEvents}
+ * from the remote. This map is where a saved device's token lives daemon-side: in memory, for the
+ * run's lifetime.
+ *
+ * The `targets` map outlives the event pump (#1067 slice 2): a finished remote agent's post-run reads,
+ * open-PR and merge still have to reach the device after its event stream has ended, so the device
+ * target is kept until {@link dispose} clears it, not dropped when the stream closes.
+ *
+ * The `metas` map (#1077) holds a local {@link AgentMeta} stub per relayed agent so `onAgents` can show a
+ * remote run in the session list and re-open it after a dashboard reload; {@link list} projects it
+ * per project. Same lifetime as `targets`: it outlives the event stream and is cleared on dispose.
+ */
+export declare class RelayedAgents {
+    private readonly agents;
+    private readonly targets;
+    private readonly metas;
+    /** Open a local stream for a remote agent and start pumping the remote's events into it. */
+    register(agentId: string, target: RemoteTarget, meta: AgentMeta, projectId: string): void;
+    /** The live event stream for a relayed agent, or undefined when this daemon is not relaying it. */
+    get(agentId: string | undefined): EventStream<FrameworkEvent> | undefined;
+    /** The device a relayed agent runs on, kept past the event stream so post-run push/PR still reach it. */
+    target(agentId: string | undefined): RemoteTarget | undefined;
+    /** A project's relayed run stubs (#1077), newest-first, so `onAgents` can surface them in the list. */
+    list(projectId: string): AgentMeta[];
+    /** Fold each relayed event into the agent's list row via the store's own reducer (#1077), so the
+     *  local stub mirrors the device: the terminal status on `end`, the waiting flag while it is parked
+     *  (#785), the driver once its session starts. Events carry no write time, so this stamps its own. */
+    private apply;
+    /** Close a relayed agent's event stream (not its target). Idempotent. */
+    private endStream;
+    /** Stop every pump, close every stream, and forget every device target + list stub, on daemon shutdown. */
+    dispose(): void;
+}
+/**
+ * Fold one relayed event into the memory-only row of a run on a device: what the device's own
+ * card would say, kept here because that card is on the device. The events are the ones a run's
+ * diary yields: the agent's session id, its cost, its end.
+ */
+export declare function foldRelayedEvent(meta: AgentMeta, event: FrameworkEvent, at: string): AgentMeta;

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

@@ -0,0 +1,102 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { FrameworkEvent } from '../events.js';
+import type { PreferencesStore } from '../registry.js';
+import type { QuotaSource } from './quota.js';
+import type { ModelsSource } from './models.js';
+import type { BridgeBrowserOwner } from '../bridge-browser.js';
+import type { ProjectErrorsReader } from '../project-errors.js';
+import type { AddProjectResult, StartAgentOptions, StartAgentResult } from './types.js';
+import type { AgentMeta } from '../store/index.js';
+/** Wired by the daemon so `sendStart` can reach the daemon's own `startAgent` closure. */
+export type StartAgentHandler = (prompt: string, options: StartAgentOptions, projectId?: string) => StartAgentResult | Promise<StartAgentResult>;
+/** Wired by the daemon so `sendAddProject` can install + register a repo (#433). */
+export type AddProjectHandler = (path: string) => AddProjectResult | Promise<AddProjectResult>;
+/** Resolve an agent to its live event stream: the relay feeds `onEvents` from its own in-memory stream
+ * rather than a file on disk (#426), and the daemon feeds an agent it is relaying from a device (#1067).
+ * Returns undefined when there is no in-memory stream, so `onEvents` falls back to tailing the log. */
+export type EventsSource = (projectId: string, agentId?: string) => AsyncIterable<FrameworkEvent> | undefined;
+/** Look up the device a relayed agent (#1067) executes on, or undefined for an ordinary local agent. The
+ *  daemon wires this from its live relayed-agent map; a run-scoped RPC uses it to forward a remote agent's
+ *  read/steer/handoff to that device instead of resolving a (nonexistent) local checkout. */
+export interface RemoteAgents {
+    target(agentId: string | undefined): {
+        url: string;
+        token: string;
+    } | undefined;
+    /** A project's relayed run stubs (#1077), so `onAgents` can show a remote agent in the list and re-open it after a reload. */
+    list(projectId: string): AgentMeta[];
+}
+/**
+ * What every RPC acts through.
+ *
+ * Every field is required (D3). These used to be optional because three hosts served this same
+ * surface — the daemon, a per-session foreground dashboard, and a public relay — each wiring a
+ * different subset, so every RPC carried an "absent capability" branch and the client rendered a
+ * degradation matrix. There is one host now, and it wires all of it.
+ */
+export interface DashboardContext {
+    startAgent: StartAgentHandler;
+    addProject: AddProjectHandler;
+    /** The in-memory event stream for an agent relayed from a connected device (#1067), else undefined. */
+    eventsSource: EventsSource;
+    /** The relayed-agent lookup (#1067 slice 2), so a run-scoped RPC can tell a local agent from one
+     *  running on a connected device and forward the call there. */
+    remote: RemoteAgents;
+    /** The user-preferences store (#410), over the registry file. */
+    preferences: PreferencesStore;
+    /** The quota source behind the usage panel (#533). */
+    quota: QuotaSource;
+    /** Which models each coding agent offers, for the agent and model menu. */
+    models: ModelsSource;
+    /** What a project currently suffers from (#1500): the daemon's error state, read per project. */
+    projectErrors: ProjectErrorsReader;
+    /** The daemon's own bridge browser (#1332): status, and show/hide/restart on request. */
+    bridgeBrowser: BridgeBrowserOwner;
+}
+/**
+ * CSRF guard for the state-changing RPCs. A browser attaches an `Origin`
+ * header to every cross-site request, so we reject any POST whose Origin is not this
+ * same server (or a loopback host) — otherwise a page on `evil.com` could `fetch()` the
+ * localhost dashboard and start or steer a run. An absent Origin means a non-browser caller
+ * (curl, the test suite) with no ambient session to abuse, so it passes. Lives here beside
+ * the mount, its only caller.
+ */
+export declare function isSameOriginRequest(req: IncomingMessage): boolean;
+/**
+ * DNS-rebinding guard, the other half of the CSRF check above. A page on `evil.com` whose DNS
+ * re-answers as `127.0.0.1` is *same-origin* with this server as far as the browser is concerned,
+ * so its `fetch()` takes the passing branch of {@link isSameOriginRequest} — and every RPC behind
+ * the mount, `sendStart` included, is reachable from a page the user merely visited.
+ *
+ * The `Host` header is what still gives the attacker away: it carries the name the browser was
+ * asked for (`evil.com`), not the address it resolved to. So when we are bound to loopback, the
+ * only `Host` a real user's browser can send is a loopback one (or the bound address itself) —
+ * anything else is a rebound name and is rejected. An absent `Host` is rejected too when we are
+ * enforcing: HTTP/1.1 requires it, and every browser sends it.
+ *
+ * A non-loopback bind (`--host`, #1051) is reached by a hostname we cannot predict, so there is
+ * no allowlist to check against; that case gates behind the shared daemon token instead. Hosts
+ * that never pass a bind host at all (the relay, which serves a public domain) are unaffected.
+ */
+export declare function isExpectedHost(req: IncomingMessage, boundHost: string | undefined): boolean;
+/** Where the dashboard's RPCs live. One prefix, so the static handler can decline it by path. */
+export declare const RPC_PREFIX = "/_rpc";
+/**
+ * Mount the dashboard's RPC surface (#405) on the daemon's `node:http` server: `POST /_rpc/<name>`
+ * for the calls, `GET /_rpc/events` for the live stream. It runs in the daemon process, so
+ * `sendStart` reaches the daemon's own `startAgent` through the wired {@link DashboardContext}.
+ *
+ * Cross-origin POSTs are rejected (CSRF: a page on evil.com must not steer or start a session), as
+ * are requests carrying someone else's `Host` when we are bound to loopback (DNS rebinding: the
+ * same page must not reach us by pointing its own name at `127.0.0.1`). Pass `opts.host` — the
+ * address the server is bound to — to enable that second check. Returns whether the request was
+ * the RPC surface's.
+ *
+ * This replaced Telefunc (F3), which required a build-time transform over every `.telefunc.ts`
+ * file, a registration table pinning each RPC to the client-baked key of the *dashboard* source
+ * path it was re-exported from, and a request-context indirection for wiring that never varied
+ * per request. What it bought over this was type-safety across a package boundary that A7 removed.
+ */
+export declare function makeRpcMount(context: DashboardContext, opts?: {
+    host?: string;
+}): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;

package/dist/widget-types/src/dashboard/run-inbox.d.ts

@@ -0,0 +1,30 @@
+import { type InboxLine } from 'agent-driver';
+/**
+ * What a person says to a run (#1774): their own words, or their answer to the question the run
+ * stopped on. The daemon runs no agent, so the line reaches the run through what the run's tool
+ * reads: the inbox file in the run's checkout while the run works, the project's `resume` hook
+ * line once it has ended. The framework names no tool in either.
+ */
+/**
+ * The inbox of a run, in its checkout's `.the-framework/`: the file agent-driver's session reads
+ * when a turn ends, one JSON line per message or answer. The run's tool hands the session the
+ * same path.
+ */
+export declare const RUN_INBOX_FILE = "inbox.jsonl";
+/** What a write to a run came to: done, or why not, in words the surface shows. */
+export type SteerResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Hand one line to a run of the project at `cwd`. A run that is working takes it from its inbox
+ * when its turn ends. A run that has ended (done, stopped, failed, or waiting on its question) is
+ * continued through the project's `resume` hook. A run that ends while the line is on its way
+ * would leave it in an inbox nobody reads, so the run is looked at again after the write, and
+ * what is still in the inbox then is taken back and resumes the run instead.
+ */
+export declare function sayToRun(cwd: string, agentId: string, line: InboxLine, deps?: {
+    isWorking?: (cwd: string, agentId: string) => Promise<boolean>;
+}): Promise<SteerResult>;

package/dist/widget-types/src/dashboard/scheduler-state.d.ts

@@ -0,0 +1,64 @@
+import type { ProjectSummary } from './projects.js';
+/** The file the scheduler keeps its state in, at the project's root; per user, hidden from git by the tool. */
+export declare const SCHEDULER_STATE_FILE = ".agent-scheduler/state.json";
+/** What the last tick decided for one scheduled command, one line for a person. */
+export interface SchedulerDecision {
+    command: string;
+    outcome: string;
+    /** The run's id when the tick started one: the same id the agent's record and checkout carry. */
+    run?: string;
+}
+/** The last tick as the state file remembers it. */
+export interface SchedulerTick {
+    /** ISO timestamp. */
+    at: string;
+    decisions: SchedulerDecision[];
+    /** Why the tick decided nothing, when it could not. */
+    note?: string;
+}
+/** One command of the project's schedule, as the scheduler's last tick read it, with this machine's switch. */
+export interface SchedulerCommand {
+    command: string;
+    /** How often at most, as written (`1d`). */
+    every?: string;
+    /** The check, when the line has one. */
+    when?: string;
+    /** Whether it runs on this machine: the machine's switch, else what the line says. */
+    on: boolean;
+}
+/** A project's scheduler as the card shows it. */
+export interface SchedulerState {
+    /** Whether the state file exists and parses: a project without it has no scheduler set up. */
+    present: boolean;
+    /** Whether ticks start agents. */
+    on: boolean;
+    /** Whether the scheduler's process outlives the dashboard that started it. */
+    keepAlive: boolean;
+    /** Whether the scheduler's own process is alive on this machine. */
+    running: boolean;
+    /** The model every run starts on. */
+    model?: string;
+    /** How far past the quota boundary this project's unattended runs may start, in percentage points. */
+    spendOffset?: number;
+    lastTick?: SchedulerTick;
+    /** The schedule's commands with their switches; empty until the scheduler has ticked once with a schedule. */
+    commands: SchedulerCommand[];
+}
+export interface ProjectScheduler extends SchedulerState {
+    projectId: string;
+    projectName: string;
+}
+/**
+ * Read one project's scheduler state. `isAlive` is the process probe; injectable so a test can
+ * decide what "running" means without holding a process.
+ */
+export declare function readSchedulerState(cwd: string, isAlive?: (pid: number) => boolean): Promise<SchedulerState>;
+/** Every registered project's scheduler, one row per project in registry order, a failing read as not set up. */
+export declare function collectSchedulers(projects: ProjectSummary[], read?: (cwd: string) => Promise<SchedulerState>): Promise<ProjectScheduler[]>;
+/**
+ * The spend offset the usage panel draws (#960), read off the projects' schedulers: the loosest
+ * one, since it is the one that lets unattended work spend the furthest; `undefined` when no
+ * scheduler names one. The panel's slider writes it back through each project's `offset` hook,
+ * so the schedulers agree unless one was set by hand.
+ */
+export declare function loosestSpendOffset(states: readonly SchedulerState[]): number | undefined;

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

@@ -0,0 +1,28 @@
+import { type Ticket, type TicketDetail, type TicketsMeta } from '@gemstack/skill-tickets';
+export type { TicketsMeta, TicketGithubLink } from '@gemstack/skill-tickets';
+/**
+ * A ticket as the dashboard shows it: the `tickets` skill's row, with the holder of its claim
+ * resolved against this project's own agents (#1748). A lock names an agent id — the same id
+ * the agent's checkout is named with — so a claim the daemon minted, or an agent on this machine
+ * made with the `tickets` command, resolves to the agent's page and its session name; a holder
+ * this project has no record of (another machine's agent, a cloud session's branch name) is
+ * shown as written.
+ */
+export interface WorkspaceTicket extends Ticket {
+    /** The agent whose id the lock names, when it is one of this project's: its id and, once named, its session name. */
+    lockedByAgent?: {
+        id: string;
+        name?: string;
+    };
+}
+/** One ticket with its entire markdown, for its own page. */
+export interface WorkspaceTicketDetail extends WorkspaceTicket, TicketDetail {
+}
+/** The project's tickets, off the skill's checkout under `.branches/agent-data`, holders resolved. */
+export declare function readTickets(cwd: string): Promise<WorkspaceTicket[]>;
+/** One ticket by filename, full text included; `null` when there is no such ticket. */
+export declare function readTicket(cwd: string, file: string): Promise<WorkspaceTicketDetail | null>;
+/** Whether the project has any ticket at all (#958): a listing, for the onboarding checklist's poll. */
+export declare function hasTickets(cwd: string): Promise<boolean>;
+/** When the tickets last caught up with GitHub (#1208), or `{}` when nothing has recorded it. */
+export declare function readTicketsMeta(cwd: string): Promise<TicketsMeta>;