@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/dashboard/rpc-serve.js

@@ -0,0 +1,180 @@
+import { hostnameFromHostHeader, isLoopbackHost } from '../loopback-host.js';
+import { setDashboardContext } from '../dashboard-rpc/context.js';
+import { RPC_HANDLERS, RPC_EVENT_STREAM } from '../dashboard-rpc/index.js';
+import { errorMessage } from '../error-message.js';
+/**
+ * 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 function isSameOriginRequest(req) {
+    const origin = req.headers.origin;
+    if (!origin)
+        return true;
+    const host = req.headers.host;
+    if (host && (origin === `http://${host}` || origin === `https://${host}`))
+        return true;
+    let hostname;
+    try {
+        hostname = new URL(origin).hostname;
+    }
+    catch {
+        return false; // malformed Origin: treat as cross-origin
+    }
+    return isLoopbackHost(hostname);
+}
+/**
+ * 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 function isExpectedHost(req, boundHost) {
+    if (boundHost === undefined || !isLoopbackHost(boundHost))
+        return true;
+    const header = req.headers.host;
+    if (!header)
+        return false;
+    const hostname = hostnameFromHostHeader(header);
+    return isLoopbackHost(hostname) || hostname === boundHost;
+}
+/** Where the dashboard's RPCs live. One prefix, so the static handler can decline it by path. */
+export const RPC_PREFIX = '/_rpc';
+/** Read a request body, bounded so a bad caller cannot make the daemon buffer without limit. */
+async function readBody(req, limit = 4 * 1024 * 1024) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        const buf = chunk;
+        size += buf.length;
+        if (size > limit)
+            throw new Error('request body too large');
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+    res.end(text);
+}
+/**
+ * Stream an agent's events as Server-Sent Events (#405). One JSON value per `data:` line; the
+ * response ending IS the clean close the client distinguishes from a dropped connection.
+ *
+ * This was a Telefunc Channel. The Channel gave serialization, reconnect and typing over a
+ * WebSocket-shaped abstraction; what the dashboard actually uses is "push me lines until I go
+ * away", and it brought its own reconnect-with-backoff on top (#948/#1383) because the Channel's
+ * did not distinguish a dead daemon from a finished stream.
+ */
+async function serveEventStream(req, res, url) {
+    const projectId = url.searchParams.get('projectId') ?? '';
+    const agentId = url.searchParams.get('agentId') ?? undefined;
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+        connection: 'keep-alive',
+        // The daemon is behind nothing, but a proxy in front of a `--host` bind would otherwise buffer.
+        'x-accel-buffering': 'no',
+    });
+    let finished = false;
+    const stop = await RPC_EVENT_STREAM(projectId, agentId, value => {
+        res.write(`data: ${JSON.stringify(value)}\n\n`);
+    }, () => {
+        finished = true;
+        res.end();
+    });
+    if (!stop) {
+        // Nothing to stream (unknown project): end cleanly, which the client reads as "done", not
+        // "lost" — the same distinction the Channel's clean-vs-errored close carried.
+        res.end();
+        return;
+    }
+    if (finished)
+        return; // the source was exhausted before it was even wired
+    const finish = () => {
+        stop();
+        res.end();
+    };
+    req.on('close', finish);
+    req.on('error', finish);
+}
+/**
+ * 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 function makeRpcMount(context, opts = {}) {
+    setDashboardContext(context);
+    return async (req, res) => {
+        // A fixed base, like every other request parse here: only the path and the query are read,
+        // and a request carrying an empty or malformed `Host` made this throw — outside the handler's
+        // own try, so the daemon died of the unhandled rejection rather than answering the request.
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname !== RPC_PREFIX && !url.pathname.startsWith(`${RPC_PREFIX}/`))
+            return false;
+        if (!isSameOriginRequest(req)) {
+            res.writeHead(403, { 'content-type': 'text/plain' });
+            res.end('cross-origin request forbidden');
+            return true;
+        }
+        if (!isExpectedHost(req, opts.host)) {
+            res.writeHead(403, { 'content-type': 'text/plain' });
+            res.end('unexpected Host header');
+            return true;
+        }
+        const name = url.pathname.slice(RPC_PREFIX.length + 1);
+        try {
+            if (req.method === 'GET' && name === 'events') {
+                await serveEventStream(req, res, url);
+                return true;
+            }
+            const handler = RPC_HANDLERS[name];
+            if (req.method !== 'POST' || !handler) {
+                sendJson(res, 404, { error: `no such RPC: ${name}` });
+                return true;
+            }
+            const raw = await readBody(req);
+            const args = raw ? JSON.parse(raw) : [];
+            if (!Array.isArray(args)) {
+                sendJson(res, 400, { error: 'the request body must be a JSON array of arguments' });
+                return true;
+            }
+            sendJson(res, 200, { ret: await handler(...args) });
+        }
+        catch (err) {
+            // An RPC that throws is a failed call, not a dead daemon: answer it and stay up. Without
+            // this a rejected promise inside the mount became an unhandled rejection.
+            if (!res.headersSent)
+                sendJson(res, 500, { error: errorMessage(err) });
+            else
+                res.end();
+        }
+        return true;
+    };
+}
+//# sourceMappingURL=rpc-serve.js.map

package/dist/dashboard/rpc-serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-serve.js","sourceRoot":"","sources":["../../src/dashboard/rpc-serve.ts"],"names":[],"mappings":"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"}

package/dist/dashboard/run-handoff.d.ts

@@ -0,0 +1,311 @@
+import { type GitRunner } from '../project.js';
+import { type GhRunner, type LinkedPr, type BranchPrLookup } from './gh.js';
+import type { Cached } from './cache.js';
+import type { AutoHandoffSkip, AutoMergeOutcome, MergeWithheldReason } from '../events.js';
+import { type RunMeta } from '../store/index.js';
+/** One commit a session put on its branch. */
+export interface HandoffCommit {
+    sha: string;
+    /** Short sha, for display. */
+    short: string;
+    subject: string;
+}
+/** One file the session changed, against the branch point. */
+export interface HandoffFile {
+    path: string;
+    insertions: number;
+    deletions: number;
+    /** True for a binary file, where line counts are meaningless. */
+    binary: boolean;
+}
+/** What a finished session produced and what can still be done with it. */
+export interface RunHandoff {
+    /** The branch the work is on. */
+    branch: string;
+    /** The branch still exists in the repo (a deleted or never-created one does not). */
+    exists: boolean;
+    /** What the branch is measured against (the repo's default branch), when one was found. */
+    base?: string;
+    commits: HandoffCommit[];
+    files: HandoffFile[];
+    insertions: number;
+    deletions: number;
+    /**
+     * The session produced nothing to hand off: the branch exists but carries no commit the base
+     * does not already have — or nothing beyond the framework's own bookkeeping (#1291), which is
+     * committed for provenance, never as publishable work. Said out loud, rather than shown as an
+     * empty branch.
+     */
+    empty: boolean;
+    /** The repo has a remote to push to at all. */
+    hasRemote: boolean;
+    /** The branch is on the remote and the remote is at the same commit. */
+    pushed: boolean;
+    /** The branch is already merged into the base. */
+    merged: boolean;
+    /** The PR opened for this branch, when there is one. */
+    pr?: LinkedPr;
+    /** The PR is not known yet, rather than absent (#1028): the lookup is still running. */
+    prPending?: boolean;
+    /**
+     * The files the session changed and never committed, read from its own checkout (#1173).
+     *
+     * The agent is instructed to commit what it *found*, never what it *wrote*, so a settled session
+     * can hold its whole output in an uncommitted tree. That work is not on the branch yet, so it is
+     * not in {@link commits} and it does not make {@link empty} false. Paths rather than a count,
+     * because a no-diff branch must *name* what is waiting instead of offering an Open PR that
+     * GitHub can only refuse. Absent when the caller did not say which checkout the session worked
+     * in — "nobody asked" and "asked, tree clean" are different answers.
+     */
+    pendingFiles?: string[];
+}
+/** Injectable seams so the reader is unit-testable off disk, plus the checkout the session worked in. */
+export interface RunHandoffDeps {
+    git?: GitRunner;
+    pr?: BranchPrLookup;
+    /**
+     * The session's own checkout (#453), when it has one. The branch lives in the project repo and is
+     * read from there; uncommitted work does not, it sits in the tree the agent actually edited.
+     */
+    checkout?: string;
+    /**
+     * When the run started (ISO), so the PR lookup can tell the run's own PR from an earlier run's
+     * on the same branch name (#1251). Without it, only an open PR is trusted.
+     */
+    since?: string;
+}
+/**
+ * The branch a run's work is on.
+ *
+ * Prefers what was recorded while the worktree existed (#799), because the #326 prompt lets the
+ * agent name its own branch, which makes both derivations below a guess. They stay as a fallback
+ * for runs archived before the branch was recorded.
+ */
+export declare function runBranchFor(run: {
+    id: string;
+    branch?: string;
+    sessionName?: string;
+}): string;
+/** What {@link resolveRunPr} needs to know about a run: structurally satisfied by {@link RunMeta}. */
+export interface RunPrRun {
+    id: string;
+    startedAt?: string;
+    branch?: string;
+    sessionName?: string;
+}
+/** The injectable lookup seam for {@link resolveRunPr}: a branch's cached PR history. */
+export type BranchPrsLookup = (cwd: string, branch: string) => Promise<Cached<LinkedPr[]>>;
+/**
+ * The PR that belongs to a run, tried across every branch name the run may have worked under
+ * (#1251/#1255): the recorded branch, the session-name branch, then the run-id branch.
+ *
+ * The ladder is what makes a hands-off web run resolvable: its local worktree is torn down (or
+ * never existed), its meta may carry only a session name whose branch is a reused pin, but the
+ * cloud session pushed the run-id branch, which no other run can ever have. Each candidate is
+ * filtered through {@link pickRunPr} with the run's start time, so a predecessor's PR on a shared
+ * branch name is never the answer. `pending` only when nothing was found and a lookup is still
+ * running, so the caller can ask again rather than render "no PR".
+ */
+export declare function resolveRunPr(cwd: string, run: RunPrRun, prs?: BranchPrsLookup): Promise<Cached<LinkedPr | undefined>>;
+/**
+ * Merge a finished session's open PR (#1391): the Merge action, pressed by a human.
+ *
+ * The direct answer to the withheld-merge ending (#1363): a session whose agent never signalled
+ * ready-for-merge leaves a draft PR behind, and this is the human saying "it's good, land it".
+ * `ghMergePr` marks a draft ready on the way, for exactly that case. Refuses when the run has no
+ * PR or it is no longer open — "already merged" is an answer, not an action.
+ */
+export declare function mergeSessionPr(cwd: string, run: RunPrRun, deps?: {
+    gh?: GhRunner;
+    prs?: BranchPrsLookup;
+}): Promise<HandoffResult>;
+/**
+ * Whether a branch is one a session made, rather than one the user did.
+ *
+ * Only a naming convention, so it is a guess for the case #326 allows — the agent picking its own
+ * branch name. Every caller uses it to decide how loudly to surface something, never to act.
+ */
+export declare function isSessionBranch(branch: string | undefined): boolean;
+/**
+ * Read what a finished session left behind, from the project repo, for `branch`.
+ *
+ * Returns undefined only when `cwd` is not a git repo at all. A branch that no longer exists
+ * still returns a handoff (with `exists: false`), because "that branch is gone" is itself the
+ * answer the dashboard needs to show.
+ */
+export declare function readRunHandoff(cwd: string, branch: string, deps?: RunHandoffDeps): Promise<RunHandoff | undefined>;
+/**
+ * Commit what a session left uncommitted, so what it did is what gets handed off (#1173).
+ *
+ * The automatic handoff commits the session's leftovers on the run's way out, but that happens
+ * when the run process exits, and the finishing step is offered as soon as the agent settles
+ * (#1178), which for a session left open for another turn is much earlier. Pressing the button is
+ * the same instruction given by hand, so it sweeps the same leftovers into what it publishes. The
+ * button only shows for a branch that already carries commits (#1173): a no-diff branch names its
+ * uncommitted work instead of offering a step, so this never turns "nothing committed" into a PR
+ * by itself.
+ *
+ * Two guards, because both failure modes end with the user's own work committed for them: the
+ * checkout has to be the session's own (#453) rather than the project root that `resolveRunCheckout`
+ * falls back to once a worktree is gone, and it has to be sitting on the session's branch.
+ *
+ * Returns whether the handoff may go ahead: true when there was nothing to do, when the guards say
+ * this is not ours to commit, or when the commit succeeded.
+ */
+export declare function commitSessionWork(checkout: string, projectCwd: string, branch: string, git?: GitRunner): Promise<boolean>;
+/** The outcome of a handoff action, in the `{ ok }` shape the dashboard's `useAction` understands. */
+export type HandoffResult = {
+    ok: true;
+    url?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Push a finished session's branch to `origin`.
+ *
+ * Publishing the agent's work under the user's name is the user's call, but since #1102 that call
+ * is made once, up front, by a checkbox that is armed by default, rather than re-taken by hand at
+ * the end of every session. The click is still here for a session that opted out, and it is what
+ * a failed auto-push falls back to.
+ */
+export declare function pushRunBranch(cwd: string, branch: string, git?: GitRunner): Promise<HandoffResult>;
+/**
+ * {@link RunHandoff.base} as a base a PR can actually be opened against.
+ *
+ * The field holds a git ref, because that is what every other use of it needs: `detectBase` reads
+ * `refs/remotes/origin/HEAD`, so it is `origin/main`, and the log range and merged check are both
+ * asking git a question about a remote-tracking ref. `gh pr create --base` is asking GitHub for a
+ * *branch on the remote*, and rejects `origin/main` with "Base ref must be a branch".
+ *
+ * So the conversion belongs at the `gh` boundary rather than in the field. Stripping `origin/`
+ * matches what the rest of this module already assumes: the remote is `origin` (`pushRunBranch`
+ * pushes there, `detectBase` reads its HEAD).
+ */
+export declare function prBaseName(base: string): string;
+/**
+ * The line of a failed git invocation worth showing.
+ *
+ * `execFile` rejects with "Command failed: git push ..." and buries git's own `fatal:` line
+ * further down, which in a one-line panel means the user reads the command back instead of the
+ * reason it failed.
+ */
+export declare function gitReason(err: unknown): string;
+/** What to put on the PR. */
+export interface PullRequestDraft {
+    title: string;
+    body: string;
+    base?: string;
+    /**
+     * Open it as a GitHub draft (#1102). What auto-handoff uses: opening a PR by itself at the end
+     * of every session should not put a review request in anyone's inbox.
+     *
+     * Safe to do only because the interventions queue was taught to keep listing a draft on a
+     * session branch. Left off, a draft would be invisible in both places at once.
+     */
+    draft?: boolean;
+}
+/**
+ * Open a PR for a finished session's branch, pushing it first when the remote does not have it.
+ *
+ * The button opens it ready for review, because a PR a human asked for by name is asking for
+ * review. {@link PullRequestDraft.draft} is the auto-handoff case, which is not.
+ */
+export declare function openRunPullRequest(cwd: string, branch: string, draft: PullRequestDraft, deps?: {
+    git?: GitRunner;
+    gh?: GhRunner;
+}): Promise<HandoffResult>;
+/**
+ * Open a PR for a finished session, deciding from what the run recorded which cases should not
+ * open one. Reads the branch's handoff first: a branch that no longer exists, or a session that
+ * changed nothing, is a clear error rather than an empty PR, and a branch that already has a PR
+ * returns that one. Title is the session name (else the intent's first line, else the id); body
+ * is the intent plus which session did it. This is the handoff decision the dashboard's
+ * open-PR button offers; the RPC layer only resolves which run it is about.
+ */
+export declare function openSessionPullRequest(cwd: string, run: RunMeta, options?: {
+    draft?: boolean;
+}): Promise<HandoffResult>;
+/**
+ * What a session was left armed to do when it ends (#1102).
+ *
+ * Both start true. The point of the feature is that the common case costs nothing: a session that
+ * is simply left alone puts its branch on the remote and opens a PR for it.
+ */
+export interface HandoffIntent {
+    push: boolean;
+    pr: boolean;
+    /**
+     * Merge the PR once it is opened (#1216). Absent = off, unlike the pair above: landing work on
+     * the default branch is not something to arm by default. No action-bar checkbox mutates it —
+     * it comes settled off the run's config.
+     */
+    merge?: boolean;
+}
+/**
+ * Whether an armed merge may actually run (#1363), and if not, why.
+ *
+ * The rule settled on #1390: config *arms* the merge, the agent *authorizes* it. Landing on the
+ * default branch unattended takes (a) the agent having declared the session done via
+ * setReadyForMerge() — the same signal the on-before-mergeable step requires — and (b) the
+ * framework not already knowing of work pending in this session (its own TODO file; never the
+ * global queue, which is decoupled from sessions). A withheld merge is not a failed handoff:
+ * push and PR go ahead, the PR just opens as a draft for a human.
+ *
+ * (b) is a temporary safety belt: the agent's word should ultimately be enough. Deleting it means
+ * deleting `sessionTodoOpen` here and `sessionTodoPending` in todo-loop.ts.
+ */
+export declare function withheldMerge(deps: {
+    readyForMerge: boolean;
+    sessionTodoOpen: boolean;
+}): MergeWithheldReason | undefined;
+/**
+ * What auto-handoff did, so the run can say it as an event (#835).
+ *
+ * A dashboard-started run is spawned with `stdio: 'ignore'`, so anything printed here reaches
+ * nobody: the outcome has to travel as an event or it does not travel at all. Skips are reported
+ * for the same reason a skipped on-before-mergeable is — silence reads as "it ran and did nothing".
+ */
+export type AutoHandoffOutcome = {
+    outcome: 'skipped';
+    reason: AutoHandoffSkip;
+    merge?: AutoMergeOutcome;
+} | {
+    outcome: 'done';
+    pushed: boolean;
+    url?: string;
+    merge?: AutoMergeOutcome;
+} | {
+    outcome: 'failed';
+    step: 'push' | 'pr';
+    error: string;
+};
+/**
+ * Do the end-of-session handoff a session was left armed for (#1102): push the branch, open a
+ * draft PR for it, or both.
+ *
+ * Reads the branch first and refuses on everything that is not a clean hand-off — a branch that is
+ * gone, a session that committed nothing, a repo with no remote, a branch that already has a PR.
+ * Those are the cases where doing it anyway would produce a confusing artefact rather than help.
+ *
+ * The PR is a draft on purpose. Opening one by itself at the end of every session must not put a
+ * review request in anyone's inbox, and the interventions queue keeps listing a session's draft
+ * so the work still comes back to the human.
+ */
+export declare function runAutoHandoff(cwd: string, run: HandoffRun, intent: HandoffIntent, deps?: RunHandoffDeps & {
+    gh?: GhRunner;
+}): Promise<AutoHandoffOutcome>;
+/**
+ * The little a handoff needs to know about the run it is for: which branch, and what to say on
+ * the PR. Narrower than {@link RunMeta} so the run process can call this before its meta is
+ * final, and so a caller cannot quietly start depending on the rest of the run's state.
+ */
+export type HandoffRun = Pick<RunMeta, 'id' | 'branch' | 'sessionName' | 'intent'> & Partial<Pick<RunMeta, 'startedAt'>> & {
+    /**
+     * The GitHub issue the run's ticket tracks (`#42`), when it implements one (#1334). Carried
+     * into the PR title as `(fix #42)` so the squash-merge commit — which inherits the title —
+     * closes the issue; without it an auto-merged quick-win leaves its ticket open.
+     */
+    fixes?: string;
+};
+//# sourceMappingURL=run-handoff.d.ts.map

package/dist/dashboard/run-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-handoff.d.ts","sourceRoot":"","sources":["../../src/dashboard/run-handoff.ts"],"names":[],"mappings":"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"}