@alejandroroman/agent-kit 0.1.4 → 0.2.1

package/dist/agent/loop.js

@@ -4,10 +4,38 @@ import { extractText } from "../llm/types.js";
 import { nanoid } from "nanoid";
 import { toolToDefinition } from "../tools/types.js";
 import { compactMessages, estimateTotalTokens } from "../session/compaction.js";
+import { pruneImages } from "../session/prune-images.js";
 import { createLogger } from "../logger.js";
 import { truncate } from "../text.js";
+import { getTracer, ATTR } from "../telemetry/index.js";
+import { context, trace, SpanStatusCode } from "@opentelemetry/api";
 const log = createLogger("agent");
 export async function runAgentLoop(initialMessages, config) {
+    const tracer = getTracer("agent");
+    const runSpan = tracer.startSpan("agent.run");
+    const agentName = config.agentName ?? config.label ?? "main";
+    runSpan.setAttribute(ATTR.AGENT, agentName);
+    runSpan.setAttribute(ATTR.SOURCE, config.source ?? "unknown");
+    runSpan.setAttribute(ATTR.MODEL, config.model);
+    const runCtx = trace.setSpan(context.active(), runSpan);
+    try {
+        const result = await _runAgentLoop(initialMessages, config, runSpan, tracer, runCtx);
+        return result;
+    }
+    catch (err) {
+        runSpan.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        if (err instanceof Error)
+            runSpan.recordException(err);
+        throw err;
+    }
+    finally {
+        runSpan.end();
+    }
+}
+async function _runAgentLoop(initialMessages, config, runSpan, tracer, runCtx) {
     const messages = [...initialMessages];
     const registry = config.toolRegistry;
     const staticTools = config.tools ?? [];
@@ -20,6 +48,7 @@ export async function runAgentLoop(initialMessages, config) {
     const toolNames = currentTools.map((t) => t.name);
     log.info({ label, model: config.model, tools: toolNames.length, toolNames, maxIterations, messages: initialMessages.length }, "loop start");
     const runId = nanoid();
+    runSpan.setAttribute(ATTR.RUN_ID, runId);
     const agentName = config.agentName ?? config.label ?? "main";
     const totalUsage = {
         inputTokens: 0,
@@ -32,140 +61,212 @@ export async function runAgentLoop(initialMessages, config) {
     let didCompact = false;
     for (let i = 0; i < maxIterations; i++) {
         const iteration = i + 1;
-        // Rebuild tool definitions each iteration (skills may register new tools mid-loop)
-        const iterTools = registry
-            ? registry.list().map((name) => registry.resolve([name])[0])
-            : staticTools;
-        const toolMap = new Map(iterTools.map((t) => [t.name, t]));
-        const toolDefs = iterTools.map(toolToDefinition);
-        // Compact conversation if it exceeds the token threshold (one-shot: only once per loop)
-        if (!didCompact && config.compactionThreshold) {
-            const estimated = estimateTotalTokens(messages);
-            if (estimated > config.compactionThreshold) {
-                log.info({ label, iteration, estimated, threshold: config.compactionThreshold }, "compacting messages");
-                try {
-                    const compacted = await compactMessages(messages, config.model, config.compactionThreshold);
-                    messages.length = 0;
-                    messages.push(...compacted);
-                    didCompact = true;
-                }
-                catch (err) {
-                    const isBug = err instanceof TypeError || err instanceof ReferenceError || err instanceof SyntaxError || err instanceof RangeError;
-                    if (isBug) {
-                        log.fatal({ err, label, iteration }, "compaction bug — programming error");
-                        throw err;
+        // Create iteration span as child of the run span
+        const iterSpan = tracer.startSpan("agent.iteration", undefined, runCtx);
+        iterSpan.setAttribute(ATTR.ITERATION, iteration);
+        const iterCtx = trace.setSpan(runCtx, iterSpan);
+        try {
+            // Rebuild tool definitions each iteration (skills may register new tools mid-loop)
+            const iterTools = registry
+                ? registry.list().map((name) => registry.resolve([name])[0])
+                : staticTools;
+            const toolMap = new Map(iterTools.map((t) => [t.name, t]));
+            const toolDefs = iterTools.map(toolToDefinition);
+            // Compact conversation if it exceeds the token threshold (one-shot: only once per loop)
+            if (!didCompact && config.compactionThreshold) {
+                const estimated = estimateTotalTokens(messages);
+                if (estimated > config.compactionThreshold) {
+                    log.info({ label, iteration, estimated, threshold: config.compactionThreshold }, "compacting messages");
+                    const compactionSpan = tracer.startSpan("session.compaction", undefined, iterCtx);
+                    compactionSpan.setAttribute(ATTR.TOKENS_BEFORE, estimated);
+                    try {
+                        const compacted = await compactMessages(messages, config.model, config.compactionThreshold);
+                        messages.length = 0;
+                        messages.push(...compacted);
+                        didCompact = true;
+                        const tokensAfter = estimateTotalTokens(messages);
+                        compactionSpan.setAttribute(ATTR.TOKENS_AFTER, tokensAfter);
+                    }
+                    catch (err) {
+                        const isBug = err instanceof TypeError || err instanceof ReferenceError || err instanceof SyntaxError || err instanceof RangeError;
+                        compactionSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: err instanceof Error ? err.message : String(err),
+                        });
+                        if (err instanceof Error)
+                            compactionSpan.recordException(err);
+                        if (isBug) {
+                            log.fatal({ err, label, iteration }, "compaction bug — programming error");
+                            throw err;
+                        }
+                        log.warn({ err, label, iteration }, "compaction failed, proceeding with full context");
+                    }
+                    finally {
+                        compactionSpan.end();
                     }
-                    log.warn({ err, label, iteration }, "compaction failed, proceeding with full context");
                 }
             }
-        }
-        const response = await completeWithFallback(config.model, config.fallbacks ?? [], messages, {
-            systemPrompt: config.systemPrompt,
-            tools: toolDefs.length > 0 ? toolDefs : undefined,
-        }, complete);
-        totalUsage.inputTokens += response.usage.inputTokens;
-        totalUsage.outputTokens += response.usage.outputTokens;
-        totalUsage.cacheCreationTokens += response.usage.cacheCreationTokens;
-        totalUsage.cacheReadTokens += response.usage.cacheReadTokens;
-        totalUsage.reasoningTokens += response.usage.reasoningTokens;
-        if (config.usageStore) {
+            // Prune images from old messages to save context tokens
+            const prunedMessages = pruneImages(messages, 4);
+            // LLM call span
+            config.onProgress?.("thinking");
+            const llmSpan = tracer.startSpan("llm.call", undefined, iterCtx);
+            let response;
             try {
-                config.usageStore.recordCall({
-                    runId,
-                    agentName,
-                    provider: response.model.split(":")[0],
-                    model: response.model,
-                    usage: response.usage,
-                    stopReason: response.stopReason,
-                    latencyMs: response.latencyMs,
-                });
+                response = await completeWithFallback(config.model, config.fallbacks ?? [], prunedMessages, {
+                    systemPrompt: config.systemPrompt,
+                    tools: toolDefs.length > 0 ? toolDefs : undefined,
+                }, complete);
+                llmSpan.setAttribute(ATTR.INPUT_TOKENS, response.usage.inputTokens);
+                llmSpan.setAttribute(ATTR.OUTPUT_TOKENS, response.usage.outputTokens);
+                llmSpan.setAttribute(ATTR.CACHE_READ_TOKENS, response.usage.cacheReadTokens);
+                llmSpan.setAttribute(ATTR.CACHE_CREATION_TOKENS, response.usage.cacheCreationTokens);
+                llmSpan.setAttribute(ATTR.STOP_REASON, response.stopReason);
+                llmSpan.setAttribute(ATTR.MODEL, response.model);
+                if (response.latencyMs != null)
+                    llmSpan.setAttribute(ATTR.LATENCY_MS, response.latencyMs);
             }
             catch (err) {
-                log.error({ err, runId }, "failed to record LLM call");
+                llmSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                if (err instanceof Error)
+                    llmSpan.recordException(err);
+                throw err;
             }
-        }
-        log.debug({ label, iteration, model: config.model, stopReason: response.stopReason, inputTokens: response.usage.inputTokens, outputTokens: response.usage.outputTokens }, "iteration complete");
-        messages.push({ role: "assistant", content: response.content });
-        if (response.stopReason !== "tool_use") {
-            let text = extractText(response.content);
-            // If the final turn has no text (e.g. LLM said everything alongside a tool call
-            // in a prior turn), scan backward for the last assistant text.
-            if (!text) {
-                for (let j = messages.length - 2; j >= 0; j--) {
-                    const msg = messages[j];
-                    if (msg.role === "assistant") {
-                        const found = extractText(msg.content);
-                        if (found) {
-                            text = found;
-                            break;
-                        }
-                    }
-                }
+            finally {
+                llmSpan.end();
             }
-            const elapsed = Date.now() - loopStart;
+            totalUsage.inputTokens += response.usage.inputTokens;
+            totalUsage.outputTokens += response.usage.outputTokens;
+            totalUsage.cacheCreationTokens += response.usage.cacheCreationTokens;
+            totalUsage.cacheReadTokens += response.usage.cacheReadTokens;
+            totalUsage.reasoningTokens += response.usage.reasoningTokens;
             if (config.usageStore) {
                 try {
-                    config.usageStore.recordRun({
-                        id: runId,
+                    config.usageStore.recordCall({
+                        runId,
                         agentName,
-                        source: config.source ?? "unknown",
-                        model: config.model,
-                        usage: totalUsage,
-                        iterations: iteration,
-                        toolCallsCount,
-                        durationMs: elapsed,
+                        provider: response.model.split(":")[0],
+                        model: response.model,
+                        usage: response.usage,
+                        stopReason: response.stopReason,
+                        latencyMs: response.latencyMs,
                     });
                 }
                 catch (err) {
-                    log.error({ err, runId }, "failed to record agent run");
+                    log.error({ err, runId }, "failed to record LLM call");
                 }
             }
-            log.info({ label, stopReason: response.stopReason, iterations: iteration, inputTokens: totalUsage.inputTokens, outputTokens: totalUsage.outputTokens, elapsed }, "loop end");
-            return {
-                text,
-                messages,
-                usage: totalUsage,
-            };
-        }
-        const toolCalls = response.content.filter((b) => b.type === "tool_call");
-        toolCallsCount += toolCalls.length;
-        for (const call of toolCalls) {
-            log.debug({ label, iteration, tool: call.name, args: truncate(JSON.stringify(call.arguments), 200) }, "tool call");
-            const tool = toolMap.get(call.name);
-            let result;
-            if (!tool) {
-                log.warn({ label, iteration, tool: call.name }, "LLM called unknown tool");
-                result = `Error: unknown tool "${call.name}"`;
+            log.debug({ label, iteration, model: config.model, stopReason: response.stopReason, inputTokens: response.usage.inputTokens, outputTokens: response.usage.outputTokens }, "iteration complete");
+            messages.push({ role: "assistant", content: response.content });
+            if (response.stopReason !== "tool_use") {
+                let text = extractText(response.content);
+                // If the final turn has no text (e.g. LLM said everything alongside a tool call
+                // in a prior turn), scan backward for the last assistant text.
+                if (!text) {
+                    for (let j = messages.length - 2; j >= 0; j--) {
+                        const msg = messages[j];
+                        if (msg.role === "assistant") {
+                            const found = extractText(msg.content);
+                            if (found) {
+                                text = found;
+                                break;
+                            }
+                        }
+                    }
+                }
+                const elapsed = Date.now() - loopStart;
+                if (config.usageStore) {
+                    try {
+                        config.usageStore.recordRun({
+                            id: runId,
+                            agentName,
+                            source: config.source ?? "unknown",
+                            model: config.model,
+                            usage: totalUsage,
+                            iterations: iteration,
+                            toolCallsCount,
+                            durationMs: elapsed,
+                        });
+                    }
+                    catch (err) {
+                        log.error({ err, runId }, "failed to record agent run");
+                    }
+                }
+                config.onProgress?.("complete");
+                log.info({ label, stopReason: response.stopReason, iterations: iteration, inputTokens: totalUsage.inputTokens, outputTokens: totalUsage.outputTokens, elapsed }, "loop end");
+                runSpan.setAttribute(ATTR.ITERATION, iteration);
+                return {
+                    text,
+                    messages,
+                    usage: totalUsage,
+                };
             }
-            else {
-                const toolStart = Date.now();
+            const toolCalls = response.content.filter((b) => b.type === "tool_call");
+            toolCallsCount += toolCalls.length;
+            for (const call of toolCalls) {
+                log.debug({ label, iteration, tool: call.name, args: truncate(JSON.stringify(call.arguments), 200) }, "tool call");
+                const tool = toolMap.get(call.name);
+                let result;
+                let toolDidThrow = false;
+                const toolSpan = tracer.startSpan("tool.execute", undefined, iterCtx);
+                toolSpan.setAttribute(ATTR.TOOL_NAME, call.name);
                 try {
-                    result = await tool.execute(call.arguments);
-                    const toolElapsed = Date.now() - toolStart;
-                    log.debug({ label, iteration, tool: call.name, resultLength: result.length, snippet: truncate(result, 150), elapsed: toolElapsed }, "tool result");
-                }
-                catch (err) {
-                    const isBug = err instanceof TypeError || err instanceof ReferenceError || err instanceof SyntaxError || err instanceof RangeError;
-                    if (isBug) {
-                        log.fatal({ err, tool: call.name, label, iteration }, "tool bug — programming error");
+                    if (!tool) {
+                        log.warn({ label, iteration, tool: call.name }, "LLM called unknown tool");
+                        result = `Error: unknown tool "${call.name}"`;
                     }
                     else {
-                        log.error({ err, tool: call.name, label, iteration }, "tool execution failed");
+                        const toolStart = Date.now();
+                        try {
+                            config.onProgress?.("tool_use", call.name);
+                            result = await tool.execute(call.arguments);
+                            const toolElapsed = Date.now() - toolStart;
+                            log.debug({ label, iteration, tool: call.name, resultLength: result.length, snippet: truncate(result, 150), elapsed: toolElapsed }, "tool result");
+                        }
+                        catch (err) {
+                            toolDidThrow = true;
+                            const isBug = err instanceof TypeError || err instanceof ReferenceError || err instanceof SyntaxError || err instanceof RangeError;
+                            if (isBug) {
+                                log.fatal({ err, tool: call.name, label, iteration }, "tool bug — programming error");
+                            }
+                            else {
+                                log.error({ err, tool: call.name, label, iteration }, "tool execution failed");
+                            }
+                            result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                            toolSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: err instanceof Error ? err.message : String(err),
+                            });
+                            if (err instanceof Error)
+                                toolSpan.recordException(err);
+                        }
+                    }
+                    // Detect error-as-string results (only if the tool didn't already throw)
+                    if (!toolDidThrow && typeof result === "string" && result.startsWith("Error:")) {
+                        toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: result });
                     }
-                    result = `Error: ${err instanceof Error ? err.message : String(err)}`;
                 }
+                finally {
+                    toolSpan.end();
+                }
+                const maxResultSize = config.maxToolResultSize ?? 8192;
+                if (result.length > maxResultSize) {
+                    const originalLength = result.length;
+                    result = result.slice(0, maxResultSize) + `\n\n[Output truncated from ${originalLength} to ${maxResultSize} characters]`;
+                    log.debug({ label, iteration, tool: call.name, originalLength, maxResultSize }, "tool result truncated");
+                }
+                messages.push({
+                    role: "tool_result",
+                    tool_call_id: call.id,
+                    content: result,
+                });
             }
-            const maxResultSize = config.maxToolResultSize ?? 8192;
-            if (result.length > maxResultSize) {
-                const originalLength = result.length;
-                result = result.slice(0, maxResultSize) + `\n\n[Output truncated from ${originalLength} to ${maxResultSize} characters]`;
-                log.debug({ label, iteration, tool: call.name, originalLength, maxResultSize }, "tool result truncated");
-            }
-            messages.push({
-                role: "tool_result",
-                tool_call_id: call.id,
-                content: result,
-            });
+        }
+        finally {
+            iterSpan.end();
         }
     }
     const elapsed = Date.now() - loopStart;
@@ -187,6 +288,7 @@ export async function runAgentLoop(initialMessages, config) {
         }
     }
     log.warn({ label, maxIterations, inputTokens: totalUsage.inputTokens, outputTokens: totalUsage.outputTokens, elapsed }, "max iterations reached");
+    runSpan.setAttribute(ATTR.ITERATION, maxIterations);
     return {
         text: "[Agent reached maximum iterations]",
         messages,

package/dist/agent/types.d.ts

@@ -2,6 +2,7 @@ import type { Tool } from "../tools/types.js";
 import type { ToolRegistry } from "../tools/registry.js";
 import type { TokenUsage } from "../llm/types.js";
 import type { UsageStore } from "../usage/store.js";
+export type ProgressPhase = "thinking" | "tool_use" | "complete";
 export interface AgentConfig {
     model: string;
     fallbacks?: string[];
@@ -15,6 +16,7 @@ export interface AgentConfig {
     source?: string;
     maxToolResultSize?: number;
     compactionThreshold?: number;
+    onProgress?: (phase: ProgressPhase, detail?: string) => void;
 }
 export interface AgentResult {
     text: string;

package/dist/api/errors.d.ts

@@ -0,0 +1,3 @@
+import type { TelemetryDb } from "../telemetry/db.js";
+import { type RouteHandler } from "./types.js";
+export declare function errorRoutes(db: TelemetryDb): Record<string, RouteHandler>;

package/dist/api/errors.js

@@ -0,0 +1,37 @@
+import { sendJson, sendError } from "./types.js";
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+const VALID_GROUP_BY = new Set(["fingerprint", "agent"]);
+function clampLimit(val) {
+    if (val === null)
+        return DEFAULT_LIMIT;
+    const n = parseInt(val, 10);
+    if (isNaN(n) || n < 1)
+        return DEFAULT_LIMIT;
+    return Math.min(n, MAX_LIMIT);
+}
+export function errorRoutes(db) {
+    return {
+        "GET /api/errors": (url, _req, res) => {
+            const data = db.getRecentErrors({
+                agent: url.searchParams.get("agent") ?? undefined,
+                source: url.searchParams.get("source") ?? undefined,
+                since: url.searchParams.get("since") ?? undefined,
+                limit: clampLimit(url.searchParams.get("limit")),
+            });
+            sendJson(res, data);
+        },
+        "GET /api/errors/stats": (url, _req, res) => {
+            const groupByParam = url.searchParams.get("group_by");
+            if (groupByParam && !VALID_GROUP_BY.has(groupByParam)) {
+                sendError(res, 400, "Invalid group_by value. Must be one of: fingerprint, agent");
+                return;
+            }
+            const data = db.getErrorStats({
+                since: url.searchParams.get("since") ?? undefined,
+                groupBy: groupByParam ?? undefined,
+            });
+            sendJson(res, data);
+        },
+    };
+}

package/dist/api/events.d.ts

@@ -0,0 +1,5 @@
+import type { RouteHandler } from "./types.js";
+export declare function addEventListener(res: import("http").ServerResponse): void;
+export declare function removeEventListener(res: import("http").ServerResponse): void;
+export declare function broadcastEvent(data: string): void;
+export declare function eventRoutes(): Record<string, RouteHandler>;

package/dist/api/events.js

@@ -0,0 +1,28 @@
+const clients = new Set();
+export function addEventListener(res) {
+    clients.add(res);
+}
+export function removeEventListener(res) {
+    clients.delete(res);
+}
+export function broadcastEvent(data) {
+    for (const client of clients) {
+        client.write(`data: ${data}\n\n`);
+    }
+}
+export function eventRoutes() {
+    return {
+        "GET /api/events/stream": (_url, req, res) => {
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            });
+            res.write(`data: ${JSON.stringify({ type: "connected", timestamp: new Date().toISOString() })}\n\n`);
+            addEventListener(res);
+            req.on("close", () => {
+                removeEventListener(res);
+            });
+        },
+    };
+}

package/dist/api/router.js

@@ -7,6 +7,9 @@ import { configRoutes } from "./config.js";
 import { cronRoutes } from "./cron.js";
 import { logRoutes } from "./logs.js";
 import { usageRoutes } from "./usage.js";
+import { traceRoutes } from "./traces.js";
+import { errorRoutes } from "./errors.js";
+import { eventRoutes } from "./events.js";
 import { createLogger } from "../logger.js";
 const log = createLogger("api");
 function parseRouteKey(key) {
@@ -29,6 +32,13 @@ export function createApiServer(ctx, port) {
     if (ctx.usageStore) {
         Object.assign(routeHandlers, usageRoutes(ctx.usageStore));
     }
+    // If telemetry db exists, add telemetry routes
+    if (ctx.telemetryDb) {
+        Object.assign(routeHandlers, traceRoutes(ctx.telemetryDb));
+        Object.assign(routeHandlers, errorRoutes(ctx.telemetryDb));
+    }
+    // SSE events stream (always available)
+    Object.assign(routeHandlers, eventRoutes());
     const routes = Object.entries(routeHandlers).map(([key, handler]) => {
         const { method, pattern } = parseRouteKey(key);
         return { method, pattern, handler };

package/dist/api/traces.d.ts

@@ -0,0 +1,3 @@
+import type { TelemetryDb } from "../telemetry/db.js";
+import { type RouteHandler } from "./types.js";
+export declare function traceRoutes(db: TelemetryDb): Record<string, RouteHandler>;

package/dist/api/traces.js

@@ -0,0 +1,35 @@
+import { sendJson, sendError } from "./types.js";
+const MAX_LIMIT = 1000;
+const DEFAULT_LIMIT = 100;
+function clampLimit(val) {
+    if (val === null)
+        return DEFAULT_LIMIT;
+    const n = parseInt(val, 10);
+    if (isNaN(n) || n < 1)
+        return DEFAULT_LIMIT;
+    return Math.min(n, MAX_LIMIT);
+}
+export function traceRoutes(db) {
+    return {
+        "GET /api/traces": (url, _req, res) => {
+            const data = db.listTraces({
+                agent: url.searchParams.get("agent") ?? undefined,
+                source: url.searchParams.get("source") ?? undefined,
+                status: url.searchParams.get("status") ?? undefined,
+                since: url.searchParams.get("since") ?? undefined,
+                limit: clampLimit(url.searchParams.get("limit")),
+            });
+            sendJson(res, data);
+        },
+        "GET /api/traces/:traceId": (url, _req, res) => {
+            const match = url.pathname.match(/^\/api\/traces\/([^/]+)$/);
+            if (!match) {
+                sendError(res, 400, "missing traceId");
+                return;
+            }
+            const traceId = decodeURIComponent(match[1]);
+            const spans = db.getTraceSpans(traceId);
+            sendJson(res, spans);
+        },
+    };
+}

package/dist/api/types.d.ts

@@ -1,11 +1,13 @@
 import type { Config } from "../config/schema.js";
 import type { UsageStore } from "../usage/store.js";
+import type { TelemetryDb } from "../telemetry/db.js";
 export interface ApiContext {
     config: Config;
     configPath: string;
     usageStore?: UsageStore;
     dataDir: string;
     memoryDbPath?: string;
+    telemetryDb?: TelemetryDb;
 }
 export type RouteHandler = (url: URL, req: import("http").IncomingMessage, res: import("http").ServerResponse) => void;
 export declare function sendJson(res: import("http").ServerResponse, data: unknown, status?: number): void;

package/dist/bootstrap.d.ts

@@ -24,7 +24,8 @@ export declare function buildAgentRuntime(agentName: string, config: Config, opt
     skillsDir: string;
     sessionId?: string;
     usageStore?: UsageStore;
-}): AgentRuntime;
+    configPath?: string;
+}): Promise<AgentRuntime>;
 /**
  * Assemble a system prompt from soul, date context, skills index, and prompt fragments.
  */
@@ -46,5 +47,6 @@ export declare function createAgentExecutor(config: Config, opts: {
     agentRegistry: AgentRegistry;
     usageStore?: UsageStore;
     source: string;
+    configPath?: string;
 }): AgentExecutorFn;
 export {};

package/dist/bootstrap.js

@@ -2,9 +2,11 @@ import * as path from "path";
 import * as fs from "fs";
 import { resolveAgent, resolveWebSearch } from "./config/resolve.js";
 import { createBuiltinRegistry } from "./tools/builtin/index.js";
-import { createActivateSkillTool } from "./skills/index.js";
+import { createActivateSkillTool, preActivateSkills } from "./skills/index.js";
 import { AgentRegistry } from "./multi/registry.js";
 import { registerSpawnWrappers } from "./tools/builtin/spawn.js";
+import { ConfigWriter } from "./config/writer.js";
+import { createUpdateAgentConfigTool, createManageCronTool } from "./tools/builtin/index.js";
 import { setupAgentSession } from "./agent/setup.js";
 import { runAgentLoop } from "./agent/loop.js";
 import { dateContext } from "./text.js";
@@ -14,7 +16,7 @@ const log = createLogger("bootstrap");
 /**
  * Build a fully-initialized agent runtime: tool registry, skills, spawn wrappers, session.
  */
-export function buildAgentRuntime(agentName, config, opts) {
+export async function buildAgentRuntime(agentName, config, opts) {
     const agentDef = config.agents[agentName];
     if (!agentDef)
         throw new Error(`Agent "${agentName}" not found in config`);
@@ -38,16 +40,32 @@ export function buildAgentRuntime(agentName, config, opts) {
             promptFragments,
             activatedSkills: new Set(),
         };
-        toolRegistry.register(createActivateSkillTool(ctx));
-        skillsIndex = "\n\nYou have the following skills available:\n\n"
-            + resolved.skills.map((s) => `- **${s.name}**: ${s.description}`).join("\n")
-            + "\n\nTo use a skill, call the `activate_skill` tool with the skill name.";
+        const activateTool = createActivateSkillTool(ctx);
+        toolRegistry.register(activateTool);
+        if (resolved.autoActivateSkills) {
+            skillsIndex = await preActivateSkills(ctx, activateTool, log);
+        }
+        else {
+            skillsIndex = "\n\nYou have the following skills available:\n\n"
+                + resolved.skills.map((s) => `- **${s.name}**: ${s.description}`).join("\n")
+                + "\n\nTo use a skill, call the `activate_skill` tool with the skill name.";
+        }
     }
     // Spawn wrapper registration
     if (resolved.canSpawn.length > 0) {
         registerSpawnWrappers(resolved.canSpawn, config, agentRegistry, toolRegistry, opts.usageStore);
         log.info({ targets: resolved.canSpawn.map((t) => `${t.tool} -> ${t.agent}`) }, "spawn wrappers registered");
     }
+    // Self-config tool registration
+    if (opts.configPath) {
+        const writer = new ConfigWriter(opts.configPath);
+        if (agentDef.tools.includes("update_agent_config")) {
+            toolRegistry.register(createUpdateAgentConfigTool(agentName, writer));
+        }
+        if (agentDef.tools.includes("manage_cron")) {
+            toolRegistry.register(createManageCronTool(agentName, writer));
+        }
+    }
     const sid = opts.sessionId ?? `session-${Date.now()}`;
     const { soul, session } = setupAgentSession(opts.dataDir, agentName, sid);
     return { resolved, toolRegistry, agentRegistry, promptFragments, skillsIndex, soul, session };
@@ -87,11 +105,12 @@ export function initUsageStore(config) {
  */
 export function createAgentExecutor(config, opts) {
     return async (agentName, messages) => {
-        const runtime = buildAgentRuntime(agentName, config, {
+        const runtime = await buildAgentRuntime(agentName, config, {
             dataDir: opts.dataDir,
             skillsDir: opts.skillsDir,
             sessionId: `${opts.source}-${Date.now()}`,
             usageStore: opts.usageStore,
+            configPath: opts.configPath,
         });
         const systemPrompt = buildSystemPrompt(runtime.soul, runtime.skillsIndex, runtime.promptFragments);
         return runAgentLoop(messages, {