@k2b/nessi 0.10.0-rc.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@k2b/nessi",
+  "version": "0.10.0-rc.0",
+  "description": "Minimal agent loop and provider adapters for nessi.",
+  "main": "index.js",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    },
+    "./ai": {
+      "import": "./ai/index.js",
+      "types": "./ai/index.d.ts"
+    },
+    "./ai/providers/openai-compatible": {
+      "import": "./ai/providers/openai-compatible.js",
+      "types": "./ai/providers/openai-compatible.d.ts"
+    },
+    "./ai/providers/openai": {
+      "import": "./ai/providers/openai.js",
+      "types": "./ai/providers/openai.d.ts"
+    },
+    "./ai/providers/openrouter": {
+      "import": "./ai/providers/openrouter.js",
+      "types": "./ai/providers/openrouter.d.ts"
+    },
+    "./ai/providers/vllm": {
+      "import": "./ai/providers/vllm.js",
+      "types": "./ai/providers/vllm.d.ts"
+    },
+    "./ai/providers/ollama": {
+      "import": "./ai/providers/ollama.js",
+      "types": "./ai/providers/ollama.d.ts"
+    },
+    "./ai/providers/anthropic": {
+      "import": "./ai/providers/anthropic.js",
+      "types": "./ai/providers/anthropic.d.ts"
+    },
+    "./ai/providers/mistral": {
+      "import": "./ai/providers/mistral.js",
+      "types": "./ai/providers/mistral.d.ts"
+    },
+    "./ai/providers/gemini": {
+      "import": "./ai/providers/gemini.js",
+      "types": "./ai/providers/gemini.d.ts"
+    }
+  },
+  "files": [
+    "**/*"
+  ],
+  "keywords": [
+    "ai",
+    "llm",
+    "agent",
+    "tools",
+    "streaming",
+    "openai",
+    "openrouter",
+    "ollama",
+    "anthropic",
+    "gemini",
+    "mistral"
+  ],
+  "author": "Valentin Kolb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k2b-dev/nessi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.3.0"
+  }
+}

package/providers/ollama.d.ts

@@ -0,0 +1,2 @@
+export { ollama } from "../ai/providers/ollama.js";
+export type { OllamaOptions } from "../ai/providers/ollama.js";

package/providers/ollama.js

@@ -0,0 +1 @@
+export { ollama } from "../ai/providers/ollama.js";

package/providers/openai.d.ts

@@ -0,0 +1,2 @@
+export { openai } from "../ai/providers/openai.js";
+export type { OpenAIOptions } from "../ai/providers/openai.js";

package/providers/openai.js

@@ -0,0 +1 @@
+export { openai } from "../ai/providers/openai.js";

package/providers/openrouter.d.ts

@@ -0,0 +1,2 @@
+export { openrouter } from "../ai/providers/openrouter.js";
+export type { OpenRouterOptions } from "../ai/providers/openrouter.js";

package/providers/openrouter.js

@@ -0,0 +1 @@
+export { openrouter } from "../ai/providers/openrouter.js";

package/stores.d.ts

@@ -0,0 +1,11 @@
+import type { SessionStore } from "./types.js";
+/**
+ * In-memory SessionStore. For tests, prototyping, single-use sessions.
+ *
+ * Messages are never deleted. Summaries are inserted via append() with
+ * `{ kind: "summary" }`. load() returns entries from the last summary onward.
+ *
+ * Tiebreaker: at the same seq, "summary" sorts after "message" so that
+ * the summary replaces (not precedes) messages at that position.
+ */
+export declare const memoryStore: () => SessionStore;

package/stores.js

@@ -0,0 +1,42 @@
+// ============================================================================
+// nessi – Session Stores
+// ============================================================================
+/**
+ * In-memory SessionStore. For tests, prototyping, single-use sessions.
+ *
+ * Messages are never deleted. Summaries are inserted via append() with
+ * `{ kind: "summary" }`. load() returns entries from the last summary onward.
+ *
+ * Tiebreaker: at the same seq, "summary" sorts after "message" so that
+ * the summary replaces (not precedes) messages at that position.
+ */
+export const memoryStore = () => {
+    const entries = [];
+    let nextSeq = 1;
+    const sortEntries = () => {
+        entries.sort((a, b) => {
+            if (a.seq !== b.seq)
+                return a.seq - b.seq;
+            // summary after message at same seq
+            if (a.kind === "summary" && b.kind === "message")
+                return 1;
+            if (a.kind === "message" && b.kind === "summary")
+                return -1;
+            return 0;
+        });
+    };
+    return {
+        async load() {
+            const lastSummaryIdx = entries.findLastIndex(e => e.kind === "summary");
+            return lastSummaryIdx >= 0 ? entries.slice(lastSummaryIdx) : [...entries];
+        },
+        async append(message, opts) {
+            const seq = opts?.seq ?? nextSeq++;
+            const kind = opts?.kind ?? "message";
+            entries.push({ seq, kind, message });
+            sortEntries();
+            // Ensure nextSeq stays ahead
+            nextSeq = Math.max(nextSeq, seq + 1);
+        },
+    };
+};

package/structured.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import type { StructuredOptions, StructuredResult } from "./types.js";
+export type StructuredOutputErrorCode = "invalid_output" | "unsupported_tool" | "loop_failed" | "max_turns" | "aborted";
+export declare class StructuredOutputError extends Error {
+    readonly code: StructuredOutputErrorCode;
+    readonly details?: unknown;
+    constructor(message: string, code: StructuredOutputErrorCode, details?: unknown);
+}
+export declare const structured: <TOutput extends z.ZodType>(options: StructuredOptions<TOutput>) => Promise<StructuredResult<z.infer<TOutput>>>;

package/structured.js

@@ -0,0 +1,413 @@
+// ============================================================================
+// nessi.structured() - schema-valid task helper
+// ============================================================================
+import { z } from "zod";
+import { aggregateFromTurns, buildLoopTiming } from "./aggregates.js";
+import { extractAssistantText } from "./ai/shared/messages.js";
+import { nessi } from "./nessi.js";
+import { memoryStore } from "./stores.js";
+import { defineTool } from "./tools.js";
+import { createLoopId, toErrorMessage } from "./utils.js";
+const DEFAULT_SYSTEM_PROMPT = "You produce schema-valid structured data for the caller.";
+const SUBMIT_RESULT_TOOL_NAME = "submit_result";
+export class StructuredOutputError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = "StructuredOutputError";
+        this.code = code;
+        this.details = details;
+    }
+}
+const normalizeContentParts = (parts) => parts.map((part) => (typeof part === "string" ? { type: "text", text: part } : part));
+const normalizeStructuredInput = (input) => {
+    if (typeof input === "string")
+        return { role: "user", content: [{ type: "text", text: input }] };
+    if (Array.isArray(input))
+        return { role: "user", content: normalizeContentParts(input) };
+    return { role: "user", content: normalizeContentParts(input.content) };
+};
+const schemaFor = (schema) => stripJsonSchemaMetadata(z.toJSONSchema(schema, { target: "draft-07" }));
+const stripJsonSchemaMetadata = (value) => {
+    if (Array.isArray(value))
+        return value.map(stripJsonSchemaMetadata);
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "$schema")
+            continue;
+        out[key] = stripJsonSchemaMetadata(child);
+    }
+    return out;
+};
+const createResponseFormat = (schema, name) => ({
+    type: "json_schema",
+    name: name ?? "structured_output",
+    schema,
+});
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const hasUnsupportedComposition = (schema) => "anyOf" in schema || "oneOf" in schema || "allOf" in schema || "not" in schema;
+const isStrictNativeSchemaCompatible = (schema) => {
+    if (!isRecord(schema))
+        return false;
+    if (hasUnsupportedComposition(schema))
+        return false;
+    const type = schema.type;
+    if (type === "object") {
+        const properties = schema.properties;
+        const required = schema.required;
+        if (!isRecord(properties))
+            return true;
+        if (!Array.isArray(required))
+            return false;
+        for (const key of Object.keys(properties)) {
+            if (!required.includes(key))
+                return false;
+            if (!isStrictNativeSchemaCompatible(properties[key]))
+                return false;
+        }
+        return true;
+    }
+    if (type === "array") {
+        return schema.items === undefined || isStrictNativeSchemaCompatible(schema.items);
+    }
+    if (Array.isArray(type)) {
+        return type.every((entry) => typeof entry === "string" && ["string", "number", "integer", "boolean", "null"].includes(entry));
+    }
+    if (typeof type === "string") {
+        return ["string", "number", "integer", "boolean", "null"].includes(type);
+    }
+    return Array.isArray(schema.enum) || Object.prototype.hasOwnProperty.call(schema, "const");
+};
+const textFromMessage = (message) => extractAssistantText(message);
+const tryParseJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const findBalancedJson = (text) => {
+    let start = -1;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === "{" || char === "[") {
+            start = index;
+            break;
+        }
+    }
+    if (start < 0)
+        return undefined;
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < text.length; index++) {
+        const char = text[index];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === "\\") {
+                escaped = true;
+            }
+            else if (char === "\"") {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === "\"") {
+            inString = true;
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            stack.push(char === "{" ? "}" : "]");
+            continue;
+        }
+        if (char !== "}" && char !== "]")
+            continue;
+        const expected = stack.pop();
+        if (expected !== char)
+            return undefined;
+        if (stack.length === 0)
+            return text.slice(start, index + 1);
+    }
+    return undefined;
+};
+const extractJsonText = (raw) => {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)?.[1]?.trim();
+    if (fenced && tryParseJson(fenced) !== undefined)
+        return fenced;
+    if (tryParseJson(trimmed) !== undefined)
+        return trimmed;
+    return findBalancedJson(trimmed);
+};
+const parseStructuredOutput = (schema, raw) => {
+    const jsonText = extractJsonText(raw);
+    if (!jsonText) {
+        return { ok: false, message: "No JSON value was found in the assistant response." };
+    }
+    let json;
+    try {
+        json = JSON.parse(jsonText);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `Assistant response contained invalid JSON: ${toErrorMessage(error)}`,
+            jsonText,
+        };
+    }
+    const parsed = schema.safeParse(json);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            message: "Assistant response did not match the requested schema.",
+            details: parsed.error.issues,
+            jsonText,
+        };
+    }
+    return { ok: true, value: parsed.data, jsonText };
+};
+const schemaInstruction = (schema, outputName) => [
+    "Return exactly one JSON value that satisfies the following JSON Schema.",
+    "Do not wrap the JSON in markdown fences. Do not include explanatory text.",
+    outputName ? `Schema name: ${outputName}` : "",
+    JSON.stringify(schema, null, 2),
+].filter(Boolean).join("\n");
+const repairInstruction = (failure) => [
+    "The previous response did not match the requested structured output.",
+    failure.message,
+    failure.details ? JSON.stringify(failure.details, null, 2) : "",
+    "Return only corrected JSON that satisfies the schema.",
+].filter(Boolean).join("\n");
+const resultToTurn = (result) => {
+    const toolCalls = result.message.content
+        .filter((block) => block.type === "tool_call")
+        .map((block) => ({
+        callId: block.id,
+        name: block.name,
+        args: block.args,
+    }));
+    return {
+        message: result.message,
+        usage: result.usage,
+        stopReason: result.message.stopReason,
+        toolCalls,
+    };
+};
+const unsupportedToolError = (message) => new StructuredOutputError(message, "unsupported_tool");
+const validateStructuredTools = (tools) => {
+    for (const tool of tools) {
+        if (tool.kind !== "server") {
+            throw unsupportedToolError("nessi.structured() only accepts server tools. Use nessi() for client tools.");
+        }
+        if (tool.def.needsApproval) {
+            throw unsupportedToolError(`nessi.structured() does not support approval tools: ${tool.def.name}`);
+        }
+        if (tool.def.name === SUBMIT_RESULT_TOOL_NAME) {
+            throw unsupportedToolError(`Tool name "${SUBMIT_RESULT_TOOL_NAME}" is reserved by nessi.structured().`);
+        }
+    }
+};
+const wrapStructuredTool = (tool) => ({
+    kind: "server",
+    def: tool.def,
+    execute(input, ctx) {
+        return tool.execute(input, {
+            signal: ctx.signal,
+            async requestApproval() {
+                throw new Error("nessi.structured() does not support tool approvals. Use nessi() for interactive tools.");
+            },
+            async requestClientTool() {
+                throw new Error("nessi.structured() does not support client tool bridges. Use nessi() for interactive tools.");
+            },
+        });
+    },
+});
+const directStructured = async (options, inputMessage, jsonSchema, loopId) => {
+    const startedAt = Date.now();
+    let generationMs = 0;
+    const completeWithTiming = async (request) => {
+        const requestStartedAt = Date.now();
+        try {
+            return await options.provider.complete(request);
+        }
+        finally {
+            generationMs += Math.max(0, Date.now() - requestStartedAt);
+        }
+    };
+    const useResponseFormat = options.provider.capabilities.structuredOutput === true
+        && isStrictNativeSchemaCompatible(jsonSchema);
+    const responseFormat = useResponseFormat ? createResponseFormat(jsonSchema, options.outputName) : undefined;
+    const systemPrompt = useResponseFormat
+        ? (options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT)
+        : [
+            options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+            schemaInstruction(jsonSchema, options.outputName),
+        ].join("\n\n");
+    const attempts = [];
+    const first = await completeWithTiming({
+        systemPrompt,
+        messages: [inputMessage],
+        responseFormat,
+        temperature: options.temperature,
+        maxOutputTokens: options.maxOutputTokens,
+        disableReasoning: options.disableReasoning,
+        signal: options.signal,
+    });
+    attempts.push(first);
+    let parsed = parseStructuredOutput(options.output, textFromMessage(first.message));
+    if (!parsed.ok) {
+        const repair = await completeWithTiming({
+            systemPrompt: [
+                options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+                schemaInstruction(jsonSchema, options.outputName),
+            ].join("\n\n"),
+            messages: [
+                inputMessage,
+                first.message,
+                { role: "user", content: [{ type: "text", text: repairInstruction(parsed) }] },
+            ],
+            responseFormat,
+            temperature: options.temperature,
+            maxOutputTokens: options.maxOutputTokens,
+            disableReasoning: options.disableReasoning,
+            signal: options.signal,
+        });
+        attempts.push(repair);
+        parsed = parseStructuredOutput(options.output, textFromMessage(repair.message));
+    }
+    const aggregate = aggregateFromTurns(attempts.map(resultToTurn));
+    aggregate.timing = buildLoopTiming({
+        wallMs: Math.max(0, Date.now() - startedAt),
+        generationMs,
+        toolExecutionMs: 0,
+        actionWaitMs: 0,
+    }, aggregate.usage);
+    if (!parsed.ok) {
+        throw new StructuredOutputError("Provider returned invalid structured output.", "invalid_output", {
+            attempts: attempts.length,
+            failure: parsed,
+            aggregate,
+        });
+    }
+    const last = attempts[attempts.length - 1];
+    const repaired = attempts.length > 1;
+    const meta = {
+        mode: repaired ? "repair" : useResponseFormat ? "native" : "fallback",
+        repaired,
+        attempts: attempts.length,
+        usedResponseFormat: useResponseFormat,
+    };
+    return {
+        output: parsed.value,
+        message: last.message,
+        aggregate,
+        reason: "stop",
+        loopId,
+        usage: aggregate.usage,
+        providerMeta: last.providerMeta,
+        structuredMeta: meta,
+    };
+};
+const loopErrorCode = (reason) => {
+    if (reason === "max_turns")
+        return "max_turns";
+    if (reason === "aborted")
+        return "aborted";
+    return "loop_failed";
+};
+const toolLoopStructured = async (options, inputMessage, jsonSchema, loopId) => {
+    const tools = options.tools ?? [];
+    validateStructuredTools(tools);
+    let submitted;
+    const submitDef = defineTool({
+        name: SUBMIT_RESULT_TOOL_NAME,
+        description: "Submit the final structured result. Call this exactly once when the task is complete.",
+        inputSchema: options.output,
+        outputSchema: z.object({ accepted: z.literal(true) }),
+    });
+    const submitTool = submitDef.server(async (input) => {
+        submitted = input;
+        return { accepted: true };
+    });
+    submitTool.def.terminal = true;
+    const store = memoryStore();
+    await store.append(inputMessage);
+    const loop = nessi({
+        agentId: options.agentId,
+        loopId,
+        provider: options.provider,
+        store,
+        systemPrompt: [
+            options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+            "Use the available tools when needed.",
+            `When the final answer is ready, call ${SUBMIT_RESULT_TOOL_NAME} with the structured result.`,
+            "Do not return the final structured result as normal assistant text.",
+            schemaInstruction(jsonSchema, options.outputName),
+        ].join("\n\n"),
+        tools: [...tools.map(wrapStructuredTool), submitTool],
+        maxTurns: options.maxTurns ?? 8,
+        temperature: options.temperature,
+        maxOutputTokens: options.maxOutputTokens,
+        disableReasoning: options.disableReasoning,
+        signal: options.signal,
+    });
+    let loopEnd;
+    let message;
+    for await (const event of loop) {
+        options.onEvent?.(event);
+        if (event.type === "turn_end")
+            message = event.message;
+        if (event.type === "loop_end")
+            loopEnd = event;
+    }
+    if (!loopEnd) {
+        throw new StructuredOutputError("Structured tool loop ended without loop_end.", "loop_failed");
+    }
+    if (loopEnd.reason !== "stop") {
+        throw new StructuredOutputError(`Structured tool loop ended with reason: ${loopEnd.reason}`, loopErrorCode(loopEnd.reason), {
+            aggregate: loopEnd.aggregate,
+        });
+    }
+    if (submitted === undefined) {
+        throw new StructuredOutputError("Structured tool loop ended without a submitted result.", "invalid_output", {
+            aggregate: loopEnd.aggregate,
+        });
+    }
+    const lastMessage = message ?? loopEnd.aggregate.turns.at(-1)?.message;
+    if (!lastMessage) {
+        throw new StructuredOutputError("Structured tool loop ended without an assistant message.", "loop_failed", {
+            aggregate: loopEnd.aggregate,
+        });
+    }
+    return {
+        output: submitted,
+        message: lastMessage,
+        aggregate: loopEnd.aggregate,
+        reason: loopEnd.reason,
+        loopId,
+        usage: loopEnd.aggregate.usage,
+        structuredMeta: {
+            mode: "tool_loop",
+            repaired: loopEnd.aggregate.toolErrorCount > 0,
+            attempts: loopEnd.aggregate.assistantMessageCount,
+            usedResponseFormat: false,
+        },
+    };
+};
+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;
+    if (hasTools)
+        return toolLoopStructured(options, inputMessage, jsonSchema, loopId);
+    return directStructured(options, inputMessage, jsonSchema, loopId);
+};

package/tools.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { ToolDefinition, ServerTool, ClientTool } from "./types.js";
+export declare const defineTool: <TInput extends z.ZodType, TOutput extends z.ZodType = z.ZodAny>(config: {
+    name: string;
+    description: string;
+    inputSchema: TInput;
+    outputSchema?: TOutput;
+    needsApproval?: boolean;
+    timeoutMs?: number | false;
+    toHistoricalResult?: (context: {
+        input: z.infer<TInput>;
+        output: z.infer<TOutput>;
+        callId: string;
+    }) => unknown | Promise<unknown>;
+}) => ToolDefinition<TInput, TOutput>;
+export declare const toolToJsonSchema: (tool: ServerTool | ClientTool) => {
+    name: string;
+    description: string;
+    parameters: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
+export declare const toolToSpec: (tool: ServerTool | ClientTool) => {
+    name: string;
+    description: string;
+    inputSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};

package/tools.js

@@ -0,0 +1,36 @@
+// ============================================================================
+// nessi – Tool Definitions
+// ============================================================================
+import { z } from "zod";
+// ----------------------------------------------------------------------------
+// defineTool()
+// ----------------------------------------------------------------------------
+export const defineTool = (config) => {
+    const def = {
+        ...config,
+        needsApproval: config.needsApproval ?? false,
+        server(execute) {
+            return { kind: "server", def, execute };
+        },
+        client(execute) {
+            return { kind: "client", def, execute };
+        },
+    };
+    return def;
+};
+// ----------------------------------------------------------------------------
+// Tool → JSON Schema (for provider adapters)
+// ----------------------------------------------------------------------------
+export const toolToJsonSchema = (tool) => ({
+    name: tool.def.name,
+    description: tool.def.description,
+    parameters: z.toJSONSchema(tool.def.inputSchema, { target: "draft-07" }),
+});
+export const toolToSpec = (tool) => {
+    const schema = toolToJsonSchema(tool);
+    return {
+        name: schema.name,
+        description: schema.description,
+        inputSchema: schema.parameters,
+    };
+};