kagent-ts 0.1.0

package/dist/tools/tool-registry.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = void 0;
+const circuit_breaker_1 = require("./circuit-breaker");
+/**
+ * Registry that manages tool definitions together with circuit breakers.
+ *
+ * Provides:
+ * - Tool registration and lookup
+ * - Safe execution with circuit breaker protection
+ * - Per-tool failure tracking with retry guidance
+ */
+class ToolRegistry {
+    tools = new Map();
+    breakers = new Map();
+    retryCount;
+    errorTracker;
+    /**
+     * @param retryCount Number of retries allowed after the first failure
+     *                    (default: 2 → 3 total attempts before circuit opens).
+     * @param errorTracker Optional ToolErrorTracker for recording failure chains.
+     */
+    constructor(retryCount, errorTracker) {
+        this.retryCount = retryCount ?? 2;
+        this.errorTracker = errorTracker;
+    }
+    /**
+     * Register a tool. Creates a circuit breaker for it automatically.
+     */
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool "${tool.name}" is already registered.`);
+        }
+        this.tools.set(tool.name, tool);
+        this.breakers.set(tool.name, new circuit_breaker_1.CircuitBreaker({
+            toolName: tool.name,
+            retryCount: this.retryCount,
+        }));
+    }
+    /**
+     * Register multiple tools at once.
+     */
+    registerMany(tools) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+    }
+    /**
+     * Get a tool by name. Returns undefined if not found.
+     */
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Get all registered tools (for passing to the LLM).
+     */
+    getTools() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Remove a tool and its circuit breaker.
+     */
+    remove(name) {
+        this.breakers.delete(name);
+        return this.tools.delete(name);
+    }
+    /**
+     * Check if a tool is registered.
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Get the number of registered tools.
+     */
+    get count() {
+        return this.tools.size;
+    }
+    /**
+     * Get all registered tool names.
+     */
+    get toolNames() {
+        return Array.from(this.tools.keys());
+    }
+    // ─── Circuit Breaker ───────────────────────────────────────────────────
+    /**
+     * Execute a tool with circuit-breaker protection and retry guidance.
+     *
+     * - If the circuit is OPEN, returns an error message with a recommendation
+     *   to try a different approach.
+     * - If execution fails and retries remain, returns a message telling the LLM
+     *   to analyze the error and retry with corrected parameters.
+     * - If execution succeeds, records a success (resets failure count).
+     *
+     * @returns The tool's result string, or an error message with retry guidance.
+     */
+    async execute(name, args) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return (`Error: Unknown tool "${name}". Available tools: ${this.toolNames.join(", ")}. ` +
+                `Please check the tool name and try again.`);
+        }
+        const breaker = this.breakers.get(name);
+        // Circuit breaker check — circuit is OPEN
+        if (!breaker.isAvailable) {
+            const status = breaker.getStatus();
+            return (`Error: Tool "${name}" has been automatically disabled after ${status.failureCount} consecutive failures. ` +
+                `It cannot be used again in this session. ` +
+                `Please try a completely different approach that does not rely on this tool. ` +
+                `Available alternatives: ${this.toolNames.filter((n) => n !== name).join(", ") || "none — try a different method."}`);
+        }
+        // Execute with failure tracking and retry guidance
+        try {
+            const result = await tool.execute(args);
+            // Success after previous failures — record recovery + reset breaker
+            if (breaker.currentFailureCount > 0) {
+                // Record recovery in the error tracker
+                if (this.errorTracker) {
+                    const activeTrace = this.errorTracker.getActiveTraceId(name);
+                    if (activeTrace) {
+                        this.errorTracker.recordRecovery(name, activeTrace, `Tool "${name}" executed successfully after ${breaker.currentFailureCount} failure(s).`);
+                    }
+                }
+                breaker.recordSuccess();
+                return (`${result}\n\n` +
+                    `[Tool "${name}" has recovered after previous failures. The failure counter has been reset.]`);
+            }
+            breaker.recordSuccess();
+            return result;
+        }
+        catch (err) {
+            const rawMessage = err instanceof Error ? err.message : String(err);
+            const remaining = breaker.recordFailure();
+            // Record the failure in the error tracker
+            if (this.errorTracker) {
+                this.errorTracker.recordFailure(name, args, rawMessage, remaining);
+            }
+            // Circuit just opened — no retries left
+            if (!breaker.isAvailable) {
+                return (`Error executing tool "${name}": ${rawMessage}\n\n` +
+                    `This was the final attempt. The tool "${name}" is now disabled after ${breaker.currentFailureCount} consecutive failures. ` +
+                    `Please do NOT try to use "${name}" again. Instead, try a different approach or a different tool.`);
+            }
+            // Retries still available — guide the LLM to re-analyze
+            const attemptNum = breaker.currentFailureCount;
+            const totalAllowed = breaker.effectiveThreshold;
+            return (`Error executing tool "${name}": ${rawMessage}\n\n` +
+                `[Retry Guidance] This is attempt ${attemptNum} of ${totalAllowed}. ` +
+                `You have ${remaining} retry attempt${remaining > 1 ? "s" : ""} remaining.\n` +
+                `Please analyze the error above carefully, correct the parameters, and retry. ` +
+                `If you believe the issue is with the input, try a different approach or different arguments.`);
+        }
+    }
+    /**
+     * Get the error tracker instance, if one is configured.
+     */
+    getErrorTracker() {
+        return this.errorTracker;
+    }
+    /**
+     * Get the circuit breaker status for a tool.
+     */
+    getBreakerStatus(name) {
+        return this.breakers.get(name)?.getStatus();
+    }
+    /**
+     * Get status for all tools.
+     */
+    getAllBreakerStatuses() {
+        return Array.from(this.breakers.values()).map((b) => b.getStatus());
+    }
+    /**
+     * Manually reset the circuit breaker for a specific tool.
+     */
+    resetBreaker(name) {
+        this.breakers.get(name)?.reset();
+    }
+    /**
+     * Reset all circuit breakers.
+     */
+    resetAllBreakers() {
+        for (const breaker of this.breakers.values()) {
+            breaker.reset();
+        }
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+//# sourceMappingURL=tool-registry.js.map

package/dist/tools/tool-registry.js.map

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

package/dist/tools/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A tool that an agent can invoke.
+ */
+export interface Tool {
+    /** Unique name of the tool. */
+    name: string;
+    /** Description of what the tool does (used by the LLM to decide when to call it). */
+    description: string;
+    /** JSON Schema describing the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /** Execute the tool with the given arguments and return a result string. */
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+/**
+ * Current state of a circuit breaker for a specific tool.
+ */
+export declare enum BreakerState {
+    /** Normal operation — tool calls are allowed. */
+    CLOSED = "closed",
+    /** Failure threshold reached — tool calls are blocked. */
+    OPEN = "open"
+}
+/**
+ * Status snapshot of a circuit breaker.
+ */
+export interface BreakerStatus {
+    /** Tool name. */
+    toolName: string;
+    /** Current circuit breaker state. */
+    state: BreakerState;
+    /** Current consecutive failure count. */
+    failureCount: number;
+    /** Max failures before the breaker opens. */
+    failureThreshold: number;
+    /** Whether the tool is available for calling. */
+    available: boolean;
+}
+/**
+ * A single event within an error trace chain.
+ */
+export interface TraceEvent {
+    /** Event type. */
+    type: "failure" | "retry" | "recovery" | "circuit_open" | "analysis";
+    /** When the event occurred. */
+    timestamp: string;
+    /** The error message (for failure/retry events). */
+    error?: string;
+    /** The attempt number (1-based). */
+    attemptNumber?: number;
+    /** How many retries remain after this attempt. */
+    retriesRemaining?: number;
+    /** LLM's analysis of the error (captured from agent). */
+    analysis?: string;
+    /** Resolution description (for recovery events). */
+    resolution?: string;
+    /** Arguments used in this attempt (for comparison). */
+    arguments?: Record<string, unknown>;
+}
+/**
+ * Full trace of a tool error chain — from first failure through retries
+ * to either resolution or circuit-open.
+ */
+export interface ToolErrorTrace {
+    /** Unique trace identifier. */
+    traceId: string;
+    /** Name of the tool that failed. */
+    toolName: string;
+    /** Session identifier (if available). */
+    sessionId?: string;
+    /** When the trace was created (first failure). */
+    createdAt: string;
+    /** When the trace was last updated. */
+    updatedAt: string;
+    /** Whether the tool eventually recovered. */
+    resolved: boolean;
+    /** Original arguments that caused the first failure. */
+    originalArguments: Record<string, unknown>;
+    /** All events in this trace, in chronological order. */
+    events: TraceEvent[];
+    /** Eventual resolution description (if resolved). */
+    resolution?: string;
+}
+/**
+ * Lightweight summary of a trace for listing/indexing.
+ */
+export interface ErrorTraceSummary {
+    traceId: string;
+    toolName: string;
+    createdAt: string;
+    resolved: boolean;
+    errorCount: number;
+    firstError: string;
+    resolution?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,4EAA4E;IAC5E,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzD;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,iDAAiD;IACjD,MAAM,WAAW;IACjB,0DAA0D;IAC1D,IAAI,SAAS;CACd;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;CACpB;AAID;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,CAAC;IACrE,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,wDAAwD;IACxD,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/tools/types.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BreakerState = void 0;
+/**
+ * Current state of a circuit breaker for a specific tool.
+ */
+var BreakerState;
+(function (BreakerState) {
+    /** Normal operation — tool calls are allowed. */
+    BreakerState["CLOSED"] = "closed";
+    /** Failure threshold reached — tool calls are blocked. */
+    BreakerState["OPEN"] = "open";
+})(BreakerState || (exports.BreakerState = BreakerState = {}));
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":";;;AAcA;;GAEG;AACH,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,iDAAiD;IACjD,iCAAiB,CAAA;IACjB,0DAA0D;IAC1D,6BAAa,CAAA;AACf,CAAC,EALW,YAAY,4BAAZ,YAAY,QAKvB"}

package/dist/utils/token-counter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Token counting utility.
+ *
+ * Uses the `tiktoken` package for accurate tokenization when available.
+ * Falls back to a simple character-based heuristic (~4 chars/token) on failure.
+ *
+ * The tiktoken module is loaded lazily and cached after the first successful check.
+ */
+/**
+ * Count tokens in a text string.
+ *
+ * Uses tiktoken (by model name) when available, falling back to
+ * a simple ~4 characters-per-token heuristic.
+ *
+ * @param text  The text to count tokens in.
+ * @param model The OpenAI model name for accurate encoding (e.g. "gpt-4o", "gpt-4o-mini").
+ *              Defaults to "gpt-4o". Only used when tiktoken is available.
+ */
+export declare function countTokens(text: string, model?: string): number;
+/**
+ * Count tokens in an array of messages.
+ * For each message, adds a small overhead for the role metadata.
+ *
+ * @param messages Array of message-like objects.
+ * @param model    Optional model name for accurate token counting.
+ */
+export declare function countMessageTokens(messages: {
+    role: string;
+    content: string;
+}[], model?: string): number;
+//# sourceMappingURL=token-counter.d.ts.map

package/dist/utils/token-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.d.ts","sourceRoot":"","sources":["../../src/utils/token-counter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoDH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAchE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,EAC7C,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAUR"}

package/dist/utils/token-counter.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Token counting utility.
+ *
+ * Uses the `tiktoken` package for accurate tokenization when available.
+ * Falls back to a simple character-based heuristic (~4 chars/token) on failure.
+ *
+ * The tiktoken module is loaded lazily and cached after the first successful check.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countTokens = countTokens;
+exports.countMessageTokens = countMessageTokens;
+let _tiktoken = null;
+let _tiktokenChecked = false;
+/**
+ * Try to load the tiktoken module (once, cached).
+ */
+function getTiktokenModule() {
+    if (!_tiktokenChecked) {
+        _tiktokenChecked = true;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            _tiktoken = require("tiktoken");
+        }
+        catch {
+            // tiktoken not available — fallback will be used
+            _tiktoken = null;
+        }
+    }
+    return _tiktoken;
+}
+/**
+ * Encode text via tiktoken and return the token count.
+ * Falls back to heuristic if anything goes wrong.
+ */
+function countWithTiktoken(text, model) {
+    const tk = getTiktokenModule();
+    if (!tk)
+        throw new Error("tiktoken not loaded");
+    let enc;
+    try {
+        // Try to get the encoding for the requested model
+        enc = tk.encoding_for_model(model ?? "gpt-4o");
+    }
+    catch {
+        // Unknown model — use o200k_base (covers GPT-4o, GPT-4o-mini)
+        // Fall back to cl100k_base for older models if o200k_base also fails
+        try {
+            enc = tk.get_encoding("o200k_base");
+        }
+        catch {
+            enc = tk.get_encoding("cl100k_base");
+        }
+    }
+    try {
+        return enc.encode(text).length;
+    }
+    finally {
+        // Free the encoder to avoid memory leaks (tiktoken is wasm-backed)
+        enc.free();
+    }
+}
+/**
+ * Count tokens in a text string.
+ *
+ * Uses tiktoken (by model name) when available, falling back to
+ * a simple ~4 characters-per-token heuristic.
+ *
+ * @param text  The text to count tokens in.
+ * @param model The OpenAI model name for accurate encoding (e.g. "gpt-4o", "gpt-4o-mini").
+ *              Defaults to "gpt-4o". Only used when tiktoken is available.
+ */
+function countTokens(text, model) {
+    if (!text)
+        return 0;
+    // Try tiktoken first
+    if (getTiktokenModule()) {
+        try {
+            return countWithTiktoken(text, model);
+        }
+        catch {
+            // tiktoken failed — fall through to heuristic
+        }
+    }
+    // Heuristic fallback: ~4 characters per token (standard English approximation)
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Count tokens in an array of messages.
+ * For each message, adds a small overhead for the role metadata.
+ *
+ * @param messages Array of message-like objects.
+ * @param model    Optional model name for accurate token counting.
+ */
+function countMessageTokens(messages, model) {
+    // Per-message format overhead (role tag, spacing, etc.)
+    const PER_MESSAGE_OVERHEAD = 3;
+    let total = 0;
+    for (const msg of messages) {
+        total += PER_MESSAGE_OVERHEAD;
+        total += countTokens(msg.content, model);
+    }
+    return total;
+}
+//# sourceMappingURL=token-counter.js.map

package/dist/utils/token-counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.js","sourceRoot":"","sources":["../../src/utils/token-counter.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AA8DH,kCAcC;AASD,gDAaC;AAhGD,IAAI,SAAS,GAAQ,IAAI,CAAC;AAC1B,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAE7B;;GAEG;AACH,SAAS,iBAAiB;IACxB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,gBAAgB,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC;YACH,8DAA8D;YAC9D,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;YACjD,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,IAAY,EAAE,KAAc;IACrD,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAC/B,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAEhD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,kDAAkD;QAClD,GAAG,GAAG,EAAE,CAAC,kBAAkB,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;QAC9D,qEAAqE;QACrE,IAAI,CAAC;YACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,mEAAmE;QACnE,GAAG,CAAC,IAAI,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,WAAW,CAAC,IAAY,EAAE,KAAc;IACtD,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IAEpB,qBAAqB;IACrB,IAAI,iBAAiB,EAAE,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;QAChD,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAChC,QAA6C,EAC7C,KAAc;IAEd,wDAAwD;IACxD,MAAM,oBAAoB,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,KAAK,IAAI,oBAAoB,CAAC;QAC9B,KAAK,IAAI,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "kagent-ts",
+  "version": "0.1.0",
+  "description": "A TypeScript agent framework — ReAct / Plan-Solve agent loops, tool management with circuit breaker, session persistence and resume, file-based progressive skills, and user preference injection.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build",
+    "test": "echo \"No tests yet — see src/ for manual test patterns\""
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "react",
+    "plan-solve",
+    "ai",
+    "framework",
+    "typescript",
+    "openai",
+    "agents",
+    "tool-use"
+  ],
+  "license": "MIT",
+  "author": "kyk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kkhhhh-ll/kagent-ts"
+  },
+  "homepage": "https://github.com/kkhhhh-ll/kagent-ts#readme",
+  "bugs": {
+    "url": "https://github.com/kkhhhh-ll/kagent-ts/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openai": "^4.80.0"
+  },
+  "optionalDependencies": {
+    "tiktoken": "^1.0.22"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}