@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/run-view.d.ts

@@ -0,0 +1,109 @@
+import type { AutoHandoffSkip, FrameworkEvent } from './events.js';
+/** The production-grade loop status (#431): the current pass, whether it passed, and any blockers. */
+export interface LoopStatus {
+    pass: number;
+    passing: boolean;
+    blockers: string[];
+    /** True once the run reached production-grade (the loop ended with no blockers). */
+    productionGrade: boolean;
+    /** True once a `done` bootstrap event has fired (the loop is over). */
+    finished: boolean;
+}
+/**
+ * The latest checklist verdict (#431), from the `checklist`/`improve`/`done` bootstrap
+ * events. Null until a checklist has run — a prototype build never loops, and neither
+ * does a run with no review configured (#1372: no preset, no serve); `done` with zero
+ * passes is not a loop ending, so it does not open a status either. `done` closes an
+ * open status out with the final verdict.
+ */
+export declare function loopStatus(events: readonly FrameworkEvent[]): LoopStatus | null;
+/** The chosen deploy plan (#433): how the app renders and where it lands, from the `deploy` bootstrap event. */
+export interface DeployPlan {
+    render: 'ssr' | 'ssg' | 'spa';
+    target: string;
+    reason: string;
+}
+/** The deploy plan the run decided on, or null before the deploy phase ran. Latest wins. */
+export declare function deployPlan(events: readonly FrameworkEvent[]): DeployPlan | null;
+/** The run's lifecycle progress (#326): the session name it chose and whether it is ready for merge. */
+export interface RunProgress {
+    /** The `[a-z0-9-]` session name (also the branch), once the agent set one via `setSessionName()`. */
+    sessionName?: string;
+    /** True once the agent signalled `setReadyForMerge()`: building (false) -> ready (true). */
+    readyForMerge: boolean;
+}
+/**
+ * The run's lifecycle progress (#326): the latest `session-name` the agent set and whether
+ * a `ready-for-merge` has fired. Drives the dashboard status label + dot (orange building,
+ * green ready). Always returns a value — an untouched run is `{ readyForMerge: false }`.
+ */
+export declare function runProgress(events: readonly FrameworkEvent[]): RunProgress;
+/** What a session will do with its work when it ends (#1102), and what it did. */
+export interface HandoffState {
+    /** Push the branch to `origin` on finish. */
+    push: boolean;
+    /** Open a draft PR on finish. Implies {@link push}. */
+    pr: boolean;
+    /**
+     * Merge the PR once opened (#1216) — armed at launch, no checkbox, never changes mid-run.
+     * Unlike the pair above this defaults to off: merging is opt-in, so a stream from before the
+     * event carried it (#1382) must not read as a run that will land on main by itself.
+     */
+    merge: boolean;
+    /** How the handoff ended, once it has run. Absent while the session is still going. */
+    result?: {
+        outcome: 'skipped';
+        reason: AutoHandoffSkip;
+    } | {
+        outcome: 'done';
+        url?: string;
+    } | {
+        outcome: 'failed';
+        error: string;
+    };
+}
+/**
+ * What the session is armed to hand back, folded from its own events (#1102).
+ *
+ * Both halves start armed, so a run from before this existed — which emits no `handoff-armed` —
+ * reads as armed, which is what it will actually do once it is running new code. Latest wins: the
+ * checkboxes re-emit on every change.
+ *
+ * `initial` seeds the armed pair for a reader whose event stream missed the opening
+ * `handoff-armed` (#1376): the run writes it as its very first event, before the live channel has
+ * attached, so a live tab can only learn the real state from the run record's mirror
+ * (`RunRecord.handoff`) — without it, a session the launcher armed push-only reads as "Open PR".
+ * A `handoff-armed` event in the stream still wins: it is newer than any record snapshot.
+ */
+export declare function handoffState(events: readonly FrameworkEvent[], initial?: {
+    push: boolean;
+    pr: boolean;
+    merge?: boolean;
+}): HandoffState;
+/** The wrapped agent session (#431): its id and a deep link, when one is known. */
+export interface SessionInfo {
+    driver?: string;
+    fake?: boolean;
+    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: a run 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 model id the current leg's agent was started with (#1438). Folded per leg like the
+     * driver/workspace: the latest `session` event wins, and a leg that recorded none clears it.
+     */
+    model?: string;
+}
+/**
+ * The session behind the run (#431): the driver + 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;
+//# sourceMappingURL=run-view.d.ts.map

package/dist/run-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-view.d.ts","sourceRoot":"","sources":["../src/run-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AASlE,sGAAsG;AACtG,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,oFAAoF;IACpF,eAAe,EAAE,OAAO,CAAA;IACxB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,GAAG,IAAI,CAsB/E;AAED,gHAAgH;AAChH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,GAAG,IAAI,CAQ/E;AAED,wGAAwG;AACxG,MAAM,WAAW,WAAW;IAC1B,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4FAA4F;IAC5F,aAAa,EAAE,OAAO,CAAA;CACvB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,WAAW,CAO1E;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,IAAI,EAAE,OAAO,CAAA;IACb,uDAAuD;IACvD,EAAE,EAAE,OAAO,CAAA;IACX;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAA;IACd,uFAAuF;IACvF,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CACpI;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,CAAC,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACxD,YAAY,CAkBd;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,WAAW,GAAG,IAAI,CAgBjF"}

package/dist/run-view.js

@@ -0,0 +1,118 @@
+/**
+ * The latest checklist verdict (#431), from the `checklist`/`improve`/`done` bootstrap
+ * events. Null until a checklist has run — a prototype build never loops, and neither
+ * does a run with no review configured (#1372: no preset, no serve); `done` with zero
+ * passes is not a loop ending, so it does not open a status either. `done` closes an
+ * open status out with the final verdict.
+ */
+export function loopStatus(events) {
+    let status = null;
+    for (const event of events) {
+        if (event.kind !== 'bootstrap')
+            continue;
+        const e = event.event;
+        if (e.type === 'checklist') {
+            status = { pass: e.pass, passing: e.passing, blockers: [...e.blockers], productionGrade: e.passing, finished: false };
+        }
+        else if (e.type === 'improve') {
+            status = { pass: e.pass, passing: false, blockers: [...e.blockers], productionGrade: false, finished: false };
+        }
+        else if (e.type === 'done') {
+            const r = e.result;
+            if (r.passes === 0 && !status)
+                continue;
+            status = {
+                pass: r.passes,
+                passing: r.productionGrade,
+                blockers: [...r.blockers],
+                productionGrade: r.productionGrade,
+                finished: true,
+            };
+        }
+    }
+    return status;
+}
+/** The deploy plan the run decided on, or null before the deploy phase ran. Latest wins. */
+export function deployPlan(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.kind !== 'bootstrap' || event.event.type !== 'deploy')
+            continue;
+        const p = event.event.plan;
+        return { render: p.render, target: p.target, reason: p.reason };
+    }
+    return null;
+}
+/**
+ * The run's lifecycle progress (#326): the latest `session-name` the agent set and whether
+ * a `ready-for-merge` has fired. Drives the dashboard status label + dot (orange building,
+ * green ready). Always returns a value — an untouched run is `{ readyForMerge: false }`.
+ */
+export function runProgress(events) {
+    const progress = { readyForMerge: false };
+    for (const event of events) {
+        if (event.kind === 'session-name')
+            progress.sessionName = event.name;
+        else if (event.kind === 'ready-for-merge')
+            progress.readyForMerge = true;
+    }
+    return progress;
+}
+/**
+ * What the session is armed to hand back, folded from its own events (#1102).
+ *
+ * Both halves start armed, so a run from before this existed — which emits no `handoff-armed` —
+ * reads as armed, which is what it will actually do once it is running new code. Latest wins: the
+ * checkboxes re-emit on every change.
+ *
+ * `initial` seeds the armed pair for a reader whose event stream missed the opening
+ * `handoff-armed` (#1376): the run writes it as its very first event, before the live channel has
+ * attached, so a live tab can only learn the real state from the run record's mirror
+ * (`RunRecord.handoff`) — without it, a session the launcher armed push-only reads as "Open PR".
+ * A `handoff-armed` event in the stream still wins: it is newer than any record snapshot.
+ */
+export function handoffState(events, initial) {
+    const state = { push: initial?.push ?? true, pr: initial?.pr ?? true, merge: initial?.merge ?? false };
+    for (const event of events) {
+        if (event.kind === 'handoff-armed') {
+            state.push = event.push;
+            state.pr = event.pr;
+            // Absent on pre-#1382 events: keep the seed rather than flipping an armed merge off.
+            if (event.merge !== undefined)
+                state.merge = event.merge;
+        }
+        else if (event.kind === 'handoff') {
+            state.result =
+                event.outcome === 'done'
+                    ? { outcome: 'done', ...(event.url ? { url: event.url } : {}) }
+                    : event.outcome === 'failed'
+                        ? { outcome: 'failed', error: event.error }
+                        : { outcome: 'skipped', reason: event.reason };
+        }
+    }
+    return state;
+}
+/**
+ * The session behind the run (#431): the driver + 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 function sessionInfo(events) {
+    let info = null;
+    for (const event of events) {
+        if (event.kind === 'session') {
+            info = {
+                driver: event.driver,
+                fake: event.fake,
+                workspace: event.workspace,
+                ...(event.sessionLink ? { sessionLink: event.sessionLink } : {}),
+                ...(event.model ? { model: event.model } : {}),
+            };
+        }
+        else if (event.kind === 'session-update') {
+            info = { ...(info ?? {}), sessionId: event.sessionId, ...(event.sessionLink ? { sessionLink: event.sessionLink } : {}) };
+        }
+    }
+    return info;
+}
+//# sourceMappingURL=run-view.js.map

package/dist/run-view.js.map

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

package/dist/run.d.ts

@@ -0,0 +1,261 @@
+import { LoopEngine, type BootstrapResult, type BootstrapScope, type DeployTarget, type DomainPreset, type FrameworkDetection, type FrameworkSignals, type RunnerSession } from '@gemstack/ai-autopilot';
+import type { Driver } from './driver/index.js';
+import { type EcoOptions } from './system-prompt.js';
+import { type BindProjectDeps, type RecordMessage } from './await-gate.js';
+import { type TodoLoopResult } from './todo-loop.js';
+import { type ChoicePick, type ChoiceRequest, type FrameworkEvent } from './events.js';
+import type { RunMessages } from './run-messages.js';
+/**
+ * The framework's default full-fledged pass budget. Higher than ai-autopilot's
+ * base of 3 because a from-scratch build spends its first pass or two just
+ * bootstrapping an empty workspace before there is anything to polish (#182).
+ */
+export declare const DEFAULT_MAX_PASSES = 5;
+/** The deploy decision to narrate at the end (plan-only in v1: it does not ship). */
+export interface DeployDecision {
+    render: 'ssr' | 'ssg' | 'spa';
+    target: string;
+    reason: string;
+}
+/**
+ * How to actually boot and serve the generated app so the loop can gate on it
+ * *running*, not just on an agent's review. When set, the run's checklist step
+ * installs, (builds,) starts the app, and fetches it; a failure becomes a
+ * blocker the loop hands back to the agent to fix.
+ */
+export interface ServeConfig {
+    /** The command that starts the app (e.g. `npm run dev`). */
+    command: string;
+    /** Install command run first (e.g. `npm install`). */
+    install?: string;
+    /** Build command run after install (e.g. `npm run build`). */
+    build?: string;
+    /** Port the app listens on. Default 3000. */
+    port?: number;
+    /** How long to wait for it to accept connections. Default 15000ms. */
+    waitMs?: number;
+    /** Path to fetch once it is up. Default `/`. */
+    healthPath?: string;
+    /**
+     * Keep the app serving after a successful run and hand back an
+     * {@link AppPreview} the caller must {@link AppPreview.stop}. Default `false`:
+     * the serve gate boots the app only to check it, then tears it down. The CLI
+     * sets this so the dashboard can show a live preview link until Ctrl+C.
+     */
+    keepAlive?: boolean;
+}
+/** Options for {@link runFramework}. */
+export interface RunFrameworkOptions {
+    /** What the user wants built (the one scope question's answer). */
+    intent: string;
+    /** How much app: a quick prototype (no full-fledged loop) or the full thing. Default `"full"`. */
+    scope?: BootstrapScope;
+    /** The wrapped coding agent. */
+    driver: Driver;
+    /** Absolute workspace path the agent builds in. */
+    cwd: string;
+    /** Model id to pass through to the driver. */
+    model?: string;
+    /** Signals for preset detection (deps/files). Default: none, so the flagship preset wins. */
+    signals?: FrameworkSignals;
+    /**
+     * A user-authored system prompt (from `SYSTEM.md`) injected into every prompt
+     * (#301). Load with `loadUserSystemPrompt(cwd)`. Composed after the built-in
+     * #326 system prompt, so a repo can add its own instructions on top of the default.
+     */
+    systemPrompt?: string;
+    /**
+     * Inject the built-in #326 system prompt into every prompt (#301). Default
+     * `true`; pass `false` (e.g. from `the-framework.yml`) to remove it. The name
+     * is the historical config key: #326 is the anti-lazy-pill's (#297) successor.
+     */
+    antiLazyPill?: boolean;
+    /** This run has a real browser (#824), so the system channel says so. */
+    browser?: boolean;
+    /**
+     * This is a project-less "topic" run (#1120): advertise the bind gate (#1121) in the system
+     * channel and wire {@link bind} so an `await-bind-project` / `await-create-project` gate resolves.
+     */
+    topic?: boolean;
+    /** The bind seams (#1121) a topic run's gate resolves against. Only meaningful with {@link topic}. */
+    bind?: BindProjectDeps;
+    /** Transparent mode (#625): empty the system channel entirely (raw `claude -p`); overrides antiLazyPill/eco. */
+    transparent?: boolean;
+    /** Eco fine-grained control (#314): drop the enabled #326 sections to save tokens. */
+    eco?: EcoOptions;
+    /** In-context directories (#439): added as one `Context:` line to the system prompt. */
+    context?: readonly string[];
+    /**
+     * A user-picked Open Loop domain preset ({loops, prompts}) to run the build
+     * under (#251). Its loops + prompts are materialized into a driver-backed {@link LoopEngine}
+     * exposed as {@link RunFrameworkResult.loop}. Load it with `loadDomainPreset` /
+     * `softwareDevelopmentPreset` (pass `modes` there to activate variants). Omit
+     * for the framework-only run.
+     */
+    preset?: DomainPreset;
+    /**
+     * The active modes for the run (e.g. `['autopilot']`). Narrated with the
+     * {@link preset}, which is expected to be loaded with them already applied.
+     * (`autopilot` no longer steers the system prompt: #556 moved the maintenance
+     * section out, leaving the choice-gate countdown as its whole effect. See #801.)
+     */
+    modes?: readonly string[];
+    /**
+     * The loop event kind the review phase dispatches (#265) — this is what makes a
+     * run a bug fix vs a feature: `bug-fix` fires the preset's bug-fix loop, the
+     * default `major-change` fires its major-change loop. Overrides the preset's own
+     * `defaultEvent`. A kind the preset has no loop for reviews nothing (#1372).
+     * No-op without a preset.
+     */
+    buildEvent?: string;
+    /** Max full-fledged passes. Default {@link DEFAULT_MAX_PASSES} (5). */
+    maxPasses?: number;
+    /** A deploy decision to narrate at the end. Omit to skip the deploy phase. */
+    deploy?: DeployDecision;
+    /**
+     * A real {@link DeployTarget} to *execute* the decided plan (e.g.
+     * `cloudflareTarget` / `dokployTarget`). Requires {@link deploy}. Omit to only
+     * narrate a plan-only decision.
+     */
+    deployTarget?: DeployTarget;
+    /**
+     * Boot-and-serve verification for the full-fledged loop: when set, the
+     * checklist gates on the app actually running, not just an agent review.
+     */
+    serve?: ServeConfig;
+    /**
+     * Where the {@link serve} verification runs (#229). `"local"` (default) boots the
+     * app on the host, adopting the agent's cwd in place. `"docker"` sandboxes it: a
+     * throwaway container is booted, the source is copied in fresh before each check
+     * (the build still runs on the host in this slice), deps install inside the
+     * container, and the app serves on a mapped port — so agent-authored code never
+     * installs or runs on the host. Requires a reachable Docker daemon; no-op without
+     * {@link serve}.
+     */
+    sandbox?: 'local' | 'docker';
+    /**
+     * A pre-provisioned {@link RunnerSession} to run the serve check in, bypassing
+     * {@link sandbox} provisioning. Advanced / testing seam — the caller owns its
+     * lifecycle is handed to the run (it is disposed with the run). Omit to let
+     * {@link sandbox} provision one.
+     */
+    runner?: RunnerSession;
+    /**
+     * A link to the live agent session, shown on the dashboard. Either a literal
+     * URL, or a template with `{sessionId}` (see {@link SESSION_ID_PLACEHOLDER})
+     * that resolves once the wrapped agent reports its real id via `session-update`.
+     */
+    sessionLink?: string;
+    /** Interrupt the run between phases. */
+    signal?: AbortSignal;
+    /**
+     * Pause the run on an interactive choice and await a pick (#304). Called when a
+     * build turn stops to ask (#337/#358): the run emits a `choice` event, calls
+     * this, and resumes on the returned option. Omit for a headless run: the gate
+     * then auto-accepts the recommended option without pausing. The CLI wires this
+     * to the dashboard's Accept button + autopilot countdown.
+     */
+    requestChoice?: (req: ChoiceRequest) => Promise<ChoicePick>;
+    /**
+     * Stop the run once cumulative agent cost reaches this many USD (budget cap,
+     * #322). Checked after each turn that reports usage: the turn that crosses the
+     * cap finishes, then the run stops itself (a clean stop, not a failure). Omit
+     * for no cap. This gates on what *this run* spent, which is a separate question
+     * from where the account's quota stands (readable via #517 / #521, and gated on
+     * by #519's consumption limits).
+     */
+    budgetUsd?: number;
+    /**
+     * Consult the consumption limits between turns (#529): return the limit that
+     * has been reached to pause the run, or `null` to carry on.
+     *
+     * Must answer from a cached reading — a live quota read spawns the whole agent
+     * CLI (~5s). Compose one from a `QuotaPoller` and `consumptionStatus`. Omit to
+     * leave the run ungated, which is also what a gate that throws resolves to:
+     * an unreadable quota must never stop the user's work (Rom's call on #519).
+     */
+    consumptionGate?: () => string | null;
+    /**
+     * Run the backlog loop (#323) after the build settles: consume the agent's own
+     * `TODO_AGENTS.md` one entry per turn until empty, gating
+     * before each entry when {@link requestChoice} is wired. Default: on for real
+     * drivers, off for the fake one (its scripted demo writes no backlog and must
+     * stay deterministic). Set explicitly to force either way.
+     */
+    todoLoop?: boolean;
+    /** Per-run cap on backlog entries worked (#323). Default 25. */
+    todoMaxItems?: number;
+    /**
+     * Continue a stopped build run's conversation (#1467): the captured agent session id to
+     * `--resume`. When set, the build turn sends {@link RunFrameworkOptions.intent} verbatim as a
+     * continuation message instead of rendering the build/extend prompt — the resumed transcript
+     * already carries the scope→build framing, which is exactly why #782 refused to bolt
+     * `--resume-session` onto a fresh build run. Everything around the turn still runs: the
+     * bootstrap narration with its synthesize framing, the review checklist where configured, the
+     * backlog loop and live chat — the flow resumes, not just the conversation.
+     */
+    resumeSessionId?: string;
+    /**
+     * Live chat (#714): once the build settles, take the user's own messages, each
+     * resuming the build session for full context. The session then ends itself when
+     * the queue is idle (#1390) unless {@link stayOpenChat} parks it. Wired only for
+     * an interactive run — a headless run leaves it unset and ends when the build is
+     * done, exactly as before.
+     */
+    messages?: RunMessages;
+    /**
+     * Keep the chat parked for the next message instead of ending on an idle queue (#1390).
+     * Only for a run whose own terminal dashboard is the single surface — it has no daemon
+     * to resume the session through, so ending would leave its composer a dead end.
+     */
+    stayOpenChat?: boolean;
+    /** Record each chat turn to the committed conversation (#908). Best-effort; unset = not recorded. */
+    recordMessage?: RecordMessage;
+    /** Observe the unified event stream. */
+    onEvent?: (event: FrameworkEvent) => void;
+}
+/**
+ * A running instance of the generated app, handed back so the caller can show a
+ * live preview link and keep it up until the user is done (then {@link stop}).
+ */
+export interface AppPreview {
+    /** The localhost URL the app is served at. */
+    url: string;
+    /** The command that started it (e.g. `npm run dev`). */
+    command: string;
+    /** Stop the app and free its runner. Idempotent. */
+    stop(): Promise<void>;
+}
+/** What a run returns. */
+export interface RunFrameworkResult {
+    result: BootstrapResult;
+    detection: FrameworkDetection;
+    events: FrameworkEvent[];
+    /**
+     * The generated app, left running when a {@link ServeConfig} was supplied and
+     * the run finished. The caller owns its lifecycle: show {@link AppPreview.url},
+     * then call {@link AppPreview.stop} (e.g. on Ctrl+C). Absent when no serve
+     * config was set or the app could not be booted.
+     */
+    preview?: AppPreview;
+    /**
+     * The domain preset's review policy, materialized against this run's driver:
+     * its loops plus its prompts as driver-backed passes. Present only when a
+     * {@link RunFrameworkOptions.preset} was supplied. It also drives the run's
+     * review phase (#252): each checklist pass dispatches a `major-change` event
+     * through it.
+     */
+    loop?: LoopEngine;
+    /** How the backlog loop (#323) ended, when it ran. */
+    todo?: TodoLoopResult;
+}
+/**
+ * Run the whole turnkey flow: detect the framework preset, frame the wrapped
+ * agent with its framework skill (page builder + docs), then drive ai-autopilot's `Bootstrap`
+ * (scope → build → full-fledged loop → deploy) entirely *through*
+ * the driver (option A). Every phase, plus the agent's own progress, streams as
+ * a {@link FrameworkEvent}. Reversible: swap in a real deploy target, or a
+ * different `Driver`, without touching this wiring.
+ */
+export declare function runFramework(opts: RunFrameworkOptions): Promise<RunFrameworkResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

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