@k2b/nessi 0.10.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ValentinKolb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# @k2b/nessi
+
+Minimal agent loop and provider adapters for TypeScript.
+
+Use the package root for the managed `nessi()` loop with tools, storage, and loop metadata. Use `@k2b/nessi/ai` when an app only needs provider calls through one normalized message and stream API.
+
+`@k2b/nessi` replaces the deprecated `@valentinkolb/nessi` package. Existing
+APIs and subpaths are unchanged; replace the package scope in dependencies and
+imports.
+
+## Quick start
+
+```bash
+bun add @k2b/nessi
+```
+
+```ts
+import { nessi, defineTool, memoryStore } from "@k2b/nessi";
+import { ollama } from "@k2b/nessi/ai";
+import { z } from "zod";
+
+const weather = defineTool({
+  name: "weather",
+  description: "Return a fake weather response",
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => {
+  return { city, forecast: "sunny" };
+});
+
+const loop = nessi({
+  loopId: crypto.randomUUID(),
+  provider: ollama("llama3.1", {
+    baseURL: "http://localhost:11434",
+  }),
+  systemPrompt: "You are concise.",
+  input: "How is the weather in Berlin?",
+  store: memoryStore(),
+  tools: [weather],
+  temperature: 0,
+  maxOutputTokens: 512,
+});
+
+const textBlocks = new Set<string>();
+
+for await (const event of loop) {
+  if (event.type === "block_start" && event.kind === "text") {
+    textBlocks.add(event.blockId);
+  }
+  if (event.type === "block_delta" && textBlocks.has(event.blockId)) {
+    process.stdout.write(event.delta);
+  }
+  if (event.type === "issue") {
+    console.error(event.issue.kind, event.issue.message);
+  }
+  if (event.type === "loop_end") {
+    console.log(event.loopId);
+    console.log(event.aggregate.usage);
+    console.log(event.aggregate.timing);
+  }
+}
+```
+
+Every outbound event from one `nessi()` run carries the same `loopId`. Pass your own `loopId` to align events with a persisted request or UI response group, or let Nessi generate one when omitted.
+
+`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`.
+
+## Historical tool results
+
+Verbose tool output can remain fully persisted without being sent to the model
+in every later loop. A tool may derive a compact historical representation once
+after its output passes validation:
+
+```ts
+const shell = defineTool({
+  name: "shell",
+  description: "Run a shell command.",
+  inputSchema: z.object({ command: z.string() }),
+  outputSchema: z.object({
+    exitCode: z.number(),
+    stdout: z.string(),
+    changedFiles: z.array(z.string()),
+  }),
+  toHistoricalResult: ({ output }) => ({
+    exitCode: output.exitCode,
+    changedFiles: output.changedFiles,
+    excerpt: output.stdout.slice(0, 500),
+  }),
+}).server(runShell);
+```
+
+Nessi persists the full `result` and the optional `historicalResult` together.
+Provider calls in the originating loop, including resumes with the same
+`loopId`, receive the full result. Calls from a different loop receive the
+historical value instead. Stored messages, events, and loop aggregates remain
+full and inspectable. Returning `undefined` skips the historical representation.
+
+If derivation throws, Nessi stores the full successful result, emits a non-fatal
+`tool_historical_result_error` issue, and continues the loop. Legacy messages
+without `historicalResult` remain unchanged. `maxToolResultChars`, when set,
+runs after this selection as the final context-size boundary.
+
+## Steering
+
+Use `loop.steer()` when the process handling new input owns the running loop:
+
+```ts
+loop.steer("Skip deployment and only prepare the migration.");
+```
+
+For loops running in another worker or process, provide a `steering` callback
+that reads pending messages from application-owned persistence:
+
+```ts
+const loop = nessi({
+  provider,
+  systemPrompt,
+  store,
+  input,
+  tools,
+  steering: ({ loopId, signal }) => steeringQueue.takePending(loopId, { signal }),
+});
+```
+
+The callback may return one message, an ordered array, or `undefined`. Nessi
+checks it before provider calls and before a normal loop completion. Applied
+messages are persisted as user messages and emit the same `steer_applied`
+event as `loop.steer()`. The application owns persistence, claiming, and
+delivery semantics; Nessi only controls when steering can affect the loop.
+
+## Structured output
+
+Use `nessi.structured()` when an app wants a schema-valid typed result instead
+of a streamed chat response:
+
+```ts
+import { nessi } from "@k2b/nessi";
+import { openrouter } from "@k2b/nessi/ai";
+import { z } from "zod";
+
+const result = await nessi.structured({
+  provider: openrouter("openai/gpt-4.1-mini", {
+    apiKey: process.env.OPENROUTER_API_KEY,
+  }),
+  input: "Extract a task card for: Ship the onboarding flow by Friday.",
+  outputName: "task_card",
+  output: z.object({
+    title: z.string(),
+    due: z.string().nullable(),
+    priority: z.enum(["low", "medium", "high"]),
+  }),
+  temperature: 0,
+});
+
+console.log(result.output.title);
+console.log(result.structuredMeta);
+console.log(result.aggregate.usage);
+```
+
+For providers and schemas that are safe for native structured output, Nessi
+passes a provider-specific `responseFormat`. Otherwise it falls back to schema
+instructions and one repair attempt. `input` can be a string, content parts, or
+a full user message, including image file parts when the provider supports
+images.
+
+`nessi.structured()` can use server tools for bounded task work. It adds an
+internal `submit_result` tool and returns after that tool receives a valid
+schema value. Client tools, approval tools, and interactive tool bridges remain
+the job of the full `nessi()` loop.
+
+## Provider-only usage
+
+```ts
+import { openrouter } from "@k2b/nessi/ai";
+
+const provider = openrouter("openai/gpt-4.1-mini", {
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+const result = await provider.complete({
+  systemPrompt: "Be concise.",
+  messages: [
+    {
+      role: "user",
+      content: [{ type: "text", text: "Summarize this package." }],
+    },
+  ],
+});
+
+console.log(result.message.content);
+```
+
+Provider streams use the same block events as the root loop:
+
+```ts
+const textBlocks = new Set<string>();
+
+for await (const event of provider.stream({ messages })) {
+  if (event.type === "block_start" && event.kind === "text") {
+    textBlocks.add(event.blockId);
+  }
+  if (event.type === "block_delta" && textBlocks.has(event.blockId)) {
+    process.stdout.write(event.delta);
+  }
+  if (event.type === "block_end" && event.block.type === "tool_call") {
+    console.log("tool call", event.block.name, event.block.args);
+  }
+  if (event.type === "issue") {
+    console.error(event.issue.kind, event.issue.message);
+  }
+}
+```
+
+## Focused provider imports
+
+```ts
+import { anthropic } from "@k2b/nessi/ai/providers/anthropic";
+import { openai } from "@k2b/nessi/ai/providers/openai";
+```
+
+## Features
+
+- Turn-based agent loop with canonical block streaming events
+- Stable `loopId` correlation across all events from one agent loop
+- `loop_start`, `turn_start`, `turn_end`, and `loop_end.aggregate` for logical response grouping
+- Local `loop.steer()` and optional `steering` callbacks for steering at safe loop boundaries
+- Loop timing metadata for wall time, generation time, active tool time, action wait time, and output tokens/second
+- `nessi.structured()` for typed schema-valid task results
+- Server tools and client tools
+- Tool approval flow and explicit `tool_action_request` events
+- Tool execution start/end events with per-tool `timeoutMs`
+- Optional per-tool historical result representations for bounded future context
+- Structured `issue` events for provider errors, timeouts, malformed tool streams, and tool execution failures
+- Pluggable session store
+- Optional history compaction
+- 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
+- Native adapters for OpenAI, OpenRouter, vLLM, Ollama, Anthropic, Mistral, and Gemini
+
+## Package layout
+
+```txt
+@k2b/nessi
+  Agent loop, structured task helper, tools, stores, compaction, shared types
+
+@k2b/nessi/ai
+  Provider factories, provider types, complete(), stream(), responseFormat
+
+@k2b/nessi/ai/providers/*
+  Focused provider entrypoints
+```

package/aggregates.d.ts

@@ -0,0 +1,7 @@
+import type { LoopAggregate, LoopIssueAggregate, LoopTimingAggregate, LoopTurnAggregate, Usage } from "./types.js";
+export declare const cloneUsage: (usage: Usage | undefined) => Usage | undefined;
+export declare const mergeUsage: (left: Usage | undefined, right: Usage | undefined) => Usage | undefined;
+export declare const buildLoopTiming: (timing: Pick<LoopTimingAggregate, "wallMs" | "generationMs" | "toolExecutionMs" | "actionWaitMs">, usage: Usage | undefined) => LoopTimingAggregate;
+export declare const aggregateFromTurns: (turns: LoopTurnAggregate[], loopIssues?: LoopIssueAggregate[], timing?: LoopTimingAggregate) => LoopAggregate;
+export declare const cloneLoopAggregate: (aggregate: LoopAggregate) => LoopAggregate;
+export declare const mergeLoopAggregates: (left: LoopAggregate | undefined, right: LoopAggregate | undefined) => LoopAggregate | undefined;

package/aggregates.js

@@ -0,0 +1,115 @@
+// ============================================================================
+// nessi - Loop aggregate helpers
+// ============================================================================
+export const cloneUsage = (usage) => usage ? { ...usage } : undefined;
+export const mergeUsage = (left, right) => {
+    if (!right)
+        return cloneUsage(left);
+    const next = {
+        input: (left?.input ?? 0) + right.input,
+        output: (left?.output ?? 0) + right.output,
+        total: (left?.total ?? 0) + right.total,
+    };
+    if (left?.cacheRead !== undefined || right.cacheRead !== undefined) {
+        next.cacheRead = (left?.cacheRead ?? 0) + (right.cacheRead ?? 0);
+    }
+    if (left?.creditsUsed !== undefined || right.creditsUsed !== undefined) {
+        next.creditsUsed = (left?.creditsUsed ?? 0) + (right.creditsUsed ?? 0);
+    }
+    return next;
+};
+const cloneToolCall = (toolCall) => ({ ...toolCall });
+const cloneToolIssue = (toolIssue) => ({ ...toolIssue });
+const cloneIssue = (issue) => ({ ...issue });
+const cloneTiming = (timing) => timing
+    ? {
+        ...timing,
+        totalElapsedMs: timing.totalElapsedMs ?? timing.generationMs + timing.toolExecutionMs,
+    }
+    : undefined;
+const outputTokensPerSecond = (usage, generationMs) => {
+    if (!usage || usage.output <= 0 || generationMs <= 0)
+        return undefined;
+    return usage.output / (generationMs / 1000);
+};
+export const buildLoopTiming = (timing, usage) => {
+    const snapshot = {
+        ...timing,
+        totalElapsedMs: timing.generationMs + timing.toolExecutionMs,
+    };
+    const throughput = outputTokensPerSecond(usage, timing.generationMs);
+    if (throughput !== undefined)
+        snapshot.outputTokensPerSecond = throughput;
+    return snapshot;
+};
+const mergeTiming = (left, right, usage) => {
+    if (!left && !right)
+        return undefined;
+    const generationMs = (left?.generationMs ?? 0) + (right?.generationMs ?? 0);
+    return buildLoopTiming({
+        wallMs: (left?.wallMs ?? 0) + (right?.wallMs ?? 0),
+        generationMs,
+        toolExecutionMs: (left?.toolExecutionMs ?? 0) + (right?.toolExecutionMs ?? 0),
+        actionWaitMs: (left?.actionWaitMs ?? 0) + (right?.actionWaitMs ?? 0),
+    }, usage);
+};
+const toolIssuesFromAggregate = (aggregate) => (aggregate.toolIssues ?? aggregate.turns.flatMap((turn) => turn.toolIssues ?? [])).map(cloneToolIssue);
+const issuesFromAggregate = (aggregate) => (aggregate.issues ?? aggregate.toolIssues ?? aggregate.turns.flatMap((turn) => turn.issues ?? turn.toolIssues ?? []))
+    .map(cloneIssue);
+const cloneTurn = (turn) => ({
+    ...turn,
+    usage: cloneUsage(turn.usage),
+    toolCalls: turn.toolCalls.map(cloneToolCall),
+    ...(turn.toolIssues ? { toolIssues: turn.toolIssues.map(cloneToolIssue) } : {}),
+    ...(turn.issues ? { issues: turn.issues.map(cloneIssue) } : {}),
+});
+export const aggregateFromTurns = (turns, loopIssues = [], timing) => {
+    const clonedTurns = turns.map(cloneTurn);
+    const issues = loopIssues.length > 0
+        ? loopIssues.map(cloneIssue)
+        : clonedTurns.flatMap((turn) => turn.issues ?? turn.toolIssues ?? []);
+    const toolIssues = issues.filter((issue) => issue.kind === "malformed_tool_call" || issue.kind === "cancelled_tool_call");
+    const usage = clonedTurns.reduce((mergedUsage, turn) => mergeUsage(mergedUsage, turn.usage), undefined);
+    return {
+        turns: clonedTurns,
+        usage,
+        ...(timing ? { timing: cloneTiming(timing) } : {}),
+        issueCount: issues.length,
+        issues: issues.map(cloneIssue),
+        toolCallCount: clonedTurns.reduce((count, turn) => count + turn.toolCalls.length, 0),
+        toolErrorCount: clonedTurns.reduce((count, turn) => count + turn.toolCalls.filter((toolCall) => toolCall.isError).length, 0),
+        toolIssueCount: toolIssues.length,
+        toolMalformedCount: toolIssues.filter((issue) => issue.kind === "malformed_tool_call").length,
+        toolCancelledCount: toolIssues.filter((issue) => issue.kind === "cancelled_tool_call").length,
+        toolIssues: toolIssues.map(cloneToolIssue),
+        assistantMessageCount: clonedTurns.length,
+    };
+};
+export const cloneLoopAggregate = (aggregate) => {
+    const turns = aggregate.turns.map(cloneTurn);
+    const issues = issuesFromAggregate(aggregate);
+    const toolIssues = toolIssuesFromAggregate(aggregate);
+    return {
+        turns,
+        usage: cloneUsage(aggregate.usage),
+        ...(aggregate.timing ? { timing: cloneTiming(aggregate.timing) } : {}),
+        issueCount: aggregate.issueCount ?? issues.length,
+        issues,
+        toolCallCount: aggregate.toolCallCount,
+        toolErrorCount: aggregate.toolErrorCount,
+        toolIssueCount: aggregate.toolIssueCount ?? toolIssues.length,
+        toolMalformedCount: aggregate.toolMalformedCount ?? toolIssues.filter((issue) => issue.kind === "malformed_tool_call").length,
+        toolCancelledCount: aggregate.toolCancelledCount ?? toolIssues.filter((issue) => issue.kind === "cancelled_tool_call").length,
+        toolIssues,
+        assistantMessageCount: aggregate.assistantMessageCount,
+    };
+};
+export const mergeLoopAggregates = (left, right) => {
+    if (!left)
+        return right ? cloneLoopAggregate(right) : undefined;
+    if (!right)
+        return cloneLoopAggregate(left);
+    const merged = aggregateFromTurns([...left.turns, ...right.turns], [...issuesFromAggregate(left), ...issuesFromAggregate(right)]);
+    const timing = mergeTiming(left.timing, right.timing, merged.usage);
+    return timing ? { ...merged, timing } : merged;
+};

package/ai/complete-from-stream.d.ts

@@ -0,0 +1,2 @@
+import type { GenerateRequest, GenerateResult, Provider } from "./types.js";
+export declare const completeFromStream: (provider: Pick<Provider, "model" | "stream">, request: GenerateRequest) => Promise<GenerateResult>;

package/ai/complete-from-stream.js

@@ -0,0 +1,36 @@
+import { appendAssistantContentBlock, buildAssistantMessageFromContent } from "./shared/messages.js";
+export const completeFromStream = async (provider, request) => {
+    let usage;
+    let finishReason;
+    const content = [];
+    const toolCalls = [];
+    for await (const event of provider.stream(request)) {
+        switch (event.type) {
+            case "block_start":
+            case "block_delta":
+                break;
+            case "block_end":
+                if (event.block.type === "tool_call")
+                    toolCalls.push(event.block);
+                appendAssistantContentBlock(content, event.block);
+                break;
+            case "issue":
+                if (event.issue.kind === "provider_error")
+                    throw new Error(event.issue.message);
+                if (event.issue.kind === "timeout" && event.issue.scope !== "tool")
+                    throw new Error(event.issue.message);
+                break;
+            case "usage":
+                usage = event.usage;
+                finishReason = event.finishReason ?? finishReason;
+                break;
+        }
+    }
+    finishReason ??= toolCalls.length > 0 ? "tool_use" : "stop";
+    return {
+        message: buildAssistantMessageFromContent(provider.model, content, usage, finishReason),
+        usage,
+        finishReason,
+        providerMeta: { model: provider.model },
+    };
+};

package/ai/index.d.ts

@@ -0,0 +1,10 @@
+export { completeFromStream } from "./complete-from-stream.js";
+export { openAICompatible } from "./providers/openai-compatible.js";
+export { openai } from "./providers/openai.js";
+export { openrouter } from "./providers/openrouter.js";
+export { vllm } from "./providers/vllm.js";
+export { ollama } from "./providers/ollama.js";
+export { anthropic } from "./providers/anthropic.js";
+export { mistral } from "./providers/mistral.js";
+export { gemini } from "./providers/gemini.js";
+export type { AssistantBlockKind, AssistantContentBlock, AssistantMessage, AssistantStopReason, BlockDeltaEvent, BlockEndEvent, BlockStartEvent, ContentPart, GenerateRequest, GenerateResult, HistoricalToolResult, InputFilePart, JsonSchemaObject, Message, NessiIssue, Provider, ProviderCapabilities, ProviderFamily, ProviderIssue, ProviderTimeouts, RuntimeIssue, ResponseFormat, StreamEvent, TextBlock, ThinkingBlock, ToolCallBlock, ToolExecutionIssue, ToolHistoricalResultIssue, ToolResultMessage, ToolStreamIssue, ToolStreamIssueKind, ToolStreamIssueReason, ToolSpec, TimeoutIssue, Usage, UserMessage, OpenAICompat, OpenAICompatibleConfig, } from "./types.js";

package/ai/index.js

@@ -0,0 +1,9 @@
+export { completeFromStream } from "./complete-from-stream.js";
+export { openAICompatible } from "./providers/openai-compatible.js";
+export { openai } from "./providers/openai.js";
+export { openrouter } from "./providers/openrouter.js";
+export { vllm } from "./providers/vllm.js";
+export { ollama } from "./providers/ollama.js";
+export { anthropic } from "./providers/anthropic.js";
+export { mistral } from "./providers/mistral.js";
+export { gemini } from "./providers/gemini.js";

package/ai/providers/anthropic.d.ts

@@ -0,0 +1,13 @@
+import type { Provider, ProviderTimeouts } from "../types.js";
+export type AnthropicOptions = {
+    apiKey?: string;
+    baseURL?: string;
+    apiVersion?: string;
+    contextWindow?: number;
+    temperature?: number;
+    maxOutputTokens?: number;
+    creditsPerInputToken?: number;
+    creditsPerOutputToken?: number;
+    timeouts?: ProviderTimeouts;
+};
+export declare const anthropic: (model: string, options?: AnthropicOptions) => Provider;