deepclause-sdk 0.0.89 → 0.1.1

package/dist/runner.js

@@ -1,22 +1,21 @@
 /**
  * DML Runner - Executes DML code using SWI-Prolog WASM
  */
-import * as fs from 'fs/promises';
-import * as path from 'path';
 import { mountWorkspace } from './prolog/loader.js';
 import { runAgentLoop } from './agent.js';
 import { judgeAnswersToValues, judgeCacheKey, normalizeJudgeState, parseJudgeQuestions, validateJudgeAnswers, valuesToPrologList } from './judge/marshal.js';
-import { executeCompactor, getCompactionBindings, resolveCompactionOptions, } from './compaction.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 { recordTokenUsage } from './system/runtime/token-usage.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.
  */
-function toJsValue(value) {
+export function toJsValue(value) {
     if (value === null || value === undefined) {
         return value;
     }
@@ -60,45 +59,45 @@ function toJsValue(value) {
     }
     return value;
 }
-function detectProvider(model) {
-    const lower = model.toLowerCase();
-    if (lower.includes('gpt') || lower.includes('o1') || lower.includes('o3')) {
-        return 'openai';
-    }
-    if (lower.includes('claude')) {
-        return 'anthropic';
-    }
-    if (lower.includes('gemini') || lower.includes('palm')) {
-        return 'google';
+/**
+ * Decode the `bindings` payload of a goal-mode `solution` event.
+ *
+ * `collect_bindings/2` yields a list of `Name-Text` pairs. swipl-wasm encodes
+ * that compound as `{ '$t': 't', '-': [[Name, Text]] }`; a dict/array form is
+ * also accepted for forward compatibility.
+ */
+export function decodeSolutionBindings(raw) {
+    const normalized = toJsValue(raw);
+    if (!Array.isArray(normalized)) {
+        return [];
     }
-    return 'openrouter';
-}
-function createChildAbortController(parentSignal, timeoutMs) {
-    const controller = new AbortController();
-    const disposers = [];
-    if (parentSignal) {
-        if (parentSignal.aborted) {
-            controller.abort(parentSignal.reason);
+    const bindings = [];
+    for (const item of normalized) {
+        const decoded = toJsValue(item);
+        if (decoded && typeof decoded === 'object') {
+            const compound = decoded;
+            const args = compound['-'];
+            if (Array.isArray(args) && Array.isArray(args[0]) && args[0].length >= 2) {
+                const [name, text] = args[0];
+                bindings.push({ name: String(toJsValue(name) ?? ''), value: String(toJsValue(text) ?? '') });
+                continue;
+            }
+            if ('name' in compound || 'value' in compound) {
+                bindings.push({
+                    name: String(toJsValue(compound.name) ?? ''),
+                    value: String(toJsValue(compound.value) ?? ''),
+                });
+                continue;
+            }
         }
-        else {
-            const onAbort = () => controller.abort(parentSignal.reason);
-            parentSignal.addEventListener('abort', onAbort, { once: true });
-            disposers.push(() => parentSignal.removeEventListener('abort', onAbort));
+        if (Array.isArray(decoded) && decoded.length >= 2) {
+            bindings.push({
+                name: String(toJsValue(decoded[0]) ?? ''),
+                value: String(toJsValue(decoded[1]) ?? ''),
+            });
         }
     }
-    let timeout;
-    if (timeoutMs > 0) {
-        timeout = setTimeout(() => controller.abort(new Error(`Compactor timed out after ${timeoutMs}ms`)), timeoutMs);
-        disposers.push(() => clearTimeout(timeout));
-    }
-    return {
-        signal: controller.signal,
-        dispose: () => {
-            for (const dispose of disposers) {
-                dispose();
-            }
-        },
-    };
+    return bindings;
 }
 export function decodeAgentOutputVars(rawOutputVars) {
     const normalized = toJsValue(rawOutputVars);
@@ -142,11 +141,18 @@ function prologTypeToJsonType(prologType) {
 export class DMLRunner {
     swipl;
     options;
-    engine = null;
     sessionId = '';
     currentMemory = [];
     stepCounter = 0;
     judgeCache = new Map();
+    /**
+     * Runner-owned frame table: FrameId -> { frame, engine }.
+     * The Prolog session owns the authoritative engine handles
+     * (session_frame_engine/2); this map mirrors them for the driver.
+     */
+    frames = new Map();
+    /** FrameId of the session's default query frame (created by createEngine). */
+    defaultFrameId = null;
     constructor(swipl, options) {
         this.swipl = swipl;
         this.options = options;
@@ -191,94 +197,18 @@ export class DMLRunner {
                 yield { type: 'error', content: parseResult.error };
                 return;
             }
-            // Create cooperative engine with args
+            // Create cooperative engine with args (registers the default query frame)
             const engineResult = this.createEngine(memoryId, args, params);
             if (engineResult.error) {
                 yield { type: 'error', content: engineResult.error };
                 return;
             }
-            // Cooperative execution loop
-            while (true) {
-                // Check for abort
-                if (options.signal?.aborted) {
-                    const reason = options.signal.reason;
-                    const abortMessage = reason instanceof Error
-                        ? reason.message
-                        : typeof reason === 'string' && reason.trim().length > 0
-                            ? reason
-                            : 'Execution aborted';
-                    yield { type: 'error', content: abortMessage };
-                    break;
-                }
-                // Step the engine
-                const step = this.stepEngine();
-                if (process.env.DEBUG_STEPS) {
-                    console.log('[MAIN_LOOP] step:', step.status, step.content?.substring(0, 50));
-                }
-                switch (step.status) {
-                    case 'output':
-                        if (step.content) {
-                            if (process.env.DEBUG_STEPS) {
-                                console.log('[MAIN_LOOP] yielding output:', step.content.substring(0, 50));
-                            }
-                            yield { type: 'output', content: step.content };
-                        }
-                        break;
-                    case 'log':
-                        if (step.content) {
-                            yield { type: 'log', content: step.content };
-                        }
-                        break;
-                    case 'answer':
-                        yield { type: 'answer', content: step.content };
-                        break;
-                    case 'request_agent_loop':
-                        // Run agent loop for task() predicate
-                        yield* this.handleAgentLoop(step.payload, memoryId, options);
-                        break;
-                    case 'request_exec':
-                        // Execute external tool
-                        yield* this.handleExec(step.payload, options);
-                        break;
-                    case 'request_sample_token':
-                        yield* this.handleSampleToken(step.payload, options);
-                        break;
-                    case 'request_llm':
-                        yield* this.handleLlm(step.payload, options);
-                        break;
-                    case 'request_judgment':
-                        yield* this.handleJudgment(step.payload, options);
-                        break;
-                    case 'wait_input':
-                        // Request user input
-                        yield { type: 'input_required', prompt: step.prompt };
-                        const input = await options.onInputRequired(step.prompt ?? '');
-                        this.provideInput(input);
-                        break;
-                    case 'finished':
-                        // Include trace data if trace mode was enabled
-                        if (this.options.trace && step.payload) {
-                            const traceData = toJsValue(step.payload.trace);
-                            yield { type: 'finished', trace: Array.isArray(traceData) ? traceData : undefined };
-                        }
-                        else {
-                            yield { type: 'finished' };
-                        }
-                        return;
-                    case 'error':
-                        if (this.options.trace && step.payload) {
-                            const traceData = toJsValue(step.payload.trace);
-                            yield { type: 'error', content: step.content, trace: Array.isArray(traceData) ? traceData : undefined };
-                        }
-                        else {
-                            yield { type: 'error', content: step.content };
-                        }
-                        return;
-                    default:
-                        yield { type: 'error', content: `Unknown step status: ${step.status}` };
-                        return;
-                }
+            const frame = this.defaultFrameId ? this.frames.get(this.defaultFrameId)?.frame : undefined;
+            if (!frame) {
+                yield { type: 'error', content: 'Failed to register default query frame' };
+                return;
             }
+            yield* this.stepLoop(frame, options);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -289,6 +219,185 @@ export class DMLRunner {
             this.cleanup();
         }
     }
+    /**
+     * Drive a single frame until it finishes or errors, yielding its events.
+     *
+     * This is the extracted, reentrant form of the original `while(true)` loop.
+     * `run()` calls it for the default query frame; `runFrame` calls it for
+     * nested frames. Because frames are read from the Prolog frame table via
+     * `step_frame/4`, stepping a different frame never disturbs a suspended
+     * parent's engine.
+     */
+    async *stepLoop(frame, options) {
+        for await (const event of this.stepLoopInner(frame, options)) {
+            // Preserve frame metadata already attached by a nested frame; otherwise
+            // stamp this frame so the renderer can attribute output correctly.
+            yield {
+                ...event,
+                frameId: event.frameId ?? frame.id,
+                depth: event.depth ?? frame.depth,
+                frameKind: event.frameKind ?? frame.kind,
+            };
+        }
+    }
+    async *stepLoopInner(frame, options) {
+        // Cooperative execution loop
+        while (true) {
+            // Check for abort
+            if (options.signal?.aborted) {
+                const reason = options.signal.reason;
+                const abortMessage = reason instanceof Error
+                    ? reason.message
+                    : typeof reason === 'string' && reason.trim().length > 0
+                        ? reason
+                        : 'Execution aborted';
+                yield { type: 'error', content: abortMessage };
+                break;
+            }
+            // Step the frame
+            const step = this.stepFrame(frame.id);
+            if (process.env.DEBUG_STEPS) {
+                console.log('[MAIN_LOOP] step:', step.status, step.content?.substring(0, 50));
+            }
+            switch (step.status) {
+                case 'output':
+                    if (step.content) {
+                        if (process.env.DEBUG_STEPS) {
+                            console.log('[MAIN_LOOP] yielding output:', step.content.substring(0, 50));
+                        }
+                        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 };
+                    }
+                    break;
+                case 'answer':
+                    yield { type: 'answer', content: step.content };
+                    break;
+                case 'solution': {
+                    const payload = (step.payload ?? {});
+                    yield {
+                        type: 'solution',
+                        solution: {
+                            bindings: decodeSolutionBindings(payload.bindings),
+                            deterministic: String(toJsValue(payload.deterministic) ?? 'false') === 'true',
+                        },
+                    };
+                    break;
+                }
+                case 'request_agent_loop':
+                    // Run agent loop for task() predicate. The frame kind decides the
+                    // tool set: `meta` frames get the host meta tools and hide the
+                    // harness's own DML tools (proposal §9.2). Budget exhaustion (and any
+                    // other agent-loop error) is surfaced as an error event.
+                    try {
+                        yield* this.handleAgentLoop(step.payload, '', options, frame);
+                    }
+                    catch (error) {
+                        yield { type: 'error', content: error instanceof Error ? error.message : String(error) };
+                        return;
+                    }
+                    break;
+                case 'meta_result': {
+                    const payload = (step.payload ?? {});
+                    yield {
+                        type: 'meta_result',
+                        metaResult: {
+                            code: String(toJsValue(payload.code) ?? ''),
+                            answer: String(toJsValue(payload.answer) ?? ''),
+                        },
+                    };
+                    break;
+                }
+                case 'request_exec':
+                    // Execute external tool
+                    yield* this.handleExec(step.payload, options);
+                    break;
+                case 'request_sample_token':
+                    yield* this.handleSampleToken(step.payload, options);
+                    break;
+                case 'request_llm':
+                    yield* this.handleLlm(step.payload, options);
+                    break;
+                case 'request_judgment':
+                    yield* this.handleJudgment(step.payload, options);
+                    break;
+                case 'wait_input': {
+                    // Request user input
+                    yield { type: 'input_required', prompt: step.prompt };
+                    const input = await options.onInputRequired(step.prompt ?? '');
+                    if (input === undefined || input === null) {
+                        this.cancelInput();
+                    }
+                    else {
+                        this.provideInput(input);
+                    }
+                    break;
+                }
+                case 'finished':
+                    // Include trace data if trace mode was enabled
+                    if (this.options.trace && step.payload) {
+                        const traceData = toJsValue(step.payload.trace);
+                        yield { type: 'finished', trace: Array.isArray(traceData) ? traceData : undefined };
+                    }
+                    else {
+                        yield { type: 'finished' };
+                    }
+                    return;
+                case 'error':
+                    if (this.options.trace && step.payload) {
+                        const traceData = toJsValue(step.payload.trace);
+                        yield { type: 'error', content: step.content, trace: Array.isArray(traceData) ? traceData : undefined };
+                    }
+                    else {
+                        yield { type: 'error', content: step.content };
+                    }
+                    return;
+                default:
+                    yield { type: 'error', content: `Unknown step status: ${step.status}` };
+                    return;
+            }
+        }
+    }
+    /**
+     * Run a specific frame to completion, yielding its events.
+     *
+     * This is the reentrant entry point used by nested execution (the REPL's
+     * `execute` meta tool): the caller builds a child frame with
+     * `createNestedFrame`, runs it with this method while the parent frame is
+     * suspended, then posts the result back to the parent.
+     */
+    async *runFrame(frameId, options) {
+        const frame = this.frames.get(frameId)?.frame;
+        if (!frame) {
+            yield { type: 'error', content: `Unknown frame: ${frameId}` };
+            return;
+        }
+        yield* this.stepLoop(frame, options);
+    }
     /**
      * Parse DML code into Prolog clauses
      */
@@ -381,10 +490,15 @@ export class DMLRunner {
     createEngine(memoryId, args, params) {
         try {
             const initialMemory = this.serializeMemoryMessages(this.currentMemory);
-            const result = this.query(`deepclause_mi:create_engine('${this.sessionId}', '${memoryId}', ${args}, ${params}, [${initialMemory}], Engine)`);
-            if (result && result.Engine) {
-                this.engine = result.Engine;
-                return {};
+            // create_engine/6 registers the default `query` frame; default_frame/2
+            // returns its FrameId so the runner can address it explicitly.
+            const result = this.query(`deepclause_mi:create_engine('${this.sessionId}', '${memoryId}', ${args}, ${params}, [${initialMemory}], Engine), deepclause_mi:default_frame('${this.sessionId}', FrameId)`);
+            if (result && result.Engine && result.FrameId) {
+                const frameId = String(toJsValue(result.FrameId));
+                const frame = { id: frameId, kind: 'query', depth: 0 };
+                this.frames.set(frameId, { frame, engine: result.Engine });
+                this.defaultFrameId = frameId;
+                return { frameId };
             }
             return { error: 'Failed to create engine' };
         }
@@ -394,11 +508,93 @@ export class DMLRunner {
         }
     }
     /**
-     * Step the cooperative engine
+     * Create a nested frame that runs a Prolog goal in this session.
+     *
+     * `goalTerm` is inserted verbatim into create_frame/6, so callers MUST pass
+     * a term built with the runner's `toPrologTerm` escaping or parsed from DML
+     * via `read_term` — never raw user text (foot gun #18). `stateTerm` is an
+     * optional Prolog `state{...}` term; the default is an empty state with no
+     * gas limit.
+     *
+     * Returns the registered frame, or null on failure. The caller is
+     * responsible for running (`runFrame`) and ending (`endFrame`) it.
      */
-    stepEngine() {
+    createNestedFrame(params) {
+        const depth = params.depth ?? 1;
+        const stateTerm = params.stateTerm
+            ?? 'state{memory: [], params: params{}, context_stack: [], depth: 0}';
+        const result = this.query(`deepclause_mi:create_frame('${this.sessionId}', ${params.kind}, ${depth}, ${params.goalTerm}, ${stateTerm}, FrameId)`);
+        if (!result || !result.FrameId) {
+            return null;
+        }
+        const id = String(toJsValue(result.FrameId));
+        const frame = { id, kind: params.kind, depth };
+        this.frames.set(id, { frame, engine: null });
+        return frame;
+    }
+    /** End a frame, destroying its engine in the Prolog session. */
+    endFrame(frameId) {
+        this.query(`deepclause_mi:end_frame('${frameId}')`);
+        this.frames.delete(frameId);
+        if (this.defaultFrameId === frameId) {
+            this.defaultFrameId = null;
+        }
+    }
+    /**
+     * Bind this runner to an existing session id. Used by the REPL's
+     * DMLSession, whose session outlives a single `run()`.
+     */
+    bindSession(sessionId) {
+        this.sessionId = sessionId;
+    }
+    /**
+     * Adopt the session's default frame (for example one created by the REPL's
+     * `query_start/5`) into the runner's frame table so `runFrame` can drive it.
+     */
+    registerDefaultFrame(kind, depth = 0) {
+        const result = this.query(`deepclause_mi:default_frame('${this.sessionId}', FrameId)`);
+        if (!result || !result.FrameId) {
+            return null;
+        }
+        const id = String(toJsValue(result.FrameId));
+        const frame = { id, kind, depth };
+        this.frames.set(id, { frame, engine: null });
+        this.defaultFrameId = id;
+        return frame;
+    }
+    /**
+     * Adopt a Prolog-created frame into the runner's frame table. Used by the
+     * REPL for `execute` child frames (`repl_execute_frame/4`).
+     */
+    registerFrame(frameId, kind, depth = 0) {
+        const frame = { id: frameId, kind, depth };
+        this.frames.set(frameId, { frame, engine: null });
+        return frame;
+    }
+    /**
+     * Drop all runner-side frame bookkeeping without touching Prolog. Used after
+     * the REPL clears a session (the Prolog side already ended every frame).
+     */
+    clearFrames() {
+        this.frames.clear();
+        this.defaultFrameId = null;
+    }
+    /**
+     * Step a specific frame exactly once and return its raw step result.
+     * Used by the reentrant driver and nested-execution tests.
+     */
+    stepFrameOnce(frameId) {
+        if (!this.frames.has(frameId)) {
+            return null;
+        }
+        return this.stepFrame(frameId);
+    }
+    /**
+     * Step the cooperative engine for a frame
+     */
+    stepFrame(frameId) {
         try {
-            const result = this.query(`deepclause_mi:step_engine('${this.sessionId}', Status, Content, Payload)`);
+            const result = this.query(`deepclause_mi:step_frame('${frameId}', Status, Content, Payload)`);
             // Convert swipl-wasm values to plain JS
             const status = toJsValue(result?.Status);
             const content = toJsValue(result?.Content);
@@ -419,13 +615,15 @@ export class DMLRunner {
      * Handle agent loop request (task() predicate)
      */
     async *handleAgentLoop(payload, _memoryId, // No longer used - memory comes from payload
-    options) {
+    options, _frame) {
         const rawPayload = payload;
         const taskDescription = String(toJsValue(rawPayload.taskDescription) ?? '');
         const stepId = `step_${this.stepCounter++}`;
         yield { type: 'task_activity', taskState: 'started', taskDescription, taskId: stepId };
         let stepSucceeded = null;
         try {
+            // The per-model-call budget is enforced inside the agent loop (before each
+            // model call) so it also covers multi-iteration turns.
             // Ensure outputVars is an array of either strings or TypedVar objects
             const outputVars = decodeAgentOutputVars(rawPayload.outputVars);
             // Parse userTools - now contains schema info as array of tool_info dicts
@@ -455,14 +653,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
@@ -503,6 +735,9 @@ export class DMLRunner {
                         try {
                             emitToolEvent({ type: 'input_required', prompt });
                             const response = await options.onInputRequired(prompt);
+                            if (response === undefined || response === null) {
+                                return { cancelled: true };
+                            }
                             return { user_response: response };
                         }
                         catch (err) {
@@ -515,14 +750,15 @@ export class DMLRunner {
             const emitToolCall = (toolName, args) => {
                 emitToolEvent({ type: 'tool_call', toolName, toolArgs: args });
             };
-            // Build available tools for agent - SIMPLIFIED: tools run in isolated engines
-            // The callback runs DML tools in isolated engines with no shared state.
+            // 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) => {
                 return this.executeToolIsolated(toolName, args, augmentedTools, onToolOutput, {
                     workspacePath: options.workspacePath,
                     signal: options.signal,
-                    compaction: options.compaction,
                     toolPolicy: options.toolPolicy,
+                    onModelCall: options.onModelCall,
                 }, [], emitToolCall, emitToolEvent);
             });
             // Run agent loop with streaming support
@@ -532,13 +768,15 @@ export class DMLRunner {
                 memory: effectiveMemory,
                 tools: availableTools,
                 workspacePath: options.workspacePath,
+                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,
@@ -550,6 +788,13 @@ export class DMLRunner {
                         streamResolve = null;
                     }
                 },
+                onReasoning: (chunk, done) => {
+                    streamQueue.push({ type: 'reasoning', content: chunk, done });
+                    if (streamResolve) {
+                        streamResolve();
+                        streamResolve = null;
+                    }
+                },
                 onToolCall: (toolName, args) => {
                     streamQueue.push({ type: 'tool_call', toolName, toolArgs: args });
                     if (streamResolve) {
@@ -564,22 +809,27 @@ export class DMLRunner {
                         streamResolve = null;
                     }
                 },
-                onBeforeModelCall: async (messages, lastInputTokens) => this.applyCompactionBindings({
-                    messages,
-                    lastInputTokens,
-                    scope: 'loop',
-                    trigger: 'before_model_call',
-                    options,
-                    executionContext: {
-                        workspacePath: options.workspacePath,
-                        signal: options.signal,
-                        compaction: options.compaction,
-                    },
-                    registeredTools: options.tools,
-                    toolPolicy: options.toolPolicy,
-                    emitEvent: emitRunnerEvent,
-                }),
+                onModelCallPhase: (phase) => {
+                    streamQueue.push({ type: 'model_call', modelCallState: phase, modelId: this.options.model });
+                    if (streamResolve) {
+                        streamResolve();
+                        streamResolve = null;
+                    }
+                },
+                selfReportingTools,
+                onToolResult: (toolName, toolArgs, toolResult) => {
+                    streamQueue.push(buildToolCompletionEvent(toolName, toolArgs, toolResult));
+                    if (streamResolve) {
+                        streamResolve();
+                        streamResolve = null;
+                    }
+                },
+                onBeforeModelCall: async (messages, lastInputTokens) => {
+                    const hostCompacted = await this.applyHostCompaction(messages, lastInputTokens, emitRunnerEvent, scopedModel?.contextWindow);
+                    return hostCompacted ?? messages;
+                },
                 onAskUser: options.onInputRequired,
+                onModelCall: options.onModelCall,
                 signal: options.signal,
                 llmBackend: this.options.llmBackend,
             });
@@ -678,15 +928,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,
@@ -717,18 +969,21 @@ 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,
+                resolveMedia: (refs) => this.readMediaRefs(options.workspacePath, refs),
             });
             succeeded = true;
             this.postLlmResult({ success: true, text });
@@ -859,15 +1114,18 @@ export class DMLRunner {
      */
     async *handleExec(payload, options) {
         const { toolName, args } = payload;
-        // Check tool policy
+        // Check tool policy (ask_user is the human channel and is exempt).
         const policyCheck = checkToolPolicy(toolName, options.toolPolicy);
         if (!policyCheck.allowed) {
             yield { type: 'log', content: `Tool '${toolName}' blocked by policy: ${policyCheck.reason}` };
             this.postExecResult({ success: false, error: policyCheck.reason });
             return;
         }
-        // Get tool definition
-        const tool = options.tools.get(toolName);
+        // Get tool definition. `ask_user` is SDK-internal so exec(ask_user(...))
+        // works in DML even when no capability tools are registered.
+        const tool = toolName === 'ask_user'
+            ? this.internalAskUserTool(options)
+            : options.tools.get(toolName);
         if (!tool) {
             yield { type: 'log', content: `Tool '${toolName}' not found` };
             this.postExecResult({ success: false, error: `Tool not found: ${toolName}` });
@@ -879,7 +1137,7 @@ export class DMLRunner {
             argsObj = this.argsToObject(args, tool);
             // Emit tool_call event before execution
             yield buildToolStartEvent(toolName, argsObj);
-            const result = await tool.execute(argsObj);
+            const result = await tool.execute(argsObj, { signal: options.signal });
             yield buildToolCompletionEvent(toolName, argsObj, result);
             // Post result back to Prolog
             this.postExecResult({ success: true, result });
@@ -1172,7 +1430,7 @@ export class DMLRunner {
                             try {
                                 argsObj = this.argsToObject(execArgs, tool);
                                 onToolEvent?.(buildToolStartEvent(execToolName, argsObj));
-                                const execResult = await tool.execute(argsObj);
+                                const execResult = await tool.execute(argsObj, { signal: runContext.signal });
                                 onToolEvent?.(buildToolCompletionEvent(execToolName, argsObj, execResult));
                                 const postGoal = `deepclause_mi:post_exec_result('${this.sessionId}', success, ${this.toPrologTerm(execResult)})`;
                                 this.query(postGoal);
@@ -1243,6 +1501,7 @@ export class DMLRunner {
                                 },
                                 signal: runContext.signal,
                                 llmBackend: this.options.llmBackend,
+                                resolveMedia: (refs) => this.readMediaRefs(runContext.workspacePath, refs),
                             });
                             this.postLlmResult({ success: true, text });
                             if (usage) {
@@ -1436,6 +1695,7 @@ export class DMLRunner {
                                 streaming: this.options.streaming,
                                 debug: this.options.debug,
                                 llmBackend: this.options.llmBackend,
+                                resolveMedia: (refs) => this.readMediaRefs(runContext.workspacePath, refs),
                                 onOutput: (text) => {
                                     outputs.push(text);
                                     onOutput(text);
@@ -1443,26 +1703,26 @@ export class DMLRunner {
                                 onStream: (chunk, done) => {
                                     onToolEvent?.({ type: 'stream', content: chunk, done });
                                 },
+                                onReasoning: (chunk, done) => {
+                                    onToolEvent?.({ type: 'reasoning', content: chunk, done });
+                                },
                                 onUsage: (usage) => {
                                     onToolEvent?.({ type: 'usage', usage });
                                 },
+                                onModelCallPhase: (phase) => {
+                                    onToolEvent?.({ type: 'model_call', modelCallState: phase, modelId: this.options.model });
+                                },
                                 onToolCall: onToolCall ?? (() => { }), // Forward tool call events to parent
-                                onBeforeModelCall: async (messages, lastInputTokens) => this.applyCompactionBindings({
-                                    messages,
-                                    lastInputTokens,
-                                    scope: 'loop',
-                                    trigger: 'before_model_call',
-                                    options: { compaction: runContext.compaction },
-                                    executionContext: runContext,
-                                    registeredTools,
-                                    toolPolicy: runContext.toolPolicy ?? null,
-                                    emitEvent: onToolEvent,
-                                }),
+                                onBeforeModelCall: async (messages, lastInputTokens) => {
+                                    const hostCompacted = await this.applyHostCompaction(messages, lastInputTokens, onToolEvent);
+                                    return hostCompacted ?? messages;
+                                },
                                 onAskUser: async () => {
                                     // Nested agent loops don't support ask_user directly
                                     // If needed, the tool should use exec(ask_user, ...) instead
                                     return '';
                                 },
+                                onModelCall: runContext.onModelCall,
                                 signal: runContext.signal,
                             });
                             if (process.env.DEBUG_RUNNER) {
@@ -1524,116 +1784,17 @@ export class DMLRunner {
             }
         }
     }
-    async applyCompactionBindings(params) {
-        const resolved = resolveCompactionOptions(this.options.compaction, params.options.compaction);
-        const bindings = getCompactionBindings(resolved, params.scope, params.trigger);
-        if (bindings.length === 0) {
-            return params.messages;
-        }
-        let messages = params.messages;
-        for (const binding of bindings) {
-            const result = await executeCompactor({
-                binding,
-                messages,
-                knownInputTokens: params.lastInputTokens,
-                maxContextTokens: this.options.contextWindow,
-                emitEvent: params.emitEvent,
-                execute: (request) => this.runBoundCompactor({
-                    request,
-                    executionContext: params.executionContext,
-                    registeredTools: params.registeredTools,
-                    toolPolicy: params.toolPolicy,
-                }),
-            });
-            params.emitEvent?.(result.event);
-            if (result.usageByModel) {
-                for (const totals of Object.values(result.usageByModel)) {
-                    params.emitEvent?.({ type: 'usage', usage: {
-                            inputTokens: totals.inputTokens,
-                            outputTokens: totals.outputTokens,
-                            totalTokens: totals.totalTokens,
-                            cacheReadTokens: totals.cacheReadTokens || undefined,
-                            cacheWriteTokens: totals.cacheWriteTokens || undefined,
-                            reasoningTokens: totals.reasoningTokens || undefined,
-                        } });
-                }
-            }
-            messages = result.messages;
-        }
-        return messages;
-    }
-    async runBoundCompactor(params) {
-        const { binding, params: compactorParams } = params.request;
-        const code = await this.resolveCompactorSource(binding.compactor.source, binding.compactor.sourceType, params.executionContext.workspacePath);
-        const model = binding.compactor.model ?? this.options.model;
-        const provider = binding.compactor.provider
-            ?? (binding.compactor.model ? detectProvider(model) : this.options.provider);
-        const compactorRunner = new DMLRunner(this.swipl, {
-            ...this.options,
-            model,
-            provider,
-            streaming: false,
-            compaction: { enabled: false },
-        });
-        const { signal, dispose } = createChildAbortController(params.executionContext.signal, binding.compactor.timeoutMs);
-        try {
-            const tools = binding.compactor.inheritTools ? params.registeredTools : new Map();
-            let answer = '';
-            let errorContent = '';
-            const usageByModel = {};
-            for await (const event of compactorRunner.run(code, {
-                workspacePath: params.executionContext.workspacePath,
-                gasLimit: binding.compactor.gasLimit,
-                params: compactorParams,
-                initialMessages: params.request.messages,
-                tools,
-                toolPolicy: binding.compactor.toolPolicy ?? (binding.compactor.inheritTools ? params.toolPolicy : null) ?? null,
-                onInputRequired: async (prompt) => {
-                    throw new Error(`Compactor requested unexpected input: ${prompt}`);
-                },
-                signal,
-                compaction: { enabled: false },
-            })) {
-                if (event.type === 'answer' && event.content) {
-                    answer = event.content;
-                }
-                else if (event.type === 'error' && event.content) {
-                    errorContent = event.content;
-                }
-                else if (event.type === 'usage' && event.usage) {
-                    recordTokenUsage(usageByModel, this.options.model, event.usage);
-                }
-            }
-            return {
-                answer,
-                error: errorContent || undefined,
-                usageByModel: Object.keys(usageByModel).length > 0 ? usageByModel : undefined,
-            };
-        }
-        finally {
-            dispose();
-            await compactorRunner.dispose();
-        }
-    }
-    async resolveCompactorSource(source, sourceType, workspacePath) {
-        if (sourceType === 'inline') {
-            return source;
-        }
-        const basePath = workspacePath ?? process.cwd();
-        const candidatePath = path.isAbsolute(source) ? source : path.resolve(basePath, source);
-        try {
-            return await fs.readFile(candidatePath, 'utf8');
+    async applyHostCompaction(messages, lastInputTokens, emit, contextWindow) {
+        const host = this.options.compactMessages;
+        if (!host) {
+            return null;
         }
-        catch (error) {
-            if (sourceType === 'file') {
-                throw error;
-            }
-            return source;
+        const result = await host(messages, lastInputTokens, contextWindow);
+        if (result.event) {
+            emit?.(result.event);
         }
+        return result.messages;
     }
-    /**
-     * Extract memory from payload (now passed via state threading)
-     */
     extractMessagesFromValue(rawMessages) {
         const normalized = toJsValue(rawMessages);
         if (!Array.isArray(normalized)) {
@@ -1643,19 +1804,46 @@ export class DMLRunner {
             const msg = toJsValue(messageValue);
             const role = String(toJsValue(msg.role) ?? 'user');
             const content = String(toJsValue(msg.content) ?? '');
+            const media = this.extractMediaRefs(msg.media);
             if (role !== 'system' && role !== 'user' && role !== 'assistant') {
-                return { role: 'user', content };
+                return { role: 'user', content, media: media.length ? media : undefined };
             }
-            return { role: role, content };
+            return { role: role, content, media: media.length ? media : undefined };
         });
     }
+    /** Decode `media{path:..., mime:...}` dicts into reference-only refs. */
+    extractMediaRefs(raw) {
+        const value = toJsValue(raw);
+        if (!Array.isArray(value))
+            return [];
+        const refs = [];
+        for (const entry of value) {
+            const obj = toJsValue(entry);
+            const mediaPath = String(obj?.path ?? '');
+            const mimeType = String(obj?.mime ?? obj?.mimeType ?? '');
+            if (mediaPath && mimeType)
+                refs.push({ path: mediaPath, mimeType });
+        }
+        return refs;
+    }
+    /** Resolve a message's reference-only media to base64 bytes (workspace files). */
+    async readMediaRefs(workspacePath, refs) {
+        return resolveMediaRefs(workspacePath ?? process.cwd(), refs);
+    }
     extractMemoryFromPayload(rawPayload) {
         const rawMemory = toJsValue(rawPayload.memory);
         return this.extractMessagesFromValue(rawMemory);
     }
     serializeMemoryMessages(messages) {
         return messages
-            .map((message) => `message{role: ${message.role}, content: ${this.toPrologTerm(message.content)}}`)
+            .map((message) => {
+            const media = message.media && message.media.length > 0
+                ? `, media: [${message.media
+                    .map((ref) => `media{path: ${this.toPrologTerm(ref.path)}, mime: ${this.toPrologTerm(ref.mimeType)}}`)
+                    .join(', ')}]`
+                : '';
+            return `message{role: ${message.role}, content: ${this.toPrologTerm(message.content)}${media}}`;
+        })
             .join(', ');
     }
     /**
@@ -1723,6 +1911,30 @@ export class DMLRunner {
         const fullMemoryStr = this.serializeMemoryMessages(fullMemory ?? []);
         this.query(`deepclause_mi:post_tool_agent_result('${this.sessionId}', '${toolEngineId}', ${result.success}, vars{${varsStr}}, [${messagesStr}], [${fullMemoryStr}])`);
     }
+    /** SDK-internal ask_user tool used by exec(ask_user(...)) in DML. */
+    internalAskUserTool(options) {
+        return {
+            description: 'Ask the user for input or clarification',
+            parameters: {
+                type: 'object',
+                properties: {
+                    prompt: { type: 'string', description: 'The question or prompt to show the user' },
+                },
+                required: ['prompt'],
+            },
+            execute: async (args) => {
+                const prompt = String(args.prompt ?? args.arg1 ?? '');
+                if (!prompt) {
+                    return { error: 'No prompt provided to ask_user' };
+                }
+                const response = await options.onInputRequired(prompt);
+                if (response === undefined || response === null) {
+                    return { cancelled: true };
+                }
+                return { user_response: response };
+            },
+        };
+    }
     /**
      * Provide user input to waiting Prolog
      */
@@ -1730,9 +1942,36 @@ export class DMLRunner {
         const escaped = input.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
         this.query(`deepclause_mi:provide_input('${this.sessionId}', "${escaped}")`);
     }
+    /** Signal a waiting input/2 that no human is available. */
+    cancelInput() {
+        this.query(`deepclause_mi:provide_input_cancelled('${this.sessionId}')`);
+    }
     /**
      * 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);
@@ -1748,14 +1987,17 @@ export class DMLRunner {
      * Cleanup resources
      */
     cleanup() {
-        if (this.engine) {
+        if (this.frames.size > 0) {
             try {
+                // destroy_engine/1 ends every frame registered for the session and
+                // retracts the session's dynamic state.
                 this.query(`deepclause_mi:destroy_engine('${this.sessionId}')`);
             }
             catch {
                 // Ignore cleanup errors
             }
-            this.engine = null;
+            this.frames.clear();
+            this.defaultFrameId = null;
         }
     }
     /**