@claudebuddy/claudebuddy-agent-sdk 0.4.0

package/dist/utils/messages.js

@@ -0,0 +1,152 @@
+/**
+ * Message Utilities
+ *
+ * Message creation factories, normalization for API,
+ * synthetic placeholders, and content processing.
+ */
+/**
+ * Create a user message.
+ */
+export function createUserMessage(content, options) {
+    return {
+        type: 'user',
+        message: {
+            role: 'user',
+            content,
+        },
+        uuid: options?.uuid || crypto.randomUUID(),
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Create an assistant message.
+ */
+export function createAssistantMessage(content, usage) {
+    return {
+        type: 'assistant',
+        message: {
+            role: 'assistant',
+            content,
+        },
+        uuid: crypto.randomUUID(),
+        timestamp: new Date().toISOString(),
+        usage,
+    };
+}
+/**
+ * Normalize messages for the LLM API.
+ * Ensures proper message format, strips internal metadata,
+ * and fixes tool result pairing.
+ */
+export function normalizeMessagesForAPI(messages) {
+    const normalized = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        // Ensure alternating user/assistant messages
+        if (normalized.length > 0) {
+            const last = normalized[normalized.length - 1];
+            if (last.role === msg.role) {
+                // Merge same-role messages
+                if (msg.role === 'user') {
+                    // Combine content
+                    const lastContent = typeof last.content === 'string'
+                        ? [{ type: 'text', text: last.content }]
+                        : last.content;
+                    const newContent = typeof msg.content === 'string'
+                        ? [{ type: 'text', text: msg.content }]
+                        : msg.content;
+                    normalized[normalized.length - 1] = {
+                        role: 'user',
+                        content: [...lastContent, ...newContent],
+                    };
+                    continue;
+                }
+            }
+        }
+        normalized.push({ ...msg });
+    }
+    // Ensure tool results are properly paired with tool_use
+    return fixToolResultPairing(normalized);
+}
+/**
+ * Fix tool result pairing: ensure every tool_result has a
+ * matching tool_use in the previous assistant message.
+ */
+function fixToolResultPairing(messages) {
+    const result = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role === 'user' && Array.isArray(msg.content)) {
+            // Check for tool_result blocks
+            const toolResults = msg.content.filter((block) => block.type === 'tool_result');
+            if (toolResults.length > 0 && result.length > 0) {
+                // Find the previous assistant message
+                const prevAssistant = result[result.length - 1];
+                if (prevAssistant.role === 'assistant' && Array.isArray(prevAssistant.content)) {
+                    const toolUseIds = new Set(prevAssistant.content
+                        .filter((b) => b.type === 'tool_use')
+                        .map((b) => b.id));
+                    // Filter out orphaned tool results
+                    const validContent = msg.content.filter((block) => {
+                        if (block.type === 'tool_result') {
+                            return toolUseIds.has(block.tool_use_id);
+                        }
+                        return true;
+                    });
+                    if (validContent.length > 0) {
+                        result.push({ ...msg, content: validContent });
+                    }
+                    continue;
+                }
+            }
+        }
+        result.push(msg);
+    }
+    return result;
+}
+/**
+ * Strip images from messages (for compaction).
+ */
+export function stripImagesFromMessages(messages) {
+    return messages.map((msg) => {
+        if (typeof msg.content === 'string')
+            return msg;
+        if (!Array.isArray(msg.content))
+            return msg;
+        const filtered = msg.content.filter((block) => block.type !== 'image');
+        return {
+            ...msg,
+            content: filtered.length > 0 ? filtered : '[content removed]',
+        };
+    });
+}
+/**
+ * Extract text from message content blocks.
+ */
+export function extractTextFromContent(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('');
+}
+/**
+ * Create a system message for compact boundary.
+ */
+export function createCompactBoundaryMessage() {
+    return {
+        role: 'user',
+        content: '[Previous context has been summarized above. Continuing conversation.]',
+    };
+}
+/**
+ * Truncate text to max length with ellipsis.
+ */
+export function truncateText(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    const half = Math.floor(maxLength / 2);
+    return text.slice(0, half) + '\n...(truncated)...\n' + text.slice(-half);
+}
+//# sourceMappingURL=messages.js.map

package/dist/utils/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/utils/messages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAuB,EACvB,OAIC;IAED,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE;YACP,IAAI,EAAE,MAAM;YACZ,OAAO;SACR;QACD,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE;QAC1C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAc,EACd,KAAkB;IAElB,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE;YACP,IAAI,EAAE,WAAW;YACjB,OAAO;SACR;QACD,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE;QACzB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK;KACN,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAA+C;IAE/C,MAAM,UAAU,GAA0C,EAAE,CAAA;IAE5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;QAEvB,6CAA6C;QAC7C,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;YAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;gBAC3B,2BAA2B;gBAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;oBACxB,kBAAkB;oBAClB,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ;wBAClD,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;wBACjD,CAAC,CAAC,IAAI,CAAC,OAAgB,CAAA;oBACzB,MAAM,UAAU,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;wBAChD,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;wBAChD,CAAC,CAAC,GAAG,CAAC,OAAgB,CAAA;oBACxB,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG;wBAClC,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC;qBACzC,CAAA;oBACD,SAAQ;gBACV,CAAC;YACH,CAAC;QACH,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAA;IAC7B,CAAC;IAED,wDAAwD;IACxD,OAAO,oBAAoB,CAAC,UAAU,CAAC,CAAA;AACzC,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAC3B,QAA+C;IAE/C,MAAM,MAAM,GAA0C,EAAE,CAAA;IAExD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;QAEvB,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,+BAA+B;YAC/B,MAAM,WAAW,GAAI,GAAG,CAAC,OAAiB,CAAC,MAAM,CAC/C,CAAC,KAAU,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,CAC7C,CAAA;YAED,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChD,sCAAsC;gBACtC,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;gBAC/C,IAAI,aAAa,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC/E,MAAM,UAAU,GAAG,IAAI,GAAG,CACvB,aAAa,CAAC,OAAiB;yBAC7B,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;yBACzC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACzB,CAAA;oBAED,mCAAmC;oBACnC,MAAM,YAAY,GAAI,GAAG,CAAC,OAAiB,CAAC,MAAM,CAAC,CAAC,KAAU,EAAE,EAAE;wBAChE,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;4BACjC,OAAO,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;wBAC1C,CAAC;wBACD,OAAO,IAAI,CAAA;oBACb,CAAC,CAAC,CAAA;oBAEF,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBAC5B,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAA;oBAChD,CAAC;oBACD,SAAQ;gBACV,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAClB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAA+C;IAE/C,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC1B,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAA;QAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,GAAG,CAAA;QAE3C,MAAM,QAAQ,GAAI,GAAG,CAAC,OAAiB,CAAC,MAAM,CAC5C,CAAC,KAAU,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CACvC,CAAA;QAED,OAAO;YACL,GAAG,GAAG;YACN,OAAO,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,mBAAmB;SAC9D,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAuB;IAEvB,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAA;IAE/C,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SACrC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SACvB,IAAI,CAAC,EAAE,CAAC,CAAA;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,wEAAwE;KAClF,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,SAAiB;IAC1D,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,IAAI,CAAA;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAA;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,uBAAuB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAA;AAC1E,CAAC"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Retry Logic with Exponential Backoff
+ *
+ * Handles API retries for rate limits, overloaded servers,
+ * and transient failures.
+ */
+/**
+ * Retry configuration.
+ */
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableStatusCodes: number[];
+}
+/**
+ * Default retry configuration.
+ */
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Check if an error is retryable.
+ */
+export declare function isRetryableError(err: any, config?: RetryConfig): boolean;
+/**
+ * Calculate delay for exponential backoff.
+ */
+export declare function getRetryDelay(attempt: number, config?: RetryConfig): number;
+/**
+ * Execute a function with retries.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig, abortSignal?: AbortSignal): Promise<T>;
+/**
+ * Check if an error is a "prompt too long" error.
+ */
+export declare function isPromptTooLongError(err: any): boolean;
+/**
+ * Check if error is an auth error.
+ */
+export declare function isAuthError(err: any): boolean;
+/**
+ * Check if error is a rate limit error.
+ */
+export declare function isRateLimitError(err: any): boolean;
+/**
+ * Format an API error for display.
+ */
+export declare function formatApiError(err: any): string;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,oBAAoB,EAAE,MAAM,EAAE,CAAA;CAC/B;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAKlC,CAAA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAE,WAAkC,GAAG,OAAO,CAgB9F;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,WAAkC,GAAG,MAAM,CAKjG;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,WAAkC,EAC1C,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,CAAC,CAAC,CA4BZ;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAQtD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAE7C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAElD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAc/C"}

package/dist/utils/retry.js

@@ -0,0 +1,111 @@
+/**
+ * Retry Logic with Exponential Backoff
+ *
+ * Handles API retries for rate limits, overloaded servers,
+ * and transient failures.
+ */
+/**
+ * Default retry configuration.
+ */
+export const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 2000,
+    maxDelayMs: 30000,
+    retryableStatusCodes: [429, 500, 502, 503, 529],
+};
+/**
+ * Check if an error is retryable.
+ */
+export function isRetryableError(err, config = DEFAULT_RETRY_CONFIG) {
+    if (err?.status && config.retryableStatusCodes.includes(err.status)) {
+        return true;
+    }
+    // Network errors
+    if (err?.code === 'ECONNRESET' || err?.code === 'ETIMEDOUT' || err?.code === 'ECONNREFUSED') {
+        return true;
+    }
+    // API overloaded
+    if (err?.error?.type === 'overloaded_error') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Calculate delay for exponential backoff.
+ */
+export function getRetryDelay(attempt, config = DEFAULT_RETRY_CONFIG) {
+    const delay = config.baseDelayMs * Math.pow(2, attempt);
+    // Add jitter (±25%)
+    const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+    return Math.min(delay + jitter, config.maxDelayMs);
+}
+/**
+ * Execute a function with retries.
+ */
+export async function withRetry(fn, config = DEFAULT_RETRY_CONFIG, abortSignal) {
+    let lastError;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        if (abortSignal?.aborted) {
+            throw new Error('Aborted');
+        }
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (!isRetryableError(err, config)) {
+                throw err;
+            }
+            if (attempt === config.maxRetries) {
+                throw err;
+            }
+            // Wait before retry
+            const delay = getRetryDelay(attempt, config);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Check if an error is a "prompt too long" error.
+ */
+export function isPromptTooLongError(err) {
+    if (err?.status === 400) {
+        const message = err?.error?.error?.message || err?.message || '';
+        return message.includes('prompt is too long') ||
+            message.includes('max_tokens') ||
+            message.includes('context length');
+    }
+    return false;
+}
+/**
+ * Check if error is an auth error.
+ */
+export function isAuthError(err) {
+    return err?.status === 401 || err?.status === 403;
+}
+/**
+ * Check if error is a rate limit error.
+ */
+export function isRateLimitError(err) {
+    return err?.status === 429;
+}
+/**
+ * Format an API error for display.
+ */
+export function formatApiError(err) {
+    if (isAuthError(err)) {
+        return 'Authentication failed. Check your CLAUDEBUDDY_API_KEY.';
+    }
+    if (isRateLimitError(err)) {
+        return 'Rate limit exceeded. Please retry after a short wait.';
+    }
+    if (err?.status === 529) {
+        return 'API overloaded. Please retry later.';
+    }
+    if (isPromptTooLongError(err)) {
+        return 'Prompt too long. Auto-compacting conversation...';
+    }
+    return `API error: ${err.message || err}`;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

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

package/dist/utils/spill.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Spill — overflow text off to disk
+ *
+ * When a tool result is far larger than the context can afford, we do not
+ * truncate it inline (which loses data and wastes tokens on the tail anyway).
+ * Instead we "spill" the full text to a file on disk and hand the model a
+ * compact head/tail preview plus a locator the model (or a later spill-aware
+ * tool) can use to retrieve the full payload on demand.
+ *
+ * Design rules (mirroring DeepSeek's spill-policy):
+ * 1. Purely presentational — it is a post-processing layer, decoupled from
+ *    the tool implementation. The underlying tool result is never mutated.
+ * 2. Best-effort — if spilling fails (disk full, no permission) the original
+ *    successful result is returned unchanged. A spill failure must never turn
+ *    a successful tool call into an error.
+ * 3. The replacement text must itself stay under the cap, with a reserved
+ *    byte budget for the locator/notice so it can never overflow.
+ * 4. Skip spill for reading tools to avoid a read -> spill -> read cycle.
+ */
+/** A stored spill: an opaque locator plus a model-visible preview. */
+export interface SpillEntry {
+    /** Opaque handle used to retrieve the stored full text later. */
+    locator: string;
+    /** File path the full text was written to (locator may reference it). */
+    path: string;
+    /** Byte size of the spilled content. */
+    size: number;
+}
+/** Configuration for the spill store. */
+export interface SpillStoreOptions {
+    /** Directory to write spill files into. Defaults to <cwd>/.spill. */
+    spillDir?: string;
+    /** Maximum bytes stored per file before we still abort a spill attempt. */
+    maxSpillBytes?: number;
+}
+/**
+ * Append-only spill store. Each spill gets its own file so there is no
+ * locking or ordering concern. The locator is the absolute file path — simple,
+ * unique per write, and trivially re-fetchable by any file tool.
+ */
+export declare class SpillStore {
+    private readonly spillDir;
+    private readonly maxSpillBytes;
+    private seq;
+    constructor(options?: SpillStoreOptions);
+    /** Lazily ensure the spill directory exists. */
+    private ensureDir;
+    /**
+     * Write `text` to a new spill file if it is non-empty and within limits.
+     * Never throws: any failure is reported via the `ok: false` shape.
+     */
+    saveText(text: string, tag?: string): Promise<{
+        ok: true;
+        entry: SpillEntry;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** Read a spilled payload back by its locator (the absolute path). */
+    read(locator: string): Promise<string | undefined>;
+}
+/**
+ * Build the compact model-visible preview for a spilled blob: head + "…truncated…"
+ * + tail, sized so head+tail+notice fit within `previewBytes` with room to spare.
+ */
+export declare function buildPreview(text: string, previewBytes?: number): string;
+/**
+ * Policy-level options controlling when a tool result is spilled.
+ */
+export interface SpillPolicyOptions {
+    /** Tool results above this many bytes are spilled. Default 20000. */
+    maxInlineBytes?: number;
+    /** Size of the head/tail preview given to the model. Default 4000. */
+    previewBytes?: number;
+    /** Tool names that should never be spilled (to avoid read->spill->read loops). */
+    neverSpillTools?: string[];
+}
+/**
+ * Apply the spill policy to a single tool result content string.
+ *
+ * Returns a tagged result so the caller can distinguish:
+ * - `{ kind: 'keep', content }`       — unchanged (small, or tool excluded)
+ * - `{ kind: 'spill', content, entry }` — spilled; preview replaces content
+ * - `{ kind: 'failed', content }`     — spill attempted but failed; keep original
+ */
+export declare function applySpillPolicy(text: string, store: SpillStore, options?: SpillPolicyOptions): Promise<{
+    kind: 'keep';
+    content: string;
+} | {
+    kind: 'spill';
+    content: string;
+    entry: SpillEntry;
+} | {
+    kind: 'failed';
+    content: string;
+    error: string;
+}>;
+/** Skip spill for a given tool name (avoid read -> spill -> read loops). */
+export declare function shouldNeverSpill(toolName: string, neverSpillTools?: string[]): boolean;
+//# sourceMappingURL=spill.d.ts.map

package/dist/utils/spill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spill.d.ts","sourceRoot":"","sources":["../../src/utils/spill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAA;IACf,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;CACb;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,GAAG,CAAI;gBAEH,OAAO,GAAE,iBAAsB;IAK3C,gDAAgD;YAClC,SAAS;IAKvB;;;OAGG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAqBnH,sEAAsE;IAChE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAazD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,MAAa,GAC1B,MAAM,CAUR;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CACN;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CACrD,CAgBA;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,eAAe,GAAE,MAAM,EAAO,GAC7B,OAAO,CAGT"}

package/dist/utils/spill.js

@@ -0,0 +1,126 @@
+/**
+ * Spill — overflow text off to disk
+ *
+ * When a tool result is far larger than the context can afford, we do not
+ * truncate it inline (which loses data and wastes tokens on the tail anyway).
+ * Instead we "spill" the full text to a file on disk and hand the model a
+ * compact head/tail preview plus a locator the model (or a later spill-aware
+ * tool) can use to retrieve the full payload on demand.
+ *
+ * Design rules (mirroring DeepSeek's spill-policy):
+ * 1. Purely presentational — it is a post-processing layer, decoupled from
+ *    the tool implementation. The underlying tool result is never mutated.
+ * 2. Best-effort — if spilling fails (disk full, no permission) the original
+ *    successful result is returned unchanged. A spill failure must never turn
+ *    a successful tool call into an error.
+ * 3. The replacement text must itself stay under the cap, with a reserved
+ *    byte budget for the locator/notice so it can never overflow.
+ * 4. Skip spill for reading tools to avoid a read -> spill -> read cycle.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * Append-only spill store. Each spill gets its own file so there is no
+ * locking or ordering concern. The locator is the absolute file path — simple,
+ * unique per write, and trivially re-fetchable by any file tool.
+ */
+export class SpillStore {
+    spillDir;
+    maxSpillBytes;
+    seq = 0;
+    constructor(options = {}) {
+        this.spillDir = options.spillDir ?? '.spill';
+        this.maxSpillBytes = options.maxSpillBytes ?? 20 * 1024 * 1024;
+    }
+    /** Lazily ensure the spill directory exists. */
+    async ensureDir() {
+        await fs.mkdir(this.spillDir, { recursive: true });
+        return this.spillDir;
+    }
+    /**
+     * Write `text` to a new spill file if it is non-empty and within limits.
+     * Never throws: any failure is reported via the `ok: false` shape.
+     */
+    async saveText(text, tag) {
+        try {
+            if (typeof text !== 'string' || text.length === 0) {
+                return { ok: false, error: 'nothing to spill' };
+            }
+            const bytes = Buffer.byteLength(text, 'utf8');
+            if (bytes > this.maxSpillBytes) {
+                return { ok: false, error: `spill exceeds maxSpillBytes (${bytes} > ${this.maxSpillBytes})` };
+            }
+            const dir = await this.ensureDir();
+            const seq = ++this.seq;
+            const safeTag = (tag ?? 'result').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 40);
+            const fileName = `${Date.now()}-${seq}-${safeTag}.spill.txt`;
+            const filePath = path.join(dir, fileName);
+            await fs.writeFile(filePath, text, 'utf8');
+            return { ok: true, entry: { locator: filePath, path: filePath, size: bytes } };
+        }
+        catch (err) {
+            return { ok: false, error: err?.message ? String(err.message) : String(err) };
+        }
+    }
+    /** Read a spilled payload back by its locator (the absolute path). */
+    async read(locator) {
+        try {
+            // Defensive: only allow reads of files under our spill directory.
+            const resolved = path.resolve(locator);
+            const dir = path.resolve(this.spillDir);
+            if (!resolved.startsWith(dir + path.sep) && resolved !== dir) {
+                return undefined;
+            }
+            return await fs.readFile(resolved, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Build the compact model-visible preview for a spilled blob: head + "…truncated…"
+ * + tail, sized so head+tail+notice fit within `previewBytes` with room to spare.
+ */
+export function buildPreview(text, previewBytes = 4000) {
+    // Reserve ~10% for the locator notice so the replacement never overflows.
+    const headBudget = Math.floor((previewBytes * 0.9) / 2);
+    const tailBudget = Math.floor((previewBytes * 0.9) / 2);
+    const total = text.length;
+    if (total <= previewBytes * 0.9)
+        return text;
+    const head = text.slice(0, headBudget);
+    const tail = text.slice(total - tailBudget);
+    const omitted = total - headBudget - tailBudget;
+    return `${head}\n\n…[${omitted} chars omitted; full result spilled to disk]…\n\n${tail}`;
+}
+/**
+ * Apply the spill policy to a single tool result content string.
+ *
+ * Returns a tagged result so the caller can distinguish:
+ * - `{ kind: 'keep', content }`       — unchanged (small, or tool excluded)
+ * - `{ kind: 'spill', content, entry }` — spilled; preview replaces content
+ * - `{ kind: 'failed', content }`     — spill attempted but failed; keep original
+ */
+export async function applySpillPolicy(text, store, options = {}) {
+    const maxInlineBytes = options.maxInlineBytes ?? 20000;
+    const previewBytes = options.previewBytes ?? 4000;
+    const bytes = Buffer.byteLength(text, 'utf8');
+    if (bytes <= maxInlineBytes)
+        return { kind: 'keep', content: text };
+    const saved = await store.saveText(text);
+    if (!saved.ok) {
+        // Best-effort: never turn a success into an error, never lose data.
+        return { kind: 'failed', content: text, error: saved.error };
+    }
+    const preview = buildPreview(text, previewBytes);
+    const notice = `\n\n[Full ${bytes} bytes spilled to: ${saved.entry.locator}]`;
+    return { kind: 'spill', content: preview + notice, entry: saved.entry };
+}
+/** Skip spill for a given tool name (avoid read -> spill -> read loops). */
+export function shouldNeverSpill(toolName, neverSpillTools = []) {
+    if (neverSpillTools.length === 0)
+        return false;
+    return neverSpillTools.some((n) => toolName === n || toolName.toLowerCase().includes(n.toLowerCase()));
+}
+//# sourceMappingURL=spill.js.map

package/dist/utils/spill.js.map

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

package/dist/utils/tokens.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Token Estimation & Counting
+ *
+ * Provides rough token estimation (character-based) and
+ * API-based exact counting when available.
+ */
+/**
+ * Rough token estimation: ~4 chars per token (conservative).
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimate tokens for a message array.
+ */
+export declare function estimateMessagesTokens(messages: Array<{
+    role: string;
+    content: any;
+}>): number;
+/**
+ * Estimate tokens for a system prompt.
+ */
+export declare function estimateSystemPromptTokens(systemPrompt: string): number;
+/**
+ * Count tokens from API usage response.
+ */
+export declare function getTokenCountFromUsage(usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}): number;
+/**
+ * Get the context window size for a model.
+ */
+export declare function getContextWindowSize(model: string, contextWindowSize?: number): number;
+/**
+ * Auto-compact buffer: trigger compaction when within this many tokens of the limit.
+ */
+export declare const AUTOCOMPACT_BUFFER_TOKENS = 13000;
+/**
+ * Get the auto-compact threshold for a model.
+ */
+export declare function getAutoCompactThreshold(model: string, contextWindowSize?: number): number;
+/**
+ * Model pricing (USD per token).
+ */
+export declare const MODEL_PRICING: Record<string, {
+    input: number;
+    output: number;
+}>;
+/**
+ * Estimate cost from usage and model.
+ */
+export declare function estimateCost(model: string, usage: {
+    input_tokens: number;
+    output_tokens: number;
+}, pricing?: {
+    input: number;
+    output: number;
+}): number;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/utils/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/utils/tokens.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAE,CAAC,GAC9C,MAAM,CAmBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,uBAAuB,CAAC,EAAE,MAAM,CAAA;CACjC,GAAG,MAAM,CAOT;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,iBAAiB,CAAC,EAAE,MAAM,GACzB,MAAM,CAwBR;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAE/C;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,iBAAiB,CAAC,EAAE,MAAM,GACzB,MAAM,CAER;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAuB3E,CAAA;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C,MAAM,CAeR"}