@k2b/nessi 0.10.0-rc.0 → 0.11.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

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-rc.0",
+  "version": "0.11.0",
   "description": "Minimal agent loop and provider adapters for nessi.",
   "main": "index.js",
   "module": "index.js",

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;