@juspay/neurolink 11.6.0 → 11.7.0

package/dist/providers/amazonBedrock/loopAdapter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bedrock's adapter onto the shared agentic loop engine.
+ *
+ * Bedrock had two hand-rolled turn loops — one for `Converse`, one for
+ * `ConverseStream` — that between them duplicated the same content-block
+ * accumulation three times. Everything here is the wire-format half of that:
+ * issuing the right command, folding a response into blocks, serializing tool
+ * results back into the conversation, and mapping the stop reason. The turn
+ * loop itself, the step cap, tool dispatch and usage accumulation belong to
+ * `runAgenticLoop`.
+ *
+ * One adapter covers both operations because the two differ only in how a
+ * step's content blocks arrive: `ConverseStream` delivers them as events that
+ * are pushed to the consumer as they land, `Converse` returns them whole.
+ * Block accumulation, tool-call extraction and the conversation shape are
+ * identical, and were identical in the hand-rolled loops too — which is why
+ * they drifted apart in the details.
+ */
+import type { ConverseCommandInput, ConverseStreamCommandInput } from "@aws-sdk/client-bedrock-runtime";
+import { type BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
+import type { AgenticLoopAdapter, BedrockContentBlock, BedrockMessage } from "../../types/index.js";
+export declare function createBedrockLoopAdapter(config: {
+    client: BedrockRuntimeClient;
+    /** `ConverseStream` when true, `Converse` when false. */
+    streaming: boolean;
+    /** The region the client was constructed with, for profile resolution. */
+    region: string;
+    maxSteps: number;
+    /**
+     * Build the request for one step. Synchronous by contract, so anything
+     * async (tool declarations in particular) is resolved once before the turn
+     * starts rather than per step. Bedrock has no mid-turn tool discovery, so
+     * there is nothing that would need re-resolving.
+     */
+    buildCommandInput: (conversation: BedrockMessage[], step: number) => ConverseCommandInput & ConverseStreamCommandInput;
+}): AgenticLoopAdapter<BedrockMessage[], BedrockContentBlock[]>;

package/dist/providers/amazonBedrock/loopAdapter.js

@@ -0,0 +1,277 @@
+/**
+ * Bedrock's adapter onto the shared agentic loop engine.
+ *
+ * Bedrock had two hand-rolled turn loops — one for `Converse`, one for
+ * `ConverseStream` — that between them duplicated the same content-block
+ * accumulation three times. Everything here is the wire-format half of that:
+ * issuing the right command, folding a response into blocks, serializing tool
+ * results back into the conversation, and mapping the stop reason. The turn
+ * loop itself, the step cap, tool dispatch and usage accumulation belong to
+ * `runAgenticLoop`.
+ *
+ * One adapter covers both operations because the two differ only in how a
+ * step's content blocks arrive: `ConverseStream` delivers them as events that
+ * are pushed to the consumer as they land, `Converse` returns them whole.
+ * Block accumulation, tool-call extraction and the conversation shape are
+ * identical, and were identical in the hand-rolled loops too — which is why
+ * they drifted apart in the details.
+ */
+import { ConverseCommand, ConverseStreamCommand, } from "@aws-sdk/client-bedrock-runtime";
+import { withTimeout } from "../../utils/errorHandling.js";
+import { withInferenceProfileFallback } from "./inferenceProfile.js";
+const STEP_TIMEOUT_MS = 120_000;
+function newToolUseId() {
+    return `tool_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Finalize a block once its `contentBlockStop` arrives: parse whatever tool
+ * input accumulated, and attach the text a plain block collected.
+ *
+ * Attaching the text matters beyond this step. `buildToolResultMessages`
+ * replays these blocks back to the model as the assistant turn, so a text
+ * block left empty here silently drops the assistant's own words from the
+ * conversation on every subsequent step of the turn.
+ */
+function finalizeBlock(block, text) {
+    if (!block) {
+        return;
+    }
+    if (block.toolUse && block._inputBuffer) {
+        try {
+            block.toolUse.input = JSON.parse(block._inputBuffer);
+        }
+        catch {
+            block.toolUse.input = {};
+        }
+        delete block._inputBuffer;
+    }
+    if (text && !block.toolUse) {
+        block.text = text;
+    }
+}
+function toolCallsFrom(blocks) {
+    return blocks
+        .filter((b) => b.toolUse)
+        .map((b) => ({
+        id: b.toolUse?.toolUseId ?? newToolUseId(),
+        name: b.toolUse?.name ?? "",
+        args: b.toolUse?.input ?? {},
+    }));
+}
+/** Fold a `ConverseStream` event sequence into finished content blocks. */
+async function readStreamedStep(response, channel, signal) {
+    const blocks = [];
+    // Blocks are keyed by the index Bedrock stamps on every event rather than
+    // by arrival order, because a text block does not necessarily announce
+    // itself with `contentBlockStart` — the first thing seen for it can be a
+    // delta. Creating the block on whichever event arrives first is what keeps
+    // assistant text that precedes a tool call from being dropped: `raw` is
+    // replayed as the assistant turn on the next step, so a lost text block
+    // means the model stops seeing its own reasoning mid-turn.
+    const blocksByIndex = new Map();
+    const textByIndex = new Map();
+    const blockFor = (index) => {
+        let block = blocksByIndex.get(index);
+        if (!block) {
+            block = {};
+            blocksByIndex.set(index, block);
+            blocks.push(block);
+        }
+        return block;
+    };
+    let text = "";
+    let rawStopReason;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    if (response.stream) {
+        for await (const rawChunk of response.stream) {
+            if (signal.aborted) {
+                break;
+            }
+            const chunk = rawChunk;
+            if (chunk.contentBlockStart) {
+                blockFor(chunk.contentBlockStart.contentBlockIndex ?? 0);
+            }
+            if (chunk.contentBlockDelta?.delta?.text) {
+                const index = chunk.contentBlockDelta.contentBlockIndex ?? 0;
+                const delta = chunk.contentBlockDelta.delta.text;
+                blockFor(index);
+                text += delta;
+                textByIndex.set(index, (textByIndex.get(index) ?? "") + delta);
+                channel.push({ content: delta });
+            }
+            if (chunk.contentBlockStart?.start?.toolUse) {
+                const block = blockFor(chunk.contentBlockStart.contentBlockIndex ?? 0);
+                block.toolUse = {
+                    name: chunk.contentBlockStart.start.toolUse.name ?? "",
+                    input: {},
+                    toolUseId: chunk.contentBlockStart.start.toolUse.toolUseId ?? newToolUseId(),
+                };
+            }
+            if (chunk.contentBlockDelta?.delta?.toolUse) {
+                const block = blockFor(chunk.contentBlockDelta.contentBlockIndex ?? 0);
+                block.toolUse ??= {
+                    name: "",
+                    input: {},
+                    toolUseId: newToolUseId(),
+                };
+                const deltaInput = chunk.contentBlockDelta.delta.toolUse.input;
+                if (typeof deltaInput === "string") {
+                    block._inputBuffer = (block._inputBuffer ?? "") + deltaInput;
+                }
+                else if (typeof deltaInput === "object" &&
+                    deltaInput !== null &&
+                    !Array.isArray(deltaInput)) {
+                    block.toolUse.input = {
+                        ...(block.toolUse.input ?? {}),
+                        ...deltaInput,
+                    };
+                }
+            }
+            if (chunk.contentBlockStop) {
+                const index = chunk.contentBlockStop.contentBlockIndex ?? 0;
+                finalizeBlock(blocksByIndex.get(index), textByIndex.get(index) ?? "");
+            }
+            if (chunk.messageStop) {
+                rawStopReason = chunk.messageStop.stopReason ?? "end_turn";
+                // Not a break: the metadata event carrying usage arrives after this.
+                continue;
+            }
+            if (chunk.metadata?.usage) {
+                inputTokens += chunk.metadata.usage.inputTokens ?? 0;
+                outputTokens += chunk.metadata.usage.outputTokens ?? 0;
+                // Converse follows the Anthropic additive convention — inputTokens is
+                // the uncached remainder, so cache reads/writes are counted apart.
+                cacheReadTokens += chunk.metadata.usage.cacheReadInputTokens ?? 0;
+                cacheWriteTokens += chunk.metadata.usage.cacheWriteInputTokens ?? 0;
+                break;
+            }
+        }
+    }
+    // Finalize anything the stream never closed. `contentBlockStop` is not
+    // guaranteed to arrive for every block: an abort breaks the loop, the
+    // metadata event breaks it, and a truncated stream simply ends. A block
+    // left unfinalized keeps `text` undefined and its tool input unparsed, and
+    // since `raw` is replayed as the assistant message — where an unrecognized
+    // block maps to `{ text: "" }`, which Bedrock rejects — that would fail the
+    // NEXT step of the turn rather than this one.
+    for (const [index, block] of blocksByIndex) {
+        finalizeBlock(block, textByIndex.get(index) ?? "");
+    }
+    // A block that opened and then received nothing carries no content at all,
+    // and `convertToAWSMessages` maps an unrecognized block to `{ text: "" }`,
+    // which Bedrock rejects. Drop them rather than replay them.
+    const usableBlocks = blocks.filter((block) => block.text || block.toolUse || block.image || block.document);
+    return {
+        text,
+        toolCalls: toolCallsFrom(usableBlocks),
+        usage: { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens },
+        rawStopReason,
+        raw: usableBlocks,
+    };
+}
+/** Fold a non-streaming `Converse` response into the same block shape. */
+function readGeneratedStep(response) {
+    const blocks = [];
+    let text = "";
+    for (const item of response.output?.message?.content ?? []) {
+        const block = {};
+        if ("text" in item && item.text) {
+            block.text = item.text;
+            text += text ? ` ${item.text}` : item.text;
+        }
+        if ("toolUse" in item && item.toolUse) {
+            block.toolUse = {
+                toolUseId: item.toolUse.toolUseId ?? newToolUseId(),
+                name: item.toolUse.name ?? "",
+                input: item.toolUse.input ?? {},
+            };
+        }
+        blocks.push(block);
+    }
+    return {
+        text,
+        toolCalls: toolCallsFrom(blocks),
+        usage: {
+            inputTokens: response.usage?.inputTokens ?? 0,
+            outputTokens: response.usage?.outputTokens ?? 0,
+            cacheReadTokens: response.usage?.cacheReadInputTokens ?? 0,
+            cacheWriteTokens: response.usage?.cacheWriteInputTokens ?? 0,
+        },
+        rawStopReason: response.stopReason,
+        raw: blocks,
+    };
+}
+export function createBedrockLoopAdapter(config) {
+    return {
+        providerLabel: "bedrock",
+        maxSteps: config.maxSteps,
+        // No toolFailureBreaker: Bedrock has never had strike counting — a failing
+        // tool becomes one error tool-result with no cross-step memory. Preserved.
+        buildStepRequest(conversation, step) {
+            return { raw: config.buildCommandInput(conversation, step) };
+        },
+        async executeStep(request, channel, signal) {
+            const commandInput = request.raw;
+            // Both sends go through the inference-profile fallback: most current
+            // Bedrock models are not invocable by their bare id in a given region
+            // and need a geography- or global-prefixed profile id instead. This is
+            // where the provider's two Converse call sites now live.
+            if (!config.streaming) {
+                const response = await withInferenceProfileFallback(commandInput.modelId ?? "", config.region, (effectiveModelId) => withTimeout(config.client.send(new ConverseCommand({
+                    ...commandInput,
+                    modelId: effectiveModelId,
+                })), STEP_TIMEOUT_MS, new Error("Bedrock API call timed out")));
+                if (!response.output?.message) {
+                    throw new Error("Invalid response structure from Bedrock API");
+                }
+                return readGeneratedStep(response);
+            }
+            const response = await withInferenceProfileFallback(commandInput.modelId ?? "", config.region, (effectiveModelId) => withTimeout(config.client.send(new ConverseStreamCommand({
+                ...commandInput,
+                modelId: effectiveModelId,
+            })), STEP_TIMEOUT_MS, new Error("Bedrock streaming API call timed out")));
+            return readStreamedStep(response, channel, signal);
+        },
+        buildToolResultMessages(conversation, stepResult, toolResults) {
+            const assistantMessage = {
+                role: "assistant",
+                content: stepResult.raw,
+            };
+            const toolResultMessage = {
+                role: "user",
+                content: toolResults.map((result) => ({
+                    toolResult: {
+                        toolUseId: result.id,
+                        content: [
+                            {
+                                text: result.error
+                                    ? `Error executing tool ${result.name}: ${result.error}`
+                                    : String(typeof result.output === "string"
+                                        ? result.output
+                                        : JSON.stringify(result.output)),
+                            },
+                        ],
+                        status: result.error ? "error" : "success",
+                    },
+                })),
+            };
+            return [...conversation, assistantMessage, toolResultMessage];
+        },
+        mapFinishReason(rawStopReason, hadToolCallsAtCap) {
+            switch (rawStopReason) {
+                case "end_turn":
+                case "stop_sequence":
+                    return "stop";
+                case "max_tokens":
+                    return "length";
+                case "tool_use":
+                    return "tool-calls";
+                default:
+                    return hadToolCallsAtCap ? "tool-calls" : "stop";
+            }
+        },
+    };
+}

package/dist/types/loopEngine.d.ts

@@ -35,6 +35,46 @@ export type AgenticLoopReclaimResult<TConversation> = {
 export type AgenticLoopToolFailureBreaker = {
     maxRetries: number;
 };
+/**
+ * DESIGN DECISION — mid-turn tool-discovery hydration (Plan 08 blocker 2,
+ * Task 7): resolved by the single optional `resolveToolOnMiss` field below,
+ * NOT by a broader `dispatchTools?` full-dispatch override. A full-dispatch
+ * override would let an adapter replace the engine's entire per-call
+ * dispatch — breaker bookkeeping, execution, toolExecutions aggregation — so
+ * every adapter needing hydration would have to reimplement that bookkeeping,
+ * and any later engine-level fix to dispatch would silently not apply to the
+ * adapters using the override. `resolveToolOnMiss` plugs into the existing
+ * dispatch at the one decision point that needs a second lookup, leaving
+ * breaker bookkeeping, retries and aggregation engine-owned for every
+ * provider, hydrated or not.
+ *
+ * DESIGN DECISION — originalNameMap propagation (blocker 3): needs ZERO
+ * engine or type change. Google's function-name sanitization is a translation
+ * concern between the wire (sanitized names out, sanitized names back on
+ * tool_call.name) and the engine's shape, which only ever sees plain string
+ * names. An adapter that needs the map threads it as a constructor-time
+ * closure and translates inside its own `executeStep` /
+ * `buildToolResultMessages`, before those names cross the engine boundary.
+ *
+ * DESIGN DECISION — reserved-step + forced finalization (blocker 1, part 2):
+ * stays OUTSIDE `runAgenticLoop`, in Vertex+Claude's own wrapper around
+ * `resultPromise`. The reserved step needs no engine change at all — an
+ * adapter declaring `maxSteps: requested - 1` means the engine's own loop
+ * never touches the reserved slot. The forced call is a one-shot action taken
+ * on the RESULT of a turn, not a repeatable step within one, so folding it in
+ * would teach the engine a family-specific concept (forced tool_choice, a
+ * distinguished terminal tool name) that every other adapter would then carry
+ * and never set.
+ *
+ * DESIGN DECISION — terminal tool-call marking (blocker 1, part 1): needs
+ * ZERO engine or type change. An adapter treats a detected terminal call as
+ * terminal by omitting it from `toolCalls` and putting its parsed payload in
+ * `text`. The engine already ends a turn the moment a step yields zero tool
+ * calls, so such a step is indistinguishable from an ordinary final text
+ * turn: never looked up in `options.tools`, never reaching TOOL_NOT_FOUND,
+ * never counted against the breaker. Proven by a case in the loop-engine
+ * suite rather than asserted here.
+ */
 export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
     readonly providerLabel: string;
     readonly maxSteps: number;
@@ -43,6 +83,18 @@ export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
     readonly stallTimeoutMs?: number;
     /** Set only for adapter instances whose client has the TOOL_NOT_FOUND strike breaker today: both Gemini adapters (AI Studio, Vertex+Gemini) AND the Vertex+Claude call to createAnthropicLoopAdapter — NOT the native-Anthropic call to that same factory, and not Bedrock. See Verified Fact 4. */
     readonly toolFailureBreaker?: AgenticLoopToolFailureBreaker;
+    /**
+     * Second lookup path, consulted when a tool call names nothing executable
+     * in the caller's `options.tools` — used by adapters supporting mid-turn
+     * discovery to hydrate a tool the model just found via `search_tools`, or a
+     * deferred-catalog tool called by its advertised name, before the engine
+     * falls through to TOOL_NOT_FOUND and the breaker strike. See the design
+     * decision above for why this is a narrow lookup and not a dispatch
+     * override.
+     */
+    readonly resolveToolOnMiss?: (name: string) => {
+        execute: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;
+    } | undefined;
     buildStepRequest(conversation: TConversation, step: number): AgenticLoopStepRequest;
     executeStep(request: AgenticLoopStepRequest, channel: {
         push(chunk: {

package/dist/types/providers.d.ts

@@ -833,6 +833,15 @@ export type BedrockContentBlock = {
     toolUse?: BedrockToolUse;
     toolResult?: BedrockToolResult;
 };
+/**
+ * A Bedrock content block still being assembled from a ConverseStream event
+ * sequence. `_inputBuffer` holds the partial tool-call JSON that arrives
+ * across several `contentBlockDelta` events and is parsed away at
+ * `contentBlockStop`, so it never appears on a finished block.
+ */
+export type BedrockPendingContentBlock = BedrockContentBlock & {
+    _inputBuffer?: string;
+};
 /**
  * Bedrock message structure
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.6.0",
+  "version": "11.7.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -211,7 +211,8 @@
     "test:model-pool": "npx tsx test/continuous-test-suite-model-pool.ts",
     "test:vector-chroma": "npx tsx test/continuous-test-suite-vector-chroma.ts",
     "test:vector-pgvector": "npx tsx test/continuous-test-suite-vector-pgvector.ts",
-    "test:vector-pinecone": "npx tsx test/continuous-test-suite-vector-pinecone.ts"
+    "test:vector-pinecone": "npx tsx test/continuous-test-suite-vector-pinecone.ts",
+    "test:bedrock-loop-characterization": "tsx test/continuous-test-suite-bedrock-loop-characterization.ts"
   },
   "files": [
     "dist",