astrocode-workflow 0.4.0 → 0.4.2

package/dist/src/tools/workflow.js

@@ -0,0 +1,345 @@
+// src/tools/workflow.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import { withTx } from "../state/db";
+import { buildContextSnapshot } from "../workflow/context";
+import { decideNextAction, createRunForStory, startStage, completeRun, failRun, getActiveRun, EVENT_TYPES, } from "../workflow/state-machine";
+import { buildStageDirective, directiveHash } from "../workflow/directives";
+import { injectChatPrompt } from "../ui/inject";
+import { nowISO } from "../shared/time";
+import { newEventId } from "../state/ids";
+import { debug } from "../shared/log";
+import { createToastManager } from "../ui/toasts";
+// Agent name mapping for case-sensitive resolution
+export const STAGE_TO_AGENT_MAP = {
+    frame: "Frame",
+    plan: "Plan",
+    spec: "Spec",
+    implement: "Implement",
+    review: "Review",
+    verify: "Verify",
+    close: "Close"
+};
+export function resolveAgentName(stageKey, config, agents, warnings) {
+    // Use configurable agent names from config, fallback to hardcoded map, then General
+    const agentNames = config.agents?.stage_agent_names;
+    let candidate;
+    if (agentNames && agentNames[stageKey]) {
+        candidate = agentNames[stageKey];
+    }
+    else {
+        candidate = STAGE_TO_AGENT_MAP[stageKey] || "General";
+    }
+    // Validate that the agent actually exists in the registry
+    if (agents && !agents[candidate]) {
+        const warning = `Agent "${candidate}" not found in registry for stage "${stageKey}". Falling back to General.`;
+        if (warnings)
+            warnings.push(warning);
+        else
+            console.warn(`[Astrocode] ${warning}`);
+        candidate = "General";
+    }
+    // Final guard: ensure General exists, fallback to built-in "general" if not
+    if (agents && !agents[candidate]) {
+        const finalWarning = `Critical: General agent not found in registry. Falling back to built-in "general".`;
+        if (warnings)
+            warnings.push(finalWarning);
+        else
+            console.warn(`[Astrocode] ${finalWarning}`);
+        return "general";
+    }
+    return candidate;
+}
+function stageGoal(stage, cfg) {
+    switch (stage) {
+        case "frame":
+            return "Define scope, constraints, and an unambiguous Definition of Done.";
+        case "plan":
+            return `Create 50-200 detailed implementation stories, each focused on a specific, implementable task. Break down every component into separate stories with clear acceptance criteria.`;
+        case "spec":
+            return "Produce minimal spec/contract: interfaces, invariants, acceptance checks.";
+        case "implement":
+            return "Implement the spec with minimal changes, referencing diffs and evidence as artifacts.";
+        case "review":
+            return "Review implementation for correctness, risks, and alignment with spec.";
+        case "verify":
+            return "Run verification commands and produce evidence artifacts.";
+        case "close":
+            return "Summarize outcome and confirm acceptance criteria, leaving clear breadcrumbs.";
+    }
+}
+function stageConstraints(stage, cfg) {
+    const common = [
+        "Do not narrate prompts.",
+        "Keep baton markdown short and structured.",
+        "If blocked: ask exactly ONE question and stop.",
+    ];
+    if (stage === "plan") {
+        common.push(`Create 50-200 stories; each story must be implementable in 2-8 hours with clear acceptance criteria.`);
+    }
+    if (stage === "verify" && cfg.workflow.evidence_required.verify) {
+        common.push("Evidence required: ASTRO JSON must include evidence[] paths.");
+    }
+    return common;
+}
+function buildDelegationPrompt(opts) {
+    const { stageDirective, run_id, stage_key, stage_agent_name } = opts;
+    const stageUpper = stage_key.toUpperCase();
+    const prompt = [
+        `[SYSTEM DIRECTIVE: ASTROCODE — DELEGATE_STAGE_${stageUpper}]`,
+        ``,
+        `Do this now, in order:`,
+        `1) Call the **task** tool to delegate to subagent \`${stage_agent_name}\`.`,
+        `   - Pass this exact prompt text to the subagent (copy/paste):`,
+        ``,
+        stageDirective,
+        ``,
+        `2) When the subagent returns, immediately call **astro_stage_complete** with:`,
+        `   - run_id = "${run_id}"`,
+        `   - stage_key = "${stage_key}"`,
+        `   - output_text = (the FULL subagent response text)`,
+        ``,
+        `3) Then call **astro_workflow_proceed** again (mode=step).`,
+        ``,
+        `Important: do NOT do any stage work yourself in orchestrator mode.`,
+    ].join("\n").trim();
+    debug(`Delegating stage ${stage_key} to agent ${stage_agent_name}`, { prompt_length: prompt.length });
+    return prompt;
+}
+function buildUiMessage(e) {
+    switch (e.kind) {
+        case "stage_started": {
+            const agent = e.agent_name ? ` (${e.agent_name})` : "";
+            const title = "Astrocode";
+            const message = `Stage started: ${e.stage_key}${agent}`;
+            const chatText = [
+                `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_STARTED]`,
+                ``,
+                `Run: ${e.run_id}`,
+                `Stage: ${e.stage_key}${agent}`,
+            ].join("\n");
+            return { title, message, variant: "info", chatText };
+        }
+        case "run_completed": {
+            const title = "Astrocode";
+            const message = `Run completed: ${e.run_id}`;
+            const chatText = [
+                `[SYSTEM DIRECTIVE: ASTROCODE — RUN_COMPLETED]`,
+                ``,
+                `Run: ${e.run_id}`,
+                `Story: ${e.story_key}`,
+            ].join("\n");
+            return { title, message, variant: "success", chatText };
+        }
+        case "run_failed": {
+            const title = "Astrocode";
+            const message = `Run failed: ${e.run_id} (${e.stage_key})`;
+            const chatText = [
+                `[SYSTEM DIRECTIVE: ASTROCODE — RUN_FAILED]`,
+                ``,
+                `Run: ${e.run_id}`,
+                `Story: ${e.story_key}`,
+                `Stage: ${e.stage_key}`,
+                `Error: ${e.error_text}`,
+            ].join("\n");
+            return { title, message, variant: "error", chatText };
+        }
+    }
+}
+export function createAstroWorkflowProceedTool(opts) {
+    const { ctx, config, db, agents } = opts;
+    const toasts = createToastManager({ ctx, throttleMs: config.ui.toasts.throttle_ms });
+    return tool({
+        description: "Deterministic harness: advances the DB-driven pipeline by one step (or loops bounded). Stops when LLM work is required (delegation/await).",
+        args: {
+            mode: tool.schema.enum(["step", "loop"]).default(config.workflow.default_mode),
+            max_steps: tool.schema.number().int().positive().default(config.workflow.default_max_steps),
+        },
+        execute: async ({ mode, max_steps }) => {
+            const sessionId = ctx.sessionID;
+            const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
+            const actions = [];
+            const warnings = [];
+            const startedAt = nowISO();
+            // Collect UI events emitted inside state-machine functions, then flush AFTER tx.
+            const uiEvents = [];
+            const emit = (e) => uiEvents.push(e);
+            for (let i = 0; i < steps; i++) {
+                const next = decideNextAction(db, config);
+                if (next.kind === "idle") {
+                    actions.push("idle: no approved stories");
+                    break;
+                }
+                if (next.kind === "start_run") {
+                    // SINGLE tx boundary: caller owns tx, state-machine is pure.
+                    const { run_id } = withTx(db, () => createRunForStory(db, config, next.story_key));
+                    actions.push(`started run ${run_id} for story ${next.story_key}`);
+                    if (mode === "step")
+                        break;
+                    continue;
+                }
+                if (next.kind === "complete_run") {
+                    withTx(db, () => completeRun(db, next.run_id, emit));
+                    actions.push(`completed run ${next.run_id}`);
+                    if (mode === "step")
+                        break;
+                    continue;
+                }
+                if (next.kind === "failed") {
+                    // Ensure DB state reflects failure in one tx; emit UI event.
+                    withTx(db, () => failRun(db, next.run_id, next.stage_key, next.error_text, emit));
+                    actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
+                    if (mode === "step")
+                        break;
+                    continue;
+                }
+                if (next.kind === "delegate_stage") {
+                    const active = getActiveRun(db);
+                    if (!active)
+                        throw new Error("Invariant: delegate_stage but no active run.");
+                    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(active.run_id);
+                    const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(run.story_key);
+                    let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
+                    const agentExists = (name) => {
+                        if (agents && agents[name])
+                            return true;
+                        const knownStageAgents = ["Frame", "Plan", "Spec", "Implement", "Review", "Verify", "Close", "General", "Astro", "general"];
+                        if (knownStageAgents.includes(name))
+                            return true;
+                        return false;
+                    };
+                    if (!agentExists(agentName)) {
+                        const originalAgent = agentName;
+                        console.warn(`[Astrocode] Agent ${agentName} not found. Falling back to orchestrator.`);
+                        agentName = config.agents?.orchestrator_name || "Astro";
+                        if (!agentExists(agentName)) {
+                            console.warn(`[Astrocode] Orchestrator ${agentName} not available. Falling back to General.`);
+                            agentName = "General";
+                            if (!agentExists(agentName)) {
+                                throw new Error(`Critical: No agents available for delegation. Primary: ${originalAgent}, Orchestrator: ${config.agents?.orchestrator_name || "Astro"}, General: unavailable`);
+                            }
+                        }
+                    }
+                    // NOTE: startStage owns its own tx (state-machine.ts).
+                    withTx(db, () => {
+                        startStage(db, active.run_id, next.stage_key, { subagent_type: agentName }, emit);
+                    });
+                    const context = buildContextSnapshot({
+                        db,
+                        config,
+                        run_id: active.run_id,
+                        next_action: `delegate stage ${next.stage_key}`,
+                    });
+                    const stageDirective = buildStageDirective({
+                        config,
+                        stage_key: next.stage_key,
+                        run_id: active.run_id,
+                        story_key: run.story_key,
+                        story_title: story?.title ?? "(missing)",
+                        stage_agent_name: agentName,
+                        stage_goal: stageGoal(next.stage_key, config),
+                        stage_constraints: stageConstraints(next.stage_key, config),
+                        context_snapshot_md: context,
+                    }).body;
+                    const delegatePrompt = buildDelegationPrompt({
+                        stageDirective,
+                        run_id: active.run_id,
+                        stage_key: next.stage_key,
+                        stage_agent_name: agentName,
+                    });
+                    // Record continuation (best-effort; no tx wrapper needed but safe either way)
+                    const h = directiveHash(delegatePrompt);
+                    const now = nowISO();
+                    if (sessionId) {
+                        // This assumes continuations table exists in vNext schema.
+                        db.prepare("INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'stage', ?, ?)").run(sessionId, active.run_id, h, `delegate ${next.stage_key}`, now);
+                    }
+                    // Visible injection so user can see state (awaited)
+                    if (sessionId) {
+                        await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
+                        const continueMessage = [
+                            `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_COMPLETION]`,
+                            ``,
+                            `Stage \`${next.stage_key}\` delegated to \`${agentName}\`.`,
+                            ``,
+                            `When \`${agentName}\` completes, call:`,
+                            `astro_stage_complete(run_id="${active.run_id}", stage_key="${next.stage_key}", output_text="[paste subagent output here]")`,
+                            ``,
+                            `This advances the workflow.`,
+                        ].join("\n");
+                        await injectChatPrompt({ ctx, sessionId, text: continueMessage, agent: "Astro" });
+                    }
+                    actions.push(`delegated stage ${next.stage_key} via ${agentName}`);
+                    // Stop here; subagent needs to run.
+                    break;
+                }
+                if (next.kind === "await_stage_completion") {
+                    actions.push(`await stage completion: ${next.stage_key}`);
+                    if (sessionId) {
+                        const context = buildContextSnapshot({
+                            db,
+                            config,
+                            run_id: next.run_id,
+                            next_action: `complete stage ${next.stage_key}`,
+                        });
+                        const prompt = [
+                            `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_OUTPUT]`,
+                            ``,
+                            `Run \`${next.run_id}\` is waiting for stage \`${next.stage_key}\` output.`,
+                            `If you have the subagent output, call astro_stage_complete with output_text=the FULL output.`,
+                            ``,
+                            `Context snapshot:`,
+                            context,
+                        ].join("\n").trim();
+                        const h = directiveHash(prompt);
+                        const now = nowISO();
+                        db.prepare("INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'continue', ?, ?)").run(sessionId, next.run_id, h, `await ${next.stage_key}`, now);
+                        await injectChatPrompt({ ctx, sessionId, text: prompt, agent: "Astro" });
+                    }
+                    break;
+                }
+                actions.push(`unhandled next action: ${next.kind}`);
+                break;
+            }
+            // Flush UI events (toast + prompt) AFTER state transitions
+            if (uiEvents.length > 0) {
+                for (const e of uiEvents) {
+                    const msg = buildUiMessage(e);
+                    if (config.ui.toasts.enabled) {
+                        await toasts.show({
+                            title: msg.title,
+                            message: msg.message,
+                            variant: msg.variant,
+                        });
+                    }
+                    if (ctx?.sessionID) {
+                        await injectChatPrompt({
+                            ctx,
+                            sessionId: ctx.sessionID,
+                            text: msg.chatText,
+                            agent: "Astro",
+                        });
+                    }
+                }
+                actions.push(`ui: flushed ${uiEvents.length} event(s)`);
+            }
+            // Housekeeping event
+            db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, ?, ?, ?)").run(newEventId(), EVENT_TYPES.WORKFLOW_PROCEED, JSON.stringify({ started_at: startedAt, mode, max_steps: steps, actions }), nowISO());
+            const active = getActiveRun(db);
+            const lines = [];
+            lines.push(`# astro_workflow_proceed`);
+            lines.push(`- mode: ${mode}`);
+            lines.push(`- steps requested: ${max_steps} (cap=${steps})`);
+            if (active)
+                lines.push(`- active run: \`${active.run_id}\` (stage=${active.current_stage_key ?? "?"})`);
+            lines.push(``, `## Actions`);
+            for (const a of actions)
+                lines.push(`- ${a}`);
+            if (warnings.length > 0) {
+                lines.push(``, `## Warnings`);
+                for (const w of warnings)
+                    lines.push(`⚠️ ${w}`);
+            }
+            return lines.join("\n").trim();
+        },
+    });
+}

package/dist/src/ui/inject.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Inject a visible prompt into the conversation.
+ * - Deterministic ordering per session
+ * - Correct SDK binding (prevents `this._client` undefined)
+ * - Awaitable: resolves when delivered, rejects after max retries
+ */
+export declare function injectChatPrompt(opts: {
+    ctx: any;
+    sessionId?: string;
+    text: string;
+    agent?: string;
+}): Promise<void>;

package/dist/src/ui/inject.js

@@ -0,0 +1,107 @@
+// src/ui/inject.ts
+import { recordInjection, recordError } from "../shared/metrics";
+const MAX_ATTEMPTS = 4;
+const RETRY_DELAYS_MS = [250, 500, 1000, 2000]; // attempt 1..4
+// Per-session queues so one stuck session doesn't block others
+const queues = new Map();
+const running = new Set();
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function getPromptInvoker(ctx) {
+    const session = ctx?.client?.session;
+    const prompt = session?.prompt;
+    if (!session || typeof prompt !== "function") {
+        throw new Error("API not available (ctx.client.session.prompt)");
+    }
+    return { session, prompt };
+}
+async function tryInjectOnce(item) {
+    const { ctx, sessionId, text, agent = "Astro" } = item;
+    const prefixedText = `[${agent}]\n\n${text}`;
+    const injectionRecorder = recordInjection({ sessionId, attempts: item.attempts + 1, agent });
+    const injectionStart = injectionRecorder.start();
+    try {
+        const { session, prompt } = getPromptInvoker(ctx);
+        // IMPORTANT: force correct `this` binding
+        await prompt.call(session, {
+            path: { id: sessionId },
+            body: {
+                parts: [{ type: "text", text: prefixedText }],
+                agent,
+            },
+        });
+        injectionRecorder.end(injectionStart, true);
+    }
+    catch (error) {
+        injectionRecorder.end(injectionStart, false);
+        throw error;
+    }
+}
+async function runSessionQueue(sessionId) {
+    if (running.has(sessionId))
+        return;
+    running.add(sessionId);
+    try {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const q = queues.get(sessionId);
+            if (!q || q.length === 0)
+                break;
+            const item = q.shift();
+            try {
+                await tryInjectOnce(item);
+                item.resolve();
+            }
+            catch (err) {
+                item.attempts += 1;
+                const msg = err instanceof Error ? err.message : String(err);
+                const delay = RETRY_DELAYS_MS[Math.min(item.attempts - 1, RETRY_DELAYS_MS.length - 1)] ?? 2000;
+                if (item.attempts >= MAX_ATTEMPTS) {
+                    console.warn(`[Astrocode] Injection failed permanently after ${item.attempts} attempts: ${msg}`);
+                    recordError("injection_failure", `Injection failed after ${item.attempts} attempts: ${msg}`);
+                    item.reject(err);
+                    continue;
+                }
+                console.warn(`[Astrocode] Injection attempt ${item.attempts}/${MAX_ATTEMPTS} failed: ${msg}; retrying in ${delay}ms`);
+                await sleep(delay);
+                // Requeue at front to preserve order (and avoid starving later messages)
+                const q2 = queues.get(sessionId) ?? [];
+                q2.unshift(item);
+                queues.set(sessionId, q2);
+            }
+        }
+    }
+    finally {
+        running.delete(sessionId);
+    }
+}
+/**
+ * Inject a visible prompt into the conversation.
+ * - Deterministic ordering per session
+ * - Correct SDK binding (prevents `this._client` undefined)
+ * - Awaitable: resolves when delivered, rejects after max retries
+ */
+export async function injectChatPrompt(opts) {
+    const sessionId = opts.sessionId ?? opts.ctx?.sessionID;
+    if (!sessionId) {
+        console.warn("[Astrocode] Skipping injection: No sessionId provided");
+        return;
+    }
+    return new Promise((resolve, reject) => {
+        const item = {
+            ctx: opts.ctx,
+            sessionId,
+            text: opts.text,
+            agent: opts.agent,
+            attempts: 0,
+            resolve,
+            reject,
+        };
+        const q = queues.get(sessionId) ?? [];
+        q.push(item);
+        queues.set(sessionId, q);
+        // Fire worker (don't await here; caller awaits the returned Promise)
+        void runSessionQueue(sessionId);
+    });
+}

package/dist/src/ui/toasts.d.ts

@@ -0,0 +1,13 @@
+export type ToastVariant = "info" | "success" | "warning" | "error";
+export type ToastOptions = {
+    title: string;
+    message: string;
+    variant?: ToastVariant;
+    durationMs?: number;
+};
+export declare function createToastManager(opts: {
+    ctx: any;
+    throttleMs: number;
+}): {
+    show: (toast: ToastOptions) => Promise<void>;
+};

package/dist/src/ui/toasts.js

@@ -0,0 +1,39 @@
+export function createToastManager(opts) {
+    const { ctx, throttleMs } = opts;
+    let lastAt = 0;
+    async function show(toast) {
+        const now = Date.now();
+        if (now - lastAt < throttleMs)
+            return;
+        lastAt = now;
+        const tui = ctx?.client?.tui;
+        if (tui?.showToast) {
+            try {
+                await tui.showToast({
+                    title: toast.title,
+                    message: toast.message,
+                    variant: toast.variant ?? "info",
+                    durationMs: toast.durationMs ?? 2500,
+                });
+                return;
+            }
+            catch {
+                // fall through
+            }
+        }
+        // Fallback: visible chat prompt
+        try {
+            const sessionId = ctx?.sessionID;
+            if (!sessionId)
+                return;
+            await ctx.client.session.prompt({
+                path: { id: sessionId },
+                body: { parts: [{ type: "text", text: `[ASTRO TOAST] ${toast.title}: ${toast.message}` }] },
+            });
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { show };
+}

package/dist/src/workflow/artifacts.d.ts

@@ -0,0 +1,24 @@
+import type { SqliteDb } from "../state/db";
+export type ArtifactType = "baton" | "summary" | "evidence" | "diff" | "log" | "commit" | "tool_output" | "snapshot" | "spec";
+export type PutArtifactOpts = {
+    repoRoot: string;
+    db: SqliteDb;
+    run_id?: string | null;
+    stage_key?: string | null;
+    type: ArtifactType | string;
+    rel_path: string;
+    content: string | Buffer;
+    meta?: Record<string, unknown>;
+};
+export declare function writeFileSafe(repoRoot: string, relPath: string, content: string | Buffer): void;
+export declare function putArtifact(opts: PutArtifactOpts): {
+    artifact_id: string;
+    sha256: string;
+    abs_path: string;
+};
+export declare function listArtifacts(db: SqliteDb, filters?: {
+    run_id?: string;
+    stage_key?: string;
+    type?: string;
+}): any[];
+export declare function getArtifact(db: SqliteDb, artifact_id: string): any | null;

package/dist/src/workflow/artifacts.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import { newArtifactId } from "../state/ids";
+import { nowISO } from "../shared/time";
+import { sha256Hex } from "../shared/hash";
+import { assertInsideAstro, ensureDir, toPosix } from "../shared/paths";
+export function writeFileSafe(repoRoot, relPath, content) {
+    const abs = path.join(repoRoot, relPath);
+    assertInsideAstro(repoRoot, abs);
+    ensureDir(path.dirname(abs));
+    fs.writeFileSync(abs, content);
+}
+export function putArtifact(opts) {
+    const { repoRoot, db, run_id = null, stage_key = null, type, rel_path, content } = opts;
+    const artifact_id = newArtifactId();
+    const abs_path = path.join(repoRoot, rel_path);
+    writeFileSafe(repoRoot, rel_path, content);
+    const sha256 = sha256Hex(content instanceof Buffer ? content : Buffer.from(content, "utf-8"));
+    const created_at = nowISO();
+    const meta_json = JSON.stringify(opts.meta ?? {});
+    db.prepare("INSERT INTO artifacts (artifact_id, run_id, stage_key, type, path, sha256, meta_json, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)").run(artifact_id, run_id, stage_key, type, toPosix(rel_path), sha256, meta_json, created_at);
+    return { artifact_id, sha256, abs_path };
+}
+export function listArtifacts(db, filters) {
+    const where = [];
+    const params = [];
+    if (filters?.run_id) {
+        where.push("run_id = ?");
+        params.push(filters.run_id);
+    }
+    if (filters?.stage_key) {
+        where.push("stage_key = ?");
+        params.push(filters.stage_key);
+    }
+    if (filters?.type) {
+        where.push("type = ?");
+        params.push(filters.type);
+    }
+    const sql = `SELECT * FROM artifacts ${where.length ? "WHERE " + where.join(" AND ") : ""} ORDER BY created_at DESC LIMIT 200`;
+    return db.prepare(sql).all(...params);
+}
+export function getArtifact(db, artifact_id) {
+    const row = db.prepare("SELECT * FROM artifacts WHERE artifact_id = ?").get(artifact_id);
+    return row ?? null;
+}

package/dist/src/workflow/baton.d.ts

@@ -0,0 +1,72 @@
+import type { AstrocodeConfig } from "../config/schema";
+import { z } from "zod";
+export declare const ASTRO_JSON_BEGIN = "<!-- ASTRO_JSON_BEGIN -->";
+export declare const ASTRO_JSON_END = "<!-- ASTRO_JSON_END -->";
+export declare const StageKeySchema: z.ZodEnum<{
+    frame: "frame";
+    plan: "plan";
+    spec: "spec";
+    implement: "implement";
+    review: "review";
+    verify: "verify";
+    close: "close";
+}>;
+export declare const AstroJsonSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodNumber>;
+    run_id: z.ZodOptional<z.ZodString>;
+    story_key: z.ZodOptional<z.ZodString>;
+    stage_key: z.ZodEnum<{
+        frame: "frame";
+        plan: "plan";
+        spec: "spec";
+        implement: "implement";
+        review: "review";
+        verify: "verify";
+        close: "close";
+    }>;
+    status: z.ZodDefault<z.ZodEnum<{
+        blocked: "blocked";
+        failed: "failed";
+        ok: "ok";
+    }>>;
+    summary: z.ZodDefault<z.ZodString>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    next_actions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        complexity: z.ZodOptional<z.ZodNumber>;
+        subtasks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodDefault<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodDefault<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    new_stories: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        body_md: z.ZodOptional<z.ZodString>;
+        priority: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    questions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metrics: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
+}, z.core.$strip>;
+export type AstroJson = z.infer<typeof AstroJsonSchema>;
+export type ParsedStageOutput = {
+    baton_md: string;
+    astro_json: AstroJson | null;
+    astro_json_raw: string | null;
+    error: string | null;
+};
+export declare function parseStageOutputText(text: string): ParsedStageOutput;
+export declare function buildBatonSummary(opts: {
+    config: AstrocodeConfig;
+    stage_key: string;
+    astro_json: AstroJson | null;
+    baton_md: string;
+}): string;