@haikeilabs/agentware 0.1.0 → 0.1.1

package/dist/executor/agent_loop.d.ts

@@ -0,0 +1,41 @@
+import type { AsyncBackend, Message, ToolDefinition } from "../llm/index.js";
+import type { ToolRegistry } from "../tools/index.js";
+import type { ResponseValidator } from "../middleware/guardrails/response_validator.js";
+import { ErrorTracker, ErrorCategory } from "../middleware/guardrails/error_tracker.js";
+import { StepEnforcer } from "../middleware/guardrails/step_enforcer.js";
+export declare enum AgentTerminationReason {
+    COMPLETE = "complete",
+    MAX_ITERATIONS = "max_iterations",
+    NUDGES_EXHAUSTED = "nudges_exhausted",
+    ERROR = "error"
+}
+export interface AgentLoopConfig {
+    backend: AsyncBackend;
+    registry: ToolRegistry;
+    validator: ResponseValidator;
+    error_tracker?: ErrorTracker;
+    step_enforcer?: StepEnforcer;
+    max_iterations?: number;
+    max_nudges?: number;
+    require_tool_call?: boolean;
+}
+export interface AgentResult {
+    final_response: string;
+    iterations: number;
+    tool_calls_made: number;
+    nudges: number;
+    termination_reason: AgentTerminationReason;
+    conversation: Message[];
+}
+export declare function registryToolDefinitions(registry: ToolRegistry): ToolDefinition[];
+export declare function categorizeError(message: string): ErrorCategory;
+export declare class AgentLoop {
+    private readonly config;
+    private readonly maxIterations;
+    private readonly maxNudges;
+    constructor(config: AgentLoopConfig);
+    run(system_prompt: string, user_message: string, history?: Message[], session_id?: string): Promise<AgentResult>;
+    private validate;
+    private finish;
+}
+//# sourceMappingURL=agent_loop.d.ts.map

package/dist/executor/agent_loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_loop.d.ts","sourceRoot":"","sources":["../../src/executor/agent_loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,YAAY,EACZ,aAAa,EACd,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAQzE,oBAAY,sBAAsB;IAChC,QAAQ,aAAa;IACrB,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;IACrC,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,sBAAsB,CAAC;IAC3C,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CASlB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CA0B9D;AAiBD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,eAAe;IAU7B,GAAG,CACP,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,OAAO,EAAO,EACvB,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,WAAW,CAAC;IAsLvB,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,MAAM;CAiBf"}

package/dist/executor/agent_loop.js

@@ -0,0 +1,206 @@
+import { Role } from "../llm/index.js";
+import { executeTool, Result } from "../tools/index.js";
+import { ErrorCategory, } from "../middleware/guardrails/error_tracker.js";
+import { NudgeKind, stepNudge, } from "../middleware/guardrails/nudge.js";
+import { MessageType } from "../middleware/types.js";
+export var AgentTerminationReason;
+(function (AgentTerminationReason) {
+    AgentTerminationReason["COMPLETE"] = "complete";
+    AgentTerminationReason["MAX_ITERATIONS"] = "max_iterations";
+    AgentTerminationReason["NUDGES_EXHAUSTED"] = "nudges_exhausted";
+    AgentTerminationReason["ERROR"] = "error";
+})(AgentTerminationReason || (AgentTerminationReason = {}));
+export function registryToolDefinitions(registry) {
+    return registry.all().map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: "inputSchema" in tool
+            ? tool.inputSchema()
+            : {},
+    }));
+}
+export function categorizeError(message) {
+    const m = message.toLowerCase();
+    if (m.includes("timeout") || m.includes("timed out")) {
+        return ErrorCategory.TIMEOUT;
+    }
+    if (m.includes("not found") || m.includes("unknown tool")) {
+        return ErrorCategory.NOT_FOUND;
+    }
+    if (m.includes("invalid arg") ||
+        m.includes("schema") ||
+        m.includes("validation")) {
+        return ErrorCategory.INVALID_ARGS;
+    }
+    if (m.includes("permission") ||
+        m.includes("denied") ||
+        m.includes("forbidden")) {
+        return ErrorCategory.PERMISSION;
+    }
+    if (m.includes("rate limit") || m.includes("rate_limit")) {
+        return ErrorCategory.RATE_LIMIT;
+    }
+    return ErrorCategory.UNKNOWN;
+}
+function nudgeMetaType(kind) {
+    switch (kind) {
+        case NudgeKind.STEP:
+            return MessageType.STEP_NUDGE;
+        case NudgeKind.PREREQUISITE:
+            return MessageType.PREREQUISITE_NUDGE;
+        default:
+            return MessageType.RETRY_NUDGE;
+    }
+}
+function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+export class AgentLoop {
+    config;
+    maxIterations;
+    maxNudges;
+    constructor(config) {
+        this.config = config;
+        this.maxIterations =
+            config.max_iterations && config.max_iterations > 0
+                ? config.max_iterations
+                : 20;
+        this.maxNudges =
+            config.max_nudges && config.max_nudges > 0 ? config.max_nudges : 3;
+    }
+    async run(system_prompt, user_message, history = [], session_id = "") {
+        const conversation = [...history];
+        conversation.push({ role: Role.SYSTEM, content: system_prompt });
+        conversation.push({ role: Role.USER, content: user_message });
+        const toolDefs = registryToolDefinitions(this.config.registry);
+        let iterations = 0;
+        let toolCallsMade = 0;
+        let nudges = 0;
+        let finalResponse = "";
+        while (iterations < this.maxIterations) {
+            iterations++;
+            let resp;
+            try {
+                resp = await this.config.backend.complete(conversation, toolDefs);
+            }
+            catch (err) {
+                this.config.error_tracker?.recordError(session_id, "", {}, toError(err), ErrorCategory.UNKNOWN);
+                return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.ERROR, conversation);
+            }
+            const validation = this.validate(resp);
+            if (validation.needsRetry) {
+                if (nudges >= this.maxNudges) {
+                    return this.finish(resp.content, iterations, toolCallsMade, nudges, AgentTerminationReason.NUDGES_EXHAUSTED, conversation);
+                }
+                nudges++;
+                conversation.push({
+                    role: Role.ASSISTANT,
+                    content: resp.content,
+                    meta: { type: MessageType.TEXT_RESPONSE },
+                });
+                if (validation.nudge) {
+                    conversation.push({
+                        role: Role.USER,
+                        content: validation.nudge.content,
+                        meta: { type: nudgeMetaType(validation.nudge.kind) },
+                    });
+                }
+                continue;
+            }
+            if (validation.toolCalls.length === 0) {
+                finalResponse = resp.content;
+                return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.COMPLETE, conversation);
+            }
+            let stepNudged = false;
+            for (const call of validation.toolCalls) {
+                if (this.config.step_enforcer) {
+                    const [allowed, missing] = this.config.step_enforcer.canExecute(session_id, call.tool);
+                    if (!allowed) {
+                        if (nudges >= this.maxNudges) {
+                            return this.finish(resp.content, iterations, toolCallsMade, nudges, AgentTerminationReason.NUDGES_EXHAUSTED, conversation);
+                        }
+                        nudges++;
+                        stepNudged = true;
+                        const nudge = stepNudge(call.tool, missing, Math.min(3, nudges));
+                        conversation.push({
+                            role: Role.USER,
+                            content: nudge.content,
+                            meta: { type: MessageType.STEP_NUDGE },
+                        });
+                        continue;
+                    }
+                }
+                if (this.config.error_tracker &&
+                    this.config.error_tracker.shouldBlockTool(session_id, call.tool)) {
+                    conversation.push({
+                        role: Role.TOOL,
+                        content: `Tool ${call.tool} error: blocked after repeated errors`,
+                        meta: { type: MessageType.TOOL_RESULT },
+                    });
+                    continue;
+                }
+                const tool = this.config.registry.get(call.tool);
+                if (!tool) {
+                    conversation.push({
+                        role: Role.TOOL,
+                        content: `Tool ${call.tool} error: unknown tool`,
+                        meta: { type: MessageType.TOOL_RESULT },
+                    });
+                    continue;
+                }
+                toolCallsMade++;
+                let result;
+                try {
+                    result = await executeTool(tool, call.args);
+                }
+                catch (err) {
+                    result = new Result(false, null, toError(err).message);
+                }
+                if (result.success) {
+                    this.config.step_enforcer?.markStepComplete(session_id, call.tool);
+                    conversation.push({
+                        role: Role.TOOL,
+                        content: `Tool ${call.tool} result: ${JSON.stringify(result.data)}`,
+                        meta: { type: MessageType.TOOL_RESULT },
+                    });
+                }
+                else {
+                    const message = result.error ?? "tool failed";
+                    this.config.error_tracker?.recordError(session_id, call.tool, call.args, new Error(message), categorizeError(message));
+                    conversation.push({
+                        role: Role.TOOL,
+                        content: `Tool ${call.tool} error: ${message}`,
+                        meta: { type: MessageType.TOOL_RESULT },
+                    });
+                }
+            }
+            if (stepNudged) {
+                continue;
+            }
+        }
+        return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.MAX_ITERATIONS, conversation);
+    }
+    validate(resp) {
+        if (resp.tool_calls.length > 0) {
+            return this.config.validator.validateToolCalls(resp.tool_calls.map((tc) => ({ tool: tc.name, args: tc.arguments })));
+        }
+        const textValidation = this.config.validator.validateTextResponse(resp.content);
+        if (textValidation.toolCalls.length > 0) {
+            return textValidation;
+        }
+        if (this.config.require_tool_call) {
+            return textValidation;
+        }
+        return { toolCalls: [], nudge: null, needsRetry: false };
+    }
+    finish(finalResponse, iterations, toolCallsMade, nudges, termination, conversation) {
+        return {
+            final_response: finalResponse,
+            iterations,
+            tool_calls_made: toolCallsMade,
+            nudges,
+            termination_reason: termination,
+            conversation,
+        };
+    }
+}

package/dist/executor/index.d.ts

@@ -1,2 +1,3 @@
-export { Executor, ExecuteRequest, ExecuteResult, TerminationReason, InferenceExecutor, InferenceExecutorConfig } from "./executor.js";
+export { Executor, ExecuteRequest, ExecuteResult, TerminationReason, InferenceExecutor, InferenceExecutorConfig, } from "./executor.js";
+export { AgentLoop, AgentLoopConfig, AgentResult, AgentTerminationReason, registryToolDefinitions, categorizeError, } from "./agent_loop.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/executor/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/executor/index.js

@@ -1 +1,2 @@
-export { TerminationReason, InferenceExecutor } from "./executor.js";
+export { TerminationReason, InferenceExecutor, } from "./executor.js";
+export { AgentLoop, AgentTerminationReason, registryToolDefinitions, categorizeError, } from "./agent_loop.js";

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export * from "./llmcontext/index.js";
 export * from "./prompts/index.js";
 export * from "./toolformat/index.js";
 export * from "./memory/index.js";
+export * from "./reasoning/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -7,3 +7,4 @@ export * from "./llmcontext/index.js";
 export * from "./prompts/index.js";
 export * from "./toolformat/index.js";
 export * from "./memory/index.js";
+export * from "./reasoning/index.js";

package/dist/llm/backend.d.ts

@@ -1,4 +1,5 @@
 import type { Message } from "./request.js";
+import type { ToolDefinition } from "./request.js";
 import type { Response } from "./response.js";
 export interface Backend {
     complete(messages: Message[]): Response;
@@ -6,4 +7,10 @@ export interface Backend {
     modelName(): string;
     contextWindowSize(): number;
 }
+export interface AsyncBackend {
+    complete(messages: Message[], tools?: ToolDefinition[]): Promise<Response>;
+    supportsNativeToolCalling(): boolean;
+    modelName(): string;
+    contextWindowSize(): number;
+}
 //# sourceMappingURL=backend.d.ts.map

package/dist/llm/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/llm/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IACxC,yBAAyB,IAAI,OAAO,CAAC;IACrC,SAAS,IAAI,MAAM,CAAC;IACpB,iBAAiB,IAAI,MAAM,CAAC;CAC7B"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/llm/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IACxC,yBAAyB,IAAI,OAAO,CAAC;IACrC,SAAS,IAAI,MAAM,CAAC;IACpB,iBAAiB,IAAI,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3E,yBAAyB,IAAI,OAAO,CAAC;IACrC,SAAS,IAAI,MAAM,CAAC;IACpB,iBAAiB,IAAI,MAAM,CAAC;CAC7B"}

package/dist/llm/index.d.ts

@@ -1,4 +1,5 @@
-export { Backend } from "./backend.js";
+export { Backend, AsyncBackend } from "./backend.js";
 export { Message, Role, Request, ToolDefinition } from "./request.js";
 export { Response, ToolCall, TokenUsage } from "./response.js";
+export { OpenAIBackend, OpenAIBackendConfig, OpenAIError, FetchFn, FetchLikeInit, FetchLikeResponse, parseToolArguments, } from "./openai_backend.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/llm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/llm/index.js

@@ -1 +1,2 @@
 export { Role } from "./request.js";
+export { OpenAIBackend, OpenAIError, parseToolArguments, } from "./openai_backend.js";

package/dist/llm/openai_backend.d.ts

@@ -0,0 +1,51 @@
+import type { Message, ToolDefinition } from "./request.js";
+import type { Response } from "./response.js";
+import type { AsyncBackend } from "./backend.js";
+export interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}
+export interface FetchLikeInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+export type FetchFn = (url: string, init?: FetchLikeInit) => Promise<FetchLikeResponse>;
+export declare class OpenAIError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+export interface OpenAIBackendConfig {
+    model: string;
+    baseUrl?: string;
+    apiKey?: string;
+    fetchFn?: FetchFn;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    maxToolArgBytes?: number;
+    contextWindowSize?: number;
+    temperature?: number;
+    maxTokens?: number;
+}
+export declare function parseToolArguments(raw: string | null | undefined, maxBytes: number): Record<string, unknown>;
+export declare class OpenAIBackend implements AsyncBackend {
+    private readonly model;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    private readonly maxResponseBytes;
+    private readonly maxToolArgBytes;
+    private readonly contextWindow;
+    private readonly temperature?;
+    private readonly maxTokens?;
+    constructor(config: OpenAIBackendConfig);
+    complete(messages: Message[], tools?: ToolDefinition[]): Promise<Response>;
+    private parseCompletion;
+    supportsNativeToolCalling(): boolean;
+    modelName(): string;
+    contextWindowSize(): number;
+}
+//# sourceMappingURL=openai_backend.d.ts.map

package/dist/llm/openai_backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai_backend.d.ts","sourceRoot":"","sources":["../../src/llm/openai_backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,KAAK,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,aAAa,KACjB,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhC,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK7C;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwCD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAkDD,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;gBAExB,MAAM,EAAE,mBAAmB;IAajC,QAAQ,CACZ,QAAQ,EAAE,OAAO,EAAE,EACnB,KAAK,CAAC,EAAE,cAAc,EAAE,GACvB,OAAO,CAAC,QAAQ,CAAC;IA2EpB,OAAO,CAAC,eAAe;IA2CvB,yBAAyB,IAAI,OAAO;IAIpC,SAAS,IAAI,MAAM;IAInB,iBAAiB,IAAI,MAAM;CAG5B"}

package/dist/llm/openai_backend.js

@@ -0,0 +1,203 @@
+import { Role } from "./request.js";
+export class OpenAIError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "OpenAIError";
+        this.status = status;
+    }
+}
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 1_048_576;
+const DEFAULT_MAX_TOOL_ARG_BYTES = 65_536;
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const MAX_ERROR_DETAIL_CHARS = 512;
+export function parseToolArguments(raw, maxBytes) {
+    if (!raw) {
+        return {};
+    }
+    const bounded = raw.length > maxBytes ? raw.slice(0, maxBytes) : raw;
+    try {
+        const parsed = JSON.parse(bounded);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through to raw fallback
+    }
+    return { _raw: bounded };
+}
+function toOpenAIMessage(message) {
+    switch (message.role) {
+        case Role.TOOL:
+            return {
+                role: "tool",
+                tool_call_id: message.tool_call_id ?? "",
+                content: message.content,
+            };
+        case Role.ASSISTANT:
+            if (message.tool_calls && message.tool_calls.length > 0) {
+                return {
+                    role: "assistant",
+                    content: message.content || null,
+                    tool_calls: message.tool_calls.map((tc) => ({
+                        id: tc.id,
+                        type: "function",
+                        function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+                    })),
+                };
+            }
+            return { role: "assistant", content: message.content };
+        default:
+            return { role: message.role, content: message.content };
+    }
+}
+function toOpenAITool(tool) {
+    return {
+        type: "function",
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.input_schema,
+        },
+    };
+}
+function truncateDetail(text) {
+    if (text.length <= MAX_ERROR_DETAIL_CHARS) {
+        return text;
+    }
+    return text.slice(0, MAX_ERROR_DETAIL_CHARS) + "...";
+}
+function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+export class OpenAIBackend {
+    model;
+    baseUrl;
+    apiKey;
+    fetchFn;
+    timeoutMs;
+    maxResponseBytes;
+    maxToolArgBytes;
+    contextWindow;
+    temperature;
+    maxTokens;
+    constructor(config) {
+        this.model = config.model;
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.apiKey = config.apiKey ?? "";
+        this.fetchFn = config.fetchFn ?? fetch;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxResponseBytes = config.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        this.maxToolArgBytes = config.maxToolArgBytes ?? DEFAULT_MAX_TOOL_ARG_BYTES;
+        this.contextWindow = config.contextWindowSize ?? DEFAULT_CONTEXT_WINDOW;
+        this.temperature = config.temperature;
+        this.maxTokens = config.maxTokens;
+    }
+    async complete(messages, tools) {
+        const payload = {
+            model: this.model,
+            messages: messages.map(toOpenAIMessage),
+        };
+        if (this.temperature !== undefined) {
+            payload.temperature = this.temperature;
+        }
+        if (this.maxTokens !== undefined) {
+            payload.max_tokens = this.maxTokens;
+        }
+        if (tools && tools.length > 0) {
+            payload.tools = tools.map(toOpenAITool);
+            payload.tool_choice = "auto";
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            let res;
+            try {
+                res = await this.fetchFn(`${this.baseUrl}/chat/completions`, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(payload),
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                if (controller.signal.aborted ||
+                    (err instanceof Error && err.name === "AbortError")) {
+                    throw new OpenAIError(`request timed out after ${this.timeoutMs}ms`);
+                }
+                throw new OpenAIError(`request failed: ${toError(err).message}`);
+            }
+            const text = await res.text();
+            if (text.length > this.maxResponseBytes) {
+                throw new OpenAIError(`response body exceeds limit of ${this.maxResponseBytes} bytes`);
+            }
+            if (!res.ok) {
+                throw new OpenAIError(`HTTP ${res.status}: ${truncateDetail(text)}`, res.status);
+            }
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new OpenAIError("malformed JSON in response body");
+            }
+            return this.parseCompletion(data);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    parseCompletion(data) {
+        const completion = data;
+        const choice = completion.choices?.[0];
+        const message = choice?.message;
+        if (!message) {
+            throw new OpenAIError("unexpected response shape: missing choices[0].message");
+        }
+        const toolCalls = [];
+        if (message.tool_calls) {
+            for (let i = 0; i < message.tool_calls.length; i++) {
+                const tc = message.tool_calls[i];
+                const name = tc.function?.name;
+                if (!name) {
+                    continue;
+                }
+                toolCalls.push({
+                    id: tc.id ?? `call_${i}`,
+                    name,
+                    arguments: parseToolArguments(tc.function?.arguments, this.maxToolArgBytes),
+                });
+            }
+        }
+        const usage = {
+            prompt_tokens: completion.usage?.prompt_tokens ?? 0,
+            completion_tokens: completion.usage?.completion_tokens ?? 0,
+            total_tokens: completion.usage?.total_tokens ?? 0,
+        };
+        return {
+            content: message.content ?? "",
+            reasoning: message.reasoning_content ?? "",
+            tool_calls: toolCalls,
+            finish_reason: choice?.finish_reason ?? "",
+            usage_tokens: usage,
+        };
+    }
+    supportsNativeToolCalling() {
+        return true;
+    }
+    modelName() {
+        return this.model;
+    }
+    contextWindowSize() {
+        return this.contextWindow;
+    }
+}

package/dist/llm/response.d.ts

@@ -10,6 +10,11 @@ export interface TokenUsage {
 }
 export interface Response {
     content: string;
+    /** Raw reasoning returned on a separate channel (e.g. reasoning_content for
+     * DeepSeek-style models). Never written into content, never returned to the
+     * end user, and never recorded on a default audit record; consumers
+     * normalize it with the reasoning adapter. */
+    reasoning: string;
     tool_calls: ToolCall[];
     finish_reason: string;
     usage_tokens: TokenUsage;

package/dist/llm/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/llm/response.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,UAAU,CAAC;CAC1B"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/llm/response.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB;;;kDAG8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,UAAU,CAAC;CAC1B"}

package/dist/middleware/guardrails/response_validator.d.ts

@@ -1,4 +1,4 @@
-import { Nudge } from "./nudge";
+import { Nudge } from "./nudge.js";
 export interface ToolCall {
     tool: string;
     args: Record<string, unknown>;

package/dist/middleware/guardrails/response_validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response_validator.d.ts","sourceRoot":"","sources":["../../../src/middleware/guardrails/response_validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAgC,MAAM,SAAS,CAAC;AAE9D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,YAAY,CAAsD;IAE1E,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,mBAAmB,CAAS;gBAGlC,SAAS,EAAE,MAAM,EAAE,EACnB,aAAa,GAAE,OAAc,EAC7B,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,KAAK;IAapE,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAYxD,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,gBAAgB;IAoB1D,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,oBAAoB;IAqC5B,OAAO,CAAC,gBAAgB;IAuBxB,OAAO,CAAC,yBAAyB;IA0BjC,OAAO,CAAC,uBAAuB;CAGhC"}
+{"version":3,"file":"response_validator.d.ts","sourceRoot":"","sources":["../../../src/middleware/guardrails/response_validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAgC,MAAM,YAAY,CAAC;AAEjE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,YAAY,CAAsD;IAE1E,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,mBAAmB,CAAS;gBAGlC,SAAS,EAAE,MAAM,EAAE,EACnB,aAAa,GAAE,OAAc,EAC7B,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,KAAK;IAapE,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAYxD,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,gBAAgB;IAoB1D,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,oBAAoB;IAqC5B,OAAO,CAAC,gBAAgB;IAuBxB,OAAO,CAAC,yBAAyB;IA0BjC,OAAO,CAAC,uBAAuB;CAGhC"}

package/dist/middleware/guardrails/response_validator.js

@@ -1,4 +1,4 @@
-import { retryNudge, unknownToolNudge } from "./nudge";
+import { retryNudge, unknownToolNudge } from "./nudge.js";
 export class ResponseValidator {
     toolNames;
     rescueEnabled;

package/dist/middleware/index.d.ts

@@ -2,4 +2,9 @@ export { MiddlewareImpl, Middleware, ToolExecutor } from "./middleware.js";
 export { Action, CallerContext, Decision, MessageType, MessageMeta } from "./types.js";
 export { PolicyEvaluator, Policy, Rule, Condition, Operator, SimplePolicyEvaluator } from "./policy.js";
 export { Auditor, AuditRecord, InMemoryAuditor, AuditFilter } from "./audit.js";
+export { runInference, InferenceConfig, InferenceResult, RetriesExhaustedError, } from "./inference.js";
+export { ResponseValidator, ValidationResult, ToolCall as ValidatedToolCall, } from "./guardrails/response_validator.js";
+export { Nudge, NudgeKind, retryNudge, unknownToolNudge, stepNudge, prerequisiteNudge, } from "./guardrails/nudge.js";
+export { ErrorTracker, ErrorCategory, ToolError, } from "./guardrails/error_tracker.js";
+export { StepEnforcer, StepNotAllowedError } from "./guardrails/step_enforcer.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,IAAI,iBAAiB,GAC9B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,KAAK,EACL,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,YAAY,EACZ,aAAa,EACb,SAAS,GACV,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/middleware/index.js

@@ -2,3 +2,8 @@ export { MiddlewareImpl } from "./middleware.js";
 export { Action, MessageType } from "./types.js";
 export { Operator, SimplePolicyEvaluator } from "./policy.js";
 export { InMemoryAuditor } from "./audit.js";
+export { runInference, RetriesExhaustedError, } from "./inference.js";
+export { ResponseValidator, } from "./guardrails/response_validator.js";
+export { NudgeKind, retryNudge, unknownToolNudge, stepNudge, prerequisiteNudge, } from "./guardrails/nudge.js";
+export { ErrorTracker, ErrorCategory, } from "./guardrails/error_tracker.js";
+export { StepEnforcer, StepNotAllowedError } from "./guardrails/step_enforcer.js";