kagent-ts 0.1.2 → 0.1.4

package/dist/trace/trace-logger.d.ts

@@ -0,0 +1,92 @@
+import { AgentHooks } from "../core/hooks";
+import { LLMResponse } from "../llm/interface";
+import { LLMNetworkError } from "../llm/openai-provider";
+import { MessageData } from "../messages/types";
+import { Tool } from "../tools/types";
+import { AgentTraceEvent } from "./types";
+/**
+ * Configuration for the TraceLogger.
+ */
+export interface TraceLoggerConfig {
+    /**
+     * Session identifier used in the trace file name.
+     * Defaults to `trace-<timestamp>-<random>`.
+     */
+    sessionId?: string;
+    /**
+     * Output directory for trace HTML files.
+     * Defaults to `.kagent-traces/`.
+     */
+    outputDir?: string;
+    /**
+     * Optional agent label shown in the trace report header.
+     */
+    agentLabel?: string;
+    /**
+     * Optional model name shown in the trace report header.
+     */
+    modelName?: string;
+}
+/**
+ * TraceLogger — records the agent's execution trajectory and generates
+ * a self-contained HTML report per session.
+ *
+ * Implements AgentHooks so it can be plugged directly into an Agent:
+ *
+ * ```ts
+ * const traceLogger = new TraceLogger({ sessionId: "my-session" });
+ * const agent = new ReActAgent({
+ *   llm: provider,
+ *   hooks: traceLogger,  // <-- hooks in as the observer
+ * });
+ * const answer = await agent.run("...");
+ * traceLogger.flush(); // writes .kagent-traces/my-session.html
+ * ```
+ *
+ * The HTML report is a standalone file with no external dependencies —
+ * all CSS and JS are inlined. It shows a vertical timeline of all events
+ * (LLM calls, tool executions, thoughts, errors) with expandable details
+ * for each.
+ */
+export declare class TraceLogger implements AgentHooks {
+    private events;
+    private eventId;
+    private sessionId;
+    private outputDir;
+    private agentLabel;
+    private modelName;
+    private startTime;
+    constructor(config?: TraceLoggerConfig);
+    /**
+     * Get the session identifier for this trace.
+     */
+    getSessionId(): string;
+    /**
+     * Get all recorded events.
+     */
+    getEvents(): AgentTraceEvent[];
+    /**
+     * Flush the trace to an HTML file on disk.
+     * Creates the output directory if it doesn't exist.
+     *
+     * @returns The absolute path to the generated HTML file.
+     */
+    flush(): string;
+    onLLMStart(messages: MessageData[], tools: Tool[]): void;
+    onLLMEnd(response: LLMResponse): void;
+    onLLMError(error: LLMNetworkError): void;
+    onToolStart(toolName: string, args: Record<string, unknown>): void;
+    onToolEnd(toolName: string, result: string): void;
+    onToolError(toolName: string, error: string): void;
+    onThought(thought: string): void;
+    onPlanCreated(plan: string[]): void;
+    onPlanRevised(plan: string[]): void;
+    onFinish(answer: string): void;
+    private addEvent;
+    private generateHTML;
+    private renderEventCard;
+    private eventIcon;
+    private escapeHtml;
+    private syntaxHighlight;
+}
+//# sourceMappingURL=trace-logger.d.ts.map

package/dist/trace/trace-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-logger.d.ts","sourceRoot":"","sources":["../../src/trace/trace-logger.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,eAAe,EAAuB,MAAM,SAAS,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,CAAC,EAAE,iBAAiB;IAatC;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,SAAS,IAAI,eAAe,EAAE;IAI9B;;;;;OAKG;IACH,KAAK,IAAI,MAAM;IAWf,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAkBxD,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAQrC,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAQxC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOlE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQjD,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAOlD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIhC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAInC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAInC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO9B,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,YAAY;IAgJpB,OAAO,CAAC,eAAe;IAsHvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,eAAe;CAkBxB"}

package/dist/trace/trace-logger.js

@@ -0,0 +1,463 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceLogger = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * TraceLogger — records the agent's execution trajectory and generates
+ * a self-contained HTML report per session.
+ *
+ * Implements AgentHooks so it can be plugged directly into an Agent:
+ *
+ * ```ts
+ * const traceLogger = new TraceLogger({ sessionId: "my-session" });
+ * const agent = new ReActAgent({
+ *   llm: provider,
+ *   hooks: traceLogger,  // <-- hooks in as the observer
+ * });
+ * const answer = await agent.run("...");
+ * traceLogger.flush(); // writes .kagent-traces/my-session.html
+ * ```
+ *
+ * The HTML report is a standalone file with no external dependencies —
+ * all CSS and JS are inlined. It shows a vertical timeline of all events
+ * (LLM calls, tool executions, thoughts, errors) with expandable details
+ * for each.
+ */
+class TraceLogger {
+    events = [];
+    eventId = 0;
+    sessionId;
+    outputDir;
+    agentLabel;
+    modelName;
+    startTime;
+    constructor(config) {
+        const ts = Date.now();
+        const rand = Math.random().toString(36).slice(2, 6);
+        this.sessionId =
+            config?.sessionId ?? `trace-${ts}-${rand}`;
+        this.outputDir = path.resolve(config?.outputDir ?? ".kagent-traces");
+        this.agentLabel = config?.agentLabel ?? "Agent";
+        this.modelName = config?.modelName ?? "unknown";
+        this.startTime = ts;
+    }
+    // ─── Public API ──────────────────────────────────────────────────────────
+    /**
+     * Get the session identifier for this trace.
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get all recorded events.
+     */
+    getEvents() {
+        return [...this.events];
+    }
+    /**
+     * Flush the trace to an HTML file on disk.
+     * Creates the output directory if it doesn't exist.
+     *
+     * @returns The absolute path to the generated HTML file.
+     */
+    flush() {
+        const html = this.generateHTML();
+        fs.mkdirSync(this.outputDir, { recursive: true });
+        const filePath = path.join(this.outputDir, `${this.sessionId}.html`);
+        fs.writeFileSync(filePath, html, "utf-8");
+        console.log(`[Trace] Saved session trace → ${filePath}`);
+        return filePath;
+    }
+    // ─── AgentHooks Implementation ─────────────────────────────────────────
+    onLLMStart(messages, tools) {
+        this.addEvent("llm_start", "LLM Call", {
+            messageCount: messages.length,
+            toolCount: tools.length,
+            messages: messages.map((m) => ({
+                role: m.role,
+                content: m.content,
+                tool_calls: m.tool_calls,
+                tool_call_id: m.tool_call_id,
+                name: m.name,
+            })),
+            tools: tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+            })),
+        });
+    }
+    onLLMEnd(response) {
+        this.addEvent("llm_end", "LLM Response", {
+            content: response.content,
+            tool_calls: response.tool_calls,
+            usage: response.usage,
+        });
+    }
+    onLLMError(error) {
+        this.addEvent("llm_error", "LLM Error", {
+            cause: error.cause,
+            message: error.message,
+        });
+        this.flush();
+    }
+    onToolStart(toolName, args) {
+        this.addEvent("tool_start", `Tool: ${toolName}`, {
+            toolName,
+            args,
+        });
+    }
+    onToolEnd(toolName, result) {
+        this.addEvent("tool_end", `Tool Result: ${toolName}`, {
+            toolName,
+            result: result.length > 2000 ? result.slice(0, 2000) + "\n... (truncated)" : result,
+            resultLength: result.length,
+        });
+    }
+    onToolError(toolName, error) {
+        this.addEvent("tool_error", `Tool Error: ${toolName}`, {
+            toolName,
+            error,
+        });
+    }
+    onThought(thought) {
+        this.addEvent("thought", "Thought", { thought });
+    }
+    onPlanCreated(plan) {
+        this.addEvent("plan_created", "Plan Created", { plan });
+    }
+    onPlanRevised(plan) {
+        this.addEvent("plan_revised", "Plan Revised", { plan });
+    }
+    onFinish(answer) {
+        this.addEvent("finish", "Final Answer", { answer });
+        this.flush();
+    }
+    // ─── Private Helpers ─────────────────────────────────────────────────────
+    addEvent(type, label, data) {
+        this.events.push({
+            id: ++this.eventId,
+            timestamp: new Date().toISOString(),
+            type,
+            label,
+            data,
+        });
+    }
+    // ─── HTML Generation ────────────────────────────────────────────────────
+    generateHTML() {
+        const duration = ((Date.now() - this.startTime) / 1000).toFixed(1);
+        const eventCards = this.events.map((e) => this.renderEventCard(e)).join("\n");
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Session Trace — ${this.sessionId}</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #0d1117; color: #c9d1d9; line-height: 1.6; padding: 24px;
+  }
+  .container { max-width: 960px; margin: 0 auto; }
+
+  /* ── Header ── */
+  .header {
+    background: linear-gradient(135deg, #161b22, #1c2333);
+    border: 1px solid #30363d; border-radius: 12px; padding: 24px 28px;
+    margin-bottom: 28px;
+  }
+  .header h1 { font-size: 20px; margin-bottom: 8px; display: flex; align-items: center; gap: 10px; }
+  .header h1 span { background: #238636; color: #fff; font-size: 11px; padding: 2px 8px; border-radius: 20px; }
+  .header .meta { display: flex; flex-wrap: wrap; gap: 16px; font-size: 13px; color: #8b949e; }
+  .header .meta .item { display: flex; align-items: center; gap: 4px; }
+  .header .meta .item strong { color: #c9d1d9; }
+
+  /* ── Timeline ── */
+  .timeline { position: relative; padding-left: 36px; }
+  .timeline::before {
+    content: ''; position: absolute; left: 14px; top: 8px; bottom: 8px;
+    width: 2px; background: #21262d;
+  }
+
+  /* ── Event Card ── */
+  .event { position: relative; margin-bottom: 12px; }
+  .event-dot {
+    position: absolute; left: -26px; top: 14px; width: 12px; height: 12px;
+    border-radius: 50%; border: 2px solid #30363d; background: #0d1117; z-index: 1;
+  }
+  .event-body {
+    background: #161b22; border: 1px solid #30363d; border-radius: 8px;
+    padding: 12px 16px; cursor: pointer; transition: border-color .15s;
+  }
+  .event-body:hover { border-color: #58a6ff; }
+  .event-header {
+    display: flex; align-items: center; gap: 8px; font-size: 13px;
+    user-select: none;
+  }
+  .event-header .icon { font-size: 16px; flex-shrink: 0; }
+  .event-header .label { flex: 1; font-weight: 600; color: #e6edf3; }
+  .event-header .time { color: #8b949e; font-size: 11px; font-family: monospace; }
+  .event-header .toggle { color: #8b949e; font-size: 12px; }
+  .event-detail {
+    display: none; margin-top: 10px; border-top: 1px solid #21262d;
+    padding-top: 10px; font-size: 13px;
+  }
+  .event.open .event-detail { display: block; }
+  .event.open .toggle { transform: rotate(90deg); }
+
+  /* ── Detail Blocks ── */
+  .detail-section { margin-bottom: 10px; }
+  .detail-section:last-child { margin-bottom: 0; }
+  .detail-section h4 { font-size: 11px; text-transform: uppercase; color: #8b949e; margin-bottom: 4px; letter-spacing: .5px; }
+  pre {
+    background: #0d1117; border: 1px solid #21262d; border-radius: 6px;
+    padding: 10px 12px; font-family: 'JetBrains Mono', 'Fira Code', monospace;
+    font-size: 12px; overflow-x: auto; white-space: pre-wrap; word-break: break-all;
+    color: #e6edf3; max-height: 400px; overflow-y: auto;
+  }
+  pre .key { color: #79c0ff; }
+  pre .string { color: #a5d6ff; }
+  pre .number { color: #79c0ff; }
+  pre .null { color: #d2a8ff; }
+  pre .bool { color: #d2a8ff; }
+
+  /* ── Event-type color accents ── */
+  .event-type-llm_start .event-dot { border-color: #58a6ff; background: #1f6feb; }
+  .event-type-llm_end .event-dot { border-color: #58a6ff; background: #1f6feb; }
+  .event-type-llm_error .event-dot { border-color: #f85149; background: #da3633; }
+  .event-type-tool_start .event-dot { border-color: #d29922; background: #9e6a03; }
+  .event-type-tool_end .event-dot { border-color: #3fb950; background: #238636; }
+  .event-type-tool_error .event-dot { border-color: #f85149; background: #da3633; }
+  .event-type-thought .event-dot { border-color: #bc8cff; background: #8957e5; }
+  .event-type-plan_created .event-dot { border-color: #79c0ff; background: #1f6feb; }
+  .event-type-plan_revised .event-dot { border-color: #f0883e; background: #bd6200; }
+  .event-type-finish .event-dot { border-color: #3fb950; background: #238636; }
+
+  .event-type-llm_error .event-body { border-color: #f85149; }
+  .event-type-tool_error .event-body { border-color: #f85149; }
+
+  /* ── Plan steps list ── */
+  ol.plan-steps { padding-left: 20px; margin: 4px 0; }
+  ol.plan-steps li { margin-bottom: 2px; color: #e6edf3; }
+
+  /* ── Tool call args table ── */
+  .kv-table { width: 100%; border-collapse: collapse; font-size: 12px; }
+  .kv-table th, .kv-table td {
+    text-align: left; padding: 4px 8px; border: 1px solid #21262d;
+  }
+  .kv-table th { background: #0d1117; color: #8b949e; font-weight: 500; white-space: nowrap; }
+
+  @media (max-width: 640px) {
+    body { padding: 12px; }
+    .timeline { padding-left: 28px; }
+  }
+</style>
+</head>
+<body>
+<div class="container">
+
+  <div class="header">
+    <h1>🤖 <span>TRACE</span> ${this.escapeHtml(this.agentLabel)}</h1>
+    <div class="meta">
+      <span class="item"><strong>Session:</strong> ${this.escapeHtml(this.sessionId)}</span>
+      <span class="item"><strong>Model:</strong> ${this.escapeHtml(this.modelName)}</span>
+      <span class="item"><strong>Duration:</strong> ${duration}s</span>
+      <span class="item"><strong>Events:</strong> ${this.events.length}</span>
+      <span class="item"><strong>Generated:</strong> ${new Date().toLocaleString("zh-CN", { hour12: false })}</span>
+    </div>
+  </div>
+
+  <div class="timeline">
+${eventCards}
+  </div>
+
+</div>
+<script>
+  document.querySelectorAll('.event-body').forEach(el => {
+    el.addEventListener('click', () => {
+      el.parentElement.classList.toggle('open');
+    });
+  });
+  // Auto-open error events and the final answer
+  document.querySelectorAll('.event-type-llm_error, .event-type-tool_error, .event-type-finish, .event-type-plan_created, .event-type-plan_revised')
+    .forEach(el => el.classList.add('open'));
+</script>
+</body>
+</html>`;
+    }
+    renderEventCard(event) {
+        const cls = `event event-type-${event.type}`;
+        const time = new Date(event.timestamp).toLocaleTimeString("en-US", { hour12: false });
+        const icon = this.eventIcon(event.type);
+        let detail = "";
+        switch (event.type) {
+            case "llm_start": {
+                const msgs = event.data.messages;
+                const tools = event.data.tools;
+                detail = `<div class="detail-section">
+          <h4>Messages (${msgs?.length ?? 0})</h4>
+          <pre>${this.syntaxHighlight(JSON.stringify(msgs ?? [], null, 2))}</pre>
+        </div>`;
+                if (tools && tools.length > 0) {
+                    detail += `<div class="detail-section">
+            <h4>Available Tools (${tools.length})</h4>
+            <pre>${this.syntaxHighlight(JSON.stringify(tools, null, 2))}</pre>
+          </div>`;
+                }
+                break;
+            }
+            case "llm_end": {
+                detail = `<div class="detail-section">
+          <h4>Content</h4>
+          <pre>${this.escapeHtml(String(event.data.content ?? ""))}</pre>
+        </div>`;
+                const tc = event.data.tool_calls;
+                if (tc && tc.length > 0) {
+                    detail += `<div class="detail-section">
+            <h4>Tool Calls</h4>
+            <pre>${this.syntaxHighlight(JSON.stringify(tc, null, 2))}</pre>
+          </div>`;
+                }
+                const usage = event.data.usage;
+                if (usage) {
+                    detail += `<div class="detail-section">
+            <h4>Usage</h4>
+            <table class="kv-table"><tr>
+              <th>Prompt</th><th>Completion</th><th>Total</th>
+            </tr><tr>
+              <td>${usage.prompt_tokens ?? "—"}</td>
+              <td>${usage.completion_tokens ?? "—"}</td>
+              <td>${usage.total_tokens ?? "—"}</td>
+            </tr></table>
+          </div>`;
+                }
+                break;
+            }
+            case "llm_error": {
+                detail = `<div class="detail-section">
+          <h4>Error (${this.escapeHtml(String(event.data.cause ?? ""))})</h4>
+          <pre>${this.escapeHtml(String(event.data.message ?? ""))}</pre>
+        </div>`;
+                break;
+            }
+            case "tool_start": {
+                const tblRows = Object.entries(event.data.args ?? {})
+                    .map(([k, v]) => `<tr><th>${this.escapeHtml(k)}</th><td><pre style="margin:0;padding:4px;background:none;border:none;max-height:200px">${this.escapeHtml(JSON.stringify(v, null, 2))}</pre></td></tr>`)
+                    .join("");
+                detail = `<div class="detail-section">
+          <h4>Arguments</h4>
+          <table class="kv-table">${tblRows}</table>
+        </div>`;
+                break;
+            }
+            case "tool_end": {
+                detail = `<div class="detail-section">
+          <h4>Result (${event.data.resultLength} chars)</h4>
+          <pre>${this.escapeHtml(String(event.data.result ?? ""))}</pre>
+        </div>`;
+                break;
+            }
+            case "tool_error": {
+                detail = `<div class="detail-section">
+          <h4>Error</h4>
+          <pre>${this.escapeHtml(String(event.data.error ?? ""))}</pre>
+        </div>`;
+                break;
+            }
+            case "thought": {
+                detail = `<div class="detail-section">
+          <pre>${this.escapeHtml(String(event.data.thought ?? ""))}</pre>
+        </div>`;
+                break;
+            }
+            case "plan_created":
+            case "plan_revised": {
+                const plan = event.data.plan;
+                if (plan && plan.length > 0) {
+                    detail = `<div class="detail-section">
+            <ol class="plan-steps">${plan.map((s) => `<li>${this.escapeHtml(s)}</li>`).join("")}</ol>
+          </div>`;
+                }
+                break;
+            }
+            case "finish": {
+                detail = `<div class="detail-section">
+          <pre>${this.escapeHtml(String(event.data.answer ?? ""))}</pre>
+        </div>`;
+                break;
+            }
+        }
+        return `    <div class="${cls}">
+      <div class="event-dot"></div>
+      <div class="event-body">
+        <div class="event-header">
+          <span class="icon">${icon}</span>
+          <span class="label">${this.escapeHtml(event.label)}</span>
+          <span class="time">${time}</span>
+          <span class="toggle">▶</span>
+        </div>
+        <div class="event-detail">${detail}</div>
+      </div>
+    </div>`;
+    }
+    eventIcon(type) {
+        switch (type) {
+            case "llm_start": return "📤";
+            case "llm_end": return "📥";
+            case "llm_error": return "❌";
+            case "tool_start": return "🔧";
+            case "tool_end": return "✅";
+            case "tool_error": return "⚠️";
+            case "thought": return "💭";
+            case "plan_created": return "📋";
+            case "plan_revised": return "🔄";
+            case "finish": return "🏁";
+        }
+    }
+    escapeHtml(text) {
+        return text
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;");
+    }
+    syntaxHighlight(json) {
+        return json.replace(/("(?:[^"\\]|\\.)*")\s*:/g, '<span class="key">$1</span>:').replace(/:\s*("(?:[^"\\]|\\.)*")/g, ': <span class="string">$1</span>').replace(/:\s*(\d+(?:\.\d+)?)/g, ': <span class="number">$1</span>').replace(/:\s*(true|false)/g, ': <span class="bool">$1</span>').replace(/:\s*(null)/g, ': <span class="null">$1</span>');
+    }
+}
+exports.TraceLogger = TraceLogger;
+//# sourceMappingURL=trace-logger.js.map

package/dist/trace/trace-logger.js.map

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

package/dist/trace/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Types of events that can occur during agent execution.
+ */
+export type AgentTraceEventType = "llm_start" | "llm_end" | "llm_error" | "tool_start" | "tool_end" | "tool_error" | "thought" | "plan_created" | "plan_revised" | "finish";
+/**
+ * A single trace event in the agent's execution timeline.
+ */
+export interface AgentTraceEvent {
+    /** Monotonically increasing event sequence number. */
+    id: number;
+    /** ISO-8601 timestamp of the event. */
+    timestamp: string;
+    /** Event type category. */
+    type: AgentTraceEventType;
+    /** Human-readable event label. */
+    label: string;
+    /** Event-specific payload. */
+    data: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/trace/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,SAAS,GACT,WAAW,GACX,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,SAAS,GACT,cAAc,GACd,cAAc,GACd,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B"}

package/dist/trace/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/trace/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/trace/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kagent-ts",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
@@ -44,6 +44,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "openai": "^4.80.0"
   },
   "optionalDependencies": {