@openagt/dashboard 0.8.0 → 0.9.0

package/dist/todo-loop.d.ts

@@ -1,110 +0,0 @@
-import type { DriverSession } from 'agent-driver';
-import type { ChoicePick, ChoiceRequest, FrameworkEvent } from './events.js';
-/**
- * The backlog loop (#323): once the main work settles, consume the agent queue one entry per
- * turn until it is empty. The agent writes the queue itself (a very large scope, the Maintenance
- * follow-ups, or the [Research] preset's deep-dive picks all add entries); the framework only
- * drives: read the queue, gate ("start the next item?") when someone can answer, prompt the agent
- * to complete exactly one entry, take it off the queue, repeat. Termination is Rom's call on the
- * issue: stop when the queue is empty. The dashboard's autopilot auto-accepts the per-item gate,
- * so `[x] autopilot` consumes the whole queue unattended; autopilot off pauses before each entry.
- *
- * The queue is the `queue` skill's (#1748): it lives on the `agent-data` branch, read and changed
- * through the skill's library — the framework holds no copy and edits no file of its own. Which
- * ticket an entry links to is the `tickets` skill's rule.
- */
-/**
- * Does this session's own backlog still have open work (#1363)?
- *
- * Reads only `TODO_<SESSION_NAME>.agent.md` — the file the [Research] preset (and a very-large
- * scope) has the agent keep for its own session. Never the global queue: the queue is decoupled
- * from sessions (#1390), and withholding a merge on it would mean auto-merge never fires while
- * the project has any backlog at all. `false` on a missing or unreadable file, and on a session
- * name that could not name a file — no pendingness known is not pendingness.
- *
- * TEMPORARY SAFETY BELT, built to be deleted (#1390): the agent's setReadyForMerge() is the
- * authorization, and this only catches the agent declaring done while its own session file says
- * otherwise. When the agent's word is deemed enough, delete this function and its single call
- * site in `maybeAutoHandoff`.
- */
-export declare function agentTodoPending(cwd: string, sessionName: string | undefined): Promise<boolean>;
-/**
- * The ticket the next drain agent will pick up, or `undefined` when there is none (#1117).
- *
- * "Next" is the first open entry of the queue, because that is what the [Drain queue] preset
- * says to work ("the FIRST open entry only") and the queue reads in file order. Read from the
- * same copy the sweep already consults when it decides whether there is anything to drain, so
- * the entry this names is the entry that decision was made on.
- *
- * A best guess by construction: the agent reads the queue a moment later, and an entry taken off
- * in between would move it on. Being wrong here costs a mislabelled lane on the Overview and
- * nothing else — no run is started or steered by this.
- */
-export declare function nextQueuedTicket(cwd: string): Promise<string | undefined>;
-/**
- * The ticket an agent started by hand is about to implement, when that agent is a drain (#1117).
- *
- * The daemon already does this for the sweep's own drain, off the `drains` flag on the job. An agent
- * fired from the dashboard reaches the same start with none of that context, so a hand-fired drain
- * showed up working on nothing: the agent implemented the ticket, and the lane it belonged in stayed
- * empty. Same read as the sweep's, so both agree on which entry is next.
- *
- * Undefined for anything that is not a drain, and for a drain over an empty queue. The `read` seam
- * is for tests; production always takes the default.
- */
-export declare function ticketForPrompt(prompt: string, cwd: string, read?: (cwd: string) => Promise<string | undefined>): Promise<string | undefined>;
-/** Why the loop ended. */
-export type TodoLoopReason = 
-/** The queue is empty (or was never written) — the success case. */
-'empty'
-/** The user picked "stop" at a per-item gate. */
- | 'stopped'
-/** Two removals in a row could not be written to the `agent-data` branch. */
- | 'stalled'
-/** The item cap was reached with entries still open. */
- | 'max-items';
-/** What {@link runTodoLoop} resolves with. */
-export interface TodoLoopResult {
-    /** Queue entries worked (turns taken), regardless of outcome. */
-    completed: number;
-    /** Why the loop ended. */
-    reason: TodoLoopReason;
-    /**
-     * An answer marked `stop` (#358) inside an item's turn — a plan the user declined — ends the
-     * whole session, not just the loop. Distinct from the benign `reason: 'stopped'` per-item gate,
-     * which only stops draining the queue. The caller aborts the session on this.
-     */
-    sessionStopped?: boolean;
-}
-/** Options for {@link runTodoLoop}. */
-export interface TodoLoopOptions {
-    /** The live driver session the agent already owns. */
-    session: DriverSession;
-    /** The agent's checkout; the queue is read from the repository it belongs to. */
-    cwd: string;
-    /** Emit the loop's events onto the agent stream. */
-    emit: (event: FrameworkEvent) => void;
-    /**
-     * The interactive gate handler (#304). When wired, the loop pauses before each
-     * entry ("start the next item?") — the dashboard's autopilot auto-accepts, so
-     * autopilot off means a human gate per item (#323). Headless runs don't pause.
-     */
-    requestChoice?: ((req: ChoiceRequest) => Promise<ChoicePick>) | undefined;
-    /** The agent signal; aborting (the Stop button, an answer marked stop) ends the loop. */
-    signal?: AbortSignal | undefined;
-    /** Hard cap on entries worked in one agent. Default {@link DEFAULT_MAX_TODO_ITEMS}. */
-    maxItems?: number | undefined;
-}
-/**
- * Drive the queue to empty: read the next open entry (fresh off the `agent-data` branch), gate, prompt
- * the agent to complete exactly that entry, take it off the queue, and repeat. The removal is the
- * framework's, not the agent's (#1582): the queue lives on a branch the agent's checkout does not
- * hold, and the one writer model keeps every edit going through the same funnel. Caps make it
- * safe to leave unattended (#322's concern): the agent's budget/abort signal ends any turn, a
- * hard item cap bounds the agent, and two removals in a row failing to land stop the loop
- * instead of re-working the same entry. A queue turn is a turn like any other: await gates
- * (`showChoices()` / `showMultiSelect()`) and the signals (`showMarkdown()`, `setReadyForMerge()`,
- * `open-pr`) are honored here too.
- */
-export declare function runTodoLoop(opts: TodoLoopOptions): Promise<TodoLoopResult>;
-//# sourceMappingURL=todo-loop.d.ts.map

package/dist/todo-loop.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"todo-loop.d.ts","sourceRoot":"","sources":["../src/todo-loop.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGjD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAK5E;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAKrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG/E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAoB,GACpE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAED,0BAA0B;AAC1B,MAAM,MAAM,cAAc;AACxB,oEAAoE;AAClE,OAAO;AACT,iDAAiD;GAC/C,SAAS;AACX,6EAA6E;GAC3E,SAAS;AACX,wDAAwD;GACtD,WAAW,CAAA;AAEf,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAA;IACjB,0BAA0B;IAC1B,MAAM,EAAE,cAAc,CAAA;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,OAAO,EAAE,aAAa,CAAA;IACtB,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAA;IACX,oDAAoD;IACpD,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACrC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,SAAS,CAAA;IACzE,yFAAyF;IACzF,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IAChC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9B;AAQD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAwFhF"}

package/dist/todo-loop.js

@@ -1,175 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { parseQueueEntries, queueDone, readQueueEntries } from '@gemstack/skill-queue';
-import { ticketFromQueueEntry } from '@gemstack/skill-tickets';
-import { requestChoices, runAwaitRounds } from './await-gate.js';
-import { drainsQueue } from './preset-catalog.js';
-import { createTurnSignalEmitter } from './turn-gate.js';
-/**
- * The backlog loop (#323): once the main work settles, consume the agent queue one entry per
- * turn until it is empty. The agent writes the queue itself (a very large scope, the Maintenance
- * follow-ups, or the [Research] preset's deep-dive picks all add entries); the framework only
- * drives: read the queue, gate ("start the next item?") when someone can answer, prompt the agent
- * to complete exactly one entry, take it off the queue, repeat. Termination is Rom's call on the
- * issue: stop when the queue is empty. The dashboard's autopilot auto-accepts the per-item gate,
- * so `[x] autopilot` consumes the whole queue unattended; autopilot off pauses before each entry.
- *
- * The queue is the `queue` skill's (#1748): it lives on the `agent-data` branch, read and changed
- * through the skill's library — the framework holds no copy and edits no file of its own. Which
- * ticket an entry links to is the `tickets` skill's rule.
- */
-/**
- * Does this session's own backlog still have open work (#1363)?
- *
- * Reads only `TODO_<SESSION_NAME>.agent.md` — the file the [Research] preset (and a very-large
- * scope) has the agent keep for its own session. Never the global queue: the queue is decoupled
- * from sessions (#1390), and withholding a merge on it would mean auto-merge never fires while
- * the project has any backlog at all. `false` on a missing or unreadable file, and on a session
- * name that could not name a file — no pendingness known is not pendingness.
- *
- * TEMPORARY SAFETY BELT, built to be deleted (#1390): the agent's setReadyForMerge() is the
- * authorization, and this only catches the agent declaring done while its own session file says
- * otherwise. When the agent's word is deemed enough, delete this function and its single call
- * site in `maybeAutoHandoff`.
- */
-export async function agentTodoPending(cwd, sessionName) {
-    // The prompt asks for [a-z0-9-]+; anything wider (a path separator above all) names no file.
-    if (!sessionName || !/^[A-Za-z0-9._-]+$/.test(sessionName))
-        return false;
-    const md = await readFile(join(cwd, `TODO_${sessionName}.agent.md`), 'utf8').catch(() => undefined);
-    return md !== undefined && parseQueueEntries(md).length > 0;
-}
-/**
- * The ticket the next drain agent will pick up, or `undefined` when there is none (#1117).
- *
- * "Next" is the first open entry of the queue, because that is what the [Drain queue] preset
- * says to work ("the FIRST open entry only") and the queue reads in file order. Read from the
- * same copy the sweep already consults when it decides whether there is anything to drain, so
- * the entry this names is the entry that decision was made on.
- *
- * A best guess by construction: the agent reads the queue a moment later, and an entry taken off
- * in between would move it on. Being wrong here costs a mislabelled lane on the Overview and
- * nothing else — no run is started or steered by this.
- */
-export async function nextQueuedTicket(cwd) {
-    const first = (await readQueueEntries(cwd))[0];
-    return first ? ticketFromQueueEntry(first) : undefined;
-}
-/**
- * The ticket an agent started by hand is about to implement, when that agent is a drain (#1117).
- *
- * The daemon already does this for the sweep's own drain, off the `drains` flag on the job. An agent
- * fired from the dashboard reaches the same start with none of that context, so a hand-fired drain
- * showed up working on nothing: the agent implemented the ticket, and the lane it belonged in stayed
- * empty. Same read as the sweep's, so both agree on which entry is next.
- *
- * Undefined for anything that is not a drain, and for a drain over an empty queue. The `read` seam
- * is for tests; production always takes the default.
- */
-export async function ticketForPrompt(prompt, cwd, read = nextQueuedTicket) {
-    if (!drainsQueue(prompt))
-        return undefined;
-    return read(cwd).catch(() => undefined);
-}
-/** The default per-agent cap on queue entries, so one agent cannot work the queue forever. */
-const DEFAULT_MAX_TODO_ITEMS = 25;
-/** How many consecutive failed removals before the loop stops rather than spins. */
-const MAX_STALLS = 2;
-/**
- * Drive the queue to empty: read the next open entry (fresh off the `agent-data` branch), gate, prompt
- * the agent to complete exactly that entry, take it off the queue, and repeat. The removal is the
- * framework's, not the agent's (#1582): the queue lives on a branch the agent's checkout does not
- * hold, and the one writer model keeps every edit going through the same funnel. Caps make it
- * safe to leave unattended (#322's concern): the agent's budget/abort signal ends any turn, a
- * hard item cap bounds the agent, and two removals in a row failing to land stop the loop
- * instead of re-working the same entry. A queue turn is a turn like any other: await gates
- * (`showChoices()` / `showMultiSelect()`) and the signals (`showMarkdown()`, `setReadyForMerge()`,
- * `open-pr`) are honored here too.
- */
-export async function runTodoLoop(opts) {
-    const { session, cwd, emit } = opts;
-    const maxItems = opts.maxItems ?? DEFAULT_MAX_TODO_ITEMS;
-    // One emitter for the whole queue, so ready-for-merge fires once across every item
-    // and a pull-request description only re-emits when it changes.
-    const gateDeps = {
-        requestChoice: opts.requestChoice,
-        emit,
-        signal: opts.signal,
-        emitTurnSignals: createTurnSignalEmitter(emit),
-    };
-    let completed = 0;
-    // The queue emptied: announce it if we did any work, and report a clean finish.
-    // Both the mid-loop find and the post-loop re-check funnel through here.
-    const finishEmpty = () => {
-        if (completed > 0)
-            emit({ kind: 'log', message: `Queue done: empty after ${completed} item(s).` });
-        return { completed, reason: 'empty' };
-    };
-    for (let item = 0; item < maxItems; item++) {
-        if (opts.signal?.aborted)
-            break;
-        const entries = await readQueueEntries(cwd, { fresh: true });
-        if (!entries.length)
-            return finishEmpty();
-        const next = entries[0];
-        const preview = next.length > 100 ? `${next.slice(0, 100)}…` : next;
-        if (item === 0)
-            emit({ kind: 'log', message: `Queue: ${entries.length} open item(s).` });
-        // The per-item gate (#323): pause before starting a new entry when someone
-        // can answer. Interactive-only, like the plan-approval gate — a headless agent
-        // emits no gate and just proceeds (autopilot semantics, budget-capped).
-        if (opts.requestChoice) {
-            const picked = await requestChoices({
-                id: item === 0 ? 'todo-next' : `todo-next-${item}`,
-                title: `Start the next queue item? (${entries.length} open)`,
-                options: [
-                    { id: 'proceed', label: `Work on: ${preview}` },
-                    { id: 'stop', label: 'Stop the queue loop' },
-                ],
-                recommended: 'proceed',
-                requestChoice: opts.requestChoice,
-                emit,
-                ...(opts.signal ? { signal: opts.signal } : {}),
-            });
-            if (picked === 'stop') {
-                emit({ kind: 'log', message: `Queue loop stopped by you (${entries.length} item(s) left).` });
-                return { completed, reason: 'stopped' };
-            }
-        }
-        emit({ kind: 'log', message: `Queue item ${completed + 1}: ${preview}` });
-        // Complete exactly this entry, honoring await gates. The queue is not the agent's to touch
-        // (#1582): it lives on the `agent-data` branch, and the removal below is the framework's.
-        const prompt = `Work on exactly this task from the project's agent queue, and nothing else:\n\n${next}\n\nComplete it fully and verify your work. Do not start any other task; the framework takes this entry off the queue when the turn ends.`;
-        const rounds = await runAwaitRounds({ session, prompt, ...gateDeps });
-        completed++;
-        // A plan the user declined with a stop-marked answer (#358) ends the whole session, not just
-        // this loop — so the session does not go on to publish work that was just rejected. The caller
-        // aborts on `sessionStopped`; `reason` stays descriptive of the loop itself.
-        if (rounds.stopped) {
-            emit({ kind: 'log', message: `Session stopped by your answer (${entries.length} item(s) left).` });
-            return { completed, reason: 'stopped', sessionStopped: true };
-        }
-        // Take the entry off the queue. A no-op when someone else already removed it meanwhile — the
-        // write re-reads the fresh queue either way. Retried inline rather than across rounds: a
-        // removal that never lands would re-serve the same entry, and re-doing finished work is worse
-        // than stopping with the queue intact.
-        let landed = false;
-        for (let tries = 0; tries < MAX_STALLS && !landed; tries++) {
-            landed = (await queueDone(cwd, next)).ok;
-        }
-        if (!landed) {
-            emit({ kind: 'log', message: `Queue loop stopped: "${preview}" could not be taken off the queue after ${MAX_STALLS} attempt(s).` });
-            return { completed, reason: 'stalled' };
-        }
-    }
-    // Aborted mid-loop (the Stop button, an answer marked stop): the agent is ending anyway,
-    // so report a clean stop without extra narration.
-    if (opts.signal?.aborted)
-        return { completed, reason: 'stopped' };
-    const remaining = await readQueueEntries(cwd);
-    if (!remaining.length)
-        return finishEmpty();
-    emit({ kind: 'log', message: `Queue loop stopped at the ${maxItems}-item cap; ${remaining.length} item(s) left.` });
-    return { completed, reason: 'max-items' };
-}
-//# sourceMappingURL=todo-loop.js.map

package/dist/todo-loop.js.map

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

package/dist/turn-gate.d.ts

@@ -1,144 +0,0 @@
-import { continuationPrompt, type Question, type QuestionOption } from 'agent-driver';
-import type { FrameworkEvent } from './events.js';
-/**
- * The framework-owned "await" protocol (#337 / #339): the *code side* of the
- * `showChoices()` / `showMultiSelect()` + `AWAIT` macros the system prompt delegates. The
- * driver runs each agent turn as a black box to completion (#165), so the only way
- * the framework can learn the agent stopped to ask (rather than deciding for itself)
- * is a signal in the turn's final message. This appends one to the system prompt: it
- * does not restate the macros, it pins *how* to emit an awaited choice so the
- * turn-boundary gate can detect it. Kept minimal and self-contained so it survives the
- * #326 wording still being written. The text lives in `prompts/protocols/await.md` (#551).
- */
-export declare const AWAIT_PROTOCOL = "## Awaiting a choice\nWhen these instructions tell you to showChoices() / showMultiSelect() / showMarkdown() and then AWAIT, do not decide for the user.\nEnd your turn with one fenced code block, then stop.\nTag it `await-choices`:\n```await-choices\n{ \"title\": \"<the question>\", \"options\": [{ \"label\": \"<option>\", \"detail\": \"<optional one-liner>\" }], \"recommended\": \"<the label to default to>\" }\n```\nEvery question you stop to ask is this one block, whatever it is about:\n- An approval is two options: `{ \"title\": \"Ship this?\", \"options\": [{ \"label\": \"Approve\" }, { \"label\": \"Decline\", \"stop\": true }], \"recommended\": \"Approve\" }`.\n- A plan or document you wrote and want signed off adds `\"file\": \"PLAN_<slug>.agent.md\"`, and the framework shows that file beside the question.\n- Several answers at once (showMultiSelect) adds `\"multi\": true`, and `\"default\": true` on the entries that start checked.\n- `recommended` is what the framework picks when nobody is there to answer, so name the option that is safe to take unattended \u2014 never an option marked `stop`.\n- `\"stop\": true` marks an answer that ends the session instead of resuming you: the user is taking over and will come back with fresh instructions. Mark the option that rejects your work \u2014 declining a plan, saying no to the approach \u2014 and leave it off everything else. You are not re-prompted with that answer, so do not plan around being told it.\n\nThe framework shows it, waits for the user, and re-prompts you with their answer. Do not continue past it on your own.\n\n## Handing the browser to a human\nWhen you are working in a browser and hit something you cannot or should not get past yourself \u2014 a login wall, a captcha, an SSO or 2FA step \u2014 stop and hand it over. Never type a password, never attempt a captcha, and never use a credential you found lying around in the repo or the environment. Ask with the same `await-choices` block, naming the page and recommending the option that is true when nobody is there:\n```await-choices\n{ \"title\": \"<what the human needs to do> (<the page you are stuck on>)\", \"options\": [{ \"label\": \"Handled it\" }, { \"label\": \"Could not handle it\" }], \"recommended\": \"Could not handle it\" }\n```\nThe user acts in that browser, then you are re-prompted. If their answer says it was not handled, do not retry the same page \u2014 say what you could not reach and work on what you can, or stop.\n\n## Showing a document without waiting\nTo display markdown in the side panel without blocking (a plan, a summary, a writeup) and keep working, put a `show-markdown` block anywhere in your turn. The first line is its title:\n```show-markdown\n# <title>\n<the markdown body>\n```\nThis just shows it; you do not stop. Re-emit the same title to update that view in place.";
-/**
- * Told to a hands-off agent only (#1225): the session leaves this machine and nothing here sees
- * its workspace, so whatever it produces has to be committed and put in a pull request before it
- * ends. The text lives in `prompts/protocols/hands_off.md`.
- */
-export declare const HANDS_OFF_PROTOCOL = "## This session runs detached \u2014 land everything\nIt was handed to a remote service: no machine sees its workspace, and nothing here follows it to\nthe end. So before ending: commit your work on your session branch and open a pull request for\nit. If the deliverable is analysis, a plan, or a decision, write it into committed files \u2014 a\nresult that lives only in this conversation, or in a gitignored file, reaches nobody. End without\na pull request only when the task genuinely required no repository change, and say so explicitly\nin your final message.";
-/**
- * Told to the agent only when the agent has a browser (#824): that it has one, and that anything
- * it needs to see or act on goes through the chrome-devtools tools rather than `WebFetch`.
- * Lives in `prompts/protocols/browser.md`.
- */
-export declare const BROWSER_PROTOCOL = "## You have a real browser\n\nThis run has a real Chrome attached, through the `chrome-devtools` tools (`new_page`, `navigate_page`, `click`, `fill`, `take_snapshot`, `evaluate_script`). It is the same browser a human can watch and take over, so use it for anything you need to *see* or *act on*: pages that render their content with JavaScript, a flow you have to click through, a form to fill, an app you are checking actually works.\n\nWhen you only need to read a page, `WebFetch` is still the better tool: it is faster and hands you the text directly. Use the browser when `WebFetch` would come back with nothing useful, such as a page that is blank until its JavaScript runs.\n\nPrefer navigating within a single page rather than opening new pages, so the user can more easily watch you navigate.";
-/**
- * The session-lifecycle protocol (#326): the code side of the `setReadyForMerge()` action the
- * system prompt calls out, plus the pull request and error blocks. Like {@link AWAIT_PROTOCOL},
- * it does not restate *when* to act — the system prompt owns that — it only pins *how* to
- * emit the signal so the turn-boundary can detect it. All are non-blocking: the agent
- * emits the block and keeps going (the framework records it and reflects it in the
- * dashboard). Injected alongside AWAIT_PROTOCOL. The text lives in
- * `prompts/protocols/signal.md` (#551). The session name is not a signal (#1725): the agent
- * names its branch through `branches name`, and the name is read off the branch.
- */
-export declare const SIGNAL_PROTOCOL = "## Ready for merge\nWhen you call setReadyForMerge() \u2014 you believe the work is complete and ready for human review \u2014 emit an empty `ready-for-merge` block. This flips the dashboard status from building to ready; it does not stop your turn.\n```ready-for-merge\n```\n\n## Opening a pull request\nWhenever you emit `ready-for-merge`, emit an `open-pr` block too, naming and describing the work. The Framework opens the pull request for you \u2014 you do not need to run `gh pr create` yourself. Write it like a commit message: the first line is the title, the rest is the body.\n```open-pr\n<one line naming what the change does, under 100 characters>\n\n<what changed, and why \u2014 markdown, as long as it needs to be>\n```\nWithout it the pull request has no name for your work and can only repeat the prompt you were given, which does not say what the work turned out to be. The Framework supplies the rest: the ticket's issue reference where there is one, and recording the number so every surface shows the same pull request. You do not stop, and you can re-emit it as the work changes \u2014 the last one is used. Opening the pull request yourself instead still works; you then own all of the above.\n\n## Reporting an error\nWhen you hit something only the user can fix \u2014 a missing file you were told to read, a command that will not run, a login you do not have \u2014 emit an `error` block saying what is wrong, then carry on or stop as the task requires. The first line is the headline; anything below it is the detail.\n```error\n<what is wrong, in one line>\n\n<the detail: what you ran, what it said>\n```\nThe Framework marks it in the session log and counts it on the session, so the user sees it without reading the whole log. It does not stop your turn and it does not ask the user anything \u2014 use `AWAIT` for a question. Report the same thing once: a re-emitted identical block is ignored.";
-/** One option of an await gate: what the user picks between. The shape is agent-driver's question option. */
-export type AwaitOption = QuestionOption;
-/** A question the agent stopped to ask, parsed from an `await-choices` block (#337). The shape is agent-driver's question. */
-export type ParsedAwaitGate = Question;
-/**
- * How many times the agent may stop to ask, and be resumed, before an agent stops honoring
- * gates and just finishes. A property of the await protocol, so every path that runs gates
- * shares it: a build and a direct prompt each used to declare their own.
- */
-export declare const MAX_AWAIT_ROUNDS = 5;
-export { continuationPrompt };
-/**
- * What a session that cannot simply be ended is told when the user picks a `stop` option (#358,
- * #1554). A local session is never re-prompted with a stopping answer — it just ends — but a
- * cloud session lives on claude.ai where nothing of ours can end it, so the bridge types this
- * instead: the decision, and that the user is taking over from here.
- */
-export declare function takeoverPrompt(question: string, answer: string): string;
-/**
- * The log line for the other outcome: the user picked a `stop` option, so there is no
- * continuation prompt and the session ends here (#358). Addressed to the user rather than to the
- * agent — the agent is not told anything, which is the point — and it names the answer, because
- * "stopped" on its own reads like a failure when it was a decision.
- */
-export declare function stopMessage(answer: string): string;
-/** A non-blocking markdown view the agent pushed via a `show-markdown` block (#441). */
-export interface ParsedMarkdownView {
-    /** Stable id (a slug of the title), so re-showing the same title updates in place. */
-    id: string;
-    /** The view's title (the first `# ` heading, or a fallback). */
-    title: string;
-    /** The markdown body (the heading line removed). */
-    markdown: string;
-}
-/**
- * Parse every `show-markdown` block (per {@link AWAIT_PROTOCOL}) out of a turn's text
- * (#441) — a non-blocking view the agent pushed to the side panel, so a turn may carry
- * several and does not stop. Each block's first `# ` line is the title (the rest is the
- * body); a block with no heading falls back to "Note". Blank blocks are skipped, and two
- * blocks that slug to the same id keep the later one (an in-turn update). Never throws.
- */
-export declare function parseMarkdownViews(text: string): ParsedMarkdownView[];
-/** What the agent asked the framework to open a pull request with (#1567/#1618). */
-export interface ParsedPullRequest {
-    /** The agent's name for the work: the block's first line, when it reads as a title. */
-    title?: string;
-    /** What changed and why: everything after that line, or the whole block when there is no title. */
-    description?: string;
-}
-/**
- * Parse the pull request the agent asked for this turn (#1567), from the last non-empty
- * `open-pr` block (per {@link SIGNAL_PROTOCOL}). Returns `undefined` when the agent wrote none,
- * which simply leaves the handoff describing the work itself. A later block in the same turn
- * wins, so an agent may revise it as the work changes.
- *
- * The block is how an agent opens a pull request *through the framework* rather than by
- * reaching for `gh` itself: the title and the description are the agent's, and the handoff keeps
- * the parts that have to be consistent — the ticket's issue reference and recording the number
- * on the agent.
- *
- * Shaped like a commit message, and read like one: the first line names the work, the rest
- * describes it. A first line too long to be a name is not treated as one (#1618) — the block is
- * all description then, and the title falls back to the session's name rather than being cut
- * mid-sentence, which is how a raw prompt ended up as a permanent commit subject.
- */
-export declare function parsePullRequest(text: string): ParsedPullRequest | undefined;
-/** An error the agent reported this turn (#1500), split the way the block is written. */
-export interface ParsedError {
-    /** What is wrong, in one line: the block's first line. */
-    headline: string;
-    /** What it ran and what that said: everything below the headline, when the agent wrote any. */
-    detail?: string;
-}
-/**
- * Parse the errors the agent reported this turn (#1500), from every non-empty `error` block
- * (per {@link SIGNAL_PROTOCOL}), in the order they were written.
- *
- * Unlike the other signals, every block is kept rather than only the last: two different things
- * going wrong in one turn are two errors, and collapsing them would lose one. Blocks that are
- * empty are skipped — an error with nothing to say is not an error.
- */
-export declare function parseErrors(text: string): ParsedError[];
-/**
- * Whether the agent signalled `setReadyForMerge()` this turn (#326): the presence of a
- * `ready-for-merge` block (per {@link SIGNAL_PROTOCOL}) anywhere in the text. Non-blocking
- * and body-less — it just flips the agent from building to ready-for-review.
- */
-export declare function parseReadyForMerge(text: string): boolean;
-/**
- * Parse the await gate a turn ended on (#337): agent-driver's question parser, which every driver
- * also reports as a `question` event. Returns `undefined` when the agent just finished.
- */
-export declare function parseAwaitGate(text: string): ParsedAwaitGate | undefined;
-/**
- * Emit the {@link PROTOCOLS_SIGNAL} signals an agent turn carries: markdown views, the errors it
- * reported, `setReadyForMerge()`, and a pull-request description. The session name is not among
- * them: the agent names its branch through the `branches` skill, and the name is read off it. Every turn the framework prompts goes through
- * one of these, because the protocols are unconditional (see `composeAgentSystem`) — the
- * agent is told it can signal on any turn, so any turn we don't parse drops the signal.
- *
- * The returned function holds the dedupe state for the turns it covers: `ready-for-merge`
- * fires once, a pull-request description only re-emits on an actual
- * change, and an error is logged once however often the agent restates it. Each caller makes one
- * for its own span of turns (a build's await rounds, the whole backlog), so keep it for as
- * many turns as should share that dedupe rather than making one per turn.
- */
-export declare function createTurnSignalEmitter(emit: (event: FrameworkEvent) => void): (text: string) => void;
-//# sourceMappingURL=turn-gate.d.ts.map

package/dist/turn-gate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"turn-gate.d.ts","sourceRoot":"","sources":["../src/turn-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAiB,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AACpG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAKjD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,ozFAAkB,CAAA;AAE7C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,2jBAAsB,CAAA;AAGrD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,uyBAAoB,CAAA;AAEjD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,24DAAmB,CAAA;AAE/C,6GAA6G;AAC7G,MAAM,MAAM,WAAW,GAAG,cAAc,CAAA;AAExC,8HAA8H;AAC9H,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAA;AAEtC;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAA;AAIjC,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAE7B;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAA;CACjB;AAWD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAerE;AASD,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAc5E;AAED,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAA;IAChB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAUvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AASD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAExE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CA0BrG"}