open-agents-ai 0.187.497 → 0.187.499

package/dist/index.js

@@ -255310,6 +255310,293 @@ var init_working_notes = __esm({
   }
 });
 
+// packages/execution/dist/tools/project-scaffolding.js
+function detectShape(task) {
+  const lower = task.toLowerCase();
+  if (/\b(cli|command[ -]line|terminal app)\b/.test(lower))
+    return "cli";
+  if (/\b(library|sdk|public api package)\b/.test(lower))
+    return "library";
+  if (/\b(pipeline|etl|data flow|stream processing)\b/.test(lower))
+    return "pipeline";
+  if (/\b(game|game loop|gameplay)\b/.test(lower))
+    return "game";
+  if (/\b(compiler|interpreter|lexer|parser|language|syntax)\b/.test(lower))
+    return "compiler";
+  if (/\b(frontend|ui|page|browser|dashboard|chat|app|website|spa)\b/.test(lower))
+    return "web-app";
+  return "service";
+}
+function defaultVerifyCommands(shape) {
+  switch (shape) {
+    case "library":
+      return [
+        "test suite passes (e.g. `npm test`, `pytest`, `cargo test`) — exit 0",
+        "type check / static analysis passes — exit 0",
+        "package builds without errors — exit 0"
+      ];
+    case "cli":
+      return [
+        "test suite passes — exit 0",
+        "build produces a runnable binary or script — exit 0",
+        "smoke test: `<binary> --help` exits 0 with usage text"
+      ];
+    case "pipeline":
+      return [
+        "test suite passes (incl. property tests for idempotency) — exit 0",
+        "end-to-end fixture run succeeds — exit 0"
+      ];
+    case "game":
+      return [
+        "test suite passes — exit 0",
+        "headless / smoke run completes one full update tick — exit 0"
+      ];
+    case "compiler":
+      return [
+        "test suite passes (incl. example-program eval tests) — exit 0",
+        "build / compile of the compiler itself — exit 0"
+      ];
+    default:
+      return [
+        "test suite passes — exit 0",
+        "type check / lint passes — exit 0",
+        "build produces a working artifact — exit 0"
+      ];
+  }
+}
+function bulletList(items, fallback = "(none specified)") {
+  if (!items || items.length === 0)
+    return `  ${fallback}`;
+  return items.map((i2) => `  - ${i2}`).join("\n");
+}
+function renderSections(shape) {
+  const sections = SHAPE_SECTIONS[shape];
+  return sections.map(([title, hint], i2) => ` ${(i2 + 1).toString().padStart(2, " ")}. **${title}** — ${hint}`).join("\n");
+}
+function buildScaffoldedPrompt(args) {
+  const task = (args.task || "").trim();
+  if (task.length === 0) {
+    throw new Error("project_scaffolding: 'task' is required and must be non-empty");
+  }
+  const shape = !args.shape || args.shape === "auto" ? detectShape(task) : args.shape;
+  const outputPath = (args.output_path || "./IMPLEMENTATION_GUIDE.md").trim();
+  const projectName = (args.project_name || "").trim();
+  const verifyCmds = args.verify_commands && args.verify_commands.length > 0 ? args.verify_commands : defaultVerifyCommands(shape);
+  const lines = [];
+  lines.push(`Create a detailed implementation specification${projectName ? ` for **${projectName}**` : ""}, written to:`);
+  lines.push(`  ${outputPath}`);
+  lines.push("");
+  lines.push(`## Task description`);
+  lines.push(task);
+  lines.push("");
+  if (args.features && args.features.length > 0) {
+    lines.push(`## Required features`);
+    lines.push(bulletList(args.features));
+    lines.push("");
+  }
+  if (args.stack && args.stack.length > 0) {
+    lines.push(`## Tech stack — POSITIVE constraints (use these)`);
+    lines.push(bulletList(args.stack));
+    lines.push("");
+  } else {
+    lines.push(`## Tech stack — POSITIVE constraints`);
+    lines.push(`The caller did not specify positive tech-stack constraints. The spec MUST declare its own tech stack explicitly in section 1 (Overview) — language, runtime, frameworks, persistence, build/test tools — so the downstream implementer has unambiguous targets. Do NOT leave the stack as an open choice.`);
+    lines.push("");
+  }
+  if (args.anti_stack && args.anti_stack.length > 0) {
+    lines.push(`## Tech stack — NEGATIVE constraints (do NOT use these)`);
+    lines.push(`These prohibitions are load-bearing. Default training data favors popular alternatives; you must respect the explicit "no" here even when a forbidden choice would be conventional.`);
+    lines.push("");
+    lines.push(bulletList(args.anti_stack));
+    lines.push("");
+  } else {
+    lines.push(`## Tech stack — NEGATIVE constraints`);
+    lines.push(`No explicit prohibitions supplied. The spec is free to choose any tooling consistent with the positive constraints, but the spec itself SHOULD include a brief "anti-requirements" section (see section 11) listing the patterns/libraries explicitly excluded — even if the caller did not pre-specify them.`);
+    lines.push("");
+  }
+  if (args.notes && args.notes.trim().length > 0) {
+    lines.push(`## Additional constraints / notes`);
+    lines.push(args.notes.trim());
+    lines.push("");
+  }
+  lines.push(`## Required spec sections (numbered, in order)`);
+  lines.push(`The spec MUST contain the following sections, each titled and numbered as below. Each section must be detailed enough to stand on its own; do not defer details to later sections.`);
+  lines.push("");
+  lines.push(renderSections(shape));
+  lines.push("");
+  lines.push(`## Reproducibility test (the load-bearing acceptance criterion)`);
+  lines.push(`The spec must be detailed enough that **a different agent**, with no access to this conversation and no shared memory with you, can implement it from the document alone — and produce a result that satisfies the verification commands below.`);
+  lines.push("");
+  lines.push(`## Verifiable acceptance criteria`);
+  lines.push(`Final implementation must pass:`);
+  lines.push(bulletList(verifyCmds));
+  lines.push("");
+  lines.push(`## Output discipline`);
+  lines.push(`- Write the entire spec to ${outputPath} in a single file_write call when you have a complete document. Iterating section-by-section across multiple calls produces incoherent specs; plan the whole document first, then emit.`);
+  lines.push(`- Do NOT implement any code outside the spec document itself. The spec is the deliverable; implementation is a separate downstream task.`);
+  lines.push(`- Call task_complete only after the spec is on disk and you have read it back to verify it covers every numbered section above.`);
+  return lines.join("\n");
+}
+var COMMON_HEAD_SECTIONS, COMMON_TAIL_SECTIONS, SHAPE_SECTIONS, ProjectScaffoldingTool;
+var init_project_scaffolding = __esm({
+  "packages/execution/dist/tools/project-scaffolding.js"() {
+    "use strict";
+    COMMON_HEAD_SECTIONS = [
+      ["Overview", "Goal, scope, non-goals."],
+      ["Non-functional requirements", "Performance, persistence, observability, error handling."]
+    ];
+    COMMON_TAIL_SECTIONS = [
+      ["Build commands", "All scripts (build, test, typecheck, dev). Each must be runnable and reproducible."],
+      ["Acceptance criteria", "Specific test counts and categories. The exact commands that must exit 0 to declare done."],
+      ["Test fixtures + sample data", "All sample inputs/outputs needed to run tests deterministically."],
+      ["Anti-requirements", "Explicit things NOT to do (frameworks, patterns, dependencies excluded)."]
+    ];
+    SHAPE_SECTIONS = {
+      "web-app": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Data models", "Schema (DB) + type definitions."],
+        ["API contract", "Endpoints, request/response shapes, error codes."],
+        ["Real-time events (if any)", "Event types, lifecycle, sequencing rules."],
+        ["Frontend architecture", "Module structure, state management, rendering pattern."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "service": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Data models", "Schema + type definitions."],
+        ["API contract", "Endpoints, request/response shapes, error codes."],
+        ["Background processing (if any)", "Workers, queues, scheduled jobs."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ["Operational concerns", "Logging, metrics, health checks, configuration."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "cli": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Command surface", "All commands, flags, args, exit codes, stdout/stderr format."],
+        ["Configuration", "Config file format, environment variables, precedence rules."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ["Error handling", "Error categories and how each surfaces to the user."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "library": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Public API surface", "Every exported symbol with signature, semantics, examples."],
+        ["Internal architecture", "Module breakdown, invariants, data flow."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ["Backward compatibility", "Versioning policy, deprecation rules."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "pipeline": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Stages", "Each stage's input, transform, output, idempotency property."],
+        ["Schemas", "Input/output schema for every stage boundary."],
+        ["Failure handling", "Retry, dead-letter, rollback, monitoring."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "game": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Game loop", "Tick rate, update/render cycle, fixed vs variable timestep."],
+        ["State machines", "All entities/scenes with transitions and invariants."],
+        ["Asset pipeline", "Format, loader, lifecycle."],
+        ["Input handling", "Mapping from device → game action."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ],
+      "compiler": [
+        ...COMMON_HEAD_SECTIONS,
+        ["Source language", "Grammar (BNF), example programs."],
+        ["Lexer", "Token kinds, error reporting."],
+        ["Parser", "AST shape, precedence, error recovery."],
+        ["Type system / static analysis", "Rules, inference algorithm if any."],
+        ["Evaluator / runtime", "Semantics, error model, foreign function calls."],
+        ["File structure", "Every file the implementer must create, with one-line purpose."],
+        ...COMMON_TAIL_SECTIONS
+      ]
+    };
+    ProjectScaffoldingTool = class {
+      name = "project_scaffolding";
+      description = "Convert a brief, mushy task description into a structured spec-generation prompt with concrete deliverable, positive+negative stack constraints, numbered sections, reproducibility framing, and verifiable acceptance criteria. Use BEFORE delegating spec generation to another agent — the scaffolded prompt produces coherent implementable specs where a mush prompt produces hand-waving. Args: task (required string), output_path (optional, default ./IMPLEMENTATION_GUIDE.md), stack (string array of POSITIVE constraints), anti_stack (string array of NEGATIVE constraints — load-bearing for small models that default to popular patterns), features (string array of required features), shape (one of 'web-app' | 'service' | 'cli' | 'library' | 'pipeline' | 'game' | 'compiler' | 'auto', default 'auto'), notes (free-text additional constraints), project_name (display name in spec heading), verify_commands (override default verification commands). Returns the scaffolded prompt as a string. The agent should then either (a) hand the prompt off to a sub-agent / another OA run, or (b) execute the spec generation itself.";
+      parameters = {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: "Brief task description (the mush). E.g. 'a real-time chat app with rooms and reactions'."
+          },
+          output_path: {
+            type: "string",
+            description: "File path the downstream agent should write the spec to. Default: ./IMPLEMENTATION_GUIDE.md."
+          },
+          stack: {
+            type: "array",
+            items: { type: "string" },
+            description: "POSITIVE tech-stack constraints. E.g. ['Node.js', 'TypeScript', 'Express', 'PostgreSQL']."
+          },
+          anti_stack: {
+            type: "array",
+            items: { type: "string" },
+            description: "NEGATIVE tech-stack constraints — things to explicitly avoid. Load-bearing for small models. E.g. ['WebSockets', 'React', 'in-memory only']."
+          },
+          features: {
+            type: "array",
+            items: { type: "string" },
+            description: "Required features to surface as MUST-have. E.g. ['user auth', 'rate limiting', 'audit log']."
+          },
+          shape: {
+            type: "string",
+            enum: ["web-app", "service", "cli", "library", "pipeline", "game", "compiler", "auto"],
+            description: "Project shape. Determines which sections appear in the spec. Default: 'auto' (detect from task)."
+          },
+          notes: {
+            type: "string",
+            description: "Free-text additional constraints (operational, security, performance, deployment)."
+          },
+          project_name: {
+            type: "string",
+            description: "Display name used in spec heading. Optional."
+          },
+          verify_commands: {
+            type: "array",
+            items: { type: "string" },
+            description: "Override default verification commands. Each item describes a command + expected outcome."
+          }
+        },
+        required: ["task"]
+      };
+      async execute(args) {
+        const start2 = Date.now();
+        try {
+          const scaffArgs = {
+            task: String(args["task"] ?? ""),
+            output_path: typeof args["output_path"] === "string" ? args["output_path"] : void 0,
+            stack: Array.isArray(args["stack"]) ? args["stack"].map(String) : void 0,
+            anti_stack: Array.isArray(args["anti_stack"]) ? args["anti_stack"].map(String) : void 0,
+            features: Array.isArray(args["features"]) ? args["features"].map(String) : void 0,
+            shape: typeof args["shape"] === "string" ? args["shape"] : void 0,
+            notes: typeof args["notes"] === "string" ? args["notes"] : void 0,
+            project_name: typeof args["project_name"] === "string" ? args["project_name"] : void 0,
+            verify_commands: Array.isArray(args["verify_commands"]) ? args["verify_commands"].map(String) : void 0
+          };
+          const prompt = buildScaffoldedPrompt(scaffArgs);
+          return {
+            success: true,
+            output: prompt,
+            durationMs: Date.now() - start2
+          };
+        } catch (e2) {
+          return {
+            success: false,
+            output: "",
+            error: e2 instanceof Error ? e2.message : String(e2),
+            durationMs: Date.now() - start2
+          };
+        }
+      }
+    };
+  }
+});
+
 // packages/execution/dist/tools/todo-store.js
 import { existsSync as existsSync30, readFileSync as readFileSync24, writeFileSync as writeFileSync12, mkdirSync as mkdirSync11, renameSync, unlinkSync as unlinkSync5, readdirSync as readdirSync9 } from "node:fs";
 import { join as join47 } from "node:path";
@@ -510376,6 +510663,7 @@ __export(dist_exports, {
   PlaywrightBrowserTool: () => PlaywrightBrowserTool,
   PluginManager: () => PluginManager,
   ProcessHealthTool: () => ProcessHealthTool,
+  ProjectScaffoldingTool: () => ProjectScaffoldingTool,
   ReflectionIntegrityTool: () => ReflectionIntegrityTool,
   ReminderTool: () => ReminderTool,
   ReplTool: () => ReplTool,
@@ -510418,6 +510706,7 @@ __export(dist_exports, {
   buildCustomTools: () => buildCustomTools,
   buildGraph: () => buildGraph,
   buildMcpToolName: () => buildMcpToolName,
+  buildScaffoldedPrompt: () => buildScaffoldedPrompt,
   buildSkillsSummary: () => buildSkillsSummary,
   buildSubProcessArgs: () => buildSubProcessArgs,
   canInvokeTool: () => canInvokeTool,
@@ -510597,6 +510886,7 @@ var init_dist5 = __esm({
     init_cron_agent();
     init_file_explore();
     init_working_notes();
+    init_project_scaffolding();
     init_todo_write();
     init_todo_store();
     init_semantic_map();
@@ -514339,6 +514629,23 @@ function renderCriticPrompt(inputs) {
   lines.push(`9. **Unresolved failures**: stems with attempts ≥ 3 that never cleared.`);
   lines.push(`10. **Generic-vs-specific drift**: code claims to be generic but contains`);
   lines.push(`    framework- or vendor-specific keywords.`);
+  lines.push(`11. **Backtest evidence for new code (CRITICAL — recurring failure mode)**: For any`);
+  lines.push(`    NEWLY ADDED tool, module, public function, or prompt-generation feature,`);
+  lines.push(`    the implementer MUST have invoked the new code with realistic input and`);
+  lines.push(`    inspected the actual rendered/returned output. Unit-test pass is necessary`);
+  lines.push(`    but NOT sufficient — unit tests verify the implementer's own assertions,`);
+  lines.push(`    not whether the output is human-usable. Look for evidence in the recent`);
+  lines.push(`    tool calls of: a node/python/shell invocation that exercises the new code`);
+  lines.push(`    with realistic args, OR a manual-inspection step (cat / file_read of the`);
+  lines.push(`    output, head/tail of generated content). If you find ONLY unit-test`);
+  lines.push(`    evidence and no realistic-invocation evidence for new code, this is a`);
+  lines.push(`    \`request_changes\` regardless of test count. Tests passing while output is`);
+  lines.push(`    nonsense is a recurring class of negligence this gate exists to catch.`);
+  lines.push(`12. **Empty-section / contradiction sweep**: For any output the implementer`);
+  lines.push(`    generates programmatically (prompts, configs, docs), check for sections`);
+  lines.push(`    that say "(none specified)" / "(no items)" / "(empty)" alongside framing`);
+  lines.push(`    text that asserts the section IS load-bearing. These contradictions`);
+  lines.push(`    indicate the generator wasn't tested with the empty / minimal-input case.`);
   lines.push(``);
   lines.push(`Do NOT flag:`);
   lines.push(`- Stylistic choices (formatting, naming) unless they hide a real bug.`);
@@ -514632,6 +514939,221 @@ var init_backward_pass_runner = __esm({
   }
 });
 
+// packages/orchestrator/dist/stuck-meta-analyzer.js
+function renderAnalyzerPrompt(inputs) {
+  const lines = [];
+  lines.push(`# STUCK-STATE META-ANALYSIS`);
+  lines.push(``);
+  lines.push(`You are a META-ANALYSIS sub-agent. Another agent (the implementer) is`);
+  lines.push(`stuck in an unproductive tool-call loop and the runtime's structural`);
+  lines.push(`stuck-detector has fired. Your job: examine the loop + state below and`);
+  lines.push(`return ONE specific next tool call that will unblock the implementer.`);
+  lines.push(``);
+  lines.push(`## Context`);
+  lines.push(`Goal: ${inputs.goal.slice(0, 600)}`);
+  lines.push(`Working directory: ${inputs.workingDir}`);
+  lines.push(`Trigger: ${inputs.triggerReason}  (turn ${inputs.turn})`);
+  if (inputs.workspaceSummary) {
+    lines.push(``);
+    lines.push(`## Workspace summary`);
+    lines.push(inputs.workspaceSummary.slice(0, 1500));
+  }
+  lines.push(``);
+  lines.push(`## Plan status (reconciled against disk)`);
+  if (inputs.planStatus.length === 0) {
+    lines.push(`(no plan items declared)`);
+  } else {
+    for (const t2 of inputs.planStatus.slice(0, 12)) {
+      lines.push(`  [${t2.reconciled}] ${t2.content.slice(0, 100)} — ${t2.rationale.slice(0, 120)}`);
+    }
+  }
+  lines.push(``);
+  lines.push(`## Recent unresolved failures`);
+  if (inputs.recentFailures.length === 0) {
+    lines.push(`(none)`);
+  } else {
+    for (const f2 of inputs.recentFailures.slice(0, 5)) {
+      lines.push(`  - ${f2.stem} (attempts=${f2.attempts}): ${f2.preview.slice(0, 200)}`);
+    }
+  }
+  lines.push(``);
+  lines.push(`## The loop pattern (recent tool calls, oldest first)`);
+  if (inputs.recentToolCalls.length === 0) {
+    lines.push(`(no recent calls)`);
+  } else {
+    const recent = inputs.recentToolCalls.slice(-30);
+    for (const c9 of recent) {
+      const status = c9.success === false ? "FAIL" : "OK";
+      const args = c9.argsKey ? ` ${c9.argsKey}` : "";
+      const preview = c9.outputPreview ? ` → "${c9.outputPreview.slice(0, 100)}"` : "";
+      lines.push(`  ${c9.name}${args} [${status}]${preview}`);
+    }
+  }
+  lines.push(``);
+  if (inputs.availableTools && inputs.availableTools.length > 0) {
+    lines.push(`## Tools available to the implementer`);
+    lines.push(inputs.availableTools.slice(0, 60).join(", "));
+    lines.push(``);
+  }
+  lines.push(`## Your task`);
+  lines.push(``);
+  lines.push(`Diagnose the loop in 1 sentence (what specific category of un-`);
+  lines.push(`productive activity is happening?). Then emit ONE concrete next`);
+  lines.push(`tool call the implementer should make. Do NOT emit a list of`);
+  lines.push(`alternatives. Do NOT emit categories like "PRODUCE" or "EDIT" —`);
+  lines.push(`emit the actual tool name and the actual args (with concrete`);
+  lines.push(`paths and a content seed when applicable).`);
+  lines.push(``);
+  lines.push(`Universal rules for the directive:`);
+  lines.push(`- Use only tools the implementer has access to.`);
+  lines.push(`- The next_action MUST produce new state on disk (file_write,`);
+  lines.push(`  file_edit, batch_edit, file_patch, shell mutation, or similar).`);
+  lines.push(`  If the loop is read-heavy, the unblocker is virtually always a`);
+  lines.push(`  write of some kind.`);
+  lines.push(`- The args_seed must contain enough content that the implementer`);
+  lines.push(`  can apply or refine it directly. For file writes, the args_seed`);
+  lines.push(`  MUST include a 'content' field with at least skeleton text`);
+  lines.push(`  (function signatures, imports, key structures). For shell calls,`);
+  lines.push(`  include the exact command.`);
+  lines.push(`- The anti_pattern must name the SPECIFIC repeated activity to stop`);
+  lines.push(`  (e.g. "list_directory of /tests/* repeatedly with no writes"),`);
+  lines.push(`  not just "stop being stuck".`);
+  lines.push(`- The verification must be a concrete check (a tool call OR an`);
+  lines.push(`  expected state change) the implementer runs after the action.`);
+  lines.push(``);
+  lines.push(`## Output format`);
+  lines.push(``);
+  lines.push(`Reason briefly (1-3 sentences) about the loop, then emit a SINGLE`);
+  lines.push(`JSON code block with this exact shape:`);
+  lines.push(``);
+  lines.push("```json");
+  lines.push(`{`);
+  lines.push(`  "diagnosis": "<1-sentence root cause>",`);
+  lines.push(`  "next_action": {`);
+  lines.push(`    "tool": "<exact tool name from the available list>",`);
+  lines.push(`    "args_seed": { /* concrete args; for writes, include 'path' + 'content' seed */ },`);
+  lines.push(`    "rationale": "<why this unblocks>"`);
+  lines.push(`  },`);
+  lines.push(`  "anti_pattern": "<the specific loop activity to stop>",`);
+  lines.push(`  "verification": "<concrete check after the action>"`);
+  lines.push(`}`);
+  lines.push("```");
+  lines.push(``);
+  lines.push(`Be SPECIFIC. Vague directives are useless to a stuck implementer.`);
+  return lines.join("\n");
+}
+function parseDirective(rawResponse) {
+  const fallback = (msg) => ({
+    diagnosis: `(meta-analyzer parse failed: ${msg})`,
+    next_action: {
+      tool: "(unknown)",
+      args_seed: {},
+      rationale: "Parser fell back; directive should not be injected."
+    },
+    anti_pattern: "(unknown)",
+    verification: "(unknown)",
+    raw: rawResponse,
+    parseFallback: true
+  });
+  if (!rawResponse || typeof rawResponse !== "string" || rawResponse.trim().length === 0) {
+    return fallback("empty response");
+  }
+  const fenceMatch = rawResponse.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+  let jsonText = null;
+  if (fenceMatch) {
+    jsonText = fenceMatch[1].trim();
+  } else {
+    const first2 = rawResponse.indexOf("{");
+    const last2 = rawResponse.lastIndexOf("}");
+    if (first2 !== -1 && last2 > first2)
+      jsonText = rawResponse.slice(first2, last2 + 1);
+  }
+  if (!jsonText)
+    return fallback("no JSON block found");
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch (e2) {
+    return fallback(`JSON parse: ${e2 instanceof Error ? e2.message : String(e2)}`);
+  }
+  if (!parsed || typeof parsed !== "object")
+    return fallback("not an object");
+  const diagnosis = typeof parsed.diagnosis === "string" && parsed.diagnosis.trim().length > 0 ? parsed.diagnosis.slice(0, 400) : "";
+  const next = parsed.next_action;
+  const tool = next && typeof next.tool === "string" ? next.tool.trim() : "";
+  const args_seed = next && typeof next.args_seed === "object" && next.args_seed !== null ? next.args_seed : {};
+  const rationale = next && typeof next.rationale === "string" ? next.rationale.slice(0, 400) : "";
+  const anti_pattern = typeof parsed.anti_pattern === "string" ? parsed.anti_pattern.slice(0, 400) : "";
+  const verification = typeof parsed.verification === "string" ? parsed.verification.slice(0, 400) : "";
+  if (!diagnosis || !tool || !anti_pattern || !verification) {
+    return fallback("missing required fields");
+  }
+  return {
+    diagnosis,
+    next_action: { tool, args_seed, rationale },
+    anti_pattern,
+    verification,
+    raw: rawResponse
+  };
+}
+function renderDirectiveAsMessage(d2) {
+  if (d2.parseFallback) {
+    return "";
+  }
+  const lines = [];
+  lines.push(`[STUCK-STATE META-ANALYZER — REG-49]`);
+  lines.push(``);
+  lines.push(`A meta-analyzer sub-agent reviewed the recent tool-call pattern, the`);
+  lines.push(`current world state, and the plan; it produced a single concrete`);
+  lines.push(`unblocking action for you to take.`);
+  lines.push(``);
+  lines.push(`DIAGNOSIS: ${d2.diagnosis}`);
+  lines.push(``);
+  lines.push(`STOP DOING (anti-pattern): ${d2.anti_pattern}`);
+  lines.push(``);
+  lines.push(`DO NEXT:`);
+  lines.push(`  Tool: ${d2.next_action.tool}`);
+  const argsJson = JSON.stringify(d2.next_action.args_seed, null, 2);
+  lines.push(`  Args:`);
+  for (const ln of argsJson.split("\n"))
+    lines.push(`    ${ln}`);
+  lines.push(`  Rationale: ${d2.next_action.rationale}`);
+  lines.push(``);
+  lines.push(`AFTER THE ACTION, verify with: ${d2.verification}`);
+  lines.push(``);
+  lines.push(`This directive comes from a meta-analysis of YOUR recent activity. The`);
+  lines.push(`args above are a SEED — refine them as needed (filenames, content) but`);
+  lines.push(`emit a tool call of this kind on your next response. Do NOT emit`);
+  lines.push(`another instance of the anti-pattern; that loop has been blocked.`);
+  return lines.join("\n");
+}
+async function runStuckAnalyzer(opts) {
+  const startMs = Date.now();
+  const prompt = renderAnalyzerPrompt(opts.inputs);
+  const promptBytes = Buffer.byteLength(prompt, "utf-8");
+  let raw = "";
+  try {
+    raw = await opts.callable(prompt);
+  } catch (e2) {
+    raw = "";
+  }
+  const responseBytes = Buffer.byteLength(raw, "utf-8");
+  const directive = parseDirective(raw);
+  const injection = renderDirectiveAsMessage(directive);
+  return {
+    directive,
+    injection,
+    promptBytes,
+    responseBytes,
+    durationMs: Date.now() - startMs
+  };
+}
+var init_stuck_meta_analyzer = __esm({
+  "packages/orchestrator/dist/stuck-meta-analyzer.js"() {
+    "use strict";
+  }
+});
+
 // packages/orchestrator/dist/pressure-gate.js
 function detectPressure(message2) {
   const hasProfanity = PRESSURE_SIGNALS.test(message2);
@@ -520197,7 +520719,7 @@ function executeHook(hook, env2 = {}) {
       maxBuffer: 1024 * 1024
       // 1MB
     });
-    const directive = parseDirective(output);
+    const directive = parseDirective2(output);
     return {
       success: true,
       output: output.trim(),
@@ -520215,7 +520737,7 @@ function executeHook(hook, env2 = {}) {
     };
   }
 }
-function parseDirective(output) {
+function parseDirective2(output) {
   const lines = output.split("\n");
   for (const line of lines) {
     const trimmed = line.trim();
@@ -520871,6 +521393,7 @@ var init_agenticRunner = __esm({
     init_world_state_regenerator();
     init_backward_pass_runner();
     init_world_state_plan_reconciler();
+    init_stuck_meta_analyzer();
     init_pressure_gate();
     init_dist5();
     init_dist7();
@@ -523747,6 +524270,91 @@ ${_staleSamples.join("\n")}` : ``,
                   content: `REG-44 STUCK detector fired at turn ${turn} — triggers=[${_trigLabels.join(",")}], reads=${_readCount}, mutations=${_mutationCount}, stale=${_staleCount}, window=${_windowCalls.length}`,
                   timestamp: (/* @__PURE__ */ new Date()).toISOString()
                 });
+                try {
+                  const _smaRaw = (process.env["OA_STUCK_META_ANALYZER"] || "off").toLowerCase();
+                  const _smaOn = _smaRaw === "on" || _smaRaw === "1" || _smaRaw === "true";
+                  if (_smaOn) {
+                    const _smaCallable = async (prompt) => {
+                      try {
+                        const _r = await this.backend.chatCompletion({
+                          messages: [
+                            { role: "system", content: "You are a META-ANALYSIS sub-agent. Audit the implementer's stuck state and emit a structured JSON directive." },
+                            { role: "user", content: prompt }
+                          ],
+                          tools: [],
+                          temperature: 0,
+                          maxTokens: parseInt(process.env["OA_STUCK_META_MAX_TOKENS"] || "2048", 10) || 2048,
+                          timeoutMs: parseInt(process.env["OA_STUCK_META_TIMEOUT_MS"] || "120000", 10) || 12e4
+                        });
+                        const _c = _r?.choices?.[0]?.message?.content;
+                        return typeof _c === "string" ? _c : "";
+                      } catch {
+                        return "";
+                      }
+                    };
+                    const _smaCalls = _windowCalls.slice(-25).map((c9) => ({
+                      name: c9.name,
+                      argsKey: c9.argsKey,
+                      success: c9.success,
+                      outputPreview: (c9.outputPreview || "").split(/\r?\n/)[0]?.slice(0, 120) ?? ""
+                    }));
+                    const _smaPlan = (() => {
+                      try {
+                        const _todos = this.readSessionTodos() || [];
+                        return _todos.slice(0, 12).map((t2) => ({
+                          content: t2.content || "",
+                          reconciled: t2.status || "pending",
+                          rationale: "(reconcile context unavailable here; structural status only)"
+                        }));
+                      } catch {
+                        return [];
+                      }
+                    })();
+                    const _smaFailures = Array.from(this._failureReflections.entries()).map(([stem, entry]) => ({
+                      stem,
+                      attempts: entry.attempts,
+                      preview: (entry.wentWrong || "").slice(0, 200)
+                    })).sort((a2, b) => b.attempts - a2.attempts).slice(0, 5);
+                    const _smaTools = Array.from(this.tools.keys());
+                    runStuckAnalyzer({
+                      inputs: {
+                        goal: this._taskState.originalGoal || this._taskState.goal || "",
+                        workingDir: this._workingDirectory || process.cwd(),
+                        triggerReason: `reg44-${_trigLabels[0] || "unknown"}`,
+                        recentToolCalls: _smaCalls,
+                        planStatus: _smaPlan,
+                        recentFailures: _smaFailures,
+                        workspaceSummary: void 0,
+                        // world-state regen owns this; analyzer infers from calls
+                        availableTools: _smaTools,
+                        turn
+                      },
+                      callable: _smaCallable
+                    }).then((_smaResult) => {
+                      if (_smaResult.injection && !_smaResult.directive.parseFallback) {
+                        messages2.push({ role: "system", content: _smaResult.injection });
+                        this.emit({
+                          type: "status",
+                          content: `REG-49 stuck-meta-analyzer fired at turn ${turn} — diagnosis="${_smaResult.directive.diagnosis.slice(0, 80)}", next=${_smaResult.directive.next_action.tool}, ${_smaResult.durationMs}ms`,
+                          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                        });
+                      } else {
+                        this.emit({
+                          type: "status",
+                          content: `REG-49 stuck-meta-analyzer parse failed at turn ${turn} — falling back to REG-44 abstract halt only`,
+                          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                        });
+                      }
+                    }).catch((_e) => {
+                      this.emit({
+                        type: "status",
+                        content: `REG-49 stuck-meta-analyzer threw: ${_e instanceof Error ? _e.message : String(_e)} (non-fatal)`,
+                        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                      });
+                    });
+                  }
+                } catch (_e) {
+                }
               }
             }
           }
@@ -596018,6 +596626,7 @@ function buildSubAgentTools(repoRoot, config) {
     new TodoWriteTool(),
     new TodoReadTool(),
     new WorkingNotesTool(),
+    new ProjectScaffoldingTool(),
     // Code understanding + navigation
     new CodebaseMapTool(repoRoot),
     new SemanticMapTool(repoRoot),
@@ -596181,6 +596790,7 @@ function buildTools(repoRoot, config, contextWindowSize, modelTier) {
     // Chunked file exploration + working notes + semantic map
     new FileExploreTool(repoRoot),
     new WorkingNotesTool(),
+    new ProjectScaffoldingTool(),
     // Agent-facing checklist (WO-TASK-02 — TodoWrite/TodoRead)
     new TodoWriteTool(),
     new TodoReadTool(),

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "open-agents-ai",
-  "version": "0.187.497",
+  "version": "0.187.499",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "open-agents-ai",
-      "version": "0.187.497",
+      "version": "0.187.499",
       "hasInstallScript": true,
       "license": "CC-BY-NC-4.0",
       "dependencies": {
@@ -7165,12 +7165,12 @@
       }
     },
     "node_modules/p-queue": {
-      "version": "9.1.2",
-      "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-9.1.2.tgz",
-      "integrity": "sha512-ktsDOALzTYTWWF1PbkNVg2rOt+HaOaMWJMUnt7T3qf5tvZ1L8dBW3tObzprBcXNMKkwj+yFSLqHso0x+UFcJXw==",
+      "version": "9.2.0",
+      "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-9.2.0.tgz",
+      "integrity": "sha512-dWgLE8AH0HjQ9fe74pUkKkvzzYT18Inp4zra3lKHnnwqGvcfcUBrvF2EAVX+envufDNBOzpPq/IBUONDbI7+3g==",
       "license": "MIT",
       "dependencies": {
-        "eventemitter3": "^5.0.1",
+        "eventemitter3": "^5.0.4",
         "p-timeout": "^7.0.0"
       },
       "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-agents-ai",
-  "version": "0.187.497",
+  "version": "0.187.499",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",