astrocode-workflow 0.2.0 → 0.2.2

package/src/state/db.ts

@@ -48,7 +48,32 @@ export function configurePragmas(db: SqliteDb, pragmas: Record<string, any>) {
   if (pragmas.temp_store) db.pragma(`temp_store = ${pragmas.temp_store}`);
 }
 
-/** BEGIN IMMEDIATE transaction helper. */
+/**
+ * Re-entrant transaction helper.
+ *
+ * SQLite rejects BEGIN inside BEGIN. We use:
+ * - depth=0: BEGIN IMMEDIATE ... COMMIT/ROLLBACK
+ * - depth>0: SAVEPOINT sp_n ... RELEASE / ROLLBACK TO + RELEASE
+ *
+ * This allows callers to safely nest withTx across layers (tools -> workflow -> state machine)
+ * without "cannot start a transaction within a transaction".
+ */
+const TX_DEPTH = new WeakMap<object, number>();
+
+function getDepth(db: SqliteDb): number {
+  return TX_DEPTH.get(db as any) ?? 0;
+}
+
+function setDepth(db: SqliteDb, depth: number) {
+  if (depth <= 0) TX_DEPTH.delete(db as any);
+  else TX_DEPTH.set(db as any, depth);
+}
+
+function savepointName(depth: number): string {
+  return `sp_${depth}`;
+}
+
+/** BEGIN IMMEDIATE transaction helper (re-entrant). */
 export function withTx<T>(db: SqliteDb, fn: () => T, opts?: { require?: boolean }): T {
   const adapter = createDatabaseAdapter();
   const available = adapter.isAvailable();
@@ -58,18 +83,52 @@ export function withTx<T>(db: SqliteDb, fn: () => T, opts?: { require?: boolean
     return fn();
   }
 
-  db.exec("BEGIN IMMEDIATE");
+  const depth = getDepth(db);
+
+  if (depth === 0) {
+    db.exec("BEGIN IMMEDIATE");
+    setDepth(db, 1);
+    try {
+      const out = fn();
+      db.exec("COMMIT");
+      return out;
+    } catch (e) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+        // ignore
+      }
+      throw e;
+    } finally {
+      setDepth(db, 0);
+    }
+  }
+
+  // Nested: use SAVEPOINT
+  const nextDepth = depth + 1;
+  const sp = savepointName(nextDepth);
+
+  db.exec(`SAVEPOINT ${sp}`);
+  setDepth(db, nextDepth);
+
   try {
     const out = fn();
-    db.exec("COMMIT");
+    db.exec(`RELEASE SAVEPOINT ${sp}`);
     return out;
   } catch (e) {
     try {
-      db.exec("ROLLBACK");
+      db.exec(`ROLLBACK TO SAVEPOINT ${sp}`);
+    } catch {
+      // ignore
+    }
+    try {
+      db.exec(`RELEASE SAVEPOINT ${sp}`);
     } catch {
       // ignore
     }
     throw e;
+  } finally {
+    setDepth(db, depth);
   }
 }
 

package/src/state/repo-lock.ts

@@ -0,0 +1,26 @@
+// src/state/repo-lock.ts
+import fs from "node:fs";
+import path from "node:path";
+
+export function acquireRepoLock(lockPath: string): { release: () => void } {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+
+  let fd: number;
+  try {
+    fd = fs.openSync(lockPath, "wx"); // exclusive create
+  } catch (e: any) {
+    const msg = e?.code === "EEXIST"
+      ? `Astrocode lock is already held (${lockPath}). Another opencode process is running in this repo.`
+      : `Failed to acquire lock (${lockPath}): ${e?.message ?? String(e)}`;
+    throw new Error(msg);
+  }
+
+  fs.writeFileSync(fd, `${(process as any).pid}\n`, "utf8");
+
+  return {
+    release: () => {
+      try { fs.closeSync(fd); } catch {}
+      try { fs.unlinkSync(lockPath); } catch {}
+    },
+  };
+}

package/src/tools/workflow.ts

@@ -1,16 +1,28 @@
+// src/tools/workflow.ts
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
 import { withTx } from "../state/db";
 import type { StageKey } from "../state/types";
+import type { UiEmitEvent } from "../workflow/state-machine";
 import { buildContextSnapshot } from "../workflow/context";
-import { decideNextAction, createRunForStory, startStage, completeRun, getActiveRun, EVENT_TYPES } from "../workflow/state-machine";
+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 type { AgentConfig } from "@opencode-ai/sdk";
+import { acquireRepoLock } from "../state/repo-lock";
 
 // Agent name mapping for case-sensitive resolution
 export const STAGE_TO_AGENT_MAP: Record<string, string> = {
@@ -37,23 +49,17 @@ export function resolveAgentName(stageKey: StageKey, config: AstrocodeConfig, ag
   // 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}`);
-    }
+    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"; // built-in, guaranteed by OpenCode
+    if (warnings) warnings.push(finalWarning);
+    else console.warn(`[Astrocode] ${finalWarning}`);
+    return "general";
   }
 
   return candidate;
@@ -94,10 +100,6 @@ function stageConstraints(stage: StageKey, cfg: AstrocodeConfig): string[] {
   return common;
 }
 
-function agentNameForStage(stage: StageKey, cfg: AstrocodeConfig): string {
-  return cfg.agents.stage_agent_names[stage];
-}
-
 function buildDelegationPrompt(opts: {
   stageDirective: string;
   run_id: string;
@@ -126,13 +128,50 @@ function buildDelegationPrompt(opts: {
     `Important: do NOT do any stage work yourself in orchestrator mode.`,
   ].join("\n").trim();
 
-  // Debug log the delegation prompt to troubleshoot agent output issues
   debug(`Delegating stage ${stage_key} to agent ${stage_agent_name}`, { prompt_length: prompt.length });
-
   return prompt;
 }
 
-import { AgentConfig } from "@opencode-ai/sdk";
+function buildUiMessage(e: UiEmitEvent): { title: string; message: string; variant: "info" | "success" | "error"; chatText: string } {
+  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: { ctx: any; config: AstrocodeConfig; db: SqliteDb; agents?: Record<string, AgentConfig> }): ToolDefinition {
   const { ctx, config, db, agents } = opts;
@@ -146,13 +185,22 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
       max_steps: tool.schema.number().int().positive().default(config.workflow.default_max_steps),
     },
     execute: async ({ mode, max_steps }) => {
-      const sessionId = (ctx as any).sessionID as string | undefined;
-      const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
+      // Acquire repo lock to ensure no concurrent workflow operations
+      const lockPath = `${(ctx as any).directory}/.astro/astro.lock`;
+      const repoLock = acquireRepoLock(lockPath);
+
+      try {
+        const sessionId = (ctx as any).sessionID as string | undefined;
+        const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
 
       const actions: string[] = [];
       const warnings: string[] = [];
       const startedAt = nowISO();
 
+      // Collect UI events emitted inside state-machine functions, then flush AFTER tx.
+      const uiEvents: UiEmitEvent[] = [];
+      const emit = (e: UiEmitEvent) => uiEvents.push(e);
+
       for (let i = 0; i < steps; i++) {
         const next = decideNextAction(db, config);
 
@@ -162,72 +210,26 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
         }
 
         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 (config.ui.toasts.enabled && config.ui.toasts.show_run_started) {
-            await toasts.show({ title: "Astrocode", message: `Run started (${run_id})`, variant: "success" });
-          }
-
           if (mode === "step") break;
           continue;
         }
 
         if (next.kind === "complete_run") {
-          withTx(db, () => completeRun(db, next.run_id));
+          withTx(db, () => completeRun(db, next.run_id, emit));
           actions.push(`completed run ${next.run_id}`);
 
-          if (config.ui.toasts.enabled && config.ui.toasts.show_run_completed) {
-            await toasts.show({ title: "Astrocode", message: `Run completed (${next.run_id})`, variant: "success" });
-          }
-
-          // Inject continuation directive for workflow resumption
-          if (sessionId) {
-            const continueDirective = [
-              `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
-              ``,
-              `Run ${next.run_id} completed successfully.`,
-              ``,
-              `The Clara Forms implementation run has finished all stages. The spec has been analyzed and decomposed into prioritized implementation stories.`,
-              ``,
-              `Next actions: Review the generated stories and approve the next one to continue development.`,
-            ].join("\n");
-
-            await injectChatPrompt({
-              ctx,
-              sessionId,
-              text: continueDirective,
-              agent: "Astro"
-            });
-
-            actions.push(`injected continuation directive for completed run ${next.run_id}`);
-          }
-
-          // Check for next approved story to start
-          const nextStory = db.prepare(
-            "SELECT story_key, title FROM stories WHERE state = 'approved' ORDER BY priority DESC, created_at ASC LIMIT 1"
-          ).get() as { story_key: string; title: string } | undefined;
-
-          if (nextStory && sessionId) {
-            const nextDirective = [
-              `[SYSTEM DIRECTIVE: ASTROCODE — START_NEXT_STORY]`,
-              ``,
-              `The previous run completed successfully. Start the next approved story.`,
-              ``,
-              `Next Story: ${nextStory.story_key} — ${nextStory.title}`,
-              ``,
-              `Action: Call astro_story_approve with story_key="${nextStory.story_key}" to start it, or select a different story.`,
-            ].join("\n");
-
-            await injectChatPrompt({
-              ctx,
-              sessionId,
-              text: nextDirective,
-              agent: "Astro"
-            });
+          if (mode === "step") break;
+          continue;
+        }
 
-            actions.push(`injected directive to start next story ${nextStory.story_key}`);
-          }
+        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;
@@ -236,62 +238,45 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
         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) as any;
           const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(run.story_key) as any;
 
-          // Mark stage started + set subagent_type to the stage agent.
           let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
 
-          // Validate agent availability with fallback chain
-          const systemConfig = config as any;
-          // Check both the system config agent map (if present) OR the local agents map passed to the tool
           const agentExists = (name: string) => {
-             // Check local agents map first (populated from src/index.ts)
-             if (agents && agents[name]) {
-               return true;
-             }
-             // Check system config agent map
-             if (systemConfig.agent && systemConfig.agent[name]) {
-               return true;
-             }
-             // For known stage agents, assume they exist (they are system-provided subagents)
-             const knownStageAgents = ["Frame", "Plan", "Spec", "Implement", "Review", "Verify", "Close"];
-             if (knownStageAgents.includes(name)) {
-               return true;
-             }
-             return false;
+            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)) {
-              const originalAgent = agentName;
-              console.warn(`[Astrocode] Agent ${agentName} not found in config. Falling back to orchestrator.`);
-              // First fallback: orchestrator
-              agentName = config.agents?.orchestrator_name || "Astro";
+              console.warn(`[Astrocode] Orchestrator ${agentName} not available. Falling back to General.`);
+              agentName = "General";
               if (!agentExists(agentName)) {
-                console.warn(`[Astrocode] Orchestrator ${agentName} not available. Falling back to General.`);
-                // Final fallback: General (guaranteed to exist)
-                agentName = "General";
-                if (!agentExists(agentName)) {
-                  throw new Error(`Critical: No agents available for delegation. Primary: ${originalAgent}, Orchestrator: ${config.agents?.orchestrator_name || "Astro"}, General: unavailable`);
-                }
+                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 });
-
-            // Log delegation observability
-            if (config.debug?.telemetry?.enabled) {
-              // eslint-disable-next-line no-console
-              console.log(`[Astrocode:delegate] run_id=${active.run_id} stage=${next.stage_key} agent=${agentName} fallback=${agentName !== resolveAgentName(next.stage_key, config, agents) ? 'yes' : 'no'}`);
-            }
+            startStage(db, active.run_id, next.stage_key, { subagent_type: agentName }, emit);
           });
 
-          if (config.ui.toasts.enabled && config.ui.toasts.show_stage_started) {
-            await toasts.show({ title: "Astrocode", message: `Stage started: ${next.stage_key}`, variant: "info" });
-          }
-
-          const context = buildContextSnapshot({ db, config, run_id: active.run_id, next_action: `delegate stage ${next.stage_key}` });
+          const context = buildContextSnapshot({
+            db,
+            config,
+            run_id: active.run_id,
+            next_action: `delegate stage ${next.stage_key}`,
+          });
 
           const stageDirective = buildStageDirective({
             config,
@@ -312,35 +297,35 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
             stage_agent_name: agentName,
           });
 
-          // Record in continuations as a stage directive (dedupe by hash)
+          // 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
-           if (sessionId) {
-             await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
+          // Visible injection so user can see state (awaited)
+          if (sessionId) {
+            await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
 
-             // Inject continuation guidance
-             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");
+            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" });
-           }
+            await injectChatPrompt({ ctx, sessionId, text: continueMessage, agent: "Astro" });
+          }
 
-           actions.push(`delegated stage ${next.stage_key} via ${agentName}`);
+          actions.push(`delegated stage ${next.stage_key} via ${agentName}`);
 
           // Stop here; subagent needs to run.
           break;
@@ -348,18 +333,25 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
 
         if (next.kind === "await_stage_completion") {
           actions.push(`await stage completion: ${next.stage_key}`);
-          // Optionally nudge with a short directive
+
           if (sessionId) {
-            const context = buildContextSnapshot({ db, config, run_id: next.run_id, next_action: `complete stage ${next.stage_key}` });
+            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.`,
+              `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(
@@ -368,19 +360,40 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
 
             await injectChatPrompt({ ctx, sessionId, text: prompt, agent: "Astro" });
           }
-          break;
-        }
 
-        if (next.kind === "failed") {
-          actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
           break;
         }
 
-        // safety
         actions.push(`unhandled next action: ${(next as any).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 as any)?.sessionID) {
+            await injectChatPrompt({
+              ctx,
+              sessionId: (ctx as any).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, ?, ?, ?)"
@@ -401,6 +414,10 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
       }
 
       return lines.join("\n").trim();
+      } finally {
+        // Always release the lock
+        repoLock.release();
+      }
     },
   });
 }