deepclause-sdk 0.1.0 → 0.1.2

package/dist/runner.js

@@ -3,12 +3,16 @@
  */
 import { mountWorkspace } from './prolog/loader.js';
 import { runAgentLoop } from './agent.js';
+import { takePrologMessages } from './prolog/loader.js';
+import { validateToolArguments } from './repl/tool-arguments.js';
 import { judgeAnswersToValues, judgeCacheKey, normalizeJudgeState, parseJudgeQuestions, validateJudgeAnswers, valuesToPrologList } from './judge/marshal.js';
 import { buildToolCompletionEvent, buildToolFailureEvent, buildToolStartEvent, } from './system/runtime/shell-tool-events.js';
 import { checkToolPolicy } from './tools.js';
 import { generateLlmReply, sampleSingleToken } from './prolog/bridge.js';
 import { buildReasoningProviderOptions } from './system/config/model-database.js';
 import { resolveMediaRefs } from './system/runtime/media.js';
+import { resolveMedia } from './visualize/image.js';
+import { parseModelSpec } from './repl/model-resolver.js';
 /**
  * Convert swipl-wasm value to plain JavaScript value
  * Handles PrologString, PrologAtom, PrologList, etc.
@@ -109,11 +113,66 @@ export function decodeAgentOutputVars(rawOutputVars) {
             && 'type' in value
             && typeof value.name === 'string'
             && typeof value.type === 'string') {
-            return value;
+            const record = value;
+            const typed = value;
+            if (Array.isArray(record.fields)) {
+                typed.fields = record.fields
+                    .map((raw) => {
+                    const field = toJsValue(raw);
+                    if (!field || typeof field !== 'object')
+                        return undefined;
+                    const f = field;
+                    const name = f.name === undefined ? undefined : String(toJsValue(f.name));
+                    if (!name)
+                        return undefined;
+                    const required = Number(toJsValue(f.required)) === 1;
+                    const rawDefault = toJsValue(f.default);
+                    const hasDefault = rawDefault !== undefined && rawDefault !== 'no_default';
+                    return { name, type: String(toJsValue(f.type) ?? 'string'), required, ...(hasDefault ? { default: rawDefault } : {}) };
+                })
+                    .filter((field) => field !== undefined);
+            }
+            return typed;
         }
         return String(value);
     });
 }
+/**
+ * User tool info from Prolog
+ */
+/**
+ * The error a tool call gets when the tool is already running further up the
+ * call chain. Shared by the runtime guard and the withheld-tool stub.
+ */
+export function unavailableToolError(toolName) {
+    return `Tool '${toolName}' is not available in this task: it is already running further up the `
+        + 'call chain, and calling it again would recurse. Do not call it again; work with the text '
+        + 'you were given, or say what is missing.';
+}
+/**
+ * Parse the `toolScope` a `task/N` carries from `with_tools/2` / `without_tools/2`.
+ *
+ * Shape: `{$t:'t', whitelist:[[Names]]}` / `blacklist:[[Names]]`, or the atom
+ * `none`. The extra list nesting comes from the term's argument list.
+ */
+export function parseToolScope(raw) {
+    const value = toJsValue(raw);
+    if (!value || typeof value !== 'object' || !('$t' in value)) {
+        return { type: 'none', list: [] };
+    }
+    const compound = value;
+    const kind = 'whitelist' in compound ? 'whitelist' : 'blacklist' in compound ? 'blacklist' : null;
+    if (!kind)
+        return { type: 'none', list: [] };
+    const args = toJsValue(compound[kind]);
+    if (!Array.isArray(args) || args.length === 0)
+        return { type: kind, list: [] };
+    const inner = toJsValue(args[0]);
+    if (!Array.isArray(inner) || inner.length === 0)
+        return { type: kind, list: [] };
+    const names = toJsValue(inner[0]);
+    return { type: kind, list: Array.isArray(names) ? names.map((n) => String(n)) : [] };
+}
 /**
  * Map Prolog types to JSON Schema types
  */
@@ -143,6 +202,16 @@ export class DMLRunner {
     currentMemory = [];
     stepCounter = 0;
     judgeCache = new Map();
+    /**
+     * DML tools currently executing, innermost last.
+     *
+     * A tool must not be reachable by any agent it spawns, or `foo(A) :- task(...)`
+     * recurses: the agent inside `task/N` calls `foo`, which spawns another agent,
+     * and so on. The tool list is built *before* the tool runs (so a static list
+     * cannot know), which is why the check is applied when the model calls the
+     * tool rather than when the list is built.
+     */
+    toolCallStack = [];
     /**
      * Runner-owned frame table: FrameId -> { frame, engine }.
      * The Prolog session owns the authoritative engine handles
@@ -201,6 +270,9 @@ export class DMLRunner {
                 yield { type: 'error', content: engineResult.error };
                 return;
             }
+            // Now that the session module exists, install the workspace predicates so
+            // an SDK run resolves `read_file/2` and friends exactly like the REPL.
+            this.query(`deepclause_mi:repl_inject_workspace_predicates('${this.sessionId}')`);
             const frame = this.defaultFrameId ? this.frames.get(this.defaultFrameId)?.frame : undefined;
             if (!frame) {
                 yield { type: 'error', content: 'Failed to register default query frame' };
@@ -254,6 +326,15 @@ export class DMLRunner {
             }
             // Step the frame
             const step = this.stepFrame(frame.id);
+            // Prolog's own output (warnings from the term reader, `format(user_error,
+            // ...)`, a stray `write/1`) is captured by the loader rather than printed,
+            // and surfaced here so it renders in order and through the normal path.
+            // This is what keeps a warning from scribbling over an interactive frame.
+            for (const message of takePrologMessages()) {
+                yield message.channel === 'stdout'
+                    ? { type: 'output', content: message.text, channel: message.channel }
+                    : { type: 'log', content: message.text, level: message.level, channel: message.channel };
+            }
             if (process.env.DEBUG_STEPS) {
                 console.log('[MAIN_LOOP] step:', step.status, step.content?.substring(0, 50));
             }
@@ -266,6 +347,27 @@ export class DMLRunner {
                         yield { type: 'output', content: step.content };
                     }
                     break;
+                case 'media': {
+                    // `output(media(...))` — resolve to a base64 PNG for inline display.
+                    const payload = (step.payload ?? {});
+                    const media = {
+                        path: typeof payload.path === 'string' && payload.path ? payload.path : undefined,
+                        mimeType: typeof payload.mimeType === 'string' ? payload.mimeType : 'image/png',
+                        kind: typeof payload.kind === 'string' ? payload.kind : undefined,
+                        data: typeof payload.data === 'string' && payload.data ? payload.data : undefined,
+                    };
+                    const resolved = await resolveMedia(options.workspacePath ?? process.cwd(), media);
+                    yield {
+                        type: 'media',
+                        media: {
+                            path: media.path,
+                            mimeType: media.mimeType,
+                            kind: media.kind,
+                            data: resolved?.pngBase64,
+                        },
+                    };
+                    break;
+                }
                 case 'log':
                     if (step.content) {
                         yield { type: 'log', content: step.content };
@@ -630,14 +732,48 @@ export class DMLRunner {
             };
             // Extract memory from payload (now passed via state threading)
             const preparedMemory = this.extractMemoryFromPayload(rawPayload);
+            // A task with a `media(X)` typed output generates an image instead of running
+            // a text agent turn; the harness displays it only when it calls output(media(X)).
+            const mediaOutputs = outputVars.filter((v) => typeof v !== 'string' && v.type === 'media');
+            if (mediaOutputs.length > 0) {
+                const imageBackend = this.options.imageBackend;
+                if (!imageBackend) {
+                    yield { type: 'error', content: 'image generation is unavailable: no image backend is configured' };
+                    this.postAgentResult({ success: false, outputs: [], variables: {}, messages: preparedMemory }, preparedMemory);
+                    stepSucceeded = false;
+                    return;
+                }
+                const refs = [];
+                for (const message of preparedMemory) {
+                    for (const ref of message.media ?? []) {
+                        refs.push(ref);
+                    }
+                }
+                const generated = await imageBackend.generate({
+                    prompt: taskDescription,
+                    refs: refs.length > 0 ? refs : undefined,
+                    signal: options.signal,
+                });
+                const variables = {};
+                for (const output of mediaOutputs) {
+                    variables[output.name] = generated.path;
+                }
+                this.postAgentResult({ success: true, outputs: [], variables, messages: preparedMemory }, preparedMemory);
+                stepSucceeded = true;
+                return;
+            }
             // Extract reasoning effort and recipe context (from with_reasoning/with_recipe scoping)
             const reasoningEffort = String(toJsValue(rawPayload.reasoningEffort) ?? 'none');
             const recipeContext = String(toJsValue(rawPayload.recipeContext) ?? '');
+            // Per-call model override from with_model/2 (undefined = the session model).
+            const scopedModel = await this.resolveScope(rawPayload.modelSpec);
             // Build provider options — merge reasoning effort if set
             const baseProviderOptions = this.options.providerOptions ?? {};
             let effectiveProviderOptions = baseProviderOptions;
-            if (reasoningEffort !== 'none' && this.options.reasoningType && this.options.reasoningType !== 'none') {
-                const reasoningOpts = buildReasoningProviderOptions(reasoningEffort, this.options.reasoningType, this.options.reasoningBudgetMap);
+            const reasoningType = scopedModel?.reasoningType ?? this.options.reasoningType;
+            const reasoningBudgetMap = scopedModel?.reasoningBudgetMap ?? this.options.reasoningBudgetMap;
+            if (reasoningEffort !== 'none' && reasoningType && reasoningType !== 'none') {
+                const reasoningOpts = buildReasoningProviderOptions(reasoningEffort, reasoningType, reasoningBudgetMap);
                 effectiveProviderOptions = { ...baseProviderOptions, ...reasoningOpts };
             }
             // Prepend recipe context as a system message if present
@@ -696,14 +832,32 @@ export class DMLRunner {
             // Build available tools for the agent: the harness's DML tool/2 predicates
             // plus registered TS tools (reachable via exec/2).
             const selfReportingTools = undefined;
-            const availableTools = this.buildAgentTools(userTools, options.toolPolicy, async (toolName, args) => {
+            // Tools already executing further up the call chain are NOT offered to this
+            // agent. This is the `task/N` inside a tool: the tool that spawned this agent
+            // is on the stack, and offering it would invite the model to call the thing
+            // that is already running. A withheld tool is still declared (with the reason
+            // in its description) so a stray call gets an explanation, but it cannot run.
+            const withheld = [...this.toolCallStack];
+            // `with_tools/2` / `without_tools/2` on this `task/N` narrow the list further.
+            // This path used to ignore the scope, so scoping a `task/N` inside a predicate
+            // silently did nothing.
+            const scope = parseToolScope(rawPayload.toolScope);
+            const scopedUserTools = scope.type === 'whitelist'
+                ? userTools.filter((t) => scope.list.includes(t.name))
+                : scope.type === 'blacklist'
+                    ? userTools.filter((t) => !scope.list.includes(t.name))
+                    : userTools;
+            const availableTools = this.buildAgentTools(scopedUserTools, options.toolPolicy, async (toolName, args) => {
+                if (this.toolCallStack.includes(toolName)) {
+                    return { result: { error: unavailableToolError(toolName) }, outputs: [] };
+                }
                 return this.executeToolIsolated(toolName, args, augmentedTools, onToolOutput, {
                     workspacePath: options.workspacePath,
                     signal: options.signal,
                     toolPolicy: options.toolPolicy,
                     onModelCall: options.onModelCall,
-                }, [], emitToolCall, emitToolEvent);
-            });
+                }, withheld, emitToolCall, emitToolEvent);
+            }, withheld);
             // Run agent loop with streaming support
             const resultPromise = runAgentLoop({
                 taskDescription,
@@ -711,14 +865,16 @@ export class DMLRunner {
                 memory: effectiveMemory,
                 tools: availableTools,
                 workspacePath: options.workspacePath,
+                environment: this.options.environment,
                 resolveMedia: (refs) => this.readMediaRefs(options.workspacePath, refs),
                 modelOptions: {
-                    model: this.options.model,
-                    provider: this.options.provider,
-                    temperature: this.options.temperature,
-                    maxOutputTokens: this.options.maxTokens,
+                    model: scopedModel?.id ?? this.options.model,
+                    provider: scopedModel?.provider ?? this.options.provider,
+                    temperature: scopedModel?.temperature ?? this.options.temperature,
+                    maxOutputTokens: scopedModel?.maxTokens ?? this.options.maxTokens,
                     baseUrl: this.options.baseUrl,
                     providerOptions: effectiveProviderOptions,
+                    target: scopedModel,
                 },
                 streaming: this.options.streaming,
                 debug: this.options.debug,
@@ -767,7 +923,7 @@ export class DMLRunner {
                     }
                 },
                 onBeforeModelCall: async (messages, lastInputTokens) => {
-                    const hostCompacted = await this.applyHostCompaction(messages, lastInputTokens, emitRunnerEvent);
+                    const hostCompacted = await this.applyHostCompaction(messages, lastInputTokens, emitRunnerEvent, scopedModel?.contextWindow);
                     return hostCompacted ?? messages;
                 },
                 onAskUser: options.onInputRequired,
@@ -870,15 +1026,17 @@ export class DMLRunner {
         yield { type: 'task_activity', taskState: 'started', taskDescription, taskId: stepId };
         let succeeded = false;
         try {
+            const scopedModel = await this.resolveScope(data.modelSpec);
             const { token, usage } = await sampleSingleToken({
                 prompt,
                 allowedTokens,
                 modelOptions: {
-                    provider: this.options.provider,
-                    model: this.options.model,
-                    temperature: this.options.temperature,
+                    provider: scopedModel?.provider ?? this.options.provider,
+                    model: scopedModel?.id ?? this.options.model,
+                    temperature: scopedModel?.temperature ?? this.options.temperature,
                     baseUrl: this.options.baseUrl,
                     providerOptions: this.options.providerOptions,
+                    target: scopedModel,
                 },
                 signal: options.signal,
                 llmBackend: this.options.llmBackend,
@@ -909,15 +1067,17 @@ export class DMLRunner {
         yield { type: 'task_activity', taskState: 'started', taskDescription, taskId: stepId };
         let succeeded = false;
         try {
+            const scopedModel = await this.resolveScope(data.modelSpec);
             const { text, usage } = await generateLlmReply({
                 messages,
                 modelOptions: {
-                    provider: this.options.provider,
-                    model: this.options.model,
-                    temperature: this.options.temperature,
-                    maxOutputTokens: this.options.maxTokens,
+                    provider: scopedModel?.provider ?? this.options.provider,
+                    model: scopedModel?.id ?? this.options.model,
+                    temperature: scopedModel?.temperature ?? this.options.temperature,
+                    maxOutputTokens: scopedModel?.maxTokens ?? this.options.maxTokens,
                     baseUrl: this.options.baseUrl,
                     providerOptions: this.options.providerOptions,
+                    target: scopedModel,
                 },
                 signal: options.signal,
                 llmBackend: this.options.llmBackend,
@@ -1065,7 +1225,11 @@ export class DMLRunner {
             ? this.internalAskUserTool(options)
             : options.tools.get(toolName);
         if (!tool) {
-            yield { type: 'log', content: `Tool '${toolName}' not found` };
+            // Emit start+failure so the renderer shows the reason. A lone `log` event
+            // is not rendered in goal mode, so an unknown tool used to fail with no
+            // explanation at all — just `false.`
+            yield buildToolStartEvent(toolName, {});
+            yield buildToolFailureEvent(toolName, {}, new Error(`Tool not found: ${toolName}`));
             this.postExecResult({ success: false, error: `Tool not found: ${toolName}` });
             return;
         }
@@ -1073,6 +1237,15 @@ export class DMLRunner {
         try {
             // Execute tool
             argsObj = this.argsToObject(args, tool);
+            // A call that names a parameter the tool does not have cannot mean what it
+            // says, and dropping the key silently is how `stdin` looked like it worked.
+            const validation = validateToolArguments(toolName, tool.parameters, argsObj);
+            if (!validation.ok) {
+                yield buildToolStartEvent(toolName, argsObj);
+                yield buildToolFailureEvent(toolName, argsObj, new Error(validation.error));
+                this.postExecResult({ success: false, error: validation.error });
+                return;
+            }
             // Emit tool_call event before execution
             yield buildToolStartEvent(toolName, argsObj);
             const result = await tool.execute(argsObj, { signal: options.signal });
@@ -1247,14 +1420,26 @@ export class DMLRunner {
      * Only includes tools defined in DML - registered TypeScript tools are NOT exposed to the LLM.
      * DML tools can internally call exec/2 to use registered tools.
      */
-    buildAgentTools(userTools, _policy, executeToolInline) {
+    buildAgentTools(userTools, _policy, executeToolInline, excludedTools = []) {
         const result = new Map();
+        if (process.env.DC_TRACE_TOOLS) {
+            // Append to a file: inside the TUI, stderr is not visible.
+            try {
+                const { appendFileSync } = require('fs');
+                appendFileSync(process.env.DC_TRACE_TOOLS, `executing=${JSON.stringify(this.toolCallStack)} withheld=${JSON.stringify(excludedTools)} offered=${JSON.stringify(userTools.map((t) => t.name))}\n`);
+            }
+            catch { /* diagnostics must not break a run */ }
+        }
         // Add user-defined tools from DML file with schema info
         // These are the ONLY tools the LLM can call during task()
         // Do not apply the host runtime-tool policy to these DML predicates. Their
         // nested exec/2 calls pass through handleExec/executeToolIsolated, where
         // the policy still restricts actual host capabilities.
         for (const tool of userTools) {
+            // A withheld tool keeps its place in the list (so a call gets the reason),
+            // but carries no schema and a refusing implementation.
+            if (excludedTools.includes(tool.name))
+                continue;
             // Build JSON Schema properties from inputs
             const properties = {};
             const required = [];
@@ -1277,12 +1462,33 @@ export class DMLRunner {
                     required: required.length > 0 ? required : undefined,
                 },
                 execute: async (args) => {
+                    if (process.env.DC_TRACE_TOOLS) {
+                        // eslint-disable-next-line no-console
+                        console.error('[toolCall] %s executing=[%s] -> %s', toolName, this.toolCallStack.join(','), this.toolCallStack.includes(toolName) ? 'REFUSED' : 'ran');
+                    }
+                    // The list is built before the tool runs, so a tool already on the call
+                    // stack is refused here rather than being withheld from the list.
+                    if (this.toolCallStack.includes(toolName)) {
+                        return { error: unavailableToolError(toolName) };
+                    }
                     // Execute tool inline via main Prolog engine (shares state with task)
                     const { result: toolResult } = await executeToolInline(toolName, args);
                     return toolResult;
                 },
             });
         }
+        // Withheld tools are still declared, but their implementation refuses with
+        // the reason. Dropping them entirely makes a call look like a missing tool,
+        // which reads as a broken harness and invites a retry loop.
+        for (const tool of userTools) {
+            if (!excludedTools.includes(tool.name))
+                continue;
+            result.set(tool.name, {
+                description: `${tool.description || `Tool: ${tool.name}`} (unavailable in this task)`,
+                parameters: { type: 'object', properties: {} },
+                execute: async () => ({ error: unavailableToolError(tool.name) }),
+            });
+        }
         // NOTE: Registered TypeScript tools are NOT added here.
         // They are only available via exec/2 in DML code.
         // DML tools can call exec/2 internally to use registered tools.
@@ -1304,6 +1510,20 @@ export class DMLRunner {
      * @param onToolCall - Callback to emit tool call events from nested tasks
      */
     async executeToolIsolated(toolName, args, registeredTools, onOutput, runContext, excludedTools = [], onToolCall, onToolEvent) {
+        if (this.toolCallStack.includes(toolName)) {
+            return { result: { error: unavailableToolError(toolName) }, outputs: [] };
+        }
+        this.toolCallStack.push(toolName);
+        try {
+            return await this.executeToolIsolatedInner(toolName, args, registeredTools, onOutput, runContext, excludedTools, onToolCall, onToolEvent);
+        }
+        finally {
+            const index = this.toolCallStack.lastIndexOf(toolName);
+            if (index !== -1)
+                this.toolCallStack.splice(index, 1);
+        }
+    }
+    async executeToolIsolatedInner(toolName, args, registeredTools, onOutput, runContext, excludedTools = [], onToolCall, onToolEvent) {
         const outputs = [];
         if (process.env.DEBUG_RUNNER) {
             console.log('[RUNNER] executeToolIsolated called for:', toolName);
@@ -1360,6 +1580,8 @@ export class DMLRunner {
                         const tool = registeredTools.get(execToolName);
                         if (!tool) {
                             // Tool not found - post failure and continue
+                            onToolEvent?.(buildToolStartEvent(execToolName, {}));
+                            onToolEvent?.(buildToolFailureEvent(execToolName, {}, new Error(`Tool not found: ${execToolName}`)));
                             const postGoal = `deepclause_mi:post_exec_result('${this.sessionId}', failure, "Tool not found: ${execToolName}")`;
                             this.query(postGoal);
                         }
@@ -1367,6 +1589,13 @@ export class DMLRunner {
                             let argsObj = null;
                             try {
                                 argsObj = this.argsToObject(execArgs, tool);
+                                const validation = validateToolArguments(execToolName, tool.parameters, argsObj);
+                                if (!validation.ok) {
+                                    onToolEvent?.(buildToolStartEvent(execToolName, argsObj));
+                                    onToolEvent?.(buildToolFailureEvent(execToolName, argsObj, new Error(validation.error)));
+                                    this.query(`deepclause_mi:post_exec_result('${this.sessionId}', failure, ${JSON.stringify(validation.error)})`);
+                                    continue;
+                                }
                                 onToolEvent?.(buildToolStartEvent(execToolName, argsObj));
                                 const execResult = await tool.execute(argsObj, { signal: runContext.signal });
                                 onToolEvent?.(buildToolCompletionEvent(execToolName, argsObj, execResult));
@@ -1561,19 +1790,24 @@ export class DMLRunner {
                                 }
                             }
                         }
-                        // Build the call stack exclusion list (current tool + previously excluded)
-                        const nestedExcludedTools = [...excludedTools, toolName];
-                        // Filter tools based on:
-                        // 1. Call stack exclusion (prevent recursion)
-                        // 2. Manual scope (if specified via with_tools/without_tools)
-                        let filteredTools = userTools.filter(t => !nestedExcludedTools.includes(t.name));
+                        // Withhold every tool that is executing at this point, not just this one
+                        // and whatever was passed in: a tool reached by a longer chain (tool →
+                        // tool → task/N) must not be offered to the agent at the end of it
+                        // either. `this.toolCallStack` is the authoritative stack.
+                        const nestedExcludedTools = [
+                            ...new Set([...excludedTools, ...this.toolCallStack, toolName]),
+                        ];
+                        // Manual scope (with_tools/without_tools). Call-stack exclusion is
+                        // applied inside buildAgentTools, which needs the withheld names so
+                        // it can declare them and refuse them with the reason.
+                        let scopedTools = userTools;
                         if (toolScopeType === 'whitelist') {
                             // Only include tools in the whitelist
-                            filteredTools = filteredTools.filter(t => toolScopeList.includes(t.name));
+                            scopedTools = scopedTools.filter(t => toolScopeList.includes(t.name));
                         }
                         else if (toolScopeType === 'blacklist') {
                             // Exclude tools in the blacklist
-                            filteredTools = filteredTools.filter(t => !toolScopeList.includes(t.name));
+                            scopedTools = scopedTools.filter(t => !toolScopeList.includes(t.name));
                         }
                         // Extract memory
                         const memory = this.extractMemoryFromPayload(payload);
@@ -1601,7 +1835,7 @@ export class DMLRunner {
                             console.log('[RUNNER] Tool agent outputVars:', outputVars);
                             console.log('[RUNNER] Call stack excluded tools:', nestedExcludedTools);
                             console.log('[RUNNER] Tool scope:', toolScopeType, toolScopeList);
-                            console.log('[RUNNER] Available tools for nested agent:', filteredTools.map(t => t.name));
+                            console.log('[RUNNER] Available tools for nested agent:', scopedTools.map(t => t.name));
                             console.log('[RUNNER] Memory passed to nested agent:', memory.length, 'messages');
                             if (memory.length > 0) {
                                 console.log('[RUNNER] Memory contents:', JSON.stringify(memory, null, 2));
@@ -1611,8 +1845,8 @@ export class DMLRunner {
                         const nestedToolCallback = async (nestedToolName, nestedArgs) => {
                             return this.executeToolIsolated(nestedToolName, nestedArgs, registeredTools, onOutput, runContext, nestedExcludedTools, onToolCall, onToolEvent);
                         };
-                        const availableTools = this.buildAgentTools(filteredTools, null, // No policy override for nested
-                        nestedToolCallback);
+                        const availableTools = this.buildAgentTools(scopedTools, null, // No policy override for nested
+                        nestedToolCallback, nestedExcludedTools);
                         const nestedStepId = `step_${this.stepCounter++}`;
                         onToolEvent?.({ type: 'task_activity', taskState: 'started', taskDescription, taskId: nestedStepId });
                         try {
@@ -1622,6 +1856,9 @@ export class DMLRunner {
                                 outputVars,
                                 memory: nestedEffectiveMemory,
                                 tools: availableTools,
+                                // Withheld to break a call cycle; declared to the model so a
+                                // call can be answered with the reason rather than "not found".
+                                excludedTools: nestedExcludedTools,
                                 modelOptions: {
                                     model: this.options.model,
                                     provider: this.options.provider,
@@ -1722,12 +1959,12 @@ export class DMLRunner {
             }
         }
     }
-    async applyHostCompaction(messages, lastInputTokens, emit) {
+    async applyHostCompaction(messages, lastInputTokens, emit, contextWindow) {
         const host = this.options.compactMessages;
         if (!host) {
             return null;
         }
-        const result = await host(messages, lastInputTokens);
+        const result = await host(messages, lastInputTokens, contextWindow);
         if (result.event) {
             emit?.(result.event);
         }
@@ -1887,6 +2124,29 @@ export class DMLRunner {
     /**
      * Execute a Prolog query
      */
+    scopedModels = new Map();
+    /**
+     * Resolve a `with_model/2` spec to a model profile (cached). Returns undefined
+     * for a `default`/absent scope (use the session model).
+     */
+    async resolveScope(rawSpec) {
+        const spec = parseModelSpec(rawSpec);
+        if (spec === 'default') {
+            return undefined;
+        }
+        const key = JSON.stringify(spec);
+        const cached = this.scopedModels.get(key);
+        if (cached) {
+            return cached;
+        }
+        const resolver = this.options.modelResolver;
+        if (!resolver) {
+            throw new Error('with_model is unavailable: no model resolver is configured');
+        }
+        const resolved = await resolver.resolve(spec);
+        this.scopedModels.set(key, resolved);
+        return resolved;
+    }
     query(goal) {
         try {
             const q = this.swipl.prolog.query(goal);