deepclause-sdk 0.1.1 → 0.1.2

package/dist/runner.js

@@ -3,6 +3,8 @@
  */
 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';
@@ -111,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
  */
@@ -145,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
@@ -203,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' };
@@ -256,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));
             }
@@ -753,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,
@@ -768,6 +865,7 @@ export class DMLRunner {
                 memory: effectiveMemory,
                 tools: availableTools,
                 workspacePath: options.workspacePath,
+                environment: this.options.environment,
                 resolveMedia: (refs) => this.readMediaRefs(options.workspacePath, refs),
                 modelOptions: {
                     model: scopedModel?.id ?? this.options.model,
@@ -1127,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;
         }
@@ -1135,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 });
@@ -1309,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 = [];
@@ -1339,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.
@@ -1366,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);
@@ -1422,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);
                         }
@@ -1429,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));
@@ -1623,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);
@@ -1663,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));
@@ -1673,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 {
@@ -1684,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,