prism-mcp-server 7.0.1 → 7.3.1

package/README.md

@@ -28,6 +28,8 @@ Works with **Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Gem
 - [What Makes Prism Different](#-what-makes-prism-different)
 - [Use Cases](#-use-cases)
 - [What's New](#-whats-new)
+  - [v7.3.1 Dark Factory (Fail-Closed Execution)](#v731--dark-factory-fail-closed-execution-)
+  - [v7.2.0 The "Executive Function" Update (Planned)](#v720--the-executive-function-update-)
 - [How Prism Compares](#-how-prism-compares)
 - [Tool Reference](#-tool-reference)
 - [Environment Variables](#environment-variables)
@@ -385,6 +387,9 @@ Powered by a pure TypeScript port of Google's TurboQuant (inspired by Google's I
 ### 🐝 Multi-Agent Hivemind
 Multiple agents (dev, QA, PM) can work on the same project with **role-isolated memory**. Agents discover each other automatically, share context in real-time via Telepathy sync, and see a team roster during context loading. → [Multi-agent setup example](examples/multi-agent-hivemind/)
 
+### 🚦 Task Router
+Prism can score coding tasks and recommend whether to keep execution on the host model or delegate to local Claw. This enables faster handling of small, local-safe edits while preserving host execution for non-delegable or higher-complexity work. In client startup/skill flows, use defensive delegation: route only coding tasks, call `session_task_route` only when available, delegate to `claw` only when executor tooling exists and task is non-destructive, and fallback to host when router/executor is unavailable. → [Task router real-life example](examples/router_real_life_test.ts)
+
 ### 🖼️ Visual Memory
 Save UI screenshots, architecture diagrams, and bug states to a searchable vault. Images are auto-captioned by a VLM (Claude Vision / GPT-4V / Gemini) and become semantically searchable across sessions.
 
@@ -407,7 +412,7 @@ Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.z
 
 **Consulting / multi-project** — Switch between client projects with progressive loading: `quick` (~50 tokens), `standard` (~200), or `deep` (~1000+).
 
-**Visual debugging** — Save UI screenshots to searchable memory. Find that CSS bug from last week by description.
+**Complex refactoring (v7.2 planned)** — Prism’s roadmap adds plan-first execution for multi-step changes with persistent plan-state tracking across sessions.
 
 **Team onboarding** — New team member's agent loads the full project history instantly.
 
@@ -436,8 +441,100 @@ Then continue a specific thread with a follow-up message to the selected agent,
 
 ## 🆕 What's New
 
+### v7.3.1 — Dark Factory (Fail-Closed Execution) 🏭
+> **Current stable release.** Hardened autonomous pipeline execution with a structured JSON action contract.
+
+When an AI agent executes code autonomously — no human watching, no approval step — a single hallucinated file path can write outside your project, corrupt sibling repos, or hit system files. This is the "dark factory" problem: **lights-out execution demands machine-enforced safety, not LLM good behavior.**
+
+> *"I started building testing harnesses with programmatic checks in the planning phase across 3 layers. I got this idea when I was doing a complex ETL process across 3 databases and I needed to stack 9's on data accuracy, but also across the agent layer. After a considerable amount of hair pulling, I started to front load. It's now part of my lifecycle harness that my dark factory uses by default."*
+> — [Stephen Driggs](https://linkedin.com/in/stephendriggs), VP Product AI at Shift4
+
+Prism v7.3.1 implements exactly this: a **3-gate fail-closed pipeline** where every `EXECUTE` step must pass parse, type, and scope validation before any filesystem side effect occurs.
+
+- 🔒 **Structured Action Contract** — `EXECUTE` steps must return machine-parseable JSON conforming to `{ actions: [{ type, targetPath, content? }] }`. Free-form text is rejected at the gate.
+- 🛡️ **3-Strategy Defensive Parser** — Raw JSON → fenced code block extraction → brace extraction. Handles adversarial LLM output (preamble text, markdown fences, trailing commentary) without ever executing malformed payloads.
+- ✅ **Type Validation** — Only `READ_FILE | WRITE_FILE | PATCH_FILE | RUN_TEST` are permitted. Novel action types invented by the LLM are rejected.
+- 📏 **Scope Validation** — Every `targetPath` is resolved against the pipeline's `workingDirectory` via `SafetyController.validateActionsInScope()`. Path traversal (`../`), sibling-prefix bypasses, and absolute paths outside the boundary are blocked.
+- 🚫 **Pipeline-Level Termination** — A scope violation doesn't just fail the step — it **terminates the entire pipeline** with `status: FAILED` and emits a `failure` experience event for the ML routing layer.
+
+<details>
+<summary><strong>🔬 The 3-Gate Architecture: How a Path Traversal Attack Fails</strong></summary>
+
+**Scenario:** An LLM running autonomously in a Dark Factory pipeline targeting `/home/user/my-app` produces this output for an EXECUTE step:
+
+```json
+{
+  "actions": [
+    { "type": "WRITE_FILE", "targetPath": "src/utils.ts", "content": "// valid" },
+    { "type": "WRITE_FILE", "targetPath": "../../.ssh/authorized_keys", "content": "ssh-rsa ATTACK..." }
+  ]
+}
+```
+
+**Gate 1 — Parse:** ✅ Valid JSON. The 3-strategy parser extracts it cleanly.
+
+**Gate 2 — Type:** ✅ Both actions use `WRITE_FILE`, a valid `ActionType`.
+
+**Gate 3 — Scope:** 🚫 **BLOCKED.** `SafetyController.validateActionsInScope()` resolves `../../.ssh/authorized_keys` to `/home/user/.ssh/authorized_keys` — which is **outside** `/home/user/my-app`. The violation is detected *before* any write occurs.
+
+**Result:** The entire pipeline is terminated immediately. No files are written — not even the valid `src/utils.ts`. A `failure` experience event is emitted so the ML router can learn to avoid this pattern.
+
+```
+ Pipeline FAILED: Scope violation — action[1] targetPath
+ "../../.ssh/authorized_keys" resolves outside workingDirectory
+```
+
+**Without v7.3.1:** The LLM's raw text output would be interpreted as instructions, and the agent runtime would attempt the write — potentially succeeding depending on filesystem permissions.
+
+**With v7.3.1:** The structured contract makes this class of attack impossible. The LLM never touches the filesystem directly; every action is validated through the 3-gate pipeline first.
+
+</details>
+
+<details>
+<summary><strong>🧪 Edge Cases Covered (67 tests)</strong></summary>
+
+| Category | Examples |
+|----------|----------|
+| **Parse adversarial output** | Prose preamble + JSON, nested fences, empty input, non-string input |
+| **Type coercion** | `"DELETE_FILE"`, `"EXEC_CMD"`, numeric types, null types |
+| **Path traversal** | `../`, `../../`, `/etc/passwd`, null bytes, unicode normalization, embedded newlines |
+| **Shape validation** | Missing `actions` array, non-object actions, empty `targetPath`, root-type coercion |
+| **Stress payloads** | 100-action arrays, 100KB content strings, 500-segment deep paths |
+
+</details>
+
+### v7.2.0 — The "Executive Function" Update 🔭
+> **Planned roadmap release.** Extends Prism from persistent memory toward autonomous plan execution.
+
+- 🗺️ **Autonomous Plan Decomposition (planned)** — Proposed `session_plan_decompose` tool to transform ambiguous multi-step goals into a structured task DAG.
+- 🔄 **Self-Healing Execution Loop (planned)** — Proposed plan-state engine to capture failed steps, suggest corrective actions, and re-queue recoverable sub-tasks before escalation.
+- 📉 **DAG Plan Visualizer (planned)** — Proposed dashboard Plan/Goal Monitor to render step progress, dependency state, and execution pivots in real time.
+- 🧠 **Context-Aware Goal Tracking (planned)** — Proposed active-plan injection during context loading so agents track not only prior work but current plan position.
+- ⚙️ **Recursive Tool Chaining (planned)** — Proposed middleware path for lower-latency plan-step updates across complex workflows.
+- 🧪 **Plan Integrity Tests (planned)** — Proposed suite validating plan-state persistence across interruptions and session handoffs.
+
+<details>
+<summary><strong>🔬 Concept Example: Before vs. After v7.2</strong></summary>
+
+**Scenario:** "Refactor the Auth module and update the unit tests."
+
+**Before (linear prompting):** The agent executes in sequence but can lose place after errors unless the host prompt restates state.
+
+**After (executive planning):** Agent decomposes to a DAG, executes per-step, recovers from failures via plan-state retries, and resumes from the correct dependency node.
+
+</details>
+
+### v7.1.0 — Prism Task Router (Heuristic + ML Experience) ✅
+> **Current stable release.** Multi-agent task routing with dynamic local vs host model delegation.
+
+- 🚦 **Heuristic Routing Engine** — Deterministic `session_task_route` tool dynamically routes tasks to either the host cloud model or local agent (Claw) based on task description, file count, and scope. Evaluated over 5 core signals.
+- 🤖 **Experience-Based ML Routing** — Cold-start protected ML layer leverages the historical performance (Win Rate) extracted by the `routerExperience` system to apply dynamic confidence boosts or penalties into the routing score.
+- 🧪 **Live Testing Samples** — Demo script added in [`examples/router_real_life_test.ts`](examples/router_real_life_test.ts) for deterministic `computeRoute()` scenarios (simple vs complex tasks), with a note that experience-adjusted routing is applied in `session_task_route` handler path.
+- 🖥️ **Dashboard Integration** — Added visual monitor and configuration toggles directly in `src/dashboard/ui.ts` under Node Editor settings.
+- 🧩 **Tool Discoverability** — Fully integrates `session_task_route` into the external registry.
+
 ### v7.0.0 — ACT-R Activation Memory ✅
-> **Current stable release.** Memory retrieval now uses a scientifically-grounded cognitive model.
+> **Previous stable release.** Memory retrieval now uses a scientifically-grounded cognitive model.
 
 - 🧠 **ACT-R Base-Level Activation** — `B_i = ln(Σ t_j^(-d))` computes recency × frequency activation per memory. Recent, frequently-accessed memories surface first; cold memories fade to near-zero. Based on Anderson's *Adaptive Control of Thought—Rational* (ACM, 2025).
 - 🔗 **Candidate-Scoped Spreading Activation** — `S_i = Σ(W × strength)` for links within the current search result set only. Prevents "God node" centrality from dominating rankings (Rule #5).
@@ -693,6 +790,41 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 
 </details>
 
+<details>
+<summary><strong>Task Routing (1 tool)</strong></summary>
+
+Requires `PRISM_TASK_ROUTER_ENABLED=true` (or dashboard toggle).
+
+| Tool | Purpose |
+|------|---------|
+| `session_task_route` | Scores task complexity and recommends host vs. local Claw delegation (`claw_run_task` when delegable; host fallback when executor/tooling is unavailable) |
+
+</details>
+
+<details>
+<summary><strong>Dark Factory Orchestration (3 tools)</strong></summary>
+
+Requires `PRISM_DARK_FACTORY_ENABLED=true`.
+
+| Tool | Purpose |
+|------|---------|
+| `session_start_pipeline` | Create and enqueue a background autonomous pipeline |
+| `session_check_pipeline_status` | Poll the current step, iteration, and status of a pipeline |
+| `session_abort_pipeline` | Emergency kill switch to halt a running background pipeline |
+
+</details>
+
+<details>
+<summary><strong>Executive Planning (Planned for v7.2)</strong></summary>
+
+| Tool | Purpose |
+|------|---------|
+| `session_plan_decompose` | Decompose natural language goals into a structured DAG of tasks |
+| `session_plan_step_update` | Atomically update the status/result of a specific sub-task |
+| `session_plan_get_active` | Retrieve the current execution DAG and task statuses |
+
+</details>
+
 ---
 
 ## Environment Variables
@@ -731,6 +863,9 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | `PRISM_SCHOLAR_INTERVAL_MS` | No | Scholar interval in ms (default: `0` = manual only) |
 | `PRISM_SCHOLAR_TOPICS` | No | Comma-separated research topics (default: `"ai,agents"`) |
 | `PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN` | No | Max articles per Scholar run (default: `3`) |
+| `PRISM_TASK_ROUTER_ENABLED` | No | `"true"` to enable task-router tool registration |
+| `PRISM_TASK_ROUTER_CONFIDENCE_THRESHOLD` | No | Min confidence required to delegate to Claw (default: `0.6`) |
+| `PRISM_TASK_ROUTER_MAX_CLAW_COMPLEXITY` | No | Max complexity score delegable to Claw (default: `4`) |
 | `PRISM_HDC_ENABLED` | No | `"true"` (default) to enable HDC cognitive routing pipeline |
 | `PRISM_HDC_EXPLAINABILITY_ENABLED` | No | `"true"` (default) to include convergence/distance/ambiguity in cognitive route responses |
 | `PRISM_ACTR_ENABLED` | No | `"true"` (default) to enable ACT-R activation re-ranking on semantic search |
@@ -738,6 +873,7 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | `PRISM_ACTR_WEIGHT_SIMILARITY` | No | Composite score similarity weight (default: `0.7`) |
 | `PRISM_ACTR_WEIGHT_ACTIVATION` | No | Composite score ACT-R activation weight (default: `0.3`) |
 | `PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS` | No | Days before access logs are pruned by background scheduler (default: `90`) |
+| `PRISM_DARK_FACTORY_ENABLED` | No | `"true"` to enable Dark Factory autonomous pipeline tools (`session_start_pipeline`, `session_check_pipeline_status`, `session_abort_pipeline`) |
 
 </details>
 
@@ -768,6 +904,7 @@ Prism is a **stdio-based MCP server** that manages persistent agent memory. Here
 │         ↕                                                │
 │  ┌────────────────────────────────────────────────────┐  │
 │  │  Background Workers                                │  │
+│  │  • Dark Factory (3-gate fail-closed pipelines)     │  │
 │  │  • Scheduler (TTL, decay, compaction, purge)       │  │
 │  │  • Web Scholar (Brave → Firecrawl → LLM → Ledger)  │  │
 │  │  • Hivemind heartbeats & Telepathy broadcasts      │  │
@@ -800,6 +937,7 @@ Each MCP client has its own mechanism for ensuring Prism context loads on sessio
 
 - **Claude Code** — Lifecycle hooks (`SessionStart` / `Stop`)
 - **Gemini / Antigravity** — Three-layer architecture (User Rules + AGENTS.md + Startup Skill)
+- **Task Router Integration (v7.2 guidance)** — For client startup/skills, use defensive delegation flow: route only coding tasks, call `session_task_route` only when available, delegate to `claw` only when executor exists and task is non-destructive, and fallback to host if router/executor is unavailable.
 - **Cursor / Windsurf / VS Code** — System prompt instructions
 
 All platforms benefit from the **server-side fallback** (v5.2.1): if `session_load_context` hasn't been called within 10 seconds, Prism auto-pushes context via `sendLoggingMessage`.
@@ -831,6 +969,8 @@ Prism is evolving from smart session logging toward a **cognitive memory archite
 | **v7.0** | Candidate-Scoped Spreading Activation — `S_i = Σ(W × strength)` bounded to search result set; prevents God-node dominance | Spreading activation networks (Collins & Loftus, 1975) | ✅ Shipped |
 | **v7.0** | Composite Retrieval Scoring — `0.7 × similarity + 0.3 × σ(activation)`; configurable via `PRISM_ACTR_WEIGHT_*` | Hybrid cognitive-neural retrieval models | ✅ Shipped |
 | **v7.0** | AccessLogBuffer — in-memory batch-write buffer with 5s flush; prevents SQLite `SQLITE_BUSY` under parallel agents | Production reliability engineering | ✅ Shipped |
+| **v7.3** | Dark Factory — 3-gate fail-closed EXECUTE pipeline (parse → type → scope) with structured JSON action contract | Industrial safety systems (defense-in-depth, fail-closed valves) | ✅ Shipped |
+| **v7.2** | Executive Planning & DAG tracking | Prefrontal cortex executive control + Directed Acyclic Graph planning | 🔭 Horizon |
 | **v7.x** | Affect-Tagged Memory — sentiment shapes what gets recalled | Affect-modulated retrieval (neuroscience) | 🔭 Horizon |
 | **v8+** | Zero-Search Retrieval — no index, no ANN, just ask the vector | Holographic Reduced Representations | 🔭 Horizon |
 
@@ -848,9 +988,18 @@ Shipped in v6.2.0. Edge synthesis, graph pruning with SLO observability, tempora
 ### v6.5: Cognitive Architecture ✅
 Shipped. Full Superposed Memory (SDM) + Hyperdimensional Computing (HDC/VSA) cognitive routing pipeline. Compositional memory states via XOR binding, Hamming resolution, and policy-gated routing (direct / clarify / fallback). 705 tests passing.
 
+### v7.3: Dark Factory — Fail-Closed Execution ✅
+Shipped. Structured JSON action contract for autonomous `EXECUTE` steps. 3-gate validation pipeline (parse → type → scope) terminates pipelines on any violation before filesystem side effects. 67 edge-case tests covering adversarial LLM output, path traversal, and type coercion.
+
+### v7.1: Prism Task Router ✅
+Shipped. Deterministic task routing (`session_task_route`) with optional experience-based confidence adjustment for host vs. local Claw delegation.
+
 ### v7.0: ACT-R Activation Memory ✅
 Shipped. Scientifically-grounded retrieval re-ranking via ACT-R base-level activation (`B_i = ln(Σ t_j^(-d))`), candidate-scoped spreading activation, parameterized sigmoid normalization, composite scoring, and zero-cold-start access log infrastructure. 49 dedicated unit tests, 705 total passing.
 
+### v7.2: Executive Function 🔭
+Planned. Adds autonomous plan decomposition, DAG-backed step tracking, and self-healing execution loops for complex multi-step operations.
+
 ### Future Tracks
 - **v7.x: Affect-Tagged Memory** — Recall prioritization improves by weighting memories with affective/contextual valence, making surfaced context more behaviorally useful.
 - **v8+: Zero-Search Retrieval** — Direct vector-addressed recall (“just ask the vector”) reduces retrieval indirection and moves Prism toward truly native associative memory.

package/dist/config.js

@@ -231,3 +231,29 @@ export const PRISM_ACTR_MAX_ACCESSES_PER_ENTRY = parseInt(process.env.PRISM_ACTR
 export const PRISM_ACTR_BUFFER_FLUSH_MS = parseInt(process.env.PRISM_ACTR_BUFFER_FLUSH_MS || "5000", 10);
 /** Days to retain access log entries before pruning. (Default: 90) */
 export const PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS = parseInt(process.env.PRISM_ACTR_ACCESS_LOG_RETENTION_DAYS || "90", 10);
+// ─── v7.1: Task Router Configuration ─────────────────────────
+// Deterministic heuristic-based routing for delegating coding tasks
+// between the host cloud model and the local claw-code-agent.
+// Set PRISM_TASK_ROUTER_ENABLED=true to unlock the session_task_route tool.
+/** Master switch for the task router tool. */
+export const PRISM_TASK_ROUTER_ENABLED_ENV = process.env.PRISM_TASK_ROUTER_ENABLED === "true";
+/** Confidence threshold below which routing defaults to the host model. (Default: 0.6) */
+export const PRISM_TASK_ROUTER_CONFIDENCE_THRESHOLD = parseFloat(process.env.PRISM_TASK_ROUTER_CONFIDENCE_THRESHOLD || "0.6");
+/** Maximum complexity score (1-10) that Claw can handle. Tasks above this → host. (Default: 4) */
+export const PRISM_TASK_ROUTER_MAX_CLAW_COMPLEXITY = parseInt(process.env.PRISM_TASK_ROUTER_MAX_CLAW_COMPLEXITY || "4", 10);
+// ─── v7.2: Verification Harness ──────────────────────────────
+/** Master switch for the v7.2.0 enhanced verification harness. */
+export const PRISM_VERIFICATION_HARNESS_ENABLED = process.env.PRISM_VERIFICATION_HARNESS_ENABLED === "true";
+/** Comma-separated list of verification layers to run. */
+export const PRISM_VERIFICATION_LAYERS = (process.env.PRISM_VERIFICATION_LAYERS || "data,agent,pipeline").split(",").map(l => l.trim()).filter(Boolean);
+/** Default severity floor for all assertions. Overrides individual assertion severity when higher. */
+export const PRISM_VERIFICATION_DEFAULT_SEVERITY = (process.env.PRISM_VERIFICATION_DEFAULT_SEVERITY || "warn");
+// ─── v7.3: Dark Factory Orchestration ─────────────────────────
+// Autonomous pipeline runner: PLAN → EXECUTE → VERIFY → iterate.
+// Opt-in because it executes LLM calls in the background.
+/** Master switch for the Dark Factory background runner. */
+export const PRISM_DARK_FACTORY_ENABLED = process.env.PRISM_DARK_FACTORY_ENABLED === "true"; // Opt-in
+/** Poll interval for the runner loop (ms). Default: 30s. */
+export const PRISM_DARK_FACTORY_POLL_MS = parseInt(process.env.PRISM_DARK_FACTORY_POLL_MS || "30000", 10);
+/** Default max wall-clock time per pipeline (ms). Default: 15 minutes. */
+export const PRISM_DARK_FACTORY_MAX_RUNTIME_MS = parseInt(process.env.PRISM_DARK_FACTORY_MAX_RUNTIME_MS || "900000", 10);

package/dist/darkfactory/clawInvocation.js

@@ -0,0 +1,77 @@
+import { getLLMProvider } from '../utils/llm/factory.js';
+import { OpenAIAdapter } from '../utils/llm/adapters/openai.js';
+import { SafetyController } from './safetyController.js';
+import { debugLog } from '../utils/logger.js';
+/**
+ * JSON output schema instruction injected into EXECUTE step prompts.
+ * Forces the LLM to respond with machine-parseable structured output
+ * instead of free-form text. The runner validates this shape before
+ * any actions are applied.
+ */
+const EXECUTE_JSON_SCHEMA = `
+You MUST respond with ONLY a valid JSON object matching this schema:
+{
+  "actions": [
+    {
+      "type": "READ_FILE" | "WRITE_FILE" | "PATCH_FILE" | "RUN_TEST",
+      "targetPath": "<relative path within the workspace>",
+      "content": "<file content for WRITE_FILE>",
+      "patch": "<patch content for PATCH_FILE>",
+      "command": "<test command for RUN_TEST>"
+    }
+  ],
+  "notes": "<optional summary of what you did>"
+}
+
+RULES:
+- type MUST be one of: READ_FILE, WRITE_FILE, PATCH_FILE, RUN_TEST
+- targetPath MUST be a relative path within the workspace
+- Do NOT include any text outside the JSON object
+- Do NOT use markdown code fences
+- If you cannot complete the task, return: {"actions": [], "notes": "reason"}
+`.trim();
+/**
+ * Invocation wrapper that routes payload specs to the local Claw agent model (Qwen 2.5),
+ * or the active LLM provider as fallback.
+ *
+ * Uses SafetyController.generateBoundaryPrompt() for scope injection
+ * instead of inline prompt construction — single source of truth for safety rules.
+ *
+ * v7.3.1: EXECUTE steps request structured JSON output via EXECUTE_JSON_SCHEMA.
+ *         Non-EXECUTE steps continue to use free-form text output.
+ */
+export async function invokeClawAgent(spec, state, timeoutMs = 120000 // 2 min default timeout for internal executions
+) {
+    // BYOM Override: Provide path to use alternative open-source pipelines 
+    // (e.g. through the OpenAI structured adapter which also points to local endpoints like Ollama / vLLM if configured)
+    const llm = spec.modelOverride
+        ? new OpenAIAdapter() // Bypasses the factory to route locally
+        : getLLMProvider();
+    // Scope injection via SafetyController — single source of truth
+    const systemPrompt = SafetyController.generateBoundaryPrompt(spec, state);
+    // v7.3.1: EXECUTE steps get structured JSON output instructions
+    const isExecuteStep = state.current_step === 'EXECUTE';
+    const executePrompt = isExecuteStep
+        ? `Based on the system instructions, execute the necessary actions for the current step (${state.current_step}).\n\n${EXECUTE_JSON_SCHEMA}`
+        : `Based on the system instructions, execute the necessary task for the current step (${state.current_step}). Respond with your actions and observations.`;
+    debugLog(`[ClawInvocation] Launching agent on pipeline ${state.id} step=${state.current_step} iter=${state.iteration} with ${timeoutMs}ms limit.${isExecuteStep ? ' (JSON mode)' : ''}`);
+    try {
+        // Timeout Promise to ensure the runner thread does not block indefinitely
+        const timeboundExecution = Promise.race([
+            llm.generateText(executePrompt, systemPrompt),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('LLM_EXECUTION_TIMEOUT')), timeoutMs))
+        ]);
+        const result = await timeboundExecution;
+        return {
+            success: true,
+            resultText: result
+        };
+    }
+    catch (error) {
+        debugLog(`[ClawInvocation] Exception during generation: ${error.message}`);
+        return {
+            success: false,
+            resultText: error.message
+        };
+    }
+}