la-machina-engine 0.7.3 → 0.7.4

package/dist/index.d.cts

@@ -1280,6 +1280,18 @@ interface StreamRequest {
     readonly tools?: readonly ModelToolDefinition[] | undefined;
     readonly maxTokens?: number | undefined;
     readonly temperature?: number | undefined;
+    /**
+     * Tool-call policy (Plan 025). Default: `'auto'` (model decides).
+     *   - `'auto'`     — model picks; pass-through behavior
+     *   - `'required'` — model MUST call a tool on its next response;
+     *                    translated per-provider (Anthropic:
+     *                    `tool_choice: { type: 'any' }`; OpenAI / AI SDK:
+     *                    `toolChoice: 'required'`).
+     *
+     * Note: `'none'` is handled engine-side by stripping `tools` before
+     * the request reaches the adapter, so adapters never see it.
+     */
+    readonly toolChoice?: 'auto' | 'required' | undefined;
 }
 
 interface ModelAdapter {
@@ -2000,7 +2012,30 @@ interface RunOptions {
     readonly runId?: string;
     readonly nodeId: string;
     readonly task: string;
+    /**
+     * Per-run tool allowlist (Plan 025). When undefined, the run sees
+     * every tool registered at engine init (subject to
+     * `config.tools.enabled / disabled`). When provided, the visible
+     * tool set is further restricted to this exact list — names that
+     * aren't registered are silently ignored. Pass `[]` to disable
+     * all tools for this run; equivalent to `toolChoice: 'none'`.
+     */
     readonly tools?: readonly string[] | undefined;
+    /**
+     * Tool-call policy for this run (Plan 025). Default: `'auto'`.
+     *   - `'auto'`     — model decides whether to call tools
+     *   - `'none'`     — model is told it has no tools; tools list is
+     *                    stripped before the model adapter sees it
+     *   - `'required'` — model MUST call a tool on its next response;
+     *                    plumbed to the provider as the "force tool use"
+     *                    flag (Anthropic: `tool_choice: { type: 'any' }`,
+     *                    OpenAI / AI SDK: `toolChoice: 'required'`)
+     *
+     * Precedence: `'none'` wins over any `tools: [...]` allowlist.
+     * `'required'` paired with an empty effective tool set throws
+     * `ERR_TOOL_CHOICE_CONFLICT` at run start.
+     */
+    readonly toolChoice?: 'auto' | 'none' | 'required' | undefined;
     readonly context?: Readonly<Record<string, unknown>> | undefined;
     /** Override maxTurns for this run only. Used by the orchestrator for per-phase budgets. */
     readonly maxTurns?: number | undefined;

package/dist/index.d.ts

@@ -1280,6 +1280,18 @@ interface StreamRequest {
     readonly tools?: readonly ModelToolDefinition[] | undefined;
     readonly maxTokens?: number | undefined;
     readonly temperature?: number | undefined;
+    /**
+     * Tool-call policy (Plan 025). Default: `'auto'` (model decides).
+     *   - `'auto'`     — model picks; pass-through behavior
+     *   - `'required'` — model MUST call a tool on its next response;
+     *                    translated per-provider (Anthropic:
+     *                    `tool_choice: { type: 'any' }`; OpenAI / AI SDK:
+     *                    `toolChoice: 'required'`).
+     *
+     * Note: `'none'` is handled engine-side by stripping `tools` before
+     * the request reaches the adapter, so adapters never see it.
+     */
+    readonly toolChoice?: 'auto' | 'required' | undefined;
 }
 
 interface ModelAdapter {
@@ -2000,7 +2012,30 @@ interface RunOptions {
     readonly runId?: string;
     readonly nodeId: string;
     readonly task: string;
+    /**
+     * Per-run tool allowlist (Plan 025). When undefined, the run sees
+     * every tool registered at engine init (subject to
+     * `config.tools.enabled / disabled`). When provided, the visible
+     * tool set is further restricted to this exact list — names that
+     * aren't registered are silently ignored. Pass `[]` to disable
+     * all tools for this run; equivalent to `toolChoice: 'none'`.
+     */
     readonly tools?: readonly string[] | undefined;
+    /**
+     * Tool-call policy for this run (Plan 025). Default: `'auto'`.
+     *   - `'auto'`     — model decides whether to call tools
+     *   - `'none'`     — model is told it has no tools; tools list is
+     *                    stripped before the model adapter sees it
+     *   - `'required'` — model MUST call a tool on its next response;
+     *                    plumbed to the provider as the "force tool use"
+     *                    flag (Anthropic: `tool_choice: { type: 'any' }`,
+     *                    OpenAI / AI SDK: `toolChoice: 'required'`)
+     *
+     * Precedence: `'none'` wins over any `tools: [...]` allowlist.
+     * `'required'` paired with an empty effective tool set throws
+     * `ERR_TOOL_CHOICE_CONFLICT` at run start.
+     */
+    readonly toolChoice?: 'auto' | 'none' | 'required' | undefined;
     readonly context?: Readonly<Record<string, unknown>> | undefined;
     /** Override maxTurns for this run only. Used by the orchestrator for per-phase budgets. */
     readonly maxTurns?: number | undefined;

package/dist/index.js

@@ -1716,7 +1716,11 @@ var AnthropicClient = class {
       messages: request.messages,
       stream: true,
       ...request.system !== void 0 ? { system: request.system } : {},
-      ...request.tools !== void 0 ? { tools: request.tools } : {}
+      ...request.tools !== void 0 ? { tools: request.tools } : {},
+      // Plan 025 — `'required'` maps to Anthropic's `tool_choice: { type: 'any' }`,
+      // which forces the model to call SOME tool but doesn't pin which.
+      // `'auto'` is the SDK default — omit to let it through unchanged.
+      ...request.toolChoice === "required" ? { tool_choice: { type: "any" } } : {}
     };
     const requestOptions = {};
     if (betas.length > 0) {
@@ -1898,6 +1902,9 @@ var AISdkAdapter = class {
       tools,
       ...request.maxTokens !== void 0 ? { maxOutputTokens: request.maxTokens } : {},
       ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
+      // Plan 025 — pass through `'required'` so the AI SDK forwards it
+      // to the provider as that provider's "force tool call" flag.
+      ...request.toolChoice === "required" ? { toolChoice: "required" } : {},
       maxRetries: this.options.maxRetries ?? 2
     });
     for await (const event of result.fullStream) {
@@ -2517,6 +2524,17 @@ function ensureToolResultPairing(messages) {
   return messages;
 }
 
+// src/engine/lastTurnGuard.ts
+init_esm_shims();
+var LAST_TURN_INSTRUCTION_JSON = "SYSTEM NOTE: This is your final allowed turn. Emit ONLY the JSON object that satisfies the output schema in the system prompt. Do not call any more tools. Do not write any explanation, narration, or markdown \u2014 only the raw JSON.";
+var LAST_TURN_INSTRUCTION_TEXT = "SYSTEM NOTE: This is your final allowed turn. Stop calling tools and deliver your final answer now. The next turn will not happen.";
+function lastTurnInstruction(outputFormat) {
+  return outputFormat === "json" ? LAST_TURN_INSTRUCTION_JSON : LAST_TURN_INSTRUCTION_TEXT;
+}
+function shouldInjectLastTurnInstruction(opts) {
+  return opts.turnCount + 1 === opts.maxTurns;
+}
+
 // src/compact/compactor.ts
 init_esm_shims();
 
@@ -3008,15 +3026,29 @@ async function agentLoop(options) {
     const toolCalls = [];
     let stopReason = null;
     let turnUsage = { input: 0, output: 0 };
+    let messagesForApi = messages;
+    if (shouldInjectLastTurnInstruction({
+      turnCount: ctx.getTurnCount(),
+      maxTurns: ctx.getMaxTurns()
+    })) {
+      messagesForApi = [
+        ...messages,
+        {
+          role: "user",
+          content: [{ type: "text", text: lastTurnInstruction(options.outputFormat) }]
+        }
+      ];
+    }
     const normalizedMessages = normalizeMessages(
-      messages
+      messagesForApi
     );
     try {
       for await (const event of client.streamMessage({
         messages: normalizedMessages,
         system,
         tools: anthropicTools,
-        ...escalatedMaxTokens !== void 0 ? { maxTokens: escalatedMaxTokens } : {}
+        ...escalatedMaxTokens !== void 0 ? { maxTokens: escalatedMaxTokens } : {},
+        ...options.toolChoice !== void 0 ? { toolChoice: options.toolChoice } : {}
       })) {
         const handled = consumeEvent(event);
         if (handled.text !== void 0) textBlocks.push(handled.text);
@@ -3567,6 +3599,9 @@ var RunContext = class {
   getTurnCount() {
     return this.turnCount;
   }
+  getMaxTurns() {
+    return this.maxTurns;
+  }
   getTokensUsed() {
     return this.tokensUsed;
   }
@@ -9565,6 +9600,35 @@ var TranscriptReader = class {
   }
 };
 
+// src/engine/runToolFilter.ts
+init_esm_shims();
+function applyRunToolFilter(registry, options) {
+  const stripAll = options.toolChoice === "none" || options.tools !== void 0 && options.tools.length === 0;
+  if (stripAll) {
+    if (options.toolChoice === "required") {
+      throw new EngineError(
+        "ERR_TOOL_CHOICE_CONFLICT",
+        "toolChoice: 'required' is incompatible with an empty tool set (received tools: [] or toolChoice: 'none')."
+      );
+    }
+    for (const tool of registry.list()) {
+      registry.unregister(tool.name);
+    }
+    return;
+  }
+  if (options.tools === void 0) return;
+  const allow = new Set(options.tools);
+  for (const tool of registry.list()) {
+    if (!allow.has(tool.name)) registry.unregister(tool.name);
+  }
+  if (options.toolChoice === "required" && registry.count() === 0) {
+    throw new EngineError(
+      "ERR_TOOL_CHOICE_CONFLICT",
+      "toolChoice: 'required' was requested but no tools matched the per-run allowlist after applying config filters."
+    );
+  }
+}
+
 // src/engine/rehydrate.ts
 init_esm_shims();
 function rebuildMessagesFromEntries(entries) {
@@ -10041,6 +10105,7 @@ var Engine = class {
       ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
+    applyRunToolFilter(registry, options);
     const writer = new TranscriptWriter({
       storage: storage.workspace,
       logPath,
@@ -10095,7 +10160,14 @@ var Engine = class {
         ...runTimeout.signal !== void 0 ? { runSignal: runTimeout.signal, runTimeoutMs: this.config.execution.runTimeoutMs } : {},
         ...gate !== void 0 ? { gateBeforeTool: gate } : {},
         ..._internal?.handoffToRunner === true ? { handoffToRunner: true } : {},
-        ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {}
+        ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
+        // Plan 025 — output mode + tool-choice plumbed down so the
+        // last-turn guard picks the right instruction text and the
+        // model adapter can pass `'required'` to the provider. `'none'`
+        // is already handled above by stripping the tool list, so the
+        // loop only ever sees `'auto'` or `'required'`.
+        ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
+        ...options.toolChoice === "required" ? { toolChoice: "required" } : {}
       });
       const result = await this.finalizeResult(loopResult, writer, logPath, {
         ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},