@juspay/neurolink 12.49.19 → 12.49.20

package/dist/core/nativeGenerateLoop.d.ts

@@ -28,6 +28,11 @@ import type { NativeGenerateLoopArgs, NativeGenerateLoopResult, StepResult, Step
  * how a caller forces a tool on step 3 only. A hook that returns no
  * `toolChoice` defers to the rule. Nothing else on the hook's result is read.
  *
+ * A forced single-tool choice, from the hook or from the turn, that names a
+ * tool outside `declaredTools` is warned about and not sent. A hook's choice
+ * is then treated as "no override" and the rule decides; the turn's own
+ * choice becomes `"auto"`. Without `declaredTools` nothing is checked.
+ *
  * A hook that THROWS is logged and treated as "no override": the steps
  * already billed are kept and the rule decides. An abort of the turn while
  * the hook is pending is not a hook failure and is re-thrown. The two are

package/dist/core/nativeGenerateLoop.js

@@ -32,6 +32,60 @@ const isForcedToolChoice = (choice) => {
     }
     return false;
 };
+/**
+ * The tool a choice forces by name, when it forces one. Both wire mappers
+ * honour exactly `{ type: "tool", toolName }` with a non-empty name, so
+ * that is the only shape that names a function on the wire.
+ */
+const forcedToolName = (choice) => {
+    if (typeof choice !== "object" || choice === null) {
+        return undefined;
+    }
+    const { type, toolName } = choice;
+    return type === "tool" && typeof toolName === "string" && toolName !== ""
+        ? toolName
+        : undefined;
+};
+/**
+ * The name a choice forces when `declaredTools` is known and lacks it, else
+ * undefined. Own keys only: the live record may have a null prototype or be
+ * keyed by a name such as "constructor".
+ */
+const undeclaredForcedToolName = (choice, declaredTools) => {
+    if (!declaredTools) {
+        return undefined;
+    }
+    const name = forcedToolName(choice);
+    return name !== undefined && !Object.hasOwn(declaredTools, name)
+        ? name
+        : undefined;
+};
+/**
+ * A forced choice for a tool the request does not declare is dropped for the
+ * step rather than sent, so a stale hook or a platform-gated tool degrades
+ * the turn to the model's own choice instead of failing it with a 400.
+ */
+const warnUndeclaredForcedTool = (toolName, step, source) => {
+    logger.warn(source === "prepareStep"
+        ? `prepareStep forced tool "${toolName}" at step ${step}, but the request does not declare it; ignoring the override for this step`
+        : `toolChoice forces tool "${toolName}" at step ${step}, but the request does not declare it; using "auto" for this step`, { toolName, step, source });
+};
+/**
+ * The names this request actually carries, in the record shape
+ * `declaredTools` takes. The loop sends `args.tools`, built once by the
+ * caller; `args.toolsRecord` can hold more (discovery hydrates into it, and
+ * this loop never re-declares), so only `tools` answers "is it offered".
+ * Null prototype: a tool may be named `__proto__` or `constructor`.
+ */
+const declaredToolRecord = (tools) => {
+    const declared = Object.create(null);
+    for (const tool of tools ?? []) {
+        if (typeof tool.name === "string") {
+            declared[tool.name] = true;
+        }
+    }
+    return declared;
+};
 /**
  * `toolChoiceSteps` is a count of leading steps, so anything but a
  * non-negative integer is meaningless. Fall back to the default with a WARN
@@ -127,6 +181,11 @@ const abortReason = (signal) => {
  * how a caller forces a tool on step 3 only. A hook that returns no
  * `toolChoice` defers to the rule. Nothing else on the hook's result is read.
  *
+ * A forced single-tool choice, from the hook or from the turn, that names a
+ * tool outside `declaredTools` is warned about and not sent. A hook's choice
+ * is then treated as "no override" and the rule decides; the turn's own
+ * choice becomes `"auto"`. Without `declaredTools` nothing is checked.
+ *
  * A hook that THROWS is logged and treated as "no override": the steps
  * already billed are kept and the rule decides. An abort of the turn while
  * the hook is pending is not a hook failure and is re-thrown. The two are
@@ -156,16 +215,27 @@ export async function resolveStepToolChoice(input) {
         }
         warnIgnoredPrepareStepFields(prepared);
         if (prepared?.toolChoice !== undefined) {
-            return prepared.toolChoice;
+            const undeclaredPrepared = undeclaredForcedToolName(prepared.toolChoice, input.declaredTools);
+            if (undeclaredPrepared === undefined) {
+                return prepared.toolChoice;
+            }
+            warnUndeclaredForcedTool(undeclaredPrepared, input.step, "prepareStep");
         }
     }
     if (input.base === undefined) {
         return undefined;
     }
-    if (!isForcedToolChoice(input.base) ||
-        input.step < normalizeToolChoiceSteps(input.toolChoiceSteps)) {
+    if (!isForcedToolChoice(input.base)) {
+        return input.base;
+    }
+    if (input.step >= normalizeToolChoiceSteps(input.toolChoiceSteps)) {
+        return "auto";
+    }
+    const undeclaredBase = undeclaredForcedToolName(input.base, input.declaredTools);
+    if (undeclaredBase === undefined) {
         return input.base;
     }
+    warnUndeclaredForcedTool(undeclaredBase, input.step, "base");
     return "auto";
 }
 /**
@@ -356,6 +426,7 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
                 steps: stepRecords,
                 maxSteps: args.maxSteps,
                 model: args.modelId,
+                declaredTools: declaredToolRecord(args.tools),
                 ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
             })
             : undefined;

package/dist/providers/anthropic/client.js

@@ -2008,6 +2008,7 @@ export class AnthropicProvider extends BaseProvider {
                             steps: stepRecords,
                             maxSteps,
                             model: modelId,
+                            declaredTools: toolsRecord,
                             ...(abortSignal ? { abortSignal } : {}),
                         })))
                     : undefined;

package/dist/providers/openaiChatCompletionsBase.js

@@ -1741,6 +1741,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                             steps,
                             maxSteps,
                             model: modelId,
+                            declaredTools: toolsRecord,
                             ...(abortSignal ? { abortSignal } : {}),
                         }), wireNameMaps?.toWire)
                         : undefined,

package/dist/types/generate.d.ts

@@ -584,6 +584,10 @@ export type GenerateOptions = {
      * compel a tool call on every step, and the loop would only end when
      * `maxSteps` ran out. `"auto"` and `"none"` are applied unchanged on every
      * step. Vertex, Google AI Studio and Bedrock do not honour `toolChoice`.
+     *
+     * A named tool that the request does not declare is not sent, because the
+     * provider would reject the request: a warning is logged and the step uses
+     * `"auto"`.
      */
     toolChoice?: ToolChoice<Record<string, Tool>>;
     /**
@@ -606,7 +610,9 @@ export type GenerateOptions = {
      * Optional callback that runs before each step in a multi-step generation.
      *
      * Honoured field of the result: `toolChoice`, applied to that step only
-     * and taking precedence over `toolChoice` / `toolChoiceSteps`.
+     * and taking precedence over `toolChoice` / `toolChoiceSteps`. A named tool
+     * the request does not declare is ignored with a warning, as if the hook had
+     * returned no `toolChoice`.
      *
      * Not honoured — accepted for source compatibility with the former Vercel
      * AI SDK `experimental_prepareStep` shape, but ignored by every native
@@ -1799,6 +1805,17 @@ export type StepToolChoiceInput = {
     model: string;
     /** The turn's abort signal; a pending `prepareStep` is released when it fires. */
     abortSignal?: AbortSignal;
+    /**
+     * The tools this request declares, keyed by SDK-side tool name. When given,
+     * a forced single-tool choice naming a tool outside it is not sent: a
+     * provider answers a request that forces a function its own tools list
+     * lacks with a 400. A loop that re-declares hydrated tools in the same
+     * step (the streaming loops) passes the live record, because discovery
+     * hydrates tools into it between steps; a loop that sends a fixed tools
+     * array (the shared generate loop) passes the names of that array.
+     * Absent means the choice is not checked.
+     */
+    declaredTools?: Readonly<Record<string, unknown>>;
 };
 /**
  * Inputs to the shared native generate loop (`core/nativeGenerateLoop.ts`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.49.19",
+  "version": "12.49.20",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {
@@ -112,6 +112,7 @@
     "test:agent:cost": "pnpm exec tsx test/continuous-test-suite-agent-cost.ts",
     "test:adjust-body-after-400": "pnpm exec tsx test/continuous-test-suite-adjust-body-after-400.ts",
     "test:zod3-schema-native-path": "pnpm exec tsx test/continuous-test-suite-zod3-schema-native-path.ts",
+    "test:forced-tool-declared": "pnpm exec tsx test/continuous-test-suite-forced-tool-declared.ts",
     "test:error-classification-e2e": "pnpm exec tsx test/continuous-test-suite-error-classification-e2e.ts",
     "test:error-classifier-contract": "pnpm exec tsx test/continuous-test-suite-error-classifier-contract.ts",
     "test:bedrock-inference-profile": "pnpm exec tsx test/continuous-test-suite-bedrock-inference-profile.ts",