@sisu-ai/mw-usage-tracker 10.0.0 → 11.0.0

package/dist/core/src/Agent.d.ts

@@ -0,0 +1,7 @@
+import { type Middleware } from './compose.js';
+import type { Ctx } from './types.js';
+export declare class Agent<C extends Ctx = Ctx> {
+    private stack;
+    use(mw: Middleware<C>): this;
+    handler(): (ctx: C, nextOuter?: (() => Promise<void>) | undefined) => Promise<void>;
+}

package/dist/core/src/Agent.js

@@ -0,0 +1,8 @@
+import { compose } from './compose.js';
+export class Agent {
+    constructor() {
+        this.stack = [];
+    }
+    use(mw) { this.stack.push(mw); return this; }
+    handler() { return compose(this.stack); }
+}

package/dist/core/src/compose.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx } from "./types.js";
+export type Middleware<C extends Ctx = Ctx> = (ctx: C, next: () => Promise<void>) => void | Promise<void>;
+export declare function compose<C extends Ctx>(stack: Middleware<C>[]): (ctx: C, nextOuter?: () => Promise<void>) => Promise<void>;

package/dist/core/src/compose.js

@@ -0,0 +1,21 @@
+export function compose(stack) {
+    if (!Array.isArray(stack)) {
+        throw new TypeError("Middleware stack must be an array");
+    }
+    if (stack.some((fn) => typeof fn !== "function")) {
+        throw new TypeError("Middleware must be composed of functions");
+    }
+    return (ctx, nextOuter) => {
+        let index = -1;
+        async function dispatch(i) {
+            if (i <= index)
+                throw new Error("next() called multiple times");
+            index = i;
+            const fn = stack[i] ?? nextOuter;
+            if (!fn)
+                return;
+            await fn(ctx, () => dispatch(i + 1));
+        }
+        return dispatch(0);
+    };
+}

package/dist/core/src/embeddings.d.ts

@@ -0,0 +1,17 @@
+import type { EmbeddingsProvider } from "./types.js";
+export interface CreateEmbeddingsClientOptions {
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    authHeader?: string;
+    authScheme?: string;
+    clientName?: string;
+    buildBody?: (args: {
+        input: string[];
+        model: string;
+    }) => Record<string, unknown>;
+    parseResponse?: (raw: string) => number[][];
+}
+export declare function createEmbeddingsClient(options: CreateEmbeddingsClientOptions): EmbeddingsProvider;

package/dist/core/src/embeddings.js

@@ -0,0 +1,75 @@
+export function createEmbeddingsClient(options) {
+    const clientName = options.clientName ?? "createEmbeddingsClient";
+    if (!options.baseUrl) {
+        throw new Error(`[${clientName}] baseUrl is required`);
+    }
+    const baseUrl = options.baseUrl.replace(/\/$/, "");
+    const path = options.path ?? "/v1/embeddings";
+    const authHeader = options.authHeader ?? "Authorization";
+    const authScheme = options.authScheme ?? "Bearer ";
+    return {
+        async embed(input, opts) {
+            if (!Array.isArray(input) || input.length === 0) {
+                throw new Error(`[${clientName}] input must contain at least one string`);
+            }
+            if (opts?.signal?.aborted) {
+                throw new Error(`[${clientName}] embedding request aborted`);
+            }
+            const model = opts?.model ?? options.model;
+            if (!model) {
+                throw new Error(`[${clientName}] model is required`);
+            }
+            const response = await fetch(`${baseUrl}${path}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                    ...(options.apiKey
+                        ? { [authHeader]: `${authScheme}${options.apiKey}` }
+                        : {}),
+                    ...(options.headers ?? {}),
+                },
+                body: JSON.stringify(options.buildBody?.({ input, model }) ?? {
+                    model,
+                    input,
+                }),
+                signal: opts?.signal,
+            });
+            const raw = await response.text();
+            if (!response.ok) {
+                throw new Error(`[${clientName}] API error: ${response.status} ${response.statusText} - ${extractErrorDetails(raw)}`);
+            }
+            let embeddings;
+            try {
+                embeddings = options.parseResponse?.(raw) ?? parseOpenAICompatibleResponse(raw);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "unknown parse error";
+                throw new Error(`[${clientName}] Failed to parse embeddings response: ${message}`);
+            }
+            if (embeddings.length !== input.length) {
+                throw new Error(`[${clientName}] Expected ${input.length} embeddings, received ${embeddings.length}`);
+            }
+            return embeddings;
+        },
+    };
+}
+function parseOpenAICompatibleResponse(raw) {
+    const parsed = JSON.parse(raw);
+    return (parsed.data ?? []).map((entry) => entry.embedding ?? []);
+}
+function extractErrorDetails(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.error === "string")
+            return parsed.error;
+        if (parsed.error?.message)
+            return parsed.error.message;
+        if (parsed.message)
+            return parsed.message;
+    }
+    catch {
+        return raw;
+    }
+    return raw;
+}

package/dist/core/src/errors.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Base error class for all Sisu errors.
+ * Provides structured error information with error codes and context.
+ */
+export declare class SisuError extends Error {
+    readonly code: string;
+    readonly context?: unknown | undefined;
+    constructor(message: string, code: string, context?: unknown | undefined);
+    /**
+     * Convert error to JSON for logging and tracing
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        context?: unknown;
+        stack?: string;
+    };
+}
+/**
+ * Error thrown when middleware execution fails.
+ * Includes the middleware index to help identify which middleware failed.
+ */
+export declare class MiddlewareError extends SisuError {
+    readonly middlewareIndex: number;
+    constructor(message: string, middlewareIndex: number, cause?: Error);
+}
+/**
+ * Error thrown when tool execution fails.
+ * Includes tool name and arguments for debugging.
+ */
+export declare class ToolExecutionError extends SisuError {
+    readonly toolName: string;
+    readonly args: unknown;
+    constructor(message: string, toolName: string, args: unknown, cause?: Error);
+}
+/**
+ * Error thrown when adapter/LLM operations fail.
+ * Includes model name and provider-specific details.
+ */
+export declare class AdapterError extends SisuError {
+    readonly modelName: string;
+    readonly provider?: string | undefined;
+    constructor(message: string, modelName: string, provider?: string | undefined, cause?: Error);
+}
+/**
+ * Error thrown when validation fails (e.g., schema validation for tools).
+ * Includes validation errors and the data that failed validation.
+ */
+export declare class ValidationError extends SisuError {
+    readonly validationErrors: unknown;
+    readonly data?: unknown | undefined;
+    constructor(message: string, validationErrors: unknown, data?: unknown | undefined, cause?: Error);
+}
+/**
+ * Error thrown when a timeout occurs.
+ * Includes timeout duration and operation details.
+ */
+export declare class TimeoutError extends SisuError {
+    readonly timeoutMs: number;
+    readonly operation?: string | undefined;
+    constructor(message: string, timeoutMs: number, operation?: string | undefined, cause?: Error);
+}
+/**
+ * Error thrown when an operation is cancelled (e.g., via AbortSignal).
+ * Includes the reason for cancellation if available.
+ */
+export declare class CancellationError extends SisuError {
+    readonly reason?: string | undefined;
+    constructor(message: string, reason?: string | undefined, cause?: Error);
+}
+/**
+ * Error thrown when a configuration is invalid.
+ * Includes the invalid configuration and expected format.
+ */
+export declare class ConfigurationError extends SisuError {
+    readonly config?: unknown | undefined;
+    readonly expected?: string | undefined;
+    constructor(message: string, config?: unknown | undefined, expected?: string | undefined, cause?: Error);
+}
+/**
+ * Helper to check if an error is a SisuError
+ */
+export declare function isSisuError(error: unknown): error is SisuError;
+/**
+ * Helper to extract error details for logging
+ */
+export declare function getErrorDetails(error: unknown): {
+    name: string;
+    message: string;
+    code?: string;
+    context?: unknown;
+    stack?: string;
+};

package/dist/core/src/errors.js

@@ -0,0 +1,156 @@
+/**
+ * Base error class for all Sisu errors.
+ * Provides structured error information with error codes and context.
+ */
+export class SisuError extends Error {
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'SisuError';
+        // Maintain proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Convert error to JSON for logging and tracing
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            stack: this.stack,
+        };
+    }
+}
+/**
+ * Error thrown when middleware execution fails.
+ * Includes the middleware index to help identify which middleware failed.
+ */
+export class MiddlewareError extends SisuError {
+    constructor(message, middlewareIndex, cause) {
+        super(message, 'MIDDLEWARE_ERROR', { middlewareIndex, cause });
+        this.middlewareIndex = middlewareIndex;
+        this.name = 'MiddlewareError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when tool execution fails.
+ * Includes tool name and arguments for debugging.
+ */
+export class ToolExecutionError extends SisuError {
+    constructor(message, toolName, args, cause) {
+        super(message, 'TOOL_EXECUTION_ERROR', { toolName, args, cause });
+        this.toolName = toolName;
+        this.args = args;
+        this.name = 'ToolExecutionError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when adapter/LLM operations fail.
+ * Includes model name and provider-specific details.
+ */
+export class AdapterError extends SisuError {
+    constructor(message, modelName, provider, cause) {
+        super(message, 'ADAPTER_ERROR', { modelName, provider, cause });
+        this.modelName = modelName;
+        this.provider = provider;
+        this.name = 'AdapterError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when validation fails (e.g., schema validation for tools).
+ * Includes validation errors and the data that failed validation.
+ */
+export class ValidationError extends SisuError {
+    constructor(message, validationErrors, data, cause) {
+        super(message, 'VALIDATION_ERROR', { validationErrors, data, cause });
+        this.validationErrors = validationErrors;
+        this.data = data;
+        this.name = 'ValidationError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when a timeout occurs.
+ * Includes timeout duration and operation details.
+ */
+export class TimeoutError extends SisuError {
+    constructor(message, timeoutMs, operation, cause) {
+        super(message, 'TIMEOUT_ERROR', { timeoutMs, operation, cause });
+        this.timeoutMs = timeoutMs;
+        this.operation = operation;
+        this.name = 'TimeoutError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when an operation is cancelled (e.g., via AbortSignal).
+ * Includes the reason for cancellation if available.
+ */
+export class CancellationError extends SisuError {
+    constructor(message, reason, cause) {
+        super(message, 'CANCELLATION_ERROR', { reason, cause });
+        this.reason = reason;
+        this.name = 'CancellationError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when a configuration is invalid.
+ * Includes the invalid configuration and expected format.
+ */
+export class ConfigurationError extends SisuError {
+    constructor(message, config, expected, cause) {
+        super(message, 'CONFIGURATION_ERROR', { config, expected, cause });
+        this.config = config;
+        this.expected = expected;
+        this.name = 'ConfigurationError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Helper to check if an error is a SisuError
+ */
+export function isSisuError(error) {
+    return error instanceof SisuError;
+}
+/**
+ * Helper to extract error details for logging
+ */
+export function getErrorDetails(error) {
+    if (isSisuError(error)) {
+        return error.toJSON();
+    }
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    return {
+        name: 'UnknownError',
+        message: String(error),
+    };
+}

package/dist/core/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './embeddings.js';
+export * from './compose.js';
+export * from './Agent.js';
+export * from './util.js';
+export * from './errors.js';

package/dist/core/src/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './embeddings.js';
+export * from './compose.js';
+export * from './Agent.js';
+export * from './util.js';
+export * from './errors.js';

package/dist/core/src/types.d.ts

@@ -0,0 +1,190 @@
+export type Role = "user" | "assistant" | "system" | "tool";
+/** Tool call envelope normalized across providers */
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+}
+/** Messages are discriminated by role for precision */
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+export interface SystemMessage {
+    role: "system";
+    content: string;
+    name?: string;
+}
+export interface UserMessage {
+    role: "user";
+    content: string;
+    name?: string;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: string;
+    name?: string;
+    /** When the model wants to call tools, it returns one or more tool calls */
+    tool_calls?: ToolCall[];
+    /**
+     * Reasoning details from thinking/reasoning models (e.g., o1, o3, ChatGPT 5.1).
+     * This field must be preserved when passing the message back to the model
+     * for multi-turn conversations to maintain reasoning context.
+     * @internal The structure is provider-specific and should be treated as opaque.
+     */
+    reasoning_details?: unknown;
+}
+export interface ToolMessage {
+    role: "tool";
+    /** Tool JSON/string result to be fed back to the model */
+    content: string;
+    /** Link back to the specific assistant tool call */
+    tool_call_id: string;
+    /** (optional) echo the tool name for debugging/trace */
+    name?: string;
+}
+/** LLM call options */
+export type ToolChoice = "auto" | "none" | "required" | {
+    name: string;
+};
+export interface GenerateOptions {
+    temperature?: number;
+    maxTokens?: number;
+    toolChoice?: ToolChoice;
+    signal?: globalThis.AbortSignal;
+    tools?: Tool[];
+    parallelToolCalls?: boolean;
+    stream?: boolean;
+    /**
+     * Enable extended reasoning/thinking for models that support it (e.g., o1, o3, ChatGPT 5.1).
+     * - `true` or `false`: Simple enable/disable
+     * - `{ enabled: true }`: OpenAI-style object notation
+     * - Custom object: Provider-specific options
+     *
+     * @example
+     * // Enable reasoning
+     * { reasoning: true }
+     *
+     * @example
+     * // OpenAI format
+     * { reasoning: { enabled: true } }
+     */
+    reasoning?: boolean | {
+        enabled: boolean;
+    } | Record<string, unknown>;
+}
+/** Streaming events */
+export type ModelEvent = {
+    type: "token";
+    token: string;
+} | {
+    type: "tool_call";
+    call: ToolCall;
+} | {
+    type: "assistant_message";
+    message: AssistantMessage;
+} | {
+    type: "usage";
+    usage: Usage;
+};
+export interface Usage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    costUSD?: number;
+}
+/** Final response */
+export interface ModelResponse {
+    message: AssistantMessage;
+    usage?: Usage;
+}
+export interface EmbedOptions {
+    model?: string;
+    signal?: globalThis.AbortSignal;
+}
+export interface EmbeddingsProvider {
+    embed(input: string[], opts?: EmbedOptions): Promise<number[][]>;
+}
+/** Adapter contract */
+export interface LLM {
+    name: string;
+    capabilities: {
+        functionCall?: boolean;
+        streaming?: boolean;
+    };
+    generate(messages: Message[], opts?: GenerateOptions): Promise<ModelResponse>;
+    generate(messages: Message[], opts?: GenerateOptions): AsyncIterable<ModelEvent>;
+    generate(messages: Message[], opts?: GenerateOptions): Promise<ModelResponse | AsyncIterable<ModelEvent>>;
+}
+/** Logger, Memory, TokenStream: unchanged */
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    span?(name: string, attrs?: Record<string, unknown>): void;
+}
+export interface Memory {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, val: unknown): Promise<void>;
+    retrieval?(index: string): {
+        search: (q: string, topK?: number) => Promise<Array<{
+            text: string;
+            score?: number;
+        }>>;
+    };
+}
+export interface TokenStream {
+    write(token: string): void;
+    end(): void;
+}
+/**
+ * Restricted context for tool execution.
+ * Tools have access to a sandboxed subset of Ctx to prevent:
+ * - Tools calling other tools (no tools registry access)
+ * - Tools manipulating conversation history (no messages access)
+ * - Tools accessing middleware state (no state access)
+ * - Tools interfering with user I/O (no input/stream access)
+ *
+ * Tools CAN:
+ * - Use the model for meta-operations (e.g., summarizeText)
+ * - Access persistent memory
+ * - Respect cancellation signals
+ * - Log their operations
+ * - Access injected dependencies (for testing/configuration)
+ */
+export interface ToolContext {
+    readonly memory: Memory;
+    readonly signal: globalThis.AbortSignal;
+    readonly log: Logger;
+    readonly model: LLM;
+    /** Optional dependency injection container for testing or runtime configuration */
+    readonly deps?: Record<string, unknown>;
+}
+export interface Tool<TArgs = unknown, TResult = unknown> {
+    name: string;
+    description?: string;
+    schema: unknown;
+    handler(args: TArgs, ctx: ToolContext): Promise<TResult>;
+}
+/** Registry */
+export interface ToolRegistry {
+    list(): Tool[];
+    get(name: string): Tool | undefined;
+    register(tool: Tool): void;
+}
+/** Context */
+export interface Ctx {
+    input?: string;
+    messages: Message[];
+    model: LLM;
+    tools: ToolRegistry;
+    memory: Memory;
+    stream: TokenStream;
+    /**
+     * Extensible state object for middleware to share data.
+     *
+     * Well-known keys used by SISU middleware:
+     * - `toolAliases` (Map<string, string>): Map of tool names to API aliases set by registerTools
+     */
+    state: Record<string, unknown>;
+    signal: globalThis.AbortSignal;
+    log: Logger;
+}

package/dist/core/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/src/util.d.ts

@@ -0,0 +1,88 @@
+import { Middleware } from "./compose.js";
+import type { Ctx, Logger, Memory, TokenStream, Tool, ToolRegistry, LLM } from "./types.js";
+type Level = "debug" | "info" | "warn" | "error";
+export declare function createConsoleLogger(opts?: {
+    level?: Level;
+    timestamps?: boolean;
+}): Logger;
+export declare const consoleLogger: Logger;
+export interface TraceEvent {
+    level: Level | "span";
+    ts: string;
+    args: unknown[];
+}
+export declare function createTracingLogger(base?: Logger): {
+    logger: Logger;
+    getTrace: () => TraceEvent[];
+    reset: () => void;
+};
+export interface RedactOptions {
+    keys?: string[];
+    mask?: string;
+    patterns?: RegExp[];
+}
+export declare function redactSensitive(input: unknown, opts?: RedactOptions): unknown;
+export declare function createRedactingLogger(base: Logger, opts?: RedactOptions): Logger;
+export declare class InMemoryKV implements Memory {
+    private m;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, val: unknown): Promise<void>;
+    retrieval(index: string): {
+        search: (q: string, topK?: number) => Promise<{
+            text: string;
+            score: number;
+        }[]>;
+    };
+}
+export declare class NullStream implements TokenStream {
+    write(_t: string): void;
+    end(): void;
+}
+export declare const stdoutStream: TokenStream;
+export declare function bufferStream(): {
+    stream: {
+        write: (t: string) => void;
+        end: () => void;
+    };
+    getText: () => string;
+};
+export declare function teeStream(...streams: TokenStream[]): TokenStream;
+export declare const streamOnce: Middleware;
+export declare class SimpleTools implements ToolRegistry {
+    private tools;
+    list(): Tool<unknown, unknown>[];
+    get(name: string): Tool<unknown, unknown> | undefined;
+    register(tool: Tool): void;
+}
+export interface CreateCtxOptions {
+    model: LLM;
+    input?: string;
+    systemPrompt?: string;
+    logLevel?: Level;
+    timestamps?: boolean;
+    signal?: globalThis.AbortSignal;
+    tools?: Tool[] | ToolRegistry;
+    memory?: Memory;
+    stream?: TokenStream;
+    state?: Record<string, unknown>;
+}
+/**
+ * Factory function to create a Ctx object with sensible defaults.
+ * Reduces boilerplate by providing defaults for all optional fields.
+ *
+ * @example
+ * ```ts
+ * const ctx = createCtx({
+ *   model: openAIAdapter({ model: 'gpt-4o-mini' }),
+ *   input: 'Hello',
+ *   systemPrompt: 'You are a helpful assistant',
+ *   logLevel: 'debug'
+ * });
+ * ```
+ */
+export declare function createCtx(options: CreateCtxOptions): Ctx;
+export type FlagMap = Record<string, string | boolean>;
+export declare function parseFlags(argv?: string[]): FlagMap;
+export declare function configFromFlagsAndEnv(envVars: string[], flags?: FlagMap, env?: typeof process.env): Record<string, string | undefined>;
+export declare function firstConfigValue(names: string[], flags?: FlagMap, env?: typeof process.env): string | undefined;
+export {};

package/dist/core/src/util.js

@@ -0,0 +1,371 @@
+const order = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function nowTs() {
+    const d = new Date();
+    const pad = (n, s = 2) => String(n).padStart(s, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+export function createConsoleLogger(opts = {}) {
+    const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+    const level = opts.level ?? envLevel ?? "info";
+    const showTs = opts.timestamps ?? true;
+    const enabled = (lvl) => order[lvl] >= order[level];
+    const prefix = (lvl) => (showTs ? `[${nowTs()}] ` : "") + `[${lvl}]`;
+    return {
+        debug: (...a) => {
+            if (enabled("debug"))
+                console.debug(prefix("debug"), ...a);
+        },
+        info: (...a) => {
+            if (enabled("info"))
+                console.info(prefix("info"), ...a);
+        },
+        warn: (...a) => {
+            if (enabled("warn"))
+                console.warn(prefix("warn"), ...a);
+        },
+        error: (...a) => {
+            if (enabled("error"))
+                console.error(prefix("error"), ...a);
+        },
+        span: (name, attrs) => {
+            if (enabled("info"))
+                console.info((showTs ? `[${nowTs()}] ` : "") + "[span]", name, attrs ?? {});
+        },
+    };
+}
+// Backward-compatible always-on logger
+export const consoleLogger = createConsoleLogger({
+    level: process.env.LOG_LEVEL ?? "debug",
+});
+export function createTracingLogger(base = createConsoleLogger()) {
+    const events = [];
+    const push = (level, ...args) => {
+        events.push({ level, ts: new Date().toISOString(), args });
+    };
+    const logger = {
+        debug: (...a) => {
+            push("debug", ...a);
+            base.debug?.(...a);
+        },
+        info: (...a) => {
+            push("info", ...a);
+            base.info?.(...a);
+        },
+        warn: (...a) => {
+            push("warn", ...a);
+            base.warn?.(...a);
+        },
+        error: (...a) => {
+            push("error", ...a);
+            base.error?.(...a);
+        },
+        span: (name, attrs) => {
+            push("span", name, attrs ?? {});
+            base.span?.(name, attrs);
+        },
+    };
+    return {
+        logger,
+        getTrace: () => events.slice(),
+        reset: () => {
+            events.length = 0;
+        },
+    };
+}
+const DEFAULT_SENSITIVE_KEYS = [
+    "api_key",
+    "apikey",
+    "apiKey",
+    "authorization",
+    "auth",
+    "token",
+    "access_token",
+    "refresh_token",
+    "password",
+    "passwd",
+    "secret",
+    "x-api-key",
+    "openai_api_key",
+];
+// Default patterns for detecting common sensitive data formats
+const DEFAULT_PATTERNS = [
+    /sk-[a-zA-Z0-9]{32,}/, // OpenAI-style keys
+    /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$/, // JWT tokens
+    /ghp_[a-zA-Z0-9]{36}/, // GitHub Personal Access Token
+    /gho_[a-zA-Z0-9]{36}/, // GitHub OAuth Access Token
+    /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/, // GitHub fine-grained PAT
+    /glpat-[a-zA-Z0-9_-]{20}/, // GitLab Personal Access Token
+    /AIza[0-9A-Za-z_-]{35}/, // Google API Key
+    /ya29\.[0-9A-Za-z_-]+/, // Google OAuth Access Token
+    /AKIA[0-9A-Z]{16}/, // AWS Access Key ID
+    /xox[baprs]-[0-9a-zA-Z-]{10,}/, // Slack tokens
+];
+function matchesPattern(value, patterns) {
+    for (const pattern of patterns) {
+        if (pattern.test(value))
+            return true;
+    }
+    return false;
+}
+function redactObject(input, keysSet, patterns, mask) {
+    if (input === null || input === undefined)
+        return input;
+    // Preserve Error objects with useful fields
+    if (input instanceof Error) {
+        return { name: input.name, message: input.message, stack: input.stack };
+    }
+    if (Array.isArray(input)) {
+        return input.map((v) => redactObject(v, keysSet, patterns, mask));
+    }
+    if (typeof input === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(input)) {
+            out[k] = keysSet.has(k.toLowerCase())
+                ? mask
+                : redactObject(v, keysSet, patterns, mask);
+        }
+        return out;
+    }
+    // Check string values against patterns
+    if (typeof input === "string" && matchesPattern(input, patterns)) {
+        return mask;
+    }
+    return input;
+}
+function redactArgs(args, keysSet, patterns, mask) {
+    return args.map((arg) => redactObject(arg, keysSet, patterns, mask));
+}
+export function redactSensitive(input, opts = {}) {
+    const envKeys = (process.env.LOG_REDACT_KEYS || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const keys = (opts.keys && opts.keys.length ? opts.keys : DEFAULT_SENSITIVE_KEYS).concat(envKeys);
+    const keysSet = new Set(keys.map((k) => k.toLowerCase()));
+    const patterns = opts.patterns ?? DEFAULT_PATTERNS;
+    const mask = opts.mask ?? "***REDACTED***";
+    return redactObject(input, keysSet, patterns, mask);
+}
+export function createRedactingLogger(base, opts = {}) {
+    const envKeys = (process.env.LOG_REDACT_KEYS || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const keys = (opts.keys && opts.keys.length ? opts.keys : DEFAULT_SENSITIVE_KEYS).concat(envKeys);
+    const keysSet = new Set(keys.map((k) => k.toLowerCase()));
+    const patterns = opts.patterns ?? DEFAULT_PATTERNS;
+    const mask = opts.mask ?? "***REDACTED***";
+    return {
+        debug: (...a) => base.debug(...redactArgs(a, keysSet, patterns, mask)),
+        info: (...a) => base.info(...redactArgs(a, keysSet, patterns, mask)),
+        warn: (...a) => base.warn(...redactArgs(a, keysSet, patterns, mask)),
+        error: (...a) => base.error(...redactArgs(a, keysSet, patterns, mask)),
+        span: (name, attrs) => base.span?.(name, redactObject(attrs, keysSet, patterns, mask)),
+    };
+}
+export class InMemoryKV {
+    constructor() {
+        this.m = new Map();
+    }
+    async get(key) {
+        return this.m.get(key);
+    }
+    async set(key, val) {
+        this.m.set(key, val);
+    }
+    retrieval(index) {
+        const docs = this.m.get(`retrieval:${index}`) ?? [];
+        return {
+            search: async (q, topK = 4) => {
+                const scored = docs.map((t) => ({
+                    text: t,
+                    score: t.toLowerCase().includes(q.toLowerCase()) ? 1 : 0,
+                }));
+                return scored.sort((a, b) => b.score - a.score).slice(0, topK);
+            },
+        };
+    }
+}
+export class NullStream {
+    write(_t) { }
+    end() { }
+}
+export const stdoutStream = {
+    write: (t) => {
+        process.stdout.write(t);
+    },
+    end: () => {
+        process.stdout.write("\n");
+    },
+};
+export function bufferStream() {
+    let buf = "";
+    return {
+        stream: {
+            write: (t) => {
+                buf += t;
+            },
+            end: () => { },
+        },
+        getText: () => buf,
+    };
+}
+export function teeStream(...streams) {
+    return {
+        write: (t) => {
+            for (const s of streams)
+                s.write(t);
+        },
+        end: () => {
+            for (const s of streams)
+                s.end();
+        },
+    };
+}
+export const streamOnce = async (c) => {
+    const out = await c.model.generate(c.messages, {
+        stream: true,
+        toolChoice: "none",
+        signal: c.signal,
+    });
+    const stream = out;
+    if (stream &&
+        typeof stream[Symbol.asyncIterator] ===
+            "function") {
+        for await (const ev of stream) {
+            if (ev && typeof ev === "object") {
+                const event = ev;
+                if (event.type === "token" && typeof event.token === "string") {
+                    c.stream.write(event.token);
+                }
+                else if (event.type === "assistant_message" && event.message) {
+                    c.messages.push(event.message);
+                }
+            }
+        }
+        c.stream.end();
+    }
+    else if (out?.message) {
+        c.messages.push(out.message);
+        c.stream.write(out.message.content);
+        c.stream.end();
+    }
+};
+export class SimpleTools {
+    constructor() {
+        this.tools = new Map();
+    }
+    list() {
+        return Array.from(this.tools.values());
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+}
+/**
+ * Factory function to create a Ctx object with sensible defaults.
+ * Reduces boilerplate by providing defaults for all optional fields.
+ *
+ * @example
+ * ```ts
+ * const ctx = createCtx({
+ *   model: openAIAdapter({ model: 'gpt-4o-mini' }),
+ *   input: 'Hello',
+ *   systemPrompt: 'You are a helpful assistant',
+ *   logLevel: 'debug'
+ * });
+ * ```
+ */
+export function createCtx(options) {
+    const messages = [];
+    if (options.systemPrompt) {
+        messages.push({ role: "system", content: options.systemPrompt });
+    }
+    // Handle tools - accept either array or registry
+    let toolRegistry;
+    if (options.tools) {
+        if (Array.isArray(options.tools)) {
+            toolRegistry = new SimpleTools();
+            options.tools.forEach((t) => toolRegistry.register(t));
+        }
+        else {
+            toolRegistry = options.tools;
+        }
+    }
+    else {
+        toolRegistry = new SimpleTools();
+    }
+    return {
+        input: options.input,
+        messages,
+        model: options.model,
+        tools: toolRegistry,
+        memory: options.memory ?? new InMemoryKV(),
+        stream: options.stream ?? new NullStream(),
+        state: options.state ?? {},
+        signal: options.signal ?? new globalThis.AbortController().signal,
+        log: createConsoleLogger({
+            level: options.logLevel ?? "info",
+            timestamps: options.timestamps,
+        }),
+    };
+}
+export function parseFlags(argv = process.argv) {
+    const out = {};
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a || !a.startsWith("--"))
+            continue;
+        const k = a.slice(2);
+        const eq = k.indexOf("=");
+        if (eq >= 0) {
+            const key = k.slice(0, eq);
+            const val = k.slice(eq + 1);
+            out[key] = val;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+            out[k] = next;
+            i++;
+        }
+        else {
+            out[k] = true;
+        }
+    }
+    return out;
+}
+function kebabForEnv(envName) {
+    return envName.toLowerCase().replace(/_/g, "-");
+}
+// Given a list of env var names (e.g., ['OPENAI_API_KEY','API_KEY']), returns values with precedence: CLI flag > env
+export function configFromFlagsAndEnv(envVars, flags = parseFlags(), env = process.env) {
+    const out = {};
+    for (const name of envVars) {
+        const flag = kebabForEnv(name);
+        const cliVal = flags[flag] ?? undefined;
+        out[name] = cliVal ?? env[name];
+    }
+    return out;
+}
+// Helper to pick the first defined value out of a set of env names, respecting CLI-over-env precedence
+export function firstConfigValue(names, flags = parseFlags(), env = process.env) {
+    for (const n of names) {
+        const flag = kebabForEnv(n);
+        const cliVal = flags[flag] ?? undefined;
+        if (cliVal !== undefined)
+            return cliVal;
+        const envVal = env[n];
+        if (envVal !== undefined)
+            return envVal;
+    }
+    return undefined;
+}

package/dist/middleware/usage-tracker/src/index.d.ts

@@ -0,0 +1,22 @@
+import type { Middleware } from "@sisu-ai/core";
+export type PriceTable = Record<string, {
+    inputPer1M?: number;
+    outputPer1M?: number;
+    inputPer1K?: number;
+    outputPer1K?: number;
+    imagePerImage?: number;
+    imagePer1K?: number;
+    imageInputPer1K?: number;
+    imageTokenPerImage?: number;
+}>;
+export interface UsageTotals {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    costUSD?: number;
+    imageTokens?: number;
+    imageCount?: number;
+}
+export declare function usageTracker(prices: PriceTable, opts?: {
+    logPerCall?: boolean;
+}): Middleware;

package/dist/middleware/usage-tracker/src/index.js

@@ -0,0 +1,165 @@
+export function usageTracker(prices, opts = {}) {
+    return async (ctx, next) => {
+        // Wrap model.generate to intercept responses
+        const orig = ctx.model.generate.bind(ctx.model);
+        const price = prices[ctx.model.name] ?? prices["*"];
+        const state = ctx.state;
+        const totals = {
+            promptTokens: Number(state.usage?.promptTokens ?? 0),
+            completionTokens: Number(state.usage?.completionTokens ?? 0),
+            totalTokens: Number(state.usage?.totalTokens ?? 0),
+            costUSD: Number(state.usage?.costUSD ?? 0),
+        };
+        function applyUsage(out, imageCount, imageTokens) {
+            const u = out.usage;
+            if (u) {
+                const p = Number(u.promptTokens ?? 0);
+                const c = Number(u.completionTokens ?? 0);
+                const t = Number(u.totalTokens ?? p + c);
+                totals.promptTokens += p;
+                totals.completionTokens += c;
+                totals.totalTokens += t;
+                if (price) {
+                    const inPer1K = price.inputPer1K ??
+                        (price.inputPer1M != null ? price.inputPer1M / 1000 : undefined) ??
+                        0;
+                    const outPer1K = price.outputPer1K ??
+                        (price.outputPer1M != null
+                            ? price.outputPer1M / 1000
+                            : undefined) ??
+                        0;
+                    const textPromptTokens = Math.max(0, p - (price.imageInputPer1K ? imageTokens : 0));
+                    const tokenCost = (textPromptTokens / 1000) * inPer1K + (c / 1000) * outPer1K;
+                    const perImage = price.imagePerImage != null
+                        ? price.imagePerImage
+                        : price.imagePer1K != null
+                            ? price.imagePer1K / 1000
+                            : undefined;
+                    const imageCost = perImage != null
+                        ? imageCount * perImage
+                        : price.imageInputPer1K
+                            ? (imageTokens / 1000) * price.imageInputPer1K
+                            : 0;
+                    const cost = tokenCost + imageCost;
+                    totals.costUSD = Number((totals.costUSD ?? 0) + cost);
+                    if (imageCount > 0 && price.imageInputPer1K) {
+                        totals.imageTokens = Number((totals.imageTokens ?? 0) + imageTokens);
+                        totals.imageCount = Number((totals.imageCount ?? 0) + imageCount);
+                    }
+                }
+                if (opts.logPerCall)
+                    ctx.log.info?.("[usage] call", {
+                        promptTokens: p,
+                        completionTokens: c,
+                        totalTokens: t,
+                        imageTokens: imageCount > 0 && price?.imageInputPer1K
+                            ? imageTokens
+                            : undefined,
+                        imageCount: imageCount > 0 ? imageCount : undefined,
+                        estCostUSD: price
+                            ? (() => {
+                                const inPer1K = price.inputPer1K ??
+                                    (price.inputPer1M != null ? price.inputPer1M / 1000 : 0);
+                                const outPer1K = price.outputPer1K ??
+                                    (price.outputPer1M != null ? price.outputPer1M / 1000 : 0);
+                                const textPromptTokens = Math.max(0, p - (price?.imageInputPer1K ? imageTokens : 0));
+                                const perImage = price?.imagePerImage != null
+                                    ? price.imagePerImage
+                                    : price?.imagePer1K != null
+                                        ? price.imagePer1K / 1000
+                                        : undefined;
+                                const tokenCost = (textPromptTokens / 1000) * inPer1K + (c / 1000) * outPer1K;
+                                const imageCost = perImage != null
+                                    ? imageCount * perImage
+                                    : price?.imageInputPer1K
+                                        ? (imageTokens / 1000) * price.imageInputPer1K
+                                        : 0;
+                                return roundUSD(tokenCost + imageCost);
+                            })()
+                            : undefined,
+                    });
+            }
+        }
+        const isAsyncIterable = (val) => !!val &&
+            typeof val[Symbol.asyncIterator] ===
+                "function";
+        function withUsage(...args) {
+            const reqMessages = args?.[0];
+            const imageCount = countImageInputs(reqMessages);
+            const imageTokens = imageCount * Number(price?.imageTokenPerImage ?? 1000);
+            const out = orig(...args);
+            if (isAsyncIterable(out)) {
+                const iter = async function* () {
+                    let final;
+                    for await (const ev of out) {
+                        if (ev.type === "assistant_message") {
+                            final = { message: ev.message };
+                        }
+                        else if (ev.type === "usage") {
+                            final = {
+                                message: { role: "assistant", content: "" },
+                                usage: ev.usage,
+                            };
+                        }
+                        yield ev;
+                    }
+                    if (final)
+                        applyUsage(final, imageCount, imageTokens);
+                };
+                return iter();
+            }
+            return (async () => {
+                const resolved = await out;
+                applyUsage(resolved, imageCount, imageTokens);
+                return resolved;
+            })();
+        }
+        state._origGenerate = orig;
+        ctx.model.generate =
+            withUsage;
+        await next();
+        // Restore
+        ctx.model.generate = orig;
+        if (!state.usage)
+            state.usage = {};
+        state.usage.promptTokens = totals.promptTokens;
+        state.usage.completionTokens = totals.completionTokens;
+        state.usage.totalTokens = totals.totalTokens;
+        if (price)
+            state.usage.costUSD = roundUSD(totals.costUSD ?? 0);
+        if (totals.imageTokens)
+            state.usage.imageTokens = totals.imageTokens;
+        if (totals.imageCount)
+            state.usage.imageCount = totals.imageCount;
+        ctx.log.info?.("[usage] totals", state.usage);
+    };
+}
+function roundUSD(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
+function countImageInputs(msgs) {
+    if (!Array.isArray(msgs))
+        return 0;
+    let count = 0;
+    for (const m of msgs) {
+        const c = m?.content;
+        if (Array.isArray(c)) {
+            for (const part of c) {
+                const partType = part?.type;
+                if (part &&
+                    typeof part === "object" &&
+                    (partType === "image_url" || partType === "image"))
+                    count += 1;
+            }
+        }
+        // Convenience shapes supported by adapters (count regardless of content presence)
+        const anyMsg = m;
+        if (Array.isArray(anyMsg.images))
+            count += anyMsg.images.length;
+        if (typeof anyMsg.image_url === "string")
+            count += 1;
+        if (typeof anyMsg.image === "string")
+            count += 1;
+    }
+    return count;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisu-ai/mw-usage-tracker",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@sisu-ai/core": "^2.4.0"
+    "@sisu-ai/core": "^2.5.0"
   },
   "repository": {
     "type": "git",