@gugacoder/agentic-sdk 0.2.0

package/dist/context/compaction.js

@@ -0,0 +1,219 @@
+import { generateText, Output, wrapLanguageModel } from "ai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { z } from "zod";
+import { countTokens } from "./tokenizer.js";
+import { getContextWindow } from "./models.js";
+const CompactionSchema = z.object({
+    summary: z.string().describe("Resumo conciso da conversa"),
+    decisions: z.array(z.string()).describe("Decisoes tomadas"),
+    filesModified: z.array(z.string()).describe("Arquivos modificados"),
+    currentState: z.string().describe("Estado atual do trabalho"),
+    nextSteps: z.array(z.string()).describe("Proximos passos"),
+});
+const TAIL_RATIO = 0.30;
+const SUMMARIZATION_PROMPT = `Summarize the conversation below preserving: decisions made, files modified, current state of work, and next steps. Be concise.`;
+function countMessageTokens(msg) {
+    let tokens = 4; // overhead for role + framing
+    if (typeof msg.content === "string") {
+        tokens += countTokens(msg.content);
+    }
+    else if (Array.isArray(msg.content)) {
+        for (const part of msg.content) {
+            if (part.type === "text" && typeof part.text === "string") {
+                tokens += countTokens(part.text);
+            }
+            else if (part.type === "image") {
+                tokens += 300;
+            }
+            else if (part.type === "file") {
+                const mime = part.mimeType ?? "";
+                if (mime === "application/pdf") {
+                    tokens += 1500;
+                }
+                else if (mime.startsWith("audio/")) {
+                    tokens += 200;
+                }
+                else {
+                    tokens += 500;
+                }
+            }
+            else {
+                tokens += 500; // unknown part fallback
+            }
+        }
+    }
+    return tokens;
+}
+function formatMessagesForSummary(messages) {
+    return messages
+        .map((msg) => {
+        const role = msg.role;
+        const content = typeof msg.content === "string"
+            ? msg.content
+            : Array.isArray(msg.content)
+                ? msg.content
+                    .filter((p) => "text" in p)
+                    .map((p) => p.text)
+                    .join("\n")
+                : "[non-text content]";
+        return `[${role}]: ${content}`;
+    })
+        .join("\n\n");
+}
+/**
+ * Splits messages into head (to summarize) and tail (to keep intact).
+ * Tail = last messages that fit within 30% of the context window.
+ */
+function splitMessages(messages, contextWindow) {
+    const tailBudget = Math.floor(contextWindow * TAIL_RATIO);
+    let tailTokens = 0;
+    let tailStart = messages.length;
+    // Walk backwards to find tail boundary
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msgTokens = countMessageTokens(messages[i]);
+        if (tailTokens + msgTokens > tailBudget)
+            break;
+        tailTokens += msgTokens;
+        tailStart = i;
+    }
+    // Ensure at least one message in head (nothing to compact otherwise)
+    if (tailStart <= 0) {
+        tailStart = 1;
+    }
+    return {
+        head: messages.slice(0, tailStart),
+        tail: messages.slice(tailStart),
+    };
+}
+/**
+ * Compacts conversation messages by summarizing older messages (head)
+ * and keeping recent messages (tail) intact.
+ *
+ * Uses the same model and apiKey as the agent for summarization.
+ * If summarization fails, returns original messages with a warning.
+ */
+export async function compactMessages(messages, options) {
+    // Nothing to compact if 2 or fewer messages
+    if (messages.length <= 2) {
+        return { messages, compacted: false };
+    }
+    const contextWindow = getContextWindow(options.model, options.contextWindow);
+    const { head, tail } = splitMessages(messages, contextWindow);
+    // If head is empty or has only 1 message, nothing to compact
+    if (head.length <= 1) {
+        return { messages, compacted: false };
+    }
+    const conversationText = formatMessagesForSummary(head);
+    // Build telemetry config for compaction spans
+    const telemetryConfig = options.telemetry?.enabled
+        ? {
+            isEnabled: true,
+            functionId: options.telemetry.functionId
+                ? `${options.telemetry.functionId}-compaction`
+                : "ai-compaction",
+            recordInputs: false,
+            recordOutputs: false,
+            metadata: {
+                ...options.telemetry.metadata,
+            },
+        }
+        : undefined;
+    try {
+        const baseModel = options.providers
+            ? options.providers.model(options.model)
+            : createOpenAICompatible({
+                name: "openrouter",
+                baseURL: "https://openrouter.ai/api/v1",
+                apiKey: options.apiKey,
+            })(options.model);
+        const model = options.middleware && options.middleware.length > 0
+            ? wrapLanguageModel({ model: baseModel, middleware: options.middleware })
+            : baseModel;
+        const result = await generateText({
+            model,
+            output: Output.object({ schema: CompactionSchema }),
+            system: SUMMARIZATION_PROMPT,
+            messages: [{ role: "user", content: conversationText }],
+            maxOutputTokens: 2000,
+            ...(telemetryConfig ? { experimental_telemetry: telemetryConfig } : {}),
+        });
+        const obj = result.output;
+        if (!obj.summary || obj.summary.trim().length === 0) {
+            return {
+                messages,
+                compacted: false,
+                warning: "Compaction produced empty summary — keeping original messages",
+            };
+        }
+        const sections = [];
+        sections.push(`## Summary\n${obj.summary}`);
+        if (obj.decisions.length > 0) {
+            sections.push(`## Decisions\n${obj.decisions.map((d) => `- ${d}`).join("\n")}`);
+        }
+        if (obj.filesModified.length > 0) {
+            sections.push(`## Files Modified\n${obj.filesModified.map((f) => `- ${f}`).join("\n")}`);
+        }
+        sections.push(`## Current State\n${obj.currentState}`);
+        if (obj.nextSteps.length > 0) {
+            sections.push(`## Next Steps\n${obj.nextSteps.map((s) => `- ${s}`).join("\n")}`);
+        }
+        const summary = sections.join("\n\n");
+        const summaryMessage = {
+            role: "user",
+            content: `<context_summary>\n${summary}\n</context_summary>`,
+        };
+        return {
+            messages: [summaryMessage, ...tail],
+            compacted: true,
+        };
+    }
+    catch (structuredErr) {
+        // Fallback: generateObject() failed — try generateText() with free-text summarization
+        try {
+            const fallbackBaseModel = options.providers
+                ? options.providers.model(options.model)
+                : createOpenAICompatible({
+                    name: "openrouter",
+                    baseURL: "https://openrouter.ai/api/v1",
+                    apiKey: options.apiKey,
+                })(options.model);
+            const fallbackModel = options.middleware && options.middleware.length > 0
+                ? wrapLanguageModel({ model: fallbackBaseModel, middleware: options.middleware })
+                : fallbackBaseModel;
+            const result = await generateText({
+                model: fallbackModel,
+                system: SUMMARIZATION_PROMPT,
+                messages: [{ role: "user", content: conversationText }],
+                maxOutputTokens: 2000,
+                ...(telemetryConfig ? { experimental_telemetry: telemetryConfig } : {}),
+            });
+            const summary = result.text;
+            if (!summary || summary.trim().length === 0) {
+                return {
+                    messages,
+                    compacted: false,
+                    warning: "Compaction fallback produced empty summary — keeping original messages",
+                };
+            }
+            const summaryMessage = {
+                role: "user",
+                content: `<context_summary>\n${summary}\n</context_summary>`,
+            };
+            const structuredMsg = structuredErr instanceof Error ? structuredErr.message : String(structuredErr);
+            return {
+                messages: [summaryMessage, ...tail],
+                compacted: true,
+                warning: `Structured compaction failed (${structuredMsg}) — used text fallback`,
+            };
+        }
+        catch (fallbackErr) {
+            const structuredMsg = structuredErr instanceof Error ? structuredErr.message : String(structuredErr);
+            const fallbackMsg = fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr);
+            return {
+                messages,
+                compacted: false,
+                warning: `Compaction failed: structured (${structuredMsg}), fallback (${fallbackMsg}) — keeping original messages`,
+            };
+        }
+    }
+}

package/dist/context/models.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the context window size for a model ID.
+ * If `override` is provided, it takes precedence over the map.
+ * Unknown models default to 128000.
+ */
+export declare function getContextWindow(modelId: string, override?: number): number;

package/dist/context/models.js

@@ -0,0 +1,41 @@
+const MODEL_CONTEXT_WINDOWS = {
+    // Anthropic — Claude 4.x
+    "anthropic/claude-opus-4-6": 200000,
+    "anthropic/claude-sonnet-4-5": 200000,
+    "anthropic/claude-haiku-4-5": 200000,
+    // Anthropic — Claude 3.x
+    "anthropic/claude-3.5-sonnet": 200000,
+    "anthropic/claude-3.5-haiku": 200000,
+    "anthropic/claude-3-opus": 200000,
+    "anthropic/claude-3-sonnet": 200000,
+    "anthropic/claude-3-haiku": 200000,
+    // OpenAI
+    "openai/gpt-4o": 128000,
+    "openai/gpt-4o-mini": 128000,
+    "openai/gpt-4-turbo": 128000,
+    "openai/o1": 200000,
+    "openai/o1-mini": 128000,
+    "openai/o3": 200000,
+    "openai/o3-mini": 200000,
+    "openai/o4-mini": 200000,
+    // Google
+    "google/gemini-2.0-flash": 1048576,
+    "google/gemini-2.5-pro": 1048576,
+    // Meta
+    "meta-llama/llama-3.1-405b-instruct": 131072,
+    "meta-llama/llama-3.1-70b-instruct": 131072,
+    // DeepSeek
+    "deepseek/deepseek-chat-v3": 131072,
+    "deepseek/deepseek-r1": 131072,
+};
+const DEFAULT_CONTEXT_WINDOW = 128000;
+/**
+ * Returns the context window size for a model ID.
+ * If `override` is provided, it takes precedence over the map.
+ * Unknown models default to 128000.
+ */
+export function getContextWindow(modelId, override) {
+    if (override !== undefined)
+        return override;
+    return MODEL_CONTEXT_WINDOWS[modelId] ?? DEFAULT_CONTEXT_WINDOW;
+}

package/dist/context/tokenizer.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns an estimated token count for the given text using cl100k_base encoding.
+ * Returns 0 for empty strings.
+ */
+export declare function countTokens(text: string): number;

package/dist/context/tokenizer.js

@@ -0,0 +1,11 @@
+import { encodingForModel } from "js-tiktoken";
+const encoder = encodingForModel("gpt-4o");
+/**
+ * Returns an estimated token count for the given text using cl100k_base encoding.
+ * Returns 0 for empty strings.
+ */
+export function countTokens(text) {
+    if (!text)
+        return 0;
+    return encoder.encode(text).length;
+}

package/dist/context/usage.d.ts

@@ -0,0 +1,11 @@
+import type { ModelMessage } from "ai";
+import type { ContextUsage } from "../types.js";
+export interface GetContextUsageOptions {
+    model: string;
+    systemPrompt: string;
+    toolDefinitions: Record<string, unknown>;
+    messages: ModelMessage[];
+    contextWindow?: number;
+    compactThreshold?: number;
+}
+export declare function getContextUsage(options: GetContextUsageOptions): ContextUsage;

package/dist/context/usage.js

@@ -0,0 +1,49 @@
+import { countTokens } from "./tokenizer.js";
+import { getContextWindow } from "./models.js";
+const DEFAULT_COMPACT_THRESHOLD = 0.65;
+function countMessagesTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        if (typeof msg.content === "string") {
+            total += countTokens(msg.content);
+        }
+        else if (Array.isArray(msg.content)) {
+            for (const part of msg.content) {
+                if ("text" in part && typeof part.text === "string") {
+                    total += countTokens(part.text);
+                }
+            }
+        }
+        // Add overhead for role + message framing (~4 tokens per message)
+        total += 4;
+    }
+    return total;
+}
+function countToolDefinitionsTokens(tools) {
+    if (!tools || Object.keys(tools).length === 0)
+        return 0;
+    return countTokens(JSON.stringify(tools));
+}
+export function getContextUsage(options) {
+    const contextWindow = getContextWindow(options.model, options.contextWindow);
+    const compactThreshold = options.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD;
+    const systemPrompt = countTokens(options.systemPrompt);
+    const toolDefinitions = countToolDefinitionsTokens(options.toolDefinitions);
+    const messages = countMessagesTokens(options.messages);
+    const used = systemPrompt + toolDefinitions + messages;
+    const free = contextWindow - used;
+    const usagePercent = (used / contextWindow) * 100;
+    const willCompact = usagePercent >= compactThreshold * 100;
+    return {
+        model: options.model,
+        contextWindow,
+        systemPrompt,
+        toolDefinitions,
+        messages,
+        used,
+        free,
+        usagePercent,
+        compactThreshold: compactThreshold * 100,
+        willCompact,
+    };
+}