@alejandroroman/agent-kit 0.1.4 → 0.2.1

package/dist/heartbeat/runner.js

@@ -5,9 +5,11 @@ import { setupAgentSession } from "../agent/setup.js";
 import { resolveAgent, resolveModelAlias, resolveWebSearch } from "../config/resolve.js";
 import { createBuiltinRegistry } from "../tools/builtin/index.js";
 import { registerSpawnWrappers } from "../tools/builtin/spawn.js";
-import { createActivateSkillTool } from "../skills/index.js";
+import { createActivateSkillTool, preActivateSkills } from "../skills/index.js";
 import { createLogger } from "../logger.js";
 import { dateContext } from "../text.js";
+import { context, trace, SpanStatusCode } from "@opentelemetry/api";
+import { getTracer, ATTR } from "../telemetry/index.js";
 const log = createLogger("heartbeat");
 const HEARTBEAT_OK = "HEARTBEAT_OK";
 export function isHeartbeatSuppressed(text) {
@@ -64,93 +66,99 @@ export class HeartbeatRunner {
         if (!agentDef?.heartbeat)
             return undefined;
         const hb = agentDef.heartbeat;
-        if (!isWithinActiveHours(hb.activeHours)) {
-            log.debug({ agent: agentName }, "outside active hours, skipping");
-            return undefined;
-        }
-        const instructions = this.loadHeartbeatInstructions(agentName);
-        if (!instructions) {
-            log.warn({ agent: agentName }, "no HEARTBEAT.md found, skipping");
-            return undefined;
-        }
-        // Isolated tool registry per tick (same pattern as CronScheduler)
-        const sandbox = agentDef.sandbox ?? this.config.defaults.sandbox;
-        const memoryConfig = this.config.defaults.memory;
-        const tickRegistry = createBuiltinRegistry({
-            allowedCommands: sandbox?.allowedCommands,
-            allowedPaths: sandbox?.allowedPaths,
-            memoryConfig,
-            webSearch: resolveWebSearch(agentName, this.config),
+        const tracer = getTracer("heartbeat");
+        const span = tracer.startSpan("source.heartbeat", {
+            attributes: {
+                [ATTR.AGENT]: agentName,
+                [ATTR.SOURCE]: "heartbeat",
+            },
         });
-        const resolved = resolveAgent(agentName, this.config, tickRegistry, this.skillsDir);
-        // Skills setup — auto-activate all skills upfront so Haiku doesn't need to call activate_skill
-        const promptFragments = [];
-        let skillsIndex = "";
-        if (resolved.skills.length > 0) {
-            const ctx = {
-                manifests: resolved.skills,
-                skillsDir: this.skillsDir,
-                toolRegistry: tickRegistry,
-                promptFragments,
-                activatedSkills: new Set(),
-            };
-            const activateTool = createActivateSkillTool(ctx);
-            tickRegistry.register(activateTool);
-            // Auto-activate all skills upfront
-            for (const manifest of resolved.skills) {
-                try {
-                    const result = await activateTool.execute({ skill_name: manifest.name });
-                    if (typeof result === "string" && result.startsWith("Error")) {
-                        log.error({ agent: agentName, skill: manifest.name, result }, "failed to auto-activate skill");
-                    }
-                }
-                catch (err) {
-                    log.error({ err, agent: agentName, skill: manifest.name }, "skill auto-activation threw");
-                }
+        const spanCtx = trace.setSpan(context.active(), span);
+        try {
+            if (!isWithinActiveHours(hb.activeHours)) {
+                log.debug({ agent: agentName }, "outside active hours, skipping");
+                span.setAttribute(ATTR.SUPPRESSED, "outside_active_hours");
+                return undefined;
             }
-            const activatedNames = [...ctx.activatedSkills];
-            if (activatedNames.length > 0) {
-                skillsIndex = "\n\nThe following skills are pre-activated: "
-                    + activatedNames.join(", ")
-                    + ".\nTheir tools are already available — you do not need to call activate_skill.";
+            const instructions = this.loadHeartbeatInstructions(agentName);
+            if (!instructions) {
+                log.warn({ agent: agentName }, "no HEARTBEAT.md found, skipping");
+                span.setAttribute(ATTR.SUPPRESSED, "no_instructions");
+                return undefined;
             }
+            return await context.with(spanCtx, async () => {
+                // Isolated tool registry per tick (same pattern as CronScheduler)
+                const sandbox = agentDef.sandbox ?? this.config.defaults.sandbox;
+                const memoryConfig = this.config.defaults.memory;
+                const tickRegistry = createBuiltinRegistry({
+                    allowedCommands: sandbox?.allowedCommands,
+                    allowedPaths: sandbox?.allowedPaths,
+                    memoryConfig,
+                    webSearch: resolveWebSearch(agentName, this.config),
+                });
+                const resolved = resolveAgent(agentName, this.config, tickRegistry, this.skillsDir);
+                // Skills setup — auto-activate all skills upfront so Haiku doesn't need to call activate_skill
+                const promptFragments = [];
+                let skillsIndex = "";
+                if (resolved.skills.length > 0) {
+                    const ctx = {
+                        manifests: resolved.skills,
+                        skillsDir: this.skillsDir,
+                        toolRegistry: tickRegistry,
+                        promptFragments,
+                        activatedSkills: new Set(),
+                    };
+                    const activateTool = createActivateSkillTool(ctx);
+                    tickRegistry.register(activateTool);
+                    // Heartbeat always auto-activates (Haiku can't reliably call activate_skill)
+                    skillsIndex = await preActivateSkills(ctx, activateTool, log);
+                }
+                // Spawn wrappers
+                if (resolved.canSpawn.length > 0) {
+                    registerSpawnWrappers(resolved.canSpawn, this.config, this.agentRegistry, tickRegistry, this.usageStore);
+                }
+                // Ephemeral session: no history accumulation, append-only audit log
+                const sessionId = `heartbeat-${agentName}`;
+                const { soul, session } = setupAgentSession(this.dataDir, agentName, sessionId);
+                // Build tick prompt with fresh instructions + timestamp
+                const tickPrompt = `[Heartbeat tick — ${new Date().toISOString()}]\n\n${instructions}`;
+                const userMsg = { role: "user", content: tickPrompt };
+                session.append(userMsg); // audit only
+                const messages = [userMsg]; // ephemeral — no history
+                // Model: heartbeat.model overrides agent model
+                const model = hb.model
+                    ? resolveModelAlias(hb.model, this.config.models)
+                    : resolved.model;
+                const systemPrompt = [soul, dateContext(), skillsIndex, ...promptFragments]
+                    .filter(Boolean)
+                    .join("\n\n") || undefined;
+                const result = await runAgentLoop(messages, {
+                    model,
+                    fallbacks: resolved.fallbacks,
+                    systemPrompt,
+                    toolRegistry: tickRegistry,
+                    maxIterations: hb.maxIterations ?? resolved.maxIterations,
+                    compactionThreshold: resolved.compactionThreshold,
+                    maxToolResultSize: resolved.maxToolResultSize,
+                    agentName,
+                    usageStore: this.usageStore,
+                    source: "heartbeat",
+                });
+                // Audit: append all new messages from the agent loop
+                for (const msg of result.messages.slice(1)) {
+                    session.append(msg);
+                }
+                return result;
+            });
         }
-        // Spawn wrappers
-        if (resolved.canSpawn.length > 0) {
-            registerSpawnWrappers(resolved.canSpawn, this.config, this.agentRegistry, tickRegistry, this.usageStore);
+        catch (err) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+            span.recordException(err instanceof Error ? err : new Error(String(err)));
+            throw err;
         }
-        // Ephemeral session: no history accumulation, append-only audit log
-        const sessionId = `heartbeat-${agentName}`;
-        const { soul, session } = setupAgentSession(this.dataDir, agentName, sessionId);
-        // Build tick prompt with fresh instructions + timestamp
-        const tickPrompt = `[Heartbeat tick — ${new Date().toISOString()}]\n\n${instructions}`;
-        const userMsg = { role: "user", content: tickPrompt };
-        session.append(userMsg); // audit only
-        const messages = [userMsg]; // ephemeral — no history
-        // Model: heartbeat.model overrides agent model
-        const model = hb.model
-            ? resolveModelAlias(hb.model, this.config.models)
-            : resolved.model;
-        const systemPrompt = [soul, dateContext(), skillsIndex, ...promptFragments]
-            .filter(Boolean)
-            .join("\n\n") || undefined;
-        const result = await runAgentLoop(messages, {
-            model,
-            fallbacks: resolved.fallbacks,
-            systemPrompt,
-            toolRegistry: tickRegistry,
-            maxIterations: hb.maxIterations ?? resolved.maxIterations,
-            compactionThreshold: resolved.compactionThreshold,
-            maxToolResultSize: resolved.maxToolResultSize,
-            agentName,
-            usageStore: this.usageStore,
-            source: "heartbeat",
-        });
-        // Audit: append all new messages from the agent loop
-        for (const msg of result.messages.slice(1)) {
-            session.append(msg);
+        finally {
+            span.end();
         }
-        return result;
     }
     start(callbacks) {
         for (const [agentName, agentDef] of Object.entries(this.config.agents)) {
@@ -162,6 +170,15 @@ export class HeartbeatRunner {
             const runTick = async () => {
                 if (this.running.has(agentName)) {
                     log.info({ agent: agentName }, "previous tick still running, skipping");
+                    const tracer = getTracer("heartbeat");
+                    const skipSpan = tracer.startSpan("source.heartbeat", {
+                        attributes: {
+                            [ATTR.AGENT]: agentName,
+                            [ATTR.SOURCE]: "heartbeat",
+                            [ATTR.SUPPRESSED]: "already_running",
+                        },
+                    });
+                    skipSpan.end();
                     return;
                 }
                 this.running.add(agentName);

package/dist/llm/anthropic.d.ts

@@ -7,6 +7,7 @@ export declare class AnthropicProvider implements LLMProvider {
     complete(model: string, messages: Message[], options?: CompleteOptions): Promise<LLMResponse>;
     stream(model: string, messages: Message[], options?: CompleteOptions): AsyncIterable<StreamEvent>;
     private toAnthropicMessages;
+    private mapUserContent;
     private fromAnthropicResponse;
     private mapStopReason;
 }

package/dist/llm/anthropic.js

@@ -39,7 +39,7 @@ export class AnthropicProvider {
     toAnthropicMessages(messages) {
         return messages.map((msg) => {
             if (msg.role === "user")
-                return { role: "user", content: msg.content };
+                return { role: "user", content: this.mapUserContent(msg.content) };
             if (msg.role === "assistant") {
                 return {
                     role: "assistant",
@@ -51,11 +51,20 @@ export class AnthropicProvider {
                 };
             }
             if (msg.role === "tool_result") {
-                return { role: "user", content: [{ type: "tool_result", tool_use_id: msg.tool_call_id, content: msg.content }] };
+                return { role: "user", content: [{ type: "tool_result", tool_use_id: msg.tool_call_id, content: this.mapUserContent(msg.content) }] };
             }
             return msg;
         });
     }
+    mapUserContent(content) {
+        if (typeof content === "string")
+            return content;
+        return content.map((block) => {
+            if (block.type === "text")
+                return { type: "text", text: block.text };
+            return { type: "image", source: block.source };
+        });
+    }
     fromAnthropicResponse(response) {
         const content = response.content.map((block) => {
             if (block.type === "text")

package/dist/llm/fallback.js

@@ -1,4 +1,6 @@
 import { createLogger } from "../logger.js";
+import { getTracer, ATTR } from "../telemetry/index.js";
+import { SpanStatusCode, context } from "@opentelemetry/api";
 const log = createLogger("llm");
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503]);
 export function isRetryableError(err) {
@@ -12,17 +14,47 @@ export function isRetryableError(err) {
     return false;
 }
 export async function completeWithFallback(primary, fallbacks, messages, options, completeFn) {
+    const tracer = getTracer("llm");
     const models = [primary, ...fallbacks];
     let lastError;
-    for (const model of models) {
+    for (let idx = 0; idx < models.length; idx++) {
+        const model = models[idx];
+        const [provider = "unknown"] = model.split(":");
+        const attemptSpan = tracer.startSpan("llm.attempt", {}, context.active());
+        attemptSpan.setAttribute(ATTR.PROVIDER, provider);
+        attemptSpan.setAttribute(ATTR.MODEL, model);
         try {
-            return await completeFn(model, messages, options);
+            const response = await completeFn(model, messages, options);
+            // Set token attributes on successful attempt
+            attemptSpan.setAttribute(ATTR.INPUT_TOKENS, response.usage.inputTokens);
+            attemptSpan.setAttribute(ATTR.OUTPUT_TOKENS, response.usage.outputTokens);
+            attemptSpan.setAttribute(ATTR.CACHE_CREATION_TOKENS, response.usage.cacheCreationTokens);
+            attemptSpan.setAttribute(ATTR.CACHE_READ_TOKENS, response.usage.cacheReadTokens);
+            attemptSpan.setAttribute(ATTR.STOP_REASON, response.stopReason);
+            if (response.latencyMs != null) {
+                attemptSpan.setAttribute(ATTR.LATENCY_MS, response.latencyMs);
+            }
+            attemptSpan.end();
+            return response;
         }
         catch (err) {
             lastError = err;
+            const errMsg = err instanceof Error ? err.message : String(err);
+            attemptSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+            if (err instanceof Error)
+                attemptSpan.recordException(err);
+            attemptSpan.end();
             if (!isRetryableError(err) || model === models[models.length - 1]) {
                 throw err;
             }
+            // Record fallback span for the transition to the next model
+            const nextModel = models[idx + 1];
+            const fallbackSpan = tracer.startSpan("llm.fallback", {}, context.active());
+            fallbackSpan.setAttribute(ATTR.FALLBACK_ORIGINAL, model);
+            fallbackSpan.setAttribute(ATTR.FALLBACK_MODEL, nextModel);
+            fallbackSpan.setAttribute(ATTR.FALLBACK_ERROR, errMsg);
+            fallbackSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+            fallbackSpan.end();
             log.warn({ err, model }, "model failed, trying next");
         }
     }

package/dist/llm/openai.d.ts

@@ -7,6 +7,8 @@ export declare class OpenAIProvider implements LLMProvider {
     complete(model: string, messages: Message[], options?: CompleteOptions): Promise<LLMResponse>;
     stream(model: string, messages: Message[], options?: CompleteOptions): AsyncIterable<StreamEvent>;
     private toOpenAIMessages;
+    private mapImageBlock;
+    private mapUserContentToOpenAI;
     private fromOpenAIResponse;
     private mapStopReason;
 }

package/dist/llm/openai.js

@@ -30,7 +30,7 @@ export class OpenAIProvider {
             result.push({ role: "system", content: systemPrompt });
         for (const msg of messages) {
             if (msg.role === "user") {
-                result.push({ role: "user", content: msg.content });
+                result.push({ role: "user", content: this.mapUserContentToOpenAI(msg.content) });
             }
             else if (msg.role === "assistant") {
                 const textParts = msg.content.filter((b) => b.type === "text").map((b) => b.text).join("");
@@ -45,11 +45,42 @@ export class OpenAIProvider {
                 result.push(openaiMsg);
             }
             else if (msg.role === "tool_result") {
-                result.push({ role: "tool", tool_call_id: msg.tool_call_id, content: msg.content });
+                if (typeof msg.content === "string") {
+                    result.push({ role: "tool", tool_call_id: msg.tool_call_id, content: msg.content });
+                }
+                else {
+                    const textParts = msg.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+                    const imageBlocks = msg.content.filter((b) => b.type === "image");
+                    result.push({ role: "tool", tool_call_id: msg.tool_call_id, content: textParts });
+                    if (imageBlocks.length) {
+                        result.push({
+                            role: "user",
+                            content: [
+                                { type: "text", text: "Image(s) from tool result:" },
+                                ...imageBlocks.map((b) => this.mapImageBlock(b)),
+                            ],
+                        });
+                    }
+                }
             }
         }
         return result;
     }
+    mapImageBlock(block) {
+        if (block.source.type === "base64") {
+            return { type: "image_url", image_url: { url: `data:${block.source.media_type};base64,${block.source.data}` } };
+        }
+        return { type: "image_url", image_url: { url: block.source.url } };
+    }
+    mapUserContentToOpenAI(content) {
+        if (typeof content === "string")
+            return content;
+        return content.map((block) => {
+            if (block.type === "text")
+                return { type: "text", text: block.text };
+            return this.mapImageBlock(block);
+        });
+    }
     fromOpenAIResponse(response) {
         const choice = response.choices[0];
         const content = [];

package/dist/llm/types.d.ts

@@ -8,10 +8,22 @@ export interface ToolCallBlock {
     name: string;
     arguments: Record<string, unknown>;
 }
+export interface ImageBlock {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    } | {
+        type: "url";
+        url: string;
+    };
+}
+export type UserContentBlock = TextBlock | ImageBlock;
 export type ContentBlock = TextBlock | ToolCallBlock;
 export interface UserMessage {
     role: "user";
-    content: string;
+    content: string | UserContentBlock[];
 }
 export interface AssistantMessage {
     role: "assistant";
@@ -20,7 +32,7 @@ export interface AssistantMessage {
 export interface ToolResultMessage {
     role: "tool_result";
     tool_call_id: string;
-    content: string;
+    content: string | UserContentBlock[];
 }
 export type Message = UserMessage | AssistantMessage | ToolResultMessage;
 export interface ToolDefinition {
@@ -71,3 +83,5 @@ export interface ErrorEvent {
 }
 export type StreamEvent = TextDeltaEvent | ToolCallStartEvent | ToolCallDeltaEvent | DoneEvent | ErrorEvent;
 export declare function extractText(content: ContentBlock[]): string;
+/** Extract text from user content (string or UserContentBlock[]) */
+export declare function extractUserText(content: string | UserContentBlock[]): string;

package/dist/llm/types.js

@@ -4,3 +4,12 @@ export function extractText(content) {
         .map((b) => b.text)
         .join("");
 }
+/** Extract text from user content (string or UserContentBlock[]) */
+export function extractUserText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+}

package/dist/logger.d.ts

@@ -1,2 +1,3 @@
 import pino from "pino";
 export declare function createLogger(name: string): pino.Logger<never, boolean>;
+export declare function setLogLevel(level: pino.Level | "silent"): void;

package/dist/logger.js

@@ -1,4 +1,5 @@
 import pino from "pino";
+import { trace } from "@opentelemetry/api";
 const root = pino({
     level: process.env.LOG_LEVEL ?? "info",
     transport: {
@@ -9,7 +10,17 @@ const root = pino({
             colorize: true,
         },
     },
+    mixin() {
+        const span = trace.getActiveSpan();
+        if (!span)
+            return {};
+        const ctx = span.spanContext();
+        return { trace_id: ctx.traceId, span_id: ctx.spanId };
+    },
 });
 export function createLogger(name) {
     return root.child({ component: name });
 }
+export function setLogLevel(level) {
+    root.level = level;
+}

package/dist/media/sanitize.d.ts

@@ -0,0 +1,5 @@
+export interface SanitizedImage {
+    base64: string;
+    mediaType: string;
+}
+export declare function sanitizeImage(buffer: Buffer, claimedMimeType?: string): Promise<SanitizedImage>;

package/dist/media/sanitize.js

@@ -0,0 +1,53 @@
+import sharp from "sharp";
+const MAX_BYTES = 20 * 1024 * 1024; // 20MB — raw upload limit (sharp will resize/compress)
+const MAX_DIMENSION = 1200;
+const JPEG_QUALITY = 85;
+const SUPPORTED_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+// Magic byte signatures
+const SIGNATURES = [
+    [Buffer.from([0x89, 0x50, 0x4e, 0x47]), "image/png"],
+    [Buffer.from([0xff, 0xd8, 0xff]), "image/jpeg"],
+    [Buffer.from("GIF87a"), "image/gif"],
+    [Buffer.from("GIF89a"), "image/gif"],
+    [Buffer.from("RIFF"), "image/webp"], // RIFF....WEBP
+];
+function sniffMimeType(buffer) {
+    for (const [sig, type] of SIGNATURES) {
+        if (buffer.length >= sig.length && buffer.subarray(0, sig.length).equals(sig)) {
+            // For WEBP, also check bytes 8-12 for "WEBP"
+            if (type === "image/webp") {
+                if (buffer.length >= 12 && buffer.subarray(8, 12).toString() === "WEBP")
+                    return type;
+                continue;
+            }
+            return type;
+        }
+    }
+    return undefined;
+}
+export async function sanitizeImage(buffer, claimedMimeType) {
+    if (buffer.length > MAX_BYTES) {
+        throw new Error(`Image exceeds 20 MB size limit (${(buffer.length / 1024 / 1024).toFixed(1)} MB)`);
+    }
+    const sniffed = sniffMimeType(buffer);
+    const mediaType = sniffed ?? claimedMimeType;
+    if (!mediaType || !SUPPORTED_TYPES.has(mediaType)) {
+        throw new Error(`Unsupported image type: ${mediaType ?? "unknown"}`);
+    }
+    const meta = await sharp(buffer).metadata();
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    let output;
+    if (width > MAX_DIMENSION || height > MAX_DIMENSION) {
+        // Resize to fit within MAX_DIMENSION, preserving aspect ratio
+        // Recompress as JPEG for smaller output
+        output = await sharp(buffer)
+            .resize(MAX_DIMENSION, MAX_DIMENSION, { fit: "inside", withoutEnlargement: true })
+            .jpeg({ quality: JPEG_QUALITY })
+            .toBuffer();
+        return { base64: output.toString("base64"), mediaType: "image/jpeg" };
+    }
+    // No resize needed — return as-is
+    output = buffer;
+    return { base64: output.toString("base64"), mediaType };
+}

package/dist/multi/spawn.js

@@ -1,14 +1,33 @@
 import { runAgentLoop } from "../agent/loop.js";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { getTracer, ATTR } from "../telemetry/index.js";
 export async function spawnAgent(options) {
-    return runAgentLoop([{ role: "user", content: options.task }], {
-        model: options.model,
-        fallbacks: options.fallbacks,
-        systemPrompt: options.systemPrompt,
-        tools: options.tools,
-        maxIterations: options.maxIterations ?? 10,
-        label: options.label,
-        agentName: options.label,
-        usageStore: options.usageStore,
-        source: "spawn",
+    const tracer = getTracer("multi");
+    const span = tracer.startSpan("agent.spawn", {
+        attributes: {
+            [ATTR.SPAWN_CHILD]: options.label ?? "unknown",
+        },
     });
+    try {
+        const result = await runAgentLoop([{ role: "user", content: options.task }], {
+            model: options.model,
+            fallbacks: options.fallbacks,
+            systemPrompt: options.systemPrompt,
+            tools: options.tools,
+            maxIterations: options.maxIterations ?? 10,
+            label: options.label,
+            agentName: options.label,
+            usageStore: options.usageStore,
+            source: "spawn",
+        });
+        return result;
+    }
+    catch (err) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+    }
+    finally {
+        span.end();
+    }
 }

package/dist/session/compaction.js

@@ -1,5 +1,6 @@
 import { complete } from "../llm/index.js";
 import { extractText } from "../llm/types.js";
+import { pruneImages } from "./prune-images.js";
 export function estimateTokens(message) {
     return Math.ceil(JSON.stringify(message).length / 4);
 }
@@ -13,6 +14,7 @@ export async function compactMessages(messages, model, tokenThreshold = 100_000)
     const splitPoint = Math.floor(messages.length / 2);
     const oldMessages = messages.slice(0, splitPoint);
     const recentMessages = messages.slice(splitPoint);
+    const prunedOld = pruneImages(oldMessages, 0);
     const summaryResponse = await complete(model, [{
             role: "user",
             content: "Summarize this conversation concisely. Preserve:\n" +
@@ -20,7 +22,7 @@ export async function compactMessages(messages, model, tokenThreshold = 100_000)
                 "- Important decisions made\n" +
                 "- Open tasks or TODOs\n" +
                 "- File paths and code changes discussed\n\n" +
-                JSON.stringify(oldMessages, null, 2),
+                JSON.stringify(prunedOld, null, 2),
         }]);
     const summaryText = extractText(summaryResponse.content);
     return [

package/dist/session/prune-images.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from "../llm/types.js";
+/**
+ * Returns a shallow copy of messages with ImageBlocks replaced by text placeholders
+ * in user messages older than `keepLastNTurns` user turns from the end.
+ * A "turn" is defined by a user message — all messages (assistant, tool_result)
+ * between two user messages belong to the same turn as the preceding user message.
+ * Does NOT mutate the original array.
+ */
+export declare function pruneImages(messages: Message[], keepLastNTurns?: number): Message[];

package/dist/session/prune-images.js

@@ -0,0 +1,42 @@
+const IMAGE_PLACEHOLDER = {
+    type: "text",
+    text: "[image previously shared \u2014 already processed]",
+};
+/**
+ * Returns a shallow copy of messages with ImageBlocks replaced by text placeholders
+ * in user messages older than `keepLastNTurns` user turns from the end.
+ * A "turn" is defined by a user message — all messages (assistant, tool_result)
+ * between two user messages belong to the same turn as the preceding user message.
+ * Does NOT mutate the original array.
+ */
+export function pruneImages(messages, keepLastNTurns = 4) {
+    // Find the Nth user message from the end — this is the start of the kept range.
+    // Everything before it (older turns and their tool results) gets image-pruned.
+    let turnsSeen = 0;
+    let cutoff = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            turnsSeen++;
+            if (turnsSeen === keepLastNTurns) {
+                cutoff = i;
+                break;
+            }
+        }
+    }
+    if (turnsSeen < keepLastNTurns)
+        return messages; // fewer turns than threshold
+    return messages.map((msg, i) => {
+        if (i >= cutoff)
+            return msg;
+        if (msg.role === "user" || msg.role === "tool_result") {
+            if (typeof msg.content === "string")
+                return msg;
+            const hasImage = msg.content.some((b) => b.type === "image");
+            if (!hasImage)
+                return msg;
+            const pruned = msg.content.map((b) => b.type === "image" ? IMAGE_PLACEHOLDER : b);
+            return { ...msg, content: pruned };
+        }
+        return msg;
+    });
+}

package/dist/skills/activate.d.ts

@@ -1,6 +1,7 @@
 import type { Tool } from "../tools/types.js";
 import type { ToolRegistry } from "../tools/registry.js";
 import type { SkillManifest } from "./schema.js";
+import type { Logger } from "pino";
 export interface SkillActivationContext {
     manifests: SkillManifest[];
     skillsDir: string;
@@ -8,4 +9,9 @@ export interface SkillActivationContext {
     promptFragments: string[];
     activatedSkills: Set<string>;
 }
+/**
+ * Auto-activate all skills upfront so the LLM doesn't need to call activate_skill.
+ * Returns the skillsIndex string to append to the system prompt.
+ */
+export declare function preActivateSkills(ctx: SkillActivationContext, activateTool: Tool, logger?: Logger): Promise<string>;
 export declare function createActivateSkillTool(ctx: SkillActivationContext): Tool;