deepclause-sdk 0.0.68 → 0.0.70

package/README.md

@@ -71,6 +71,7 @@ All commands except `init`, `help`, `--help`, `--version`, and `-V` expect a `.d
     - `skill-creator.dml`
     - `CONDUCTOR_PROMPT.md`
     - `DML_COMPILER_PROMPT.md`
+    - `TASK_PROMPT.md`
 
 The default recipe is created at `.deepclause/system/recipes/deepclause-coding-workflow/SKILL.md`. It is a real example, not a placeholder: it teaches the conductor how to approach local repository changes with small edits and focused validation. You can edit it, remove it, or add your own recipes next to it.
 
@@ -85,6 +86,9 @@ Running `deepclause` with no subcommand starts the fullscreen TUI.
 - Execution log and context summary on the right
 - Slash commands such as `/new`, `/sessions`, `/set-model <model> [--slot <slot>]`, `/compile <spec>`, `/skill-creator <spec>`, `/cancel`, and `/<skill> [args]`
 - Direct shell commands with `!<command>`, streamed live in the execution pane and cancelled with `/cancel`
+- Persistent shell commands with `!!<command>`, which also append the command and its output to the active session transcript so the conductor can see them on the next turn
+
+Use `!<command>` when you just want an ephemeral shell escape in the execution pane. Use `!!<command>` when the shell result should become part of the conversation state for later conductor turns.
 
 For non-interactive use, `deepclause -p "..."` runs a single headless conductor turn with a fresh session.
 
@@ -228,10 +232,13 @@ If you want to customize behavior for one workspace without modifying the packag
 - `.deepclause/system/skill-creator.dml`
 - `.deepclause/system/CONDUCTOR_PROMPT.md`
 - `.deepclause/system/DML_COMPILER_PROMPT.md`
+- `.deepclause/system/TASK_PROMPT.md`
 - `.deepclause/system/recipes/<recipe-slug>/SKILL.md`
 
 When present, the CLI runtime prefers those files over the packaged system DML and system prompt markdown. For recipes, workspace files override packaged recipes with the same slug.
 
+`.deepclause/system/TASK_PROMPT.md` is the markdown template used for `task(...)` and `prompt(...)` harness calls. `deepclause init` seeds it into the workspace, and the runtime resolves that workspace copy before falling back to the packaged default.
+
 #### 2. Source-level hacking in this repository
 
 If you are developing DeepClause itself, these are the main files to edit:
@@ -240,6 +247,7 @@ If you are developing DeepClause itself, these are the main files to edit:
 - `src/system/assets/skills/skill-creator.dml` - the skill creator's DML logic
 - `src/system/assets/docs/CONDUCTOR_PROMPT.md` - the conductor system prompt template
 - `src/system/assets/docs/DML_COMPILER_PROMPT.md` - the skill creator/compiler system prompt template
+- `src/system/assets/docs/TASK_PROMPT.md` - the `task(...)` / `prompt(...)` harness template
 - `src/system/assets/recipes/` - packaged default recipes copied into new workspaces
 - `src/system/runtime/conductor.ts` - session loading, memory injection, tool registration, child-skill routing
 - `src/system/runtime/skill-creator.ts` - compile-slot execution, skill-creator tool registration, validation/testing/deploy flow
@@ -250,8 +258,8 @@ Notes:
 - The conductor uses the `gateway` model slot.
 - Normal compiled skills use the `run` model slot.
 - The skill creator uses the `compile` model slot.
-- The TUI context pane shows the resolved source paths for the conductor DML/prompt and skill creator DML/prompt.
-- Changes to those `.deepclause/system/` files are picked up on the next conductor turn or skill-creator run; a dedicated TUI reload is not required.
+- The TUI context pane shows the resolved source paths for the conductor DML/prompt, skill creator DML/prompt, and task prompt template.
+- Changes to those `.deepclause/system/` files are picked up on the next conductor turn, skill-creator run, or `task(...)` / `prompt(...)` execution; a dedicated TUI reload is not required.
 
 After source-level changes, rebuild the package:
 

package/dist/agent.d.ts

@@ -12,6 +12,7 @@ export interface AgentLoopOptions {
     outputVars: (string | TypedVar)[];
     memory: MemoryMessage[];
     tools: Map<string, ToolDefinition>;
+    workspacePath?: string;
     modelOptions: {
         model: string;
         provider: string;

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAsC1E,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,CAAC,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC,YAAY,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;KACvD,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACvE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,YAAY,EAAE,QAAQ,KAAK,IAAI,CAAC;IACzD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5E,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,mGAAmG;IACnG,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AA4KD;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsmBtF"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAwC1E,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,CAAC,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;KACvD,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACvE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,YAAY,EAAE,QAAQ,KAAK,IAAI,CAAC;IACzD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5E,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,mGAAmG;IACnG,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAqWD;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAuqBtF"}

package/dist/agent.js

@@ -9,9 +9,11 @@
 import { generateText, streamText, hasToolCall, tool as aiTool } from 'ai';
 import { z } from 'zod';
 import { createModelProvider } from './prolog/bridge.js';
+import { readSystemPromptAsset } from './system/assets/index.js';
 /** Maximum number of retries for LLM error finish reasons */
 const MAX_ERROR_RETRIES = 3;
 const DEFAULT_STREAM_RESPONSE_AWAIT_TIMEOUT_MS = 2_000;
+const MAX_STALLED_ITERATIONS = 3;
 /**
  * Clean Prolog dict markers ($tag, $t) from tool results
  * This makes the data more readable for the LLM
@@ -59,6 +61,110 @@ function normalizeMessagesForCompaction(messages) {
         content: normalizeMessageContent(message.content),
     }));
 }
+function normalizeLoopText(text) {
+    return text.trim().replace(/\s+/g, ' ').toLowerCase().slice(0, 400);
+}
+function sortJsonValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJsonValue);
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, sortJsonValue(entryValue)]));
+}
+function stableSerialize(value) {
+    try {
+        return JSON.stringify(sortJsonValue(value));
+    }
+    catch {
+        return String(value);
+    }
+}
+function buildIterationSignature(options) {
+    return stableSerialize({
+        finishReason: options.finishReason,
+        text: normalizeLoopText(options.text),
+        toolCalls: options.toolCalls.map((toolCall) => ({
+            toolName: toolCall.toolName,
+            input: toolCall.input,
+        })),
+        variables: options.variables,
+    });
+}
+function buildRecoveryPrompt(outputVars, repeatedStallCount, noToolCalls) {
+    const resultInstruction = outputVars.length > 0
+        ? `If you can answer now, call set_result for ${outputVars.map((variable) => variable.name).join(', ')} and then finish(true).`
+        : 'If you can answer now, call finish(true).';
+    if (repeatedStallCount > 0) {
+        return [
+            'You are repeating the same response or action without making progress.',
+            'Do not repeat the previous step.',
+            resultInstruction,
+            'Otherwise call one different tool, or call finish(false) if the task is blocked.',
+        ].join(' ');
+    }
+    if (noToolCalls) {
+        return [
+            'You did not call any tool and you did not finish the subtask.',
+            resultInstruction,
+            'If more information is required, call exactly one relevant tool.',
+            'If the task cannot be completed, call finish(false).',
+        ].join(' ');
+    }
+    return null;
+}
+function truncateSummaryText(text, maxLength = 240) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return text.slice(0, Math.max(0, maxLength - 3)) + '...';
+}
+function renderSummaryValue(value, maxLength = 140) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const cleaned = cleanPrologMarkers(value);
+    const rendered = typeof cleaned === 'string' ? cleaned : stableSerialize(cleaned);
+    const normalized = rendered.trim().replace(/\s+/g, ' ');
+    if (!normalized) {
+        return undefined;
+    }
+    return truncateSummaryText(normalized, maxLength);
+}
+function summarizeCompletedToolActivity(activity) {
+    const renderedInput = renderSummaryValue(activity.input, 100);
+    const renderedOutput = renderSummaryValue(activity.output, 140);
+    if (renderedInput && renderedOutput) {
+        return `${activity.toolName}(${renderedInput}) -> ${renderedOutput}`;
+    }
+    if (renderedOutput) {
+        return `${activity.toolName} -> ${renderedOutput}`;
+    }
+    if (renderedInput) {
+        return `${activity.toolName}(${renderedInput})`;
+    }
+    return activity.toolName;
+}
+function buildImplicitTaskSummary(assistantTextResponses, completedToolActivities) {
+    if (assistantTextResponses.length > 0) {
+        const latestAssistantText = assistantTextResponses[assistantTextResponses.length - 1]?.trim();
+        if (latestAssistantText) {
+            return latestAssistantText.startsWith('Task completed')
+                ? latestAssistantText
+                : `Task completed. Summary: ${truncateSummaryText(latestAssistantText)}`;
+        }
+    }
+    const renderedActivities = completedToolActivities
+        .map(summarizeCompletedToolActivity)
+        .filter((entry) => entry.length > 0);
+    if (renderedActivities.length > 0) {
+        return `Task completed. Summary: ${renderedActivities.slice(-3).join('; ')}`;
+    }
+    return 'Task completed successfully.';
+}
 function getStreamResponseAwaitTimeoutMs() {
     const raw = process.env.DC_STREAM_RESPONSE_TIMEOUT_MS;
     if (raw != null) {
@@ -128,6 +234,49 @@ function validateTypedResultValue(typedVar, value) {
             return null;
     }
 }
+function coerceTypedResultValue(typedVar, value) {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return value;
+    }
+    switch (typedVar.type) {
+        case 'array':
+            try {
+                const parsed = JSON.parse(trimmed);
+                return Array.isArray(parsed) ? parsed : value;
+            }
+            catch {
+                return value;
+            }
+        case 'object':
+            try {
+                const parsed = JSON.parse(trimmed);
+                return isPlainObject(parsed) ? parsed : value;
+            }
+            catch {
+                return value;
+            }
+        case 'number': {
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? parsed : value;
+        }
+        case 'integer': {
+            const parsed = Number(trimmed);
+            return Number.isInteger(parsed) ? parsed : value;
+        }
+        case 'boolean':
+            if (trimmed === 'true')
+                return true;
+            if (trimmed === 'false')
+                return false;
+            return value;
+        default:
+            return value;
+    }
+}
 /**
  * Convert JSON Schema to Zod schema
  * Handles basic JSON Schema types used in tool definitions
@@ -197,9 +346,13 @@ export async function runAgentLoop(options) {
     debugLog('Output vars:', normalizedOutputVars.map(v => `${v.name}:${v.type}`));
     const outputs = [];
     const variables = {};
+    const completedToolActivities = [];
+    const pendingStreamingToolCalls = [];
     let finished = false;
     let success = false;
     let errorRetryCount = 0;
+    let previousIterationSignature = null;
+    let repeatedStallCount = 0;
     // Build the AI SDK tools using Zod schemas
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const aiTools = {};
@@ -250,15 +403,16 @@ export async function runAgentLoop(options) {
             execute: async ({ variable, value }) => {
                 const typedVar = normalizedOutputVars.find(v => v.name === variable);
                 if (typedVar) {
-                    const validationError = validateTypedResultValue(typedVar, value);
+                    const coercedValue = coerceTypedResultValue(typedVar, value);
+                    const validationError = validateTypedResultValue(typedVar, coercedValue);
                     if (validationError) {
                         return {
                             success: false,
                             error: `${validationError} for ${variable}`,
                         };
                     }
-                    variables[variable] = value;
-                    return { success: true, variable, value };
+                    variables[variable] = coercedValue;
+                    return { success: true, variable, value: coercedValue };
                 }
                 return { success: false, error: `Unknown variable: ${variable}` };
             },
@@ -267,7 +421,7 @@ export async function runAgentLoop(options) {
     // Reserved internal tool names that cannot be overwritten by user-defined tools
     const reservedToolNames = ['finish', 'set_result'];
     // Add user-defined tools - convert JSON Schema to Zod
-    for (const [name, tool] of tools) {
+    for (const [name, tool] of options.tools) {
         if (reservedToolNames.includes(name)) {
             continue;
         }
@@ -289,7 +443,12 @@ export async function runAgentLoop(options) {
         });
     }
     // Build the base system prompt with task instructions and tools
-    const baseSystemPrompt = buildSystemPrompt(taskDescription, normalizedOutputVars, tools);
+    const baseSystemPrompt = await buildSystemPrompt({
+        taskDescription,
+        outputVars: normalizedOutputVars,
+        tools,
+        workspacePath: options.workspacePath,
+    });
     // Extract system context from memory (user-defined system() calls)
     const systemContext = memory
         .filter(m => m.role === 'system' && typeof m.content === 'string')
@@ -386,6 +545,7 @@ export async function runAgentLoop(options) {
                 });
                 // Collect results from fullStream
                 let fullText = '';
+                const toolCallsThisIteration = [];
                 let ttftMs = null; // time to first TEXT token
                 let ttfeMs = null; // time to first event (any type)
                 let ttfrMs = null; // time to first reasoning token
@@ -397,7 +557,6 @@ export async function runAgentLoop(options) {
                 let toolInputChunks = 0;
                 let toolInputChars = 0;
                 let finishReason = 'other';
-                let lastToolCallName = null;
                 let stepUsage = null;
                 let lastEventMs = apiCallMs;
                 const eventCounts = {};
@@ -433,13 +592,25 @@ export async function runAgentLoop(options) {
                         case 'tool-call':
                             if (firstToolCallMs === null)
                                 firstToolCallMs = nowMs - apiCallMs;
-                            lastToolCallName = part.toolName;
+                            toolCallsThisIteration.push({ toolName: part.toolName, input: part.input });
+                            pendingStreamingToolCalls.push({ toolName: part.toolName, input: part.input });
                             debugLog(`Tool call: ${part.toolName}`, JSON.stringify(part.input));
                             if (onToolCall) {
                                 onToolCall(part.toolName, part.input);
                             }
                             break;
                         case 'tool-result':
+                            {
+                                const pendingIndex = pendingStreamingToolCalls.findIndex((pending) => pending.toolName === part.toolName);
+                                const pendingCall = pendingIndex >= 0
+                                    ? pendingStreamingToolCalls.splice(pendingIndex, 1)[0]
+                                    : undefined;
+                                completedToolActivities.push({
+                                    toolName: part.toolName,
+                                    input: pendingCall?.input,
+                                    output: part.output,
+                                });
+                            }
                             debugLog(`Tool result for ${part.toolName}:`, JSON.stringify(part.output).substring(0, 500));
                             break;
                         case 'error':
@@ -484,10 +655,8 @@ export async function runAgentLoop(options) {
                     }
                 }
                 debugLog(`Iteration ${iteration} timing: TTFE=${ttfeMs ?? '-'}ms TTFR=${ttfrMs ?? '-'}ms TTFT=${ttftMs ?? 'no-text'}ms stream=${streamDoneMs}ms total=${Date.now() - iterStartMs}ms${usageStr}`);
-                // Check if finish was called during tool execution
                 if (finished) {
-                    debugLog('Finish tool was called, exiting loop');
-                    break;
+                    debugLog('Finish tool was called; finalizing streamed iteration before exit');
                 }
                 debugLog(`Response text: ${fullText || '(empty)'}`);
                 debugLog(`Finish reason: ${finishReason}`);
@@ -524,12 +693,26 @@ export async function runAgentLoop(options) {
                 else if (responseResolution.timedOut && fullText) {
                     messages.push({ role: 'assistant', content: fullText });
                 }
+                const iterationSignature = buildIterationSignature({
+                    finishReason,
+                    text: fullText,
+                    toolCalls: toolCallsThisIteration,
+                    variables,
+                });
+                repeatedStallCount = iterationSignature === previousIterationSignature ? repeatedStallCount + 1 : 0;
+                previousIterationSignature = iterationSignature;
+                if (!finished && repeatedStallCount >= MAX_STALLED_ITERATIONS) {
+                    success = false;
+                    outputs.push('Agent loop detected repeated non-progressing responses and stopped early.');
+                    break;
+                }
                 // If no tool calls were made, nudge the model to act.
                 // This handles 'stop', 'other', and any unexpected finish reason.
-                if (lastToolCallName === null && !finished) {
+                const recoveryPrompt = buildRecoveryPrompt(normalizedOutputVars, repeatedStallCount, toolCallsThisIteration.length === 0);
+                if (recoveryPrompt && !finished) {
                     messages.push({
                         role: 'user',
-                        content: 'Please take action using the available tools, or call finish() when done.',
+                        content: recoveryPrompt,
                     });
                 }
             }
@@ -574,10 +757,8 @@ export async function runAgentLoop(options) {
                     }
                 }
                 debugLog(`Iteration ${iteration} timing: generateText=${Date.now() - apiCallMs}ms total=${Date.now() - iterStartMs}ms${genUsageStr}`);
-                // Check if finish was called during tool execution
                 if (finished) {
-                    debugLog('Finish tool was called, exiting loop');
-                    break;
+                    debugLog('Finish tool was called; finalizing non-streaming iteration before exit');
                 }
                 debugLog(`Response text: ${result.text || '(empty)'}`);
                 debugLog(`Tool calls: ${result.toolCalls?.length ?? 0}`);
@@ -609,7 +790,13 @@ export async function runAgentLoop(options) {
                     }
                     // Log tool results
                     if (result.toolResults) {
-                        for (const tr of result.toolResults) {
+                        for (const [index, tr] of result.toolResults.entries()) {
+                            const matchingToolCall = result.toolCalls?.[index];
+                            completedToolActivities.push({
+                                toolName: tr.toolName,
+                                input: matchingToolCall?.input,
+                                output: tr.output,
+                            });
                             debugLog(`Tool result for ${tr.toolName}:`, JSON.stringify(tr.output).substring(0, 500));
                         }
                     }
@@ -617,12 +804,30 @@ export async function runAgentLoop(options) {
                 // Use response.messages to update message history (AI SDK v6 pattern)
                 // This is the key change - let the SDK handle message formatting
                 messages = [...messages, ...getResponseMessages(result.response)];
+                const toolCallsThisIteration = (result.toolCalls ?? []).map((toolCall) => ({
+                    toolName: toolCall.toolName,
+                    input: toolCall.input,
+                }));
+                const iterationSignature = buildIterationSignature({
+                    finishReason: result.finishReason,
+                    text: result.text,
+                    toolCalls: toolCallsThisIteration,
+                    variables,
+                });
+                repeatedStallCount = iterationSignature === previousIterationSignature ? repeatedStallCount + 1 : 0;
+                previousIterationSignature = iterationSignature;
+                if (!finished && repeatedStallCount >= MAX_STALLED_ITERATIONS) {
+                    success = false;
+                    outputs.push('Agent loop detected repeated non-progressing responses and stopped early.');
+                    break;
+                }
                 // If no tool calls were made, nudge the model to act.
                 // This handles 'stop', 'other', and any unexpected finish reason.
-                if ((!result.toolCalls || result.toolCalls.length === 0) && !finished) {
+                const recoveryPrompt = buildRecoveryPrompt(normalizedOutputVars, repeatedStallCount, toolCallsThisIteration.length === 0);
+                if (recoveryPrompt && !finished) {
                     messages.push({
                         role: 'user',
-                        content: 'Please take action using the available tools, or call finish() when done.',
+                        content: recoveryPrompt,
                     });
                 }
             }
@@ -682,6 +887,12 @@ export async function runAgentLoop(options) {
             content: `Task completed. Results: ${varSummary}`,
         });
     }
+    else if (success && normalizedOutputVars.length === 0) {
+        persistentMessages.push({
+            role: 'assistant',
+            content: buildImplicitTaskSummary(assistantTextResponses, completedToolActivities),
+        });
+    }
     else if (assistantTextResponses.length > 0) {
         persistentMessages.push({
             role: 'assistant',
@@ -712,10 +923,9 @@ function getResponseMessages(response) {
 /**
  * Build the system prompt for the agent
  */
-function buildSystemPrompt(taskDescription, outputVars, tools) {
+async function buildSystemPrompt(options) {
     const toolDescriptions = [];
-    // Normalize outputVars to TypedVar[]
-    const normalizedOutputVars = outputVars.map(v => typeof v === 'string' ? { name: v, type: 'string' } : v);
+    const normalizedOutputVars = options.outputVars;
     // Add finish tool description
     toolDescriptions.push('- finish(success: boolean): Signal task completion. Call finish(true) when done successfully, or finish(false) if the task cannot be completed.');
     // Add set_result tool if we have output variables
@@ -727,7 +937,7 @@ function buildSystemPrompt(taskDescription, outputVars, tools) {
         toolDescriptions.push(`- set_result(variable: string, value: any): Store a result value. Variable must be one of: ${varList}`);
     }
     // Add user-defined tools
-    for (const [name, tool] of tools) {
+    for (const [name, tool] of options.tools) {
         if (name === 'finish' || name === 'set_result')
             continue;
         // Build parameter signature from schema
@@ -742,50 +952,25 @@ function buildSystemPrompt(taskDescription, outputVars, tools) {
             .join(', ');
         toolDescriptions.push(`- ${name}(${paramList}): ${tool.description}`);
     }
-    let prompt = `You are an AI agent executing a subtask within a larger workflow. Your job is to complete the following subtask:
-
-Subtask: ${taskDescription}
-
-Available tools:
-
-${toolDescriptions.join('\n')}
-
-Workflow:
-1. Analyze the task and gather any needed information using available tools.
-2. Once the task is complete, call finish(true).
-
-If you determine the task cannot be completed, call finish(false) immediately.`;
-    if (normalizedOutputVars.length > 0) {
-        const varList = normalizedOutputVars.map(v => {
-            const typeStr = v.type === 'array' && v.itemType ? `array<${v.itemType}>` : v.type;
-            return `"${v.name}" (${typeStr})`;
-        }).join(', ');
-        prompt += `
-
-IMPORTANT: You MUST use set_result() to store values for: ${varList}
-Call set_result for each variable before calling finish.
-The tool will enforce strict type checking based on the variable type.`;
-    }
-    prompt += `
-
-CRITICAL INSTRUCTIONS:
-- You MUST use the structured tool-calling interface to invoke tools.
-- NEVER write code syntax like print(), default_api.X(), or function_name() in your text response.
-- NEVER describe tool calls in text - actually invoke them using the tool interface.
-- Each tool call should be a separate structured function call, not embedded in text.
-- When storing values, pass simple strings without code formatting or escaping unless the type is 'string'.
-
-EXAMPLES OF CORRECT TOOL USAGE:
-
-To complete a task successfully, invoke the finish tool with:
-  Tool: finish
-  Arguments: { "success": true }
-
-WRONG (do NOT do this):
-- print(finish(success=true))
-- default_api.set_result(variable="X", value="Y")
-- I will now call finish(true)
-- \`\`\`finish(success=true)\`\`\``;
-    return prompt;
+    const resultSection = normalizedOutputVars.length > 0
+        ? [
+            'You must set all named results before finishing successfully.',
+            ...normalizedOutputVars.map((variable) => {
+                const typeStr = variable.type === 'array' && variable.itemType ? `array<${variable.itemType}>` : variable.type;
+                return `- ${variable.name}: ${typeStr}`;
+            }),
+        ].join('\n')
+        : 'No named result variables are required. Call finish(true) as soon as the subtask is complete.';
+    const stallGuidance = [
+        '- Do not repeat the same explanation or identical tool call if the previous turn did not change the state.',
+        '- If you are stuck, either choose one different tool or call finish(false).',
+        '- Once enough information exists, stop planning, set results if needed, and finish.',
+    ].join('\n');
+    const template = await readSystemPromptAsset('task', { workspacePath: options.workspacePath });
+    return template
+        .replace('{TASK_DESCRIPTION}', options.taskDescription)
+        .replace('{TOOL_DESCRIPTIONS}', toolDescriptions.join('\n'))
+        .replace('{RESULT_SECTION}', resultSection)
+        .replace('{STALL_GUIDANCE}', stallGuidance);
 }
 //# sourceMappingURL=agent.js.map