kagent-ts 0.1.0

package/dist/tools/circuit-breaker.d.ts

@@ -0,0 +1,77 @@
+import { BreakerState, BreakerStatus } from "./types";
+/**
+ * Configuration for a circuit breaker instance.
+ */
+export interface CircuitBreakerConfig {
+    /** Tool name this breaker protects. */
+    toolName: string;
+    /**
+     * Number of retries allowed after the first failure.
+     * The effective maximum attempts = retryCount + 1.
+     * Default: 2 (3 total attempts before the circuit opens).
+     */
+    retryCount?: number;
+}
+/**
+ * Circuit breaker that tracks consecutive failures for a single tool.
+ *
+ * States:
+ * - CLOSED: Normal operation — executions are allowed.
+ * - OPEN:   All retries exhausted — subsequent calls are blocked
+ *           without attempting execution.
+ *
+ * Flow:
+ *   1st failure → 2 retries remaining → LLM should analyze the error and retry
+ *   2nd failure → 1 retry remaining
+ *   3rd failure → circuit OPENS → LLM must try a different approach
+ *   Success → failure count resets to zero
+ */
+export declare class CircuitBreaker {
+    private toolName;
+    private retryCount;
+    private failureCount;
+    private _state;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Whether the circuit is closed and the tool can be called.
+     */
+    get isAvailable(): boolean;
+    /**
+     * Current breaker state.
+     */
+    get state(): BreakerState;
+    /**
+     * Current consecutive failure count.
+     */
+    get currentFailureCount(): number;
+    /**
+     * How many retries remain before the circuit opens.
+     * When this reaches 0 and another failure occurs, the circuit opens.
+     */
+    get retriesRemaining(): number;
+    /**
+     * The total number of consecutive failures that would open the circuit.
+     */
+    get effectiveThreshold(): number;
+    /**
+     * Record a successful tool execution — resets failure count
+     * and closes the circuit if it was open.
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed tool execution.
+     * If all retries are exhausted, the circuit opens.
+     *
+     * @returns The updated number of retries remaining (0 means the circuit opened).
+     */
+    recordFailure(): number;
+    /**
+     * Manually reset the breaker back to CLOSED.
+     */
+    reset(): void;
+    /**
+     * Get a snapshot of the current breaker status.
+     */
+    getStatus(): BreakerStatus;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/tools/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/tools/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,MAAM,CAAqC;gBAEvC,MAAM,EAAE,oBAAoB;IAKxC;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,YAAY,CAExB;IAED;;OAEG;IACH,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED;;;OAGG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;OAEG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;;OAGG;IACH,aAAa,IAAI,IAAI;IAKrB;;;;;OAKG;IACH,aAAa,IAAI,MAAM;IASvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,SAAS,IAAI,aAAa;CAS3B"}

package/dist/tools/circuit-breaker.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = void 0;
+const types_1 = require("./types");
+/**
+ * Circuit breaker that tracks consecutive failures for a single tool.
+ *
+ * States:
+ * - CLOSED: Normal operation — executions are allowed.
+ * - OPEN:   All retries exhausted — subsequent calls are blocked
+ *           without attempting execution.
+ *
+ * Flow:
+ *   1st failure → 2 retries remaining → LLM should analyze the error and retry
+ *   2nd failure → 1 retry remaining
+ *   3rd failure → circuit OPENS → LLM must try a different approach
+ *   Success → failure count resets to zero
+ */
+class CircuitBreaker {
+    toolName;
+    retryCount;
+    failureCount = 0;
+    _state = types_1.BreakerState.CLOSED;
+    constructor(config) {
+        this.toolName = config.toolName;
+        this.retryCount = config.retryCount ?? 2;
+    }
+    /**
+     * Whether the circuit is closed and the tool can be called.
+     */
+    get isAvailable() {
+        return this._state === types_1.BreakerState.CLOSED;
+    }
+    /**
+     * Current breaker state.
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Current consecutive failure count.
+     */
+    get currentFailureCount() {
+        return this.failureCount;
+    }
+    /**
+     * How many retries remain before the circuit opens.
+     * When this reaches 0 and another failure occurs, the circuit opens.
+     */
+    get retriesRemaining() {
+        return Math.max(0, this.retryCount - this.failureCount);
+    }
+    /**
+     * The total number of consecutive failures that would open the circuit.
+     */
+    get effectiveThreshold() {
+        return this.retryCount + 1;
+    }
+    /**
+     * Record a successful tool execution — resets failure count
+     * and closes the circuit if it was open.
+     */
+    recordSuccess() {
+        this.failureCount = 0;
+        this._state = types_1.BreakerState.CLOSED;
+    }
+    /**
+     * Record a failed tool execution.
+     * If all retries are exhausted, the circuit opens.
+     *
+     * @returns The updated number of retries remaining (0 means the circuit opened).
+     */
+    recordFailure() {
+        this.failureCount++;
+        if (this.failureCount > this.retryCount) {
+            this._state = types_1.BreakerState.OPEN;
+            return 0;
+        }
+        return this.retriesRemaining;
+    }
+    /**
+     * Manually reset the breaker back to CLOSED.
+     */
+    reset() {
+        this.failureCount = 0;
+        this._state = types_1.BreakerState.CLOSED;
+    }
+    /**
+     * Get a snapshot of the current breaker status.
+     */
+    getStatus() {
+        return {
+            toolName: this.toolName,
+            state: this._state,
+            failureCount: this.failureCount,
+            failureThreshold: this.effectiveThreshold,
+            available: this.isAvailable,
+        };
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/tools/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/tools/circuit-breaker.ts"],"names":[],"mappings":";;;AAAA,mCAAsD;AAiBtD;;;;;;;;;;;;;GAaG;AACH,MAAa,cAAc;IACjB,QAAQ,CAAS;IACjB,UAAU,CAAS;IACnB,YAAY,GAAG,CAAC,CAAC;IACjB,MAAM,GAAiB,oBAAY,CAAC,MAAM,CAAC;IAEnD,YAAY,MAA4B;QACtC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,KAAK,oBAAY,CAAC,MAAM,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,mBAAmB;QACrB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,IAAI,kBAAkB;QACpB,OAAO,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,oBAAY,CAAC,MAAM,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,aAAa;QACX,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,GAAG,oBAAY,CAAC,IAAI,CAAC;YAChC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,oBAAY,CAAC,MAAM,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,gBAAgB,EAAE,IAAI,CAAC,kBAAkB;YACzC,SAAS,EAAE,IAAI,CAAC,WAAW;SAC5B,CAAC;IACJ,CAAC;CACF;AA3FD,wCA2FC"}

package/dist/tools/error-tracker.d.ts

@@ -0,0 +1,116 @@
+import { ToolErrorTrace, ErrorTraceSummary } from "./types";
+/**
+ * Configuration for the ToolErrorTracker.
+ */
+export interface ErrorTrackerConfig {
+    /**
+     * Directory where trace files are stored.
+     * Defaults to `.error-traces` relative to the working directory.
+     */
+    storageDir?: string;
+    /**
+     * Whether to persist traces to disk immediately.
+     * Defaults to true.
+     */
+    persistImmediately?: boolean;
+}
+/**
+ * Categorize a tool error based on its message content.
+ * Helps developers quickly identify common failure patterns.
+ */
+export declare function categorizeError(error: string): string;
+/**
+ * ToolErrorTracker records the complete lifecycle of tool failures.
+ *
+ * Usage:
+ * ```ts
+ * const tracker = new ToolErrorTracker({ storageDir: ".error-traces" });
+ * const registry = new ToolRegistry({ errorTracker: tracker });
+ * ```
+ *
+ * Lifecycle of a trace:
+ * 1. First failure  → `recordFailure()` creates a new trace
+ * 2. LLM analysis   → `recordAnalysis()` attaches the LLM's reasoning
+ * 3. Retry failure  → `recordFailure()` appends to the existing trace
+ * 4. Recovery       → `recordRecovery()` marks the trace as resolved
+ * 5. Circuit open   → `recordFailure()` marks the trace as unresolved
+ *
+ * All traces are persisted as individual JSON files in the storage
+ * directory, plus an index file for quick browsing.
+ */
+export declare class ToolErrorTracker {
+    private traces;
+    private activeTraceByTool;
+    private storageDir;
+    private persistImmediately;
+    private sessionId?;
+    constructor(config?: ErrorTrackerConfig);
+    /**
+     * Set a session identifier that will be attached to all traces.
+     */
+    setSessionId(id: string): void;
+    /**
+     * Record a tool execution failure.
+     *
+     * - If this is the first failure for the tool in the current chain,
+     *   a new trace is created.
+     * - If a trace for this tool already exists and is still open,
+     *   the failure is appended as a retry event.
+     *
+     * @returns The trace ID for the chain this failure belongs to.
+     */
+    recordFailure(toolName: string, args: Record<string, unknown>, error: string, retriesRemaining: number): string;
+    /**
+     * Record a tool recovery (successful execution after previous failures).
+     *
+     * @param toolName The tool that recovered.
+     * @param traceId  The trace ID for this failure chain.
+     * @param resolution Optional description of how it was resolved.
+     */
+    recordRecovery(toolName: string, traceId: string, resolution?: string): void;
+    /**
+     * Attach LLM analysis to the latest failure/retry event in a trace.
+     *
+     * Called by the agent after the LLM has reasoned about a tool error.
+     */
+    recordAnalysis(traceId: string, analysis: string): void;
+    /**
+     * Get a full trace by ID.
+     */
+    getTrace(traceId: string): ToolErrorTrace | undefined;
+    /**
+     * Get all trace summaries — lightweight list for browsing.
+     */
+    getAllSummaries(): ErrorTraceSummary[];
+    /**
+     * Get the active (open, unresolved) trace ID for a tool, if any.
+     */
+    getActiveTraceId(toolName: string): string | undefined;
+    /**
+     * Get the total number of traces recorded.
+     */
+    get traceCount(): number;
+    /**
+     * Persist all traces to disk immediately.
+     */
+    persistAll(): void;
+    /**
+     * Load traces from disk (e.g., on startup to resume monitoring).
+     */
+    loadFromDisk(): void;
+    /**
+     * Generate a human-readable markdown report of all traces.
+     */
+    generateMarkdownReport(): string;
+    /**
+     * Delete all stored traces.
+     */
+    clearAll(): void;
+    private createTrace;
+    private persistTrace;
+    private ensureStorageDir;
+    private writeTraceFile;
+    private writeIndexFile;
+    private formatEventType;
+}
+//# sourceMappingURL=error-tracker.d.ts.map

package/dist/tools/error-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-tracker.d.ts","sourceRoot":"","sources":["../../src/tools/error-tracker.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,cAAc,EAEd,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAoDD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA6BrD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAAU;IACpC,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,MAAM,CAAC,EAAE,kBAAkB;IAKvC;;OAEG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAM9B;;;;;;;;;OASG;IACH,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,GACvB,MAAM;IA6CT;;;;;;OAMG;IACH,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI;IAsBP;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IA4BvD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIrD;;OAEG;IACH,eAAe,IAAI,iBAAiB,EAAE;IAyBtC;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAItD;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAID;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACH,YAAY,IAAI,IAAI;IAyBpB;;OAEG;IACH,sBAAsB,IAAI,MAAM;IA4DhC;;OAEG;IACH,QAAQ,IAAI,IAAI;IAoBhB,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,eAAe;CAkBxB"}