@k2b/nessi 0.10.0 → 0.12.0

package/README.md

@@ -64,6 +64,61 @@ Every outbound event from one `nessi()` run carries the same `loopId`. Pass your
 
 `turn_end` reports each internal provider turn. The final `loop_end` event includes `aggregate`, which groups assistant turns, executable tool calls, tool results, validation/execution errors, malformed or cancelled tool streams, summed usage, and timing for the complete logical loop. `aggregate.timing.totalElapsedMs` is model generation plus active tool execution; approval/client-tool waits are tracked separately as `aggregate.timing.actionWaitMs`. Helper exports such as `mergeUsage()`, `cloneLoopAggregate()`, and `mergeLoopAggregates()` are available from `@k2b/nessi`.
 
+## Dynamic tools
+
+Pass a resolver when the active tools depend on application state:
+
+```ts
+const loop = nessi({
+  provider,
+  systemPrompt,
+  input,
+  store,
+  tools: async () => toolRegistry.activeFor(userId),
+});
+```
+
+Nessi resolves dynamic tools before every provider turn. One copied and
+validated snapshot supplies both the provider schemas and all tool execution
+for that turn. Changes made during tool execution therefore become visible on
+the following provider turn, while calls already emitted by the provider remain
+executable from their original snapshot. Duplicate names and resolver failures
+end the loop with a `runtime_error` issue.
+
+Pending tool calls restored from history resolve one fresh snapshot before
+execution because an in-memory snapshot cannot survive a restart. Keep the
+resolver side-effect free; persistence, discovery, authorization, and cleanup
+remain application-owned.
+
+Server tools receive the provider tool call ID through `ctx.callId`:
+
+```ts
+const inspect = defineTool({
+  name: "inspect",
+  description: "Inspect an item",
+  inputSchema: z.object({ id: z.string() }),
+}).server(async ({ id }, ctx) => {
+  return inspectItem(id, { callId: ctx.callId, signal: ctx.signal });
+});
+```
+
+`nessi.structured()` accepts the same pattern for server tools:
+
+```ts
+const result = await nessi.structured({
+  provider,
+  input: "Resolve the current task.",
+  output: taskSchema,
+  tools: () => toolRegistry.activeServerTools(),
+});
+```
+
+A structured tool resolver always selects `tool_loop` mode, even when a
+snapshot is empty, because later turns may add tools. Nessi appends its internal
+`submit_result` tool to every snapshot. Client tools, approval tools, and a
+user-defined `submit_result` remain unsupported. A static empty array keeps the
+direct native/fallback structured-output path.
+
 ## Historical tool results
 
 Verbose tool output can remain fully persisted without being sent to the model
@@ -210,11 +265,62 @@ for await (const event of provider.stream({ messages })) {
 }
 ```
 
+## Audio transcription
+
+Use `openAICompatibleTranscription()` to upload an audio file to a service that
+implements the OpenAI-compatible `/audio/transcriptions` endpoint. Configure
+the service URL, API key and transcription model explicitly:
+
+```ts
+import { openAICompatibleTranscription } from "@k2b/nessi/ai";
+
+const speech = openAICompatibleTranscription("whisper-large-v3", {
+  baseURL: "https://api.scaleway.ai/v1",
+  apiKey: process.env.SCW_SECRET_KEY,
+});
+
+const result = await speech.transcribe({
+  file: Bun.file("./aufnahme.mp3"),
+  filename: "aufnahme.mp3",
+  language: "de",
+  signal: AbortSignal.timeout(120_000),
+});
+
+console.log(result.text);
+```
+
+For OpenAI, set `baseURL: "https://api.openai.com/v1"`, use your OpenAI key and
+a supported transcription model such as `whisper-1`. Local compatible services
+can omit `apiKey`. No environment variable is read automatically. Optional
+`headers` support gateways; `apiKey` overrides their Authorization header.
+
+`file` accepts a `Blob`, `File` or `Bun.file()`. Use `filename` to supply an
+extension for an unnamed Blob or override the filename. Automatically derived
+filenames omit local directories. Omit `language`
+for automatic detection. Optional `prompt` supplies vocabulary or context
+when supported by the model. File formats, size limits and optional parameter
+support depend on the service; Nessi does not convert or split audio.
+
+The result is `{ text: string }`, including an empty string for an empty
+transcript. HTTP, connection and malformed-response errors reject the promise.
+Pass `signal` for cancellation or a timeout; cancellation preserves the signal's
+reason. There are no automatic retries or default timeout.
+
+Transcription uses its own `TranscriptionProvider` contract with `name`, `model`
+and `transcribe(request)`. Custom adapters can implement that interface for other
+protocols. It is separate from the chat provider passed to `nessi()`; pass the
+resulting text into the agent when needed. Streaming transcription, timestamps
+and speaker identification are not exposed.
+
+The example follows [Scaleway's audio API documentation](https://www.scaleway.com/en/docs/generative-apis/how-to/query-audio-models/).
+Keep API keys on the server when integrating a browser application.
+
 ## Focused provider imports
 
 ```ts
 import { anthropic } from "@k2b/nessi/ai/providers/anthropic";
 import { openai } from "@k2b/nessi/ai/providers/openai";
+import { openAICompatibleTranscription } from "@k2b/nessi/ai/providers/openai-compatible-transcription";
 ```
 
 ## Features
@@ -235,6 +341,7 @@ import { openai } from "@k2b/nessi/ai/providers/openai";
 - Standalone `compact()` loop with `loop_start`, `compaction_start`, `compaction_end`, `issue`, and `loop_end` events
 - Optional token-credit budgeting
 - Provider adapters with shared `complete()` and `stream()` APIs
+- Audio transcription through configurable OpenAI-compatible services
 - Native adapters for OpenAI, OpenRouter, vLLM, Ollama, Anthropic, Mistral, and Gemini
 
 ## Package layout
@@ -244,7 +351,7 @@ import { openai } from "@k2b/nessi/ai/providers/openai";
   Agent loop, structured task helper, tools, stores, compaction, shared types
 
 @k2b/nessi/ai
-  Provider factories, provider types, complete(), stream(), responseFormat
+  Provider factories, provider types, complete(), stream(), responseFormat, transcribe()
 
 @k2b/nessi/ai/providers/*
   Focused provider entrypoints

package/ai/index.d.ts

@@ -1,4 +1,7 @@
 export { completeFromStream } from "./complete-from-stream.js";
+export { openAICompatibleTranscription } from "./providers/openai-compatible-transcription.js";
+export type { OpenAICompatibleTranscriptionOptions } from "./providers/openai-compatible-transcription.js";
+export type { TranscriptionProvider, TranscriptionRequest, TranscriptionResult } from "./transcription.js";
 export { openAICompatible } from "./providers/openai-compatible.js";
 export { openai } from "./providers/openai.js";
 export { openrouter } from "./providers/openrouter.js";

package/ai/index.js

@@ -1,4 +1,5 @@
 export { completeFromStream } from "./complete-from-stream.js";
+export { openAICompatibleTranscription } from "./providers/openai-compatible-transcription.js";
 export { openAICompatible } from "./providers/openai-compatible.js";
 export { openai } from "./providers/openai.js";
 export { openrouter } from "./providers/openrouter.js";

package/ai/providers/openai-compatible-transcription.d.ts

@@ -0,0 +1,8 @@
+import type { TranscriptionProvider } from "../transcription.js";
+export type OpenAICompatibleTranscriptionOptions = {
+    baseURL: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    name?: string;
+};
+export declare const openAICompatibleTranscription: (model: string, options: OpenAICompatibleTranscriptionOptions) => TranscriptionProvider;

package/ai/providers/openai-compatible-transcription.js

@@ -0,0 +1,60 @@
+import { formatConnectionError, normalizeHttpError } from "../shared/errors.js";
+export const openAICompatibleTranscription = (model, options) => {
+    const baseURL = options.baseURL.replace(/\/+$/, "");
+    const name = options.name ?? "openai-compatible";
+    const headers = new Headers(options.headers);
+    // Fetch must supply the multipart boundary, including with custom headers.
+    headers.delete("Content-Type");
+    if (options.apiKey)
+        headers.set("Authorization", `Bearer ${options.apiKey}`);
+    return {
+        name,
+        model,
+        async transcribe(request) {
+            request.signal?.throwIfAborted();
+            const body = new FormData();
+            // Bun.file().name can contain a local path; only upload the basename.
+            const fileName = "name" in request.file && typeof request.file.name === "string"
+                ? request.file.name.split(/[\\/]/).at(-1)
+                : undefined;
+            const filename = request.filename ?? fileName;
+            if (filename !== undefined)
+                body.append("file", request.file, filename);
+            else
+                body.append("file", request.file);
+            body.append("model", model);
+            body.append("response_format", "json");
+            if (request.language !== undefined)
+                body.append("language", request.language);
+            if (request.prompt !== undefined)
+                body.append("prompt", request.prompt);
+            const response = await fetch(`${baseURL}/audio/transcriptions`, {
+                method: "POST",
+                headers,
+                body,
+                signal: request.signal,
+            }).catch((error) => {
+                request.signal?.throwIfAborted();
+                throw new Error(formatConnectionError(name, error));
+            });
+            if (!response.ok) {
+                const normalized = await normalizeHttpError(name, response);
+                request.signal?.throwIfAborted();
+                throw new Error(normalized.error);
+            }
+            const raw = await response.text();
+            let payload;
+            try {
+                payload = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`${name} returned invalid transcription JSON.`);
+            }
+            if (typeof payload !== "object" || payload === null
+                || !("text" in payload) || typeof payload.text !== "string") {
+                throw new Error(`${name} returned a transcription without a string text field.`);
+            }
+            return { text: payload.text };
+        },
+    };
+};

package/ai/transcription.d.ts

@@ -0,0 +1,18 @@
+export type TranscriptionRequest = {
+    file: Blob;
+    /** Override the file name, or supply one for an unnamed Blob. */
+    filename?: string;
+    /** ISO-639-1 language code, for example "de". Omit for automatic detection. */
+    language?: string;
+    /** Optional vocabulary or context hint, subject to model support. */
+    prompt?: string;
+    signal?: AbortSignal;
+};
+export type TranscriptionResult = {
+    text: string;
+};
+export type TranscriptionProvider = {
+    name: string;
+    model: string;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+};

package/index.d.ts

@@ -8,4 +8,4 @@ export { defineTool, toolToJsonSchema, toolToSpec } from "./tools.js";
 export { memoryStore } from "./stores.js";
 export { estimateTokens, truncateMiddle, truncateToolResults } from "./utils.js";
 export { cloneLoopAggregate, cloneUsage, mergeLoopAggregates, mergeUsage } from "./aggregates.js";
-export type { NessiOptions, NessiLoop, SteeringContext, SteeringFn, StructuredInput, StructuredMeta, StructuredMode, StructuredOptions, StructuredResult, ContentPart, JsonSchemaObject, Input, OutboundEvent, InboundEvent, DoneReason, LoopAggregate, LoopTimingAggregate, LoopTurnAggregate, LoopToolCallAggregate, LoopToolIssueAggregate, Message, UserMessage, AssistantMessage, AssistantStopReason, HistoricalToolResult, ToolResultMessage, AssistantContentBlock, TextBlock, ThinkingBlock, ToolCallBlock, ToolStreamIssue, ToolStreamIssueKind, ToolStreamIssueReason, ToolHistoricalResultIssue, Usage, ToolDefinition, HistoricalToolResultContext, ServerTool, ClientTool, Tool, ToolContext, Provider, ProviderRequest, ProviderEvent, ResponseFormat, StoreEntry, SessionStore, CompactFn, CompactContext, CompactOptions, CompactResult, CompactDoneReason, CompactEvent, CompactLoop, CreditStore, } from "./types.js";
+export type { NessiOptions, NessiLoop, SteeringContext, SteeringFn, StructuredInput, StructuredMeta, StructuredMode, StructuredOptions, StructuredResult, StructuredToolResolver, ContentPart, JsonSchemaObject, Input, OutboundEvent, InboundEvent, DoneReason, LoopAggregate, LoopTimingAggregate, LoopTurnAggregate, LoopToolCallAggregate, LoopToolIssueAggregate, Message, UserMessage, AssistantMessage, AssistantStopReason, HistoricalToolResult, ToolResultMessage, AssistantContentBlock, TextBlock, ThinkingBlock, ToolCallBlock, ToolStreamIssue, ToolStreamIssueKind, ToolStreamIssueReason, ToolHistoricalResultIssue, Usage, ToolDefinition, HistoricalToolResultContext, ServerTool, ClientTool, Tool, ToolResolver, ToolContext, Provider, ProviderRequest, ProviderEvent, ResponseFormat, StoreEntry, SessionStore, CompactFn, CompactContext, CompactOptions, CompactResult, CompactDoneReason, CompactEvent, CompactLoop, CreditStore, } from "./types.js";

package/nessi.js

@@ -5,6 +5,20 @@ import { aggregateFromTurns, buildLoopTiming, cloneUsage } from "./aggregates.js
 import { appendAssistantContentBlock, buildAssistantMessageFromContent } from "./ai/shared/messages.js";
 import { toolToSpec } from "./tools.js";
 import { createLoopId, projectHistoricalToolResults, toErrorMessage, truncateToolResults, zeroUsage, } from "./utils.js";
+const createToolSnapshot = (value) => {
+    if (!Array.isArray(value))
+        throw new Error("Tool resolver must return an array");
+    const tools = [...value];
+    const names = tools.map((tool) => tool.def.name);
+    if (new Set(names).size !== names.length) {
+        const duplicate = names.find((name, index) => names.indexOf(name) !== index);
+        throw new Error(`Duplicate tool name: ${duplicate}`);
+    }
+    return {
+        providerTools: tools.map(toolToSpec),
+        toolMap: new Map(tools.map((tool) => [tool.def.name, tool])),
+    };
+};
 class PullCancelledError extends Error {
     constructor() {
         super("channel pull cancelled");
@@ -320,7 +334,7 @@ const coalesceOutboundEvents = async function* (source, options) {
 // nessi()
 // ----------------------------------------------------------------------------
 export const nessi = (options) => {
-    const { agentId = "main", loopId: requestedLoopId, input, provider, systemPrompt, tools = [], store, creditStore, compact, steering, maxTurns = Infinity, temperature, maxOutputTokens, disableReasoning, coalesce, maxToolResultChars, signal: externalSignal, } = options;
+    const { agentId = "main", loopId: requestedLoopId, input, provider, systemPrompt, tools: toolSource = [], store, creditStore, compact, steering, maxTurns = Infinity, temperature, maxOutputTokens, disableReasoning, coalesce, maxToolResultChars, signal: externalSignal, } = options;
     const channel = createChannel();
     const deferredInbound = [];
     const steerQueue = [];
@@ -432,6 +446,9 @@ export const nessi = (options) => {
             externalSignal.addEventListener("abort", () => abortController.abort(), { once: true });
     }
     const signal = abortController.signal;
+    const toolResolver = typeof toolSource === "function" ? toolSource : undefined;
+    const staticToolSnapshot = toolResolver ? undefined : createToolSnapshot(toolSource);
+    const resolveToolSnapshot = async () => staticToolSnapshot ?? createToolSnapshot(await toolResolver());
     async function* applyPendingSteering() {
         const pending = steerQueue.splice(0);
         const supplied = await steering?.({ agentId, loopId, signal });
@@ -451,13 +468,6 @@ export const nessi = (options) => {
         }
         return applied;
     }
-    const names = tools.map((tool) => tool.def.name);
-    if (new Set(names).size !== names.length) {
-        const dup = names.find((name, index) => names.indexOf(name) !== index);
-        throw new Error(`Duplicate tool name: ${dup}`);
-    }
-    const toolMap = new Map(tools.map((tool) => [tool.def.name, tool]));
-    const isTerminalTool = (name) => Boolean(toolMap.get(name)?.def?.terminal);
     const appendToolResult = async (callId, name, result, isError = false) => {
         const msg = { role: "tool_result", callId, name, result, isError };
         await store.append(msg);
@@ -516,10 +526,10 @@ export const nessi = (options) => {
         toolExecutionMs: timing.toolExecutionMs,
         actionWaitMs: timing.actionWaitMs,
     }, usage);
-    async function* executeToolCall(tc, turnCtx, updateAggregateToolCall, turnIssues) {
+    async function* executeToolCall(tc, toolSnapshot, turnCtx, updateAggregateToolCall, turnIssues) {
         const eventFields = { agentId, loopId, ...turnCtx };
         yield { type: "tool_execution_start", ...eventFields, callId: tc.id, name: tc.name, args: tc.args };
-        const tool = toolMap.get(tc.name);
+        const tool = toolSnapshot.toolMap.get(tc.name);
         if (!tool) {
             yield* failToolCall(tc, turnCtx, updateAggregateToolCall, toolExecutionIssue("unknown_tool", `Unknown tool: ${tc.name}`, tc), turnIssues);
             return;
@@ -640,6 +650,7 @@ export const nessi = (options) => {
             let approvalCounter = 0;
             let clientToolCounter = 0;
             const ctx = {
+                callId: tc.id,
                 signal: toolAbort.signal,
                 requestApproval(message) {
                     return new Promise((resolve) => {
@@ -734,7 +745,7 @@ export const nessi = (options) => {
                 }
                 while (clientToolQueue.length > 0) {
                     const req = clientToolQueue.shift();
-                    const bridgeTool = toolMap.get(req.name);
+                    const bridgeTool = toolSnapshot.toolMap.get(req.name);
                     let requestArgs = req.args;
                     if (bridgeTool) {
                         if (bridgeTool.kind !== "client") {
@@ -872,6 +883,7 @@ export const nessi = (options) => {
         const pending = toolCallBlocks.filter((block) => !resolvedCallIds.has(block.id));
         if (pending.length === 0)
             return;
+        const toolSnapshot = await resolveToolSnapshot();
         const aggregateTurn = loopTurns.findLast((turn) => turn.message === assistantMessage);
         const aggregateToolCallMap = new Map((aggregateTurn?.toolCalls ?? []).map((toolCall) => [toolCall.callId, toolCall]));
         const updateAggregateToolCall = aggregateTurn
@@ -886,7 +898,7 @@ export const nessi = (options) => {
         for (const tc of pending) {
             if (signal.aborted)
                 return;
-            yield* executeToolCall(tc, turnCtx, updateAggregateToolCall, turnIssues);
+            yield* executeToolCall(tc, toolSnapshot, turnCtx, updateAggregateToolCall, turnIssues);
         }
         if (aggregateTurn && turnIssues.issues.length > 0) {
             aggregateTurn.issues = [...(aggregateTurn.issues ?? []), ...turnIssues.issues.map((issue) => ({ ...issue }))];
@@ -901,7 +913,6 @@ export const nessi = (options) => {
         let providerTurn = 0;
         let eventTurnIndex = 0;
         let compactionRetried = false;
-        const providerTools = tools.map(toolToSpec);
         const prepareProviderMessages = (sourceEntries) => {
             const rawMessages = sourceEntries.map((entry) => entry.message);
             const projectedMessages = projectHistoricalToolResults(rawMessages, loopId);
@@ -950,6 +961,8 @@ export const nessi = (options) => {
                     yield loopEndEvent("max_turns");
                     return;
                 }
+                const toolSnapshot = await resolveToolSnapshot();
+                const providerTools = toolSnapshot.providerTools;
                 let entries = await store.load();
                 let messages = prepareProviderMessages(entries);
                 const contextWindow = provider.contextWindow;
@@ -1168,9 +1181,10 @@ export const nessi = (options) => {
                 };
                 let terminalToolCompleted = false;
                 for (const tc of toolCalls) {
-                    yield* executeToolCall(tc, turnCtx, updateAggregateToolCall, turnIssues);
+                    yield* executeToolCall(tc, toolSnapshot, turnCtx, updateAggregateToolCall, turnIssues);
                     const aggregateToolCall = aggregateToolCallMap.get(tc.id);
-                    if (isTerminalTool(tc.name) && aggregateToolCall && !aggregateToolCall.isError) {
+                    const isTerminalTool = Boolean(toolSnapshot.toolMap.get(tc.name)?.def?.terminal);
+                    if (isTerminalTool && aggregateToolCall && !aggregateToolCall.isError) {
                         terminalToolCompleted = true;
                         break;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/nessi",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Minimal agent loop and provider adapters for nessi.",
   "main": "index.js",
   "module": "index.js",
@@ -16,6 +16,10 @@
       "import": "./ai/index.js",
       "types": "./ai/index.d.ts"
     },
+    "./ai/providers/openai-compatible-transcription": {
+      "import": "./ai/providers/openai-compatible-transcription.js",
+      "types": "./ai/providers/openai-compatible-transcription.d.ts"
+    },
     "./ai/providers/openai-compatible": {
       "import": "./ai/providers/openai-compatible.js",
       "types": "./ai/providers/openai-compatible.d.ts"

package/structured.js

@@ -220,6 +220,7 @@ const wrapStructuredTool = (tool) => ({
     def: tool.def,
     execute(input, ctx) {
         return tool.execute(input, {
+            callId: ctx.callId,
             signal: ctx.signal,
             async requestApproval() {
                 throw new Error("nessi.structured() does not support tool approvals. Use nessi() for interactive tools.");
@@ -324,8 +325,7 @@ const loopErrorCode = (reason) => {
     return "loop_failed";
 };
 const toolLoopStructured = async (options, inputMessage, jsonSchema, loopId) => {
-    const tools = options.tools ?? [];
-    validateStructuredTools(tools);
+    const toolSource = options.tools ?? [];
     let submitted;
     const submitDef = defineTool({
         name: SUBMIT_RESULT_TOOL_NAME,
@@ -338,6 +338,24 @@ const toolLoopStructured = async (options, inputMessage, jsonSchema, loopId) =>
         return { accepted: true };
     });
     submitTool.def.terminal = true;
+    let structuredToolError;
+    const prepareTools = (value) => {
+        if (!Array.isArray(value))
+            throw new Error("Structured tool resolver must return an array");
+        const tools = [...value];
+        try {
+            validateStructuredTools(tools);
+        }
+        catch (error) {
+            if (error instanceof StructuredOutputError)
+                structuredToolError = error;
+            throw error;
+        }
+        return [...tools.map(wrapStructuredTool), submitTool];
+    };
+    const tools = typeof toolSource === "function"
+        ? async () => prepareTools(await toolSource())
+        : prepareTools(toolSource);
     const store = memoryStore();
     await store.append(inputMessage);
     const loop = nessi({
@@ -352,7 +370,7 @@ const toolLoopStructured = async (options, inputMessage, jsonSchema, loopId) =>
             "Do not return the final structured result as normal assistant text.",
             schemaInstruction(jsonSchema, options.outputName),
         ].join("\n\n"),
-        tools: [...tools.map(wrapStructuredTool), submitTool],
+        tools,
         maxTurns: options.maxTurns ?? 8,
         temperature: options.temperature,
         maxOutputTokens: options.maxOutputTokens,
@@ -372,6 +390,11 @@ const toolLoopStructured = async (options, inputMessage, jsonSchema, loopId) =>
         throw new StructuredOutputError("Structured tool loop ended without loop_end.", "loop_failed");
     }
     if (loopEnd.reason !== "stop") {
+        if (structuredToolError) {
+            throw new StructuredOutputError(structuredToolError.message, structuredToolError.code, {
+                aggregate: loopEnd.aggregate,
+            });
+        }
         throw new StructuredOutputError(`Structured tool loop ended with reason: ${loopEnd.reason}`, loopErrorCode(loopEnd.reason), {
             aggregate: loopEnd.aggregate,
         });
@@ -406,7 +429,7 @@ export const structured = async (options) => {
     const loopId = options.loopId?.trim() ? options.loopId : createLoopId();
     const inputMessage = normalizeStructuredInput(options.input);
     const jsonSchema = schemaFor(options.output);
-    const hasTools = (options.tools?.length ?? 0) > 0;
+    const hasTools = typeof options.tools === "function" || (options.tools?.length ?? 0) > 0;
     if (hasTools)
         return toolLoopStructured(options, inputMessage, jsonSchema, loopId);
     return directStructured(options, inputMessage, jsonSchema, loopId);

package/types.d.ts

@@ -137,7 +137,10 @@ export type ClientTool<TInput extends z.ZodType = z.ZodType, TOutput extends z.Z
     execute(input: z.infer<TInput>): z.infer<TOutput> | Promise<z.infer<TOutput>>;
 };
 export type Tool = ServerTool | ClientTool;
+export type ToolResolver = () => Tool[] | Promise<Tool[]>;
 export type ToolContext = {
+    /** Provider-assigned ID of the tool call currently being executed. */
+    callId?: string;
     signal: AbortSignal;
     /** Request user approval mid-execution. Returns true if approved, false if denied. */
     requestApproval(message: string): Promise<boolean>;
@@ -158,7 +161,8 @@ export type NessiOptions = {
     input?: Input;
     provider: Provider;
     systemPrompt: string;
-    tools?: Tool[];
+    /** Static tools or a resolver evaluated once before every provider turn. */
+    tools?: Tool[] | ToolResolver;
     store: SessionStore;
     creditStore?: CreditStore;
     compact?: CompactFn;
@@ -198,6 +202,7 @@ export type StructuredMeta = {
     attempts: number;
     usedResponseFormat: boolean;
 };
+export type StructuredToolResolver = () => ServerTool[] | Promise<ServerTool[]>;
 export type StructuredOptions<TOutput extends z.ZodType = z.ZodType> = {
     agentId?: string;
     /** Correlates the internal structured task. Generated when omitted. */
@@ -207,7 +212,8 @@ export type StructuredOptions<TOutput extends z.ZodType = z.ZodType> = {
     input: StructuredInput;
     output: TOutput;
     outputName?: string;
-    tools?: ServerTool[];
+    /** Static server tools or a resolver evaluated once before every provider turn. */
+    tools?: ServerTool[] | StructuredToolResolver;
     maxTurns?: number;
     temperature?: number;
     maxOutputTokens?: number;