@gencode/agents 0.0.1

package/dist/config/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Agent configuration types for AIMax multi-agent support.
+ * Compatible with the .aimax/agents.json config file.
+ */
+/**
+ * Single agent configuration.
+ * Each agent can have its own model, skills, identity, and subagent settings.
+ */
+export type AgentConfig = {
+    /** Unique agent identifier */
+    id: string;
+    /** Whether this is the default agent */
+    default?: boolean;
+    /** Display name (overrides identity.name) */
+    name?: string;
+    /** Model configuration (string or object with primary/fallbacks) */
+    model?: string | AgentModelConfig;
+    /** Skills allowlist (omit = all skills; empty = none) */
+    skills?: string[];
+    /** Identity configuration for display/persona */
+    identity?: {
+        name?: string;
+        theme?: string;
+        emoji?: string;
+        avatar?: string;
+    };
+    /** Subagent configuration for this agent */
+    subagents?: {
+        /** Allow spawning subagents under other agent ids. Use "*" to allow any. */
+        allowAgents?: string[];
+        /** Per-agent default model for spawned subagents (string or {primary,fallbacks}). */
+        model?: string | AgentModelConfig;
+    };
+};
+/**
+ * Model configuration with primary and optional fallbacks.
+ */
+export type AgentModelConfig = {
+    primary: string;
+    fallbacks?: string[];
+};
+/**
+ * Routing binding configuration.
+ * Maps channel/account/peer to a specific agent.
+ */
+export type AgentBinding = {
+    /** Target agent ID for this binding */
+    agentId: string;
+    /** Optional comment/description */
+    comment?: string;
+    /** Match conditions for this binding */
+    match: {
+        /** Channel type: H5 | WEB | KLPA | CRON */
+        channel: "H5" | "WEB" | "KLPA" | "CRON";
+        /** Account ID (optional, for multi-account routing) */
+        accountId?: string;
+        /** User ID (optional, for user-specific routing) */
+        userId?: string;
+    };
+};
+/**
+ * Root agents configuration structure.
+ * Stored in .aimax/agents.json
+ */
+export type AgentsConfig = {
+    /** List of configured agents */
+    agents: AgentConfig[];
+    /** Routing bindings (channel -> agent mapping) */
+    bindings?: AgentBinding[];
+    /** Default configuration (optional) */
+    defaults?: {
+        model?: string | AgentModelConfig;
+        /**
+         * Maximum number of recent user turns to keep in context.
+         * 0 or undefined means no limit.
+         */
+        historyLimit?: number;
+        /** LLM-based history compaction settings */
+        compaction?: {
+            /** Whether to enable automatic LLM summarisation; defaults to true */
+            enabled?: boolean;
+            /** Fraction of context window that triggers compaction; defaults to 0.6 */
+            thresholdRatio?: number;
+        };
+    };
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAClC,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,4CAA4C;IAC5C,SAAS,CAAC,EAAE;QACV,4EAA4E;QAC5E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,qFAAqF;QACrF,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;KACnC,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE;QACL,2CAA2C;QAC3C,OAAO,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;QACxC,uDAAuD;QACvD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,oDAAoD;QACpD,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,gCAAgC;IAChC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;QAClC;;;WAGG;QACH,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,4CAA4C;QAC5C,UAAU,CAAC,EAAE;YACX,sEAAsE;YACtE,OAAO,CAAC,EAAE,OAAO,CAAC;YAClB,2EAA2E;YAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;SACzB,CAAC;KACH,CAAC;CACH,CAAC"}

package/dist/config/types.js

@@ -0,0 +1,6 @@
+/**
+ * Agent configuration types for AIMax multi-agent support.
+ * Compatible with the .aimax/agents.json config file.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

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

package/dist/history/compaction.d.ts

@@ -0,0 +1,42 @@
+import type { MessageEntry } from "../types.js";
+import type { PluginHookAgentContext, PluginHookRegistry } from "../plugins/hooks.js";
+/** Ratio of context window that triggers compaction when history exceeds it */
+export declare const DEFAULT_COMPACTION_THRESHOLD_RATIO = 0.6;
+export type SummariseParams = {
+    entries: MessageEntry[];
+    llm: {
+        baseUrl: string;
+        apiKey: string;
+        model: string;
+    };
+    previousSummary?: string;
+    instructions?: string;
+    signal?: AbortSignal;
+    hooks?: PluginHookRegistry;
+    hookCtx?: PluginHookAgentContext;
+};
+/**
+ * Call the LLM to produce a summary of the provided entries.
+ * If `previousSummary` is given, the LLM is asked to incorporate it so the
+ * new summary builds on prior compaction rounds.
+ */
+export declare function generateSummary(params: SummariseParams): Promise<string>;
+/**
+ * Return true when the total estimated token count of `entries` exceeds the
+ * compaction threshold fraction of `contextWindowTokens`.
+ */
+export declare function shouldCompact(params: {
+    entries: MessageEntry[];
+    contextWindowTokens: number;
+    thresholdRatio?: number;
+}): boolean;
+/**
+ * Partition `entries` into two slices:
+ * - `toKeep`: the most-recent entries that fit within the keep budget
+ * - `toSummarise`: the older entries that will be summarised
+ */
+export declare function splitForCompaction(entries: MessageEntry[], contextWindowTokens: number): {
+    toKeep: MessageEntry[];
+    toSummarise: MessageEntry[];
+};
+//# sourceMappingURL=compaction.d.ts.map

package/dist/history/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/history/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEtF,+EAA+E;AAC/E,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAsBtD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAwC9E;AA+CD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAKV;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,mBAAmB,EAAE,MAAM,GAC1B;IAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,WAAW,EAAE,YAAY,EAAE,CAAA;CAAE,CAgBzD"}

package/dist/history/compaction.js

@@ -0,0 +1,135 @@
+import { estimateEntryTokens, estimateEntriesTokens } from "./token-estimate.js";
+import { createLlmClient } from "../llm/client.js";
+/** Ratio of context window that triggers compaction when history exceeds it */
+export const DEFAULT_COMPACTION_THRESHOLD_RATIO = 0.6;
+/**
+ * Ratio of context window reserved for the message slice kept after compaction.
+ * The older portion (beyond this budget) is summarised.
+ */
+const KEEP_BUDGET_RATIO = 0.35;
+const SUMMARIZATION_PROMPT = [
+    "You are a conversation history summariser. Compress the conversation below into a concise summary.",
+    "",
+    "MUST PRESERVE:",
+    "- Active tasks and their current status (including batch progress e.g. '5/17 items done')",
+    "- The last thing the user requested and what was being done about it",
+    "- Decisions made and their rationale",
+    "- TODOs, open questions, and constraints",
+    "- All opaque identifiers exactly as written: UUIDs, hashes, file paths, URLs, IPs, ports (never shorten or reconstruct them)",
+    "",
+    "Prioritise recent context over older history.",
+    "Output only the summary text — no preamble, no headings.",
+].join("\n");
+/**
+ * Call the LLM to produce a summary of the provided entries.
+ * If `previousSummary` is given, the LLM is asked to incorporate it so the
+ * new summary builds on prior compaction rounds.
+ */
+export async function generateSummary(params) {
+    const { entries, llm, previousSummary, instructions, signal, hooks, hookCtx } = params;
+    const userContent = buildSummarisationUserMessage(entries, previousSummary, instructions);
+    const MAX_ATTEMPTS = 3;
+    let lastError;
+    const client = createLlmClient({
+        baseUrl: llm.baseUrl,
+        apiKey: llm.apiKey,
+        defaultModel: llm.model,
+        hooks,
+        hookCtx,
+    });
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            const result = await client.chat({
+                system: SUMMARIZATION_PROMPT,
+                user: userContent,
+                temperature: 0,
+                maxTokens: 2048,
+                signal,
+            });
+            const text = result.text.trim();
+            if (!text) {
+                throw new Error("LLM summarisation returned empty content");
+            }
+            return text;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError")
+                throw err;
+            lastError = err;
+            if (attempt < MAX_ATTEMPTS) {
+                // Simple backoff: 500ms, 1000ms between retries
+                await sleep(500 * attempt);
+            }
+        }
+    }
+    throw lastError;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function buildSummarisationUserMessage(entries, previousSummary, instructions) {
+    const parts = [];
+    if (instructions?.trim()) {
+        parts.push(`[Extra instructions]\n${instructions.trim()}\n`);
+    }
+    if (previousSummary?.trim()) {
+        parts.push(`[Prior summary]\n${previousSummary.trim()}\n`);
+        parts.push("[Conversation to incorporate]");
+    }
+    else {
+        parts.push("[Conversation to summarise]");
+    }
+    for (const entry of entries) {
+        if (entry.role === "user") {
+            parts.push(`User: ${entry.content}`);
+        }
+        else if (entry.role === "assistant") {
+            const toolLine = entry.toolCalls && entry.toolCalls.length > 0
+                ? ` [called tools: ${entry.toolCalls.map((t) => t.name).join(", ")}]`
+                : "";
+            parts.push(`Assistant:${toolLine} ${entry.content}`.trimEnd());
+        }
+        else if (entry.role === "tool_result") {
+            const status = entry.isError ? "error" : "ok";
+            // Truncate very long tool outputs to avoid blowing the summarisation context
+            const truncated = entry.content.length > 2000
+                ? `${entry.content.slice(0, 2000)}… [truncated]`
+                : entry.content;
+            parts.push(`Tool(${entry.toolName})[${status}]: ${truncated}`);
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Return true when the total estimated token count of `entries` exceeds the
+ * compaction threshold fraction of `contextWindowTokens`.
+ */
+export function shouldCompact(params) {
+    const { entries, contextWindowTokens, thresholdRatio = DEFAULT_COMPACTION_THRESHOLD_RATIO } = params;
+    if (entries.length === 0)
+        return false;
+    const threshold = Math.floor(contextWindowTokens * thresholdRatio);
+    return estimateEntriesTokens(entries) > threshold;
+}
+/**
+ * Partition `entries` into two slices:
+ * - `toKeep`: the most-recent entries that fit within the keep budget
+ * - `toSummarise`: the older entries that will be summarised
+ */
+export function splitForCompaction(entries, contextWindowTokens) {
+    const keepBudget = Math.floor(contextWindowTokens * KEEP_BUDGET_RATIO);
+    let accumulated = 0;
+    let keepFrom = entries.length; // default: summarise everything
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const t = estimateEntryTokens(entries[i]);
+        if (accumulated + t > keepBudget)
+            break;
+        accumulated += t;
+        keepFrom = i;
+    }
+    return {
+        toKeep: entries.slice(keepFrom),
+        toSummarise: entries.slice(0, keepFrom),
+    };
+}
+//# sourceMappingURL=compaction.js.map

package/dist/history/compaction.js.map

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

package/dist/history/index.d.ts

@@ -0,0 +1,57 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { TranscriptEntry, MessageEntry, CompactionEntry } from "../types.js";
+import type { PluginHookAgentContext, PluginHookRegistry } from "../plugins/hooks.js";
+export type ManageHistoryParams = {
+    /** Full transcript entries including any prior compaction records */
+    entries: TranscriptEntry[];
+    modelInfo: {
+        model: string;
+        api: string;
+    };
+    contextWindowTokens: number;
+    llm: {
+        baseUrl: string;
+        apiKey: string;
+        model: string;
+    };
+    /** Max user turns to keep; 0/undefined = no limit */
+    historyLimit?: number;
+    /** Set to false to skip LLM-based compaction; defaults to true */
+    compactionEnabled?: boolean;
+    /** Fraction of context window that triggers compaction; defaults to 0.6 */
+    thresholdRatio?: number;
+    signal?: AbortSignal;
+    hooks?: PluginHookRegistry;
+    hookCtx?: PluginHookAgentContext;
+};
+export type HistoryManagementResult = {
+    /** Messages ready to pass to agent.replaceMessages() */
+    messages: AgentMessage[];
+    /** Summary text to inject into the system prompt (from existing or new compaction) */
+    priorSummary: string | undefined;
+    /** New compaction record to append to the transcript (undefined if no compaction ran) */
+    compactionEntry: CompactionEntry | undefined;
+    stats: {
+        originalCount: number;
+        keptCount: number;
+        estimatedTokens: number;
+        compacted: boolean;
+    };
+};
+/**
+ * Manage conversation history before each agent run:
+ * 1. Extract message entries that follow the last compaction record.
+ * 2. Apply the turn limit (drop oldest user turns beyond `historyLimit`).
+ * 3. Repair orphaned tool_result entries created by truncation.
+ * 4. If token count exceeds the threshold, generate an LLM summary and
+ *    return a compaction record to persist.
+ */
+export declare function manageHistory(params: ManageHistoryParams): Promise<HistoryManagementResult>;
+/**
+ * Convert MessageEntry[] to AgentMessage[] for use with agent.replaceMessages().
+ */
+export declare function entriesToMessages(entries: MessageEntry[], modelInfo: {
+    model: string;
+    api: string;
+}): AgentMessage[];
+//# sourceMappingURL=index.d.ts.map

package/dist/history/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/history/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EAIZ,eAAe,EAChB,MAAM,aAAa,CAAC;AAKrB,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAatF,MAAM,MAAM,mBAAmB,GAAG;IAChC,qEAAqE;IACrE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,wDAAwD;IACxD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,sFAAsF;IACtF,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,yFAAyF;IACzF,eAAe,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,CAAC;QACxB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;CACH,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAoFjG;AAaD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACxC,YAAY,EAAE,CAEhB"}

package/dist/history/index.js

@@ -0,0 +1,145 @@
+import { estimateEntriesTokens } from "./token-estimate.js";
+import { limitHistoryTurns } from "./limit.js";
+import { repairToolPairing } from "./repair.js";
+import { shouldCompact, splitForCompaction, generateSummary } from "./compaction.js";
+// Zero-usage placeholder for reconstructed assistant messages.
+// The actual usage figures are not meaningful for history replay.
+const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+/**
+ * Manage conversation history before each agent run:
+ * 1. Extract message entries that follow the last compaction record.
+ * 2. Apply the turn limit (drop oldest user turns beyond `historyLimit`).
+ * 3. Repair orphaned tool_result entries created by truncation.
+ * 4. If token count exceeds the threshold, generate an LLM summary and
+ *    return a compaction record to persist.
+ */
+export async function manageHistory(params) {
+    const { entries, modelInfo, contextWindowTokens, llm, historyLimit, compactionEnabled = true, thresholdRatio, signal, } = params;
+    // ── 1. Separate the latest compaction record from message entries ──────────
+    let existingSummary;
+    let messageEntries;
+    const lastCompactionIdx = findLastCompactionIndex(entries);
+    if (lastCompactionIdx >= 0) {
+        existingSummary = entries[lastCompactionIdx].content;
+        messageEntries = entries.slice(lastCompactionIdx + 1);
+    }
+    else {
+        messageEntries = entries;
+    }
+    const originalCount = entries.length;
+    // ── 2. Apply turn limit ────────────────────────────────────────────────────
+    const limited = limitHistoryTurns(messageEntries, historyLimit);
+    // ── 3. Repair orphaned tool_results caused by truncation ──────────────────
+    const repaired = repairToolPairing(limited);
+    // ── 4. Compaction if needed ────────────────────────────────────────────────
+    if (compactionEnabled &&
+        shouldCompact({ entries: repaired, contextWindowTokens, thresholdRatio })) {
+        const { toKeep, toSummarise } = splitForCompaction(repaired, contextWindowTokens);
+        if (toSummarise.length > 0) {
+            const newSummary = await generateSummary({
+                entries: toSummarise,
+                llm,
+                previousSummary: existingSummary,
+                signal,
+                hooks: params.hooks,
+                hookCtx: params.hookCtx,
+            });
+            const repairedToKeep = repairToolPairing(toKeep);
+            const compactionEntry = {
+                role: "compaction",
+                content: newSummary,
+                keptCount: repairedToKeep.length,
+                droppedCount: toSummarise.length,
+                timestamp: new Date().toISOString(),
+            };
+            return {
+                messages: entriesToMessages(repairedToKeep, modelInfo),
+                priorSummary: newSummary,
+                compactionEntry,
+                stats: {
+                    originalCount,
+                    keptCount: repairedToKeep.length,
+                    estimatedTokens: estimateEntriesTokens(repairedToKeep),
+                    compacted: true,
+                },
+            };
+        }
+    }
+    // ── No compaction ──────────────────────────────────────────────────────────
+    return {
+        messages: entriesToMessages(repaired, modelInfo),
+        priorSummary: existingSummary,
+        compactionEntry: undefined,
+        stats: {
+            originalCount,
+            keptCount: repaired.length,
+            estimatedTokens: estimateEntriesTokens(repaired),
+            compacted: false,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function findLastCompactionIndex(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (entries[i].role === "compaction")
+            return i;
+    }
+    return -1;
+}
+/**
+ * Convert MessageEntry[] to AgentMessage[] for use with agent.replaceMessages().
+ */
+export function entriesToMessages(entries, modelInfo) {
+    return entries.map((entry) => entryToMessage(entry, modelInfo));
+}
+function entryToMessage(entry, modelInfo) {
+    const timestamp = new Date(entry.timestamp).getTime();
+    if (isUserEntry(entry)) {
+        return { role: "user", content: entry.content, timestamp };
+    }
+    if (isAssistantEntry(entry)) {
+        const content = [];
+        if (entry.content) {
+            content.push({ type: "text", text: entry.content });
+        }
+        for (const tc of entry.toolCalls ?? []) {
+            content.push({ type: "toolCall", id: tc.id, name: tc.name, arguments: tc.arguments });
+        }
+        return {
+            role: "assistant",
+            content,
+            api: modelInfo.api,
+            provider: "openai",
+            model: modelInfo.model,
+            usage: ZERO_USAGE,
+            stopReason: "stop",
+            timestamp,
+        };
+    }
+    // tool_result
+    const tr = entry;
+    return {
+        role: "toolResult",
+        toolCallId: tr.toolCallId,
+        toolName: tr.toolName,
+        content: [{ type: "text", text: tr.content }],
+        isError: tr.isError,
+        timestamp,
+    };
+}
+function isUserEntry(entry) {
+    return entry.role === "user";
+}
+function isAssistantEntry(entry) {
+    return entry.role === "assistant";
+}
+//# sourceMappingURL=index.js.map

package/dist/history/index.js.map

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

package/dist/history/limit.d.ts

@@ -0,0 +1,13 @@
+import type { MessageEntry } from "../types.js";
+/**
+ * Limit conversation history to the last `limit` user turns (and their
+ * associated assistant/tool_result responses).
+ *
+ * Counting works from the end: each `user` entry increments the counter.
+ * Once the counter exceeds `limit`, the entries before that point are dropped.
+ *
+ * Returns the original array reference when no trimming is needed, avoiding
+ * an unnecessary copy.
+ */
+export declare function limitHistoryTurns(entries: MessageEntry[], limit: number | undefined): MessageEntry[];
+//# sourceMappingURL=limit.d.ts.map

package/dist/history/limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit.d.ts","sourceRoot":"","sources":["../../src/history/limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,YAAY,EAAE,CAuBhB"}

package/dist/history/limit.js

@@ -0,0 +1,32 @@
+/**
+ * Limit conversation history to the last `limit` user turns (and their
+ * associated assistant/tool_result responses).
+ *
+ * Counting works from the end: each `user` entry increments the counter.
+ * Once the counter exceeds `limit`, the entries before that point are dropped.
+ *
+ * Returns the original array reference when no trimming is needed, avoiding
+ * an unnecessary copy.
+ */
+export function limitHistoryTurns(entries, limit) {
+    if (!limit || limit <= 0 || entries.length === 0) {
+        return entries;
+    }
+    let userCount = 0;
+    // Tracks the index of the most-recently-seen user entry as we scan backward.
+    let lastUserIndex = entries.length;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (entries[i].role === "user") {
+            userCount++;
+            if (userCount > limit) {
+                // We have seen one more user turn than allowed — drop everything before
+                // the index we saved on the previous iteration.
+                return entries.slice(lastUserIndex);
+            }
+            lastUserIndex = i;
+        }
+    }
+    // Fewer user turns than the limit — return as-is.
+    return entries;
+}
+//# sourceMappingURL=limit.js.map

package/dist/history/limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit.js","sourceRoot":"","sources":["../../src/history/limit.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAuB,EACvB,KAAyB;IAEzB,IAAI,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,6EAA6E;IAC7E,IAAI,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC/B,SAAS,EAAE,CAAC;YACZ,IAAI,SAAS,GAAG,KAAK,EAAE,CAAC;gBACtB,wEAAwE;gBACxE,gDAAgD;gBAChD,OAAO,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;YACtC,CAAC;YACD,aAAa,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/history/repair.d.ts

@@ -0,0 +1,13 @@
+import type { MessageEntry } from "../types.js";
+/**
+ * Remove orphaned tool_result entries whose matching assistant toolCall was
+ * dropped by history truncation.
+ *
+ * An orphaned tool_result has a `toolCallId` that cannot be found in any
+ * preceding AssistantEntry.toolCalls[].id within the provided slice.
+ * Sending such entries to the LLM causes "unexpected tool_use_id" errors.
+ *
+ * Returns the original array reference when nothing was dropped.
+ */
+export declare function repairToolPairing(entries: MessageEntry[]): MessageEntry[];
+//# sourceMappingURL=repair.d.ts.map

package/dist/history/repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../src/history/repair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAiBzE"}

package/dist/history/repair.js

@@ -0,0 +1,25 @@
+/**
+ * Remove orphaned tool_result entries whose matching assistant toolCall was
+ * dropped by history truncation.
+ *
+ * An orphaned tool_result has a `toolCallId` that cannot be found in any
+ * preceding AssistantEntry.toolCalls[].id within the provided slice.
+ * Sending such entries to the LLM causes "unexpected tool_use_id" errors.
+ *
+ * Returns the original array reference when nothing was dropped.
+ */
+export function repairToolPairing(entries) {
+    // Collect all toolCall ids that are present in the slice.
+    const knownIds = new Set();
+    for (const entry of entries) {
+        if (entry.role === "assistant") {
+            for (const tc of entry.toolCalls ?? []) {
+                knownIds.add(tc.id);
+            }
+        }
+    }
+    const repaired = entries.filter((entry) => entry.role !== "tool_result" || knownIds.has(entry.toolCallId));
+    // Avoid allocating a new array when nothing was removed.
+    return repaired.length === entries.length ? entries : repaired;
+}
+//# sourceMappingURL=repair.js.map

package/dist/history/repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.js","sourceRoot":"","sources":["../../src/history/repair.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAuB;IACvD,0DAA0D;IAC1D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/B,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;gBACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAC7B,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAC1E,CAAC;IAEF,yDAAyD;IACzD,OAAO,QAAQ,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;AACjE,CAAC"}

package/dist/history/token-estimate.d.ts

@@ -0,0 +1,22 @@
+import type { MessageEntry } from "../types.js";
+/**
+ * Safety margin applied on top of the chars/4 heuristic to compensate for
+ * tokeniser differences (multi-byte chars, code tokens, special tokens, etc.)
+ */
+export declare const SAFETY_MARGIN = 1.2;
+/**
+ * Estimate token count for a text string.
+ * Uses the chars/4 heuristic (rough average for English/mixed content) plus
+ * a 20% safety margin to reduce the risk of underestimation.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimate token count for a single MessageEntry.
+ * Tool results are measured separately because they can be very large.
+ */
+export declare function estimateEntryTokens(entry: MessageEntry): number;
+/**
+ * Estimate total token count for an array of MessageEntry items.
+ */
+export declare function estimateEntriesTokens(entries: MessageEntry[]): number;
+//# sourceMappingURL=token-estimate.d.ts.map

package/dist/history/token-estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimate.d.ts","sourceRoot":"","sources":["../../src/history/token-estimate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAa/D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAErE"}