kagent-ts 0.1.3 → 0.1.5

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/llm/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,iBAAiB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI3E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACzC,oEAAoE;IACpE,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,iBAAiB,CAAC;CACtD;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EACrC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,CAAC,CAAC,CA+BZ"}

package/dist/llm/retry.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const errors_1 = require("./errors");
+// ─── withRetry ──────────────────────────────────────────────────────────────
+/**
+ * Wrap an async operation with network-error retry logic.
+ *
+ * Retry strategy:
+ * - The `callbacks.isRetryable` predicate decides which errors are retried.
+ * - Uses exponential backoff with full jitter: delay = base * 2^attempt * random(0.5, 1.0).
+ * - Non-retryable errors propagate immediately.
+ * - After all retries are exhausted, throws an `LLMNetworkError`.
+ *
+ * @param fn        The async operation to retry.
+ * @param config    Retry configuration (maxRetries, baseDelayMs, maxDelayMs).
+ * @param callbacks Provider-specific error classification callbacks.
+ */
+async function withRetry(fn, config, callbacks) {
+    const { maxRetries, baseDelayMs, maxDelayMs } = config;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Non-network errors propagate immediately (e.g., invalid API key, bad request)
+            if (!callbacks.isRetryable(error))
+                throw error;
+            if (attempt >= maxRetries)
+                break; // all retries exhausted
+            // Exponential backoff with full jitter
+            const delay = Math.min(baseDelayMs * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5), maxDelayMs);
+            // eslint-disable-next-line @typescript-eslint/no-loop-func
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    // All retries exhausted — wrap the final error
+    const cause = callbacks.classifyError(lastError);
+    const message = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new errors_1.LLMNetworkError(message, cause);
+}
+//# sourceMappingURL=retry.js.map

package/dist/llm/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/llm/retry.ts"],"names":[],"mappings":";;AA8BA,8BAmCC;AAjED,qCAA2E;AAe3E,+EAA+E;AAE/E;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,SAAS,CAC7B,EAAqC,EACrC,MAA6B,EAC7B,SAAyB;IAEzB,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IACvD,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,SAAS,GAAG,KAAK,CAAC;YAElB,gFAAgF;YAChF,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAE/C,IAAI,OAAO,IAAI,UAAU;gBAAE,MAAM,CAAC,wBAAwB;YAE1D,uCAAuC;YACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,EAChE,UAAU,CACX,CAAC;YAEF,2DAA2D;YAC3D,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,OAAO,GACX,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACrE,MAAM,IAAI,wBAAe,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC5C,CAAC"}

package/dist/llm/token-budget.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Token Budget — session-level circuit breaker that stops LLM calls when
+ * a cumulative token limit is exceeded.
+ *
+ * The check runs in the agent loop BEFORE each LLM call (with an estimated
+ * input size) and usage is recorded AFTER each successful response (using
+ * the actual token counts from the LLM provider).
+ */
+export interface TokenBudgetConfig {
+    /** Maximum total tokens allowed across all LLM calls in a session (input + output). */
+    maxTotalTokens: number;
+    /**
+     * Warn via the logger when usage exceeds this fraction of the budget.
+     * Default: 0.8 (80 %).
+     */
+    warnThreshold?: number;
+    /**
+     * Pricing model for cost estimation.
+     * Prices are per 1,000 tokens (standard LLM pricing unit).
+     *
+     * @example
+     * ```ts
+     * // GPT-4o
+     * pricing: { inputPricePer1K: 0.0025, outputPricePer1K: 0.01 }
+     * ```
+     */
+    pricing?: {
+        inputPricePer1K: number;
+        outputPricePer1K: number;
+    };
+}
+export interface TokenBudgetStatus {
+    /** Total tokens consumed so far (input + output). */
+    totalTokensUsed: number;
+    /** Budget ceiling. */
+    maxTotalTokens: number;
+    /** Tokens remaining before exhaustion. */
+    remainingTokens: number;
+    /** Whether the budget has been fully exhausted. */
+    isExhausted: boolean;
+    /** Number of LLM calls tracked. */
+    callCount: number;
+}
+/** Cumulative cost breakdown for the current session. */
+export interface TokenBudgetCost {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+}
+export declare class TokenBudget {
+    private maxTotalTokens;
+    private warnThreshold;
+    private pricing?;
+    private totalTokensUsed;
+    private inputTokensUsed;
+    private outputTokensUsed;
+    private callCount;
+    private warned;
+    constructor(config: TokenBudgetConfig);
+    /**
+     * Record token usage from a completed LLM call.
+     * Called after the LLM response is received.
+     */
+    recordUsage(promptTokens: number, completionTokens: number): void;
+    /**
+     * Check whether the budget allows another LLM call.
+     *
+     * @param estimatedInputTokens  Estimated tokens in the upcoming request
+     *                              (system prompt + context messages).
+     * @returns Status snapshot. Callers should check `isExhausted` before
+     *          making the LLM call.
+     */
+    checkBeforeCall(estimatedInputTokens: number): TokenBudgetStatus;
+    /**
+     * Whether the budget has been warned about (passed `warnThreshold`).
+     * Returns true exactly once per threshold crossing — the flag resets
+     * after this call so the warning fires only once.
+     */
+    shouldWarn(): boolean;
+    /**
+     * Get the cumulative cost of the current session.
+     * Returns all zeros if no pricing model was configured.
+     */
+    getSessionCost(): TokenBudgetCost;
+    /**
+     * Reset the budget for a new conversation.
+     */
+    reset(): void;
+    /**
+     * Get a read-only snapshot of the current budget.
+     */
+    getStatus(): TokenBudgetStatus;
+}
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/llm/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../../src/llm/token-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE;QACR,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,WAAW,EAAE,OAAO,CAAC;IACrB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAC,CAAwD;IACxE,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,iBAAiB;IAQrC;;;OAGG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAOjE;;;;;;;OAOG;IACH,eAAe,CAAC,oBAAoB,EAAE,MAAM,GAAG,iBAAiB;IAWhE;;;;OAIG;IACH,UAAU,IAAI,OAAO;IAUrB;;;OAGG;IACH,cAAc,IAAI,eAAe;IAkBjC;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,SAAS,IAAI,iBAAiB;CAS/B"}

package/dist/llm/token-budget.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Token Budget — session-level circuit breaker that stops LLM calls when
+ * a cumulative token limit is exceeded.
+ *
+ * The check runs in the agent loop BEFORE each LLM call (with an estimated
+ * input size) and usage is recorded AFTER each successful response (using
+ * the actual token counts from the LLM provider).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenBudget = void 0;
+// ─── TokenBudget ─────────────────────────────────────────────────────────────
+class TokenBudget {
+    maxTotalTokens;
+    warnThreshold;
+    pricing;
+    totalTokensUsed = 0;
+    inputTokensUsed = 0;
+    outputTokensUsed = 0;
+    callCount = 0;
+    warned = false;
+    constructor(config) {
+        this.maxTotalTokens = config.maxTotalTokens;
+        this.warnThreshold = config.warnThreshold ?? 0.8;
+        this.pricing = config.pricing;
+    }
+    // ─── Public API ──────────────────────────────────────────────────────────
+    /**
+     * Record token usage from a completed LLM call.
+     * Called after the LLM response is received.
+     */
+    recordUsage(promptTokens, completionTokens) {
+        this.totalTokensUsed += promptTokens + completionTokens;
+        this.inputTokensUsed += promptTokens;
+        this.outputTokensUsed += completionTokens;
+        this.callCount++;
+    }
+    /**
+     * Check whether the budget allows another LLM call.
+     *
+     * @param estimatedInputTokens  Estimated tokens in the upcoming request
+     *                              (system prompt + context messages).
+     * @returns Status snapshot. Callers should check `isExhausted` before
+     *          making the LLM call.
+     */
+    checkBeforeCall(estimatedInputTokens) {
+        const projected = this.totalTokensUsed + estimatedInputTokens;
+        return {
+            totalTokensUsed: this.totalTokensUsed,
+            maxTotalTokens: this.maxTotalTokens,
+            remainingTokens: Math.max(0, this.maxTotalTokens - projected),
+            isExhausted: projected >= this.maxTotalTokens,
+            callCount: this.callCount,
+        };
+    }
+    /**
+     * Whether the budget has been warned about (passed `warnThreshold`).
+     * Returns true exactly once per threshold crossing — the flag resets
+     * after this call so the warning fires only once.
+     */
+    shouldWarn() {
+        if (this.warned)
+            return false;
+        const ratio = this.totalTokensUsed / this.maxTotalTokens;
+        if (ratio >= this.warnThreshold) {
+            this.warned = true;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get the cumulative cost of the current session.
+     * Returns all zeros if no pricing model was configured.
+     */
+    getSessionCost() {
+        const inputCost = this.pricing
+            ? Math.round(this.inputTokensUsed / 1000 * this.pricing.inputPricePer1K * 10000) / 10000
+            : 0;
+        const outputCost = this.pricing
+            ? Math.round(this.outputTokensUsed / 1000 * this.pricing.outputPricePer1K * 10000) / 10000
+            : 0;
+        return {
+            inputTokens: this.inputTokensUsed,
+            outputTokens: this.outputTokensUsed,
+            totalTokens: this.totalTokensUsed,
+            inputCost,
+            outputCost,
+            totalCost: Math.round((inputCost + outputCost) * 10000) / 10000,
+        };
+    }
+    /**
+     * Reset the budget for a new conversation.
+     */
+    reset() {
+        this.totalTokensUsed = 0;
+        this.inputTokensUsed = 0;
+        this.outputTokensUsed = 0;
+        this.callCount = 0;
+        this.warned = false;
+    }
+    /**
+     * Get a read-only snapshot of the current budget.
+     */
+    getStatus() {
+        return {
+            totalTokensUsed: this.totalTokensUsed,
+            maxTotalTokens: this.maxTotalTokens,
+            remainingTokens: Math.max(0, this.maxTotalTokens - this.totalTokensUsed),
+            isExhausted: this.totalTokensUsed >= this.maxTotalTokens,
+            callCount: this.callCount,
+        };
+    }
+}
+exports.TokenBudget = TokenBudget;
+//# sourceMappingURL=token-budget.js.map

package/dist/llm/token-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.js","sourceRoot":"","sources":["../../src/llm/token-budget.ts"],"names":[],"mappings":"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"}

package/dist/logging/index.d.ts

@@ -0,0 +1,2 @@
+export { Logger, ConsoleLogger, SilentLogger } from "./logger";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/logging/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SilentLogger = exports.ConsoleLogger = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "ConsoleLogger", { enumerable: true, get: function () { return logger_1.ConsoleLogger; } });
+Object.defineProperty(exports, "SilentLogger", { enumerable: true, get: function () { return logger_1.SilentLogger; } });
+//# sourceMappingURL=index.js.map

package/dist/logging/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":";;;AAAA,mCAA+D;AAA9C,uGAAA,aAAa,OAAA;AAAE,sGAAA,YAAY,OAAA"}

package/dist/logging/logger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Structured logger interface for the agent framework.
+ *
+ * All framework-internal logging goes through this interface so consumers
+ * can plug in their own logger (winston, pino, etc.) or silence output
+ * entirely for test environments.
+ */
+export interface Logger {
+    /** Debug-level diagnostic messages (verbose, typically disabled in production). */
+    debug(tag: string, message: string, context?: Record<string, unknown>): void;
+    /** Informational messages about agent lifecycle and progress. */
+    info(tag: string, message: string, context?: Record<string, unknown>): void;
+    /** Warnings — non-fatal issues the operator should know about. */
+    warn(tag: string, message: string, context?: Record<string, unknown>): void;
+    /** Errors — fatal or near-fatal issues requiring attention. */
+    error(tag: string, message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Default logger that writes to `console` with the existing `[Tag]` prefix
+ * convention. Preserves the exact output format of the pre-logger codebase.
+ */
+export declare class ConsoleLogger implements Logger {
+    debug(tag: string, message: string, _context?: Record<string, unknown>): void;
+    info(tag: string, message: string, _context?: Record<string, unknown>): void;
+    warn(tag: string, message: string, _context?: Record<string, unknown>): void;
+    error(tag: string, message: string, _context?: Record<string, unknown>): void;
+}
+/**
+ * Logger that discards all messages. Use in tests or when you want to
+ * suppress all framework output.
+ */
+export declare class SilentLogger implements Logger {
+    debug(_tag: string, _message: string, _context?: Record<string, unknown>): void;
+    info(_tag: string, _message: string, _context?: Record<string, unknown>): void;
+    warn(_tag: string, _message: string, _context?: Record<string, unknown>): void;
+    error(_tag: string, _message: string, _context?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,mFAAmF;IACnF,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7E,iEAAiE;IACjE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE5E,kEAAkE;IAClE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE5E,+DAA+D;IAC/D,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9E;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7E,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5E,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5E,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAG9E;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,MAAM;IACzC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAC/E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAC9E,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAChF"}

package/dist/logging/logger.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SilentLogger = exports.ConsoleLogger = void 0;
+/**
+ * Default logger that writes to `console` with the existing `[Tag]` prefix
+ * convention. Preserves the exact output format of the pre-logger codebase.
+ */
+class ConsoleLogger {
+    debug(tag, message, _context) {
+        console.debug(`[${tag}] ${message}`);
+    }
+    info(tag, message, _context) {
+        console.log(`[${tag}] ${message}`);
+    }
+    warn(tag, message, _context) {
+        console.warn(`[${tag}] ${message}`);
+    }
+    error(tag, message, _context) {
+        console.error(`[${tag}] ${message}`);
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;
+/**
+ * Logger that discards all messages. Use in tests or when you want to
+ * suppress all framework output.
+ */
+class SilentLogger {
+    debug(_tag, _message, _context) { }
+    info(_tag, _message, _context) { }
+    warn(_tag, _message, _context) { }
+    error(_tag, _message, _context) { }
+}
+exports.SilentLogger = SilentLogger;
+//# sourceMappingURL=logger.js.map

package/dist/logging/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":";;;AAqBA;;;GAGG;AACH,MAAa,aAAa;IACxB,KAAK,CAAC,GAAW,EAAE,OAAe,EAAE,QAAkC;QACpE,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,OAAe,EAAE,QAAkC;QACnE,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,OAAe,EAAE,QAAkC;QACnE,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,OAAe,EAAE,QAAkC;QACpE,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;CACF;AAhBD,sCAgBC;AAED;;;GAGG;AACH,MAAa,YAAY;IACvB,KAAK,CAAC,IAAY,EAAE,QAAgB,EAAE,QAAkC,IAAS,CAAC;IAClF,IAAI,CAAC,IAAY,EAAE,QAAgB,EAAE,QAAkC,IAAS,CAAC;IACjF,IAAI,CAAC,IAAY,EAAE,QAAgB,EAAE,QAAkC,IAAS,CAAC;IACjF,KAAK,CAAC,IAAY,EAAE,QAAgB,EAAE,QAAkC,IAAS,CAAC;CACnF;AALD,oCAKC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,4 @@
+export { McpClientManager } from "./mcp-client-manager";
+export { McpConnectionError } from "./mcp-types";
+export type { McpServerConfig, McpConnectionStatus, McpConnectionErrorReport, } from "./mcp-types";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,aAAa,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpConnectionError = exports.McpClientManager = void 0;
+var mcp_client_manager_1 = require("./mcp-client-manager");
+Object.defineProperty(exports, "McpClientManager", { enumerable: true, get: function () { return mcp_client_manager_1.McpClientManager; } });
+var mcp_types_1 = require("./mcp-types");
+Object.defineProperty(exports, "McpConnectionError", { enumerable: true, get: function () { return mcp_types_1.McpConnectionError; } });
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":";;;AAAA,2DAAwD;AAA/C,sHAAA,gBAAgB,OAAA;AACzB,yCAAiD;AAAxC,+GAAA,kBAAkB,OAAA"}

package/dist/mcp/mcp-client-manager.d.ts

@@ -0,0 +1,72 @@
+import { ToolRegistry } from "../tools/tool-registry";
+import { McpServerConfig, McpConnectionStatus, McpConnectionErrorReport } from "./mcp-types";
+import { Logger } from "../logging/logger";
+/**
+ * Manages connections to MCP (Model Context Protocol) servers.
+ *
+ * Lifecycle:
+ * 1. `connectToServer()` / `connectAll()` — connect, discover tools,
+ *    register adapted tools in ToolRegistry
+ * 2. Tools execute via the adapted `Tool` wrapper (delegates to MCP client)
+ * 3. `disconnect()` / `disconnectAll()` — unregister tools, close connections
+ */
+export declare class McpClientManager {
+    /** Active connections keyed by server name. */
+    private connections;
+    /** The ToolRegistry where adapted tools are registered. */
+    private toolRegistry;
+    private logger;
+    constructor(toolRegistry: ToolRegistry, logger?: Logger);
+    /**
+     * Connect to a single MCP server, discover its tools, and register them
+     * in the ToolRegistry with a `{serverName}_` prefix.
+     *
+     * Idempotent — if the server is already connected, this is a no-op.
+     *
+     * @throws McpConnectionError if the config is invalid or the
+     *         connection/tool-discovery fails (only for new connections).
+     */
+    connectToServer(serverName: string, config: McpServerConfig): Promise<void>;
+    /**
+     * Connect to multiple MCP servers. Failures for individual servers are
+     * collected and logged; other servers still connect.
+     *
+     * @returns An array of connection error reports (empty if all succeeded).
+     */
+    connectAll(servers: Record<string, McpServerConfig>): Promise<McpConnectionErrorReport[]>;
+    /**
+     * Disconnect from a single server and unregister its tools.
+     */
+    disconnect(serverName: string): Promise<void>;
+    /**
+     * Disconnect from all MCP servers and unregister all MCP-provided tools.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Check if a specific server is currently connected.
+     */
+    hasServer(serverName: string): boolean;
+    /**
+     * Get connection status for all servers.
+     */
+    getStatus(): McpConnectionStatus[];
+    /**
+     * Whether at least one server is connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Get the number of connected servers.
+     */
+    get connectedCount(): number;
+    /**
+     * Adapt an MCP SDK tool descriptor into the framework's Tool interface.
+     *
+     * The adapted tool's name is `{serverName}_{mcpToolName}` to avoid
+     * collisions between servers and with locally-registered tools.
+     *
+     * The `execute` function closes over the client instance and handles
+     * result content parsing (extracting text from MCP's Content[] array).
+     */
+    private adaptTool;
+}
+//# sourceMappingURL=mcp-client-manager.d.ts.map

package/dist/mcp/mcp-client-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client-manager.d.ts","sourceRoot":"","sources":["../../src/mcp/mcp-client-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EAEzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAiB,MAAM,mBAAmB,CAAC;AAmC1D;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAC3B,+CAA+C;IAC/C,OAAO,CAAC,WAAW,CAA+C;IAElE,2DAA2D;IAC3D,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,MAAM,CAAS;gBAEX,YAAY,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM;IAOvD;;;;;;;;OAQG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IA0EjF;;;;;OAKG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAkB/F;;OAEG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBnD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAItC;;OAEG;IACH,SAAS,IAAI,mBAAmB,EAAE;IAQlC;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAID;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;CAgDlB"}