la-machina-engine 0.7.2 → 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;
@@ -2020,11 +2055,19 @@ interface RunOptions {
      */
     readonly outputFormat?: 'text' | 'json' | undefined;
     /**
-     * Zod schema for structured output. Only used when outputFormat is 'json'.
-     * Injected into system prompt as JSON Schema description, used to
-     * validate the model's response. If validation fails, retries once.
+     * Schema for structured output. Only used when outputFormat is 'json'.
+     * Injected into the system prompt and (for Zod schemas) used to
+     * validate the model's response.
+     *
+     * Two shapes accepted:
+     *   - A Zod schema — strictly validated via `safeParse`; retries
+     *     once on failure with a corrective prompt.
+     *   - A plain JSON Schema object — used verbatim in the prompt; no
+     *     server-side strict validation (callers wanting that should
+     *     pass Zod). This shape is what serialized workflow definitions
+     *     (e.g. nikaido) carry, since they can't embed Zod instances.
      */
-    readonly outputSchema?: zod.ZodTypeAny | undefined;
+    readonly outputSchema?: zod.ZodTypeAny | Record<string, unknown> | undefined;
     /**
      * Per-run skill override (Plan 017). When present, the engine IGNORES
      * `config.skills.autoload` + `config.skills.path` and uses this list
@@ -3047,11 +3090,21 @@ declare const defaultToolResultSummarizer: ToolResultSummarizerV1;
  * All pure JS — no `node:` imports, Workers-compatible.
  */
 
+/**
+ * Schema users can supply for structured output. Either:
+ *   - a Zod schema (typed validation, runs `safeParse` post-parse), or
+ *   - a plain JSON Schema object (used verbatim in the system prompt;
+ *     no strict server-side validation in v1).
+ *
+ * Workflow definitions stored as JSON (e.g. nikaido) can only carry
+ * the JSON Schema variant; native TS callers may use either.
+ */
+type OutputSchema = ZodTypeAny | Record<string, unknown>;
 /**
  * Build the output format section to append to the system prompt.
  * Called when outputFormat is 'json'.
  */
-declare function buildSchemaPrompt(schema?: ZodTypeAny): string;
+declare function buildSchemaPrompt(schema?: OutputSchema): string;
 interface ParseResult {
     readonly ok: boolean;
     readonly value?: unknown;
@@ -3065,10 +3118,14 @@ interface ParseResult {
  */
 declare function tryParseJSON(text: string): ParseResult;
 /**
- * Validate parsed JSON against a Zod schema.
- * Returns the validated data or an error message.
+ * Validate parsed JSON against a schema.
+ *
+ * Zod schemas get strict `safeParse` validation. Plain JSON Schema
+ * objects are NOT strictly validated (skipping ajv keeps the bundle
+ * small for Workers); the prompt-injected schema is the contract and
+ * the caller can validate downstream if needed.
  */
-declare function validateOutput(value: unknown, schema: ZodTypeAny): {
+declare function validateOutput(value: unknown, schema: OutputSchema): {
     ok: true;
     data: unknown;
 } | {

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;
@@ -2020,11 +2055,19 @@ interface RunOptions {
      */
     readonly outputFormat?: 'text' | 'json' | undefined;
     /**
-     * Zod schema for structured output. Only used when outputFormat is 'json'.
-     * Injected into system prompt as JSON Schema description, used to
-     * validate the model's response. If validation fails, retries once.
+     * Schema for structured output. Only used when outputFormat is 'json'.
+     * Injected into the system prompt and (for Zod schemas) used to
+     * validate the model's response.
+     *
+     * Two shapes accepted:
+     *   - A Zod schema — strictly validated via `safeParse`; retries
+     *     once on failure with a corrective prompt.
+     *   - A plain JSON Schema object — used verbatim in the prompt; no
+     *     server-side strict validation (callers wanting that should
+     *     pass Zod). This shape is what serialized workflow definitions
+     *     (e.g. nikaido) carry, since they can't embed Zod instances.
      */
-    readonly outputSchema?: zod.ZodTypeAny | undefined;
+    readonly outputSchema?: zod.ZodTypeAny | Record<string, unknown> | undefined;
     /**
      * Per-run skill override (Plan 017). When present, the engine IGNORES
      * `config.skills.autoload` + `config.skills.path` and uses this list
@@ -3047,11 +3090,21 @@ declare const defaultToolResultSummarizer: ToolResultSummarizerV1;
  * All pure JS — no `node:` imports, Workers-compatible.
  */
 
+/**
+ * Schema users can supply for structured output. Either:
+ *   - a Zod schema (typed validation, runs `safeParse` post-parse), or
+ *   - a plain JSON Schema object (used verbatim in the system prompt;
+ *     no strict server-side validation in v1).
+ *
+ * Workflow definitions stored as JSON (e.g. nikaido) can only carry
+ * the JSON Schema variant; native TS callers may use either.
+ */
+type OutputSchema = ZodTypeAny | Record<string, unknown>;
 /**
  * Build the output format section to append to the system prompt.
  * Called when outputFormat is 'json'.
  */
-declare function buildSchemaPrompt(schema?: ZodTypeAny): string;
+declare function buildSchemaPrompt(schema?: OutputSchema): string;
 interface ParseResult {
     readonly ok: boolean;
     readonly value?: unknown;
@@ -3065,10 +3118,14 @@ interface ParseResult {
  */
 declare function tryParseJSON(text: string): ParseResult;
 /**
- * Validate parsed JSON against a Zod schema.
- * Returns the validated data or an error message.
+ * Validate parsed JSON against a schema.
+ *
+ * Zod schemas get strict `safeParse` validation. Plain JSON Schema
+ * objects are NOT strictly validated (skipping ajv keeps the bundle
+ * small for Workers); the prompt-injected schema is the contract and
+ * the caller can validate downstream if needed.
  */
-declare function validateOutput(value: unknown, schema: ZodTypeAny): {
+declare function validateOutput(value: unknown, schema: OutputSchema): {
     ok: true;
     data: unknown;
 } | {

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;
   }
@@ -7767,6 +7802,9 @@ async function collectSkills(storage, skillsDir) {
 // src/engine/jsonOutput.ts
 init_esm_shims();
 import { zodToJsonSchema as zodToJsonSchema2 } from "zod-to-json-schema";
+function isZodSchema(s) {
+  return s !== null && typeof s === "object" && "_def" in s && typeof s.safeParse === "function";
+}
 function buildSchemaPrompt(schema) {
   const lines = [
     "# Output Format",
@@ -7776,11 +7814,18 @@ function buildSchemaPrompt(schema) {
     "Do NOT wrap in ```json ... ```. Just raw JSON."
   ];
   if (schema) {
-    const jsonSchema2 = zodToJsonSchema2(schema, {
-      target: "jsonSchema7",
-      $refStrategy: "none"
-    });
-    const { $schema: _, ...clean } = jsonSchema2;
+    let clean;
+    if (isZodSchema(schema)) {
+      const jsonSchema2 = zodToJsonSchema2(schema, {
+        target: "jsonSchema7",
+        $refStrategy: "none"
+      });
+      const { $schema: _z, ...rest } = jsonSchema2;
+      clean = rest;
+    } else {
+      const { $schema: _j, ...rest } = schema;
+      clean = rest;
+    }
     lines.push("", "The JSON MUST conform to this schema:", JSON.stringify(clean, null, 2));
   } else {
     lines.push("", "Return a JSON object with the relevant data.");
@@ -7816,6 +7861,9 @@ function tryParseJSON2(text2) {
   return { ok: false, error: "No valid JSON found in response" };
 }
 function validateOutput(value, schema) {
+  if (!isZodSchema(schema)) {
+    return { ok: true, data: value };
+  }
   const result = schema.safeParse(value);
   if (result.success) {
     return { ok: true, data: result.data };
@@ -9552,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) {
@@ -10028,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,
@@ -10082,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 } : {},