astrocode-workflow 0.3.0 → 0.3.2

package/dist/src/tools/story.d.ts

@@ -0,0 +1,23 @@
+import { type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+export declare function createAstroStoryQueueTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;
+export declare function createAstroStoryApproveTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;
+export declare function createAstroStoryBoardTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;
+export declare function createAstroStorySetStateTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;

package/dist/src/tools/story.js

@@ -0,0 +1,85 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { withTx } from "../state/db";
+import { nowISO } from "../shared/time";
+import { insertStory } from "../workflow/story-helpers";
+export function createAstroStoryQueueTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Create a queued story (ticket) in Astrocode. Returns story_key.",
+        args: {
+            title: tool.schema.string().min(1),
+            body_md: tool.schema.string().default(""),
+            epic_key: tool.schema.string().optional(),
+            priority: tool.schema.number().int().default(0),
+        },
+        execute: async ({ title, body_md, epic_key, priority }) => {
+            const story_key = withTx(db, () => {
+                const key = insertStory(db, { title, body_md, epic_key: epic_key ?? null, priority: priority ?? 0, state: 'queued' });
+                return key;
+            });
+            return `✅ Queued story ${story_key}: ${title}`;
+        },
+    });
+}
+export function createAstroStoryApproveTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Approve a story so it becomes eligible to run.",
+        args: {
+            story_key: tool.schema.string().min(1),
+        },
+        execute: async ({ story_key }) => {
+            const now = nowISO();
+            const row = db.prepare("SELECT story_key, state, title FROM stories WHERE story_key=?").get(story_key);
+            if (!row)
+                throw new Error(`Story not found: ${story_key}`);
+            if (row.state === "approved")
+                return `ℹ️ Story ${story_key} already approved.`;
+            db.prepare("UPDATE stories SET state='approved', approved_at=?, updated_at=? WHERE story_key=?").run(now, now, story_key);
+            return `✅ Approved story ${story_key}: ${row.title}`;
+        },
+    });
+}
+export function createAstroStoryBoardTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Show stories grouped by state (a compact board).",
+        args: {
+            limit_per_state: tool.schema.number().int().positive().default(20),
+        },
+        execute: async ({ limit_per_state }) => {
+            const states = ["queued", "approved", "in_progress", "blocked", "done", "archived"];
+            const lines = [];
+            lines.push("# Story board");
+            for (const st of states) {
+                const rows = db
+                    .prepare("SELECT story_key, title, priority, created_at FROM stories WHERE state=? ORDER BY priority DESC, created_at ASC LIMIT ?")
+                    .all(st, limit_per_state);
+                lines.push("", `## ${st} (${rows.length})`);
+                for (const r of rows)
+                    lines.push(`- \`${r.story_key}\` (p=${r.priority}) — ${r.title}`);
+            }
+            return lines.join("\n").trim();
+        },
+    });
+}
+export function createAstroStorySetStateTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Admin: set story state manually (queued|approved|in_progress|done|blocked|archived). Use carefully.",
+        args: {
+            story_key: tool.schema.string().min(1),
+            state: tool.schema.enum(["queued", "approved", "in_progress", "done", "blocked", "archived"]),
+            note: tool.schema.string().default(""),
+        },
+        execute: async ({ story_key, state, note }) => {
+            const now = nowISO();
+            const row = db.prepare("SELECT story_key, title, state FROM stories WHERE story_key=?").get(story_key);
+            if (!row)
+                throw new Error(`Story not found: ${story_key}`);
+            db.prepare("UPDATE stories SET state=?, updated_at=? WHERE story_key=?").run(state, now, story_key);
+            db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, 'story.state_set', ?, ?)").run(`evt_${Date.now()}_${Math.random().toString(16).slice(2)}`, JSON.stringify({ story_key, from: row.state, to: state, note }), now);
+            return `✅ Story ${story_key} state: ${row.state} → ${state}${note ? ` (${note})` : ""}`;
+        },
+    });
+}

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

@@ -0,0 +1,13 @@
+import { type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import type { StageKey } from "../state/types";
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const STAGE_TO_AGENT_MAP: Record<string, string>;
+export declare function resolveAgentName(stageKey: StageKey, config: AstrocodeConfig, agents?: any, warnings?: string[]): string;
+export declare function createAstroWorkflowProceedTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+    agents?: Record<string, AgentConfig>;
+}): ToolDefinition;

package/dist/src/tools/workflow.js

@@ -0,0 +1,355 @@
+// 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";
+import { acquireRepoLock } from "../state/repo-lock";
+// 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 }) => {
+            // Acquire repo lock to ensure no concurrent workflow operations
+            const lockPath = `${ctx.directory}/.astro/astro.lock`;
+            const repoLock = acquireRepoLock(lockPath);
+            try {
+                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();
+            }
+            finally {
+                // Always release the lock
+                repoLock.release();
+            }
+        },
+    });
+}

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 };
+}