@ai-agent-forge/agent-forge 0.85.0

package/dist/core/agent-session-projection.js

@@ -0,0 +1,195 @@
+/**
+ * Read-only session projections for AgentSession: fork selector entries,
+ * session stats, context usage, and export entry points.
+ *
+ * Extracted from `agent-session.ts`. Every function here operates on the
+ * internal session facade ({@link AgentSessionInternals}); `AgentSession`
+ * keeps same-name delegates so call sites, dynamic dispatch, and test spies
+ * keep working unchanged. Method-to-method calls that have a facade member go
+ * through the session parameter (not direct function calls) to preserve that
+ * dispatch — `getSessionStats` reads context usage through
+ * `session.getContextUsage()` and `exportToHtml` resolves tool definitions
+ * through `session.getToolDefinition()`.
+ */
+import { contentText } from "@agent-forge/ai";
+import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
+import { calculateContextTokens, estimateContextTokens } from "./compaction/index.js";
+import { exportSessionToHtml } from "./export-html/index.js";
+import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
+import { exportSessionToJsonl } from "./session-export.js";
+import { getLatestCompactionEntry } from "./session-manager.js";
+import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
+/**
+ * Get all user messages from session for fork selector.
+ */
+export function getUserMessagesForForking(session) {
+    const entries = session.sessionManager.getEntries();
+    const result = [];
+    for (const entry of entries) {
+        if (entry.type !== "message")
+            continue;
+        if (entry.message.role !== "user")
+            continue;
+        const text = contentText(entry.message.content, "");
+        if (text) {
+            result.push({ entryId: entry.id, text });
+        }
+    }
+    return result;
+}
+/**
+ * Get session statistics. Aggregates over ALL session entries (including
+ * history that was compacted away), so token/cost totals reflect what was
+ * actually billed across the session.
+ */
+export function getSessionStats(session) {
+    let userMessages = 0;
+    let assistantMessages = 0;
+    let toolResults = 0;
+    let totalMessages = 0;
+    let toolCalls = 0;
+    const usageTotals = createUsageTotals();
+    for (const entry of session.sessionManager.getEntries()) {
+        if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+            addUsageToTotals(usageTotals, entry.usage);
+        }
+        if (entry.type !== "message")
+            continue;
+        totalMessages++;
+        const message = entry.message;
+        if (message.role === "user") {
+            userMessages++;
+        }
+        else if (message.role === "toolResult") {
+            toolResults++;
+            if (message.usage) {
+                addUsageToTotals(usageTotals, message.usage);
+            }
+        }
+        else if (message.role === "assistant") {
+            assistantMessages++;
+            const assistantMsg = message;
+            if (Array.isArray(assistantMsg.content)) {
+                toolCalls += assistantMsg.content.filter((c) => c.type === "toolCall").length;
+            }
+            addUsageToTotals(usageTotals, assistantMsg.usage);
+        }
+    }
+    return {
+        sessionFile: session.sessionFile,
+        sessionId: session.sessionId,
+        userMessages,
+        assistantMessages,
+        toolCalls,
+        toolResults,
+        totalMessages,
+        tokens: {
+            input: usageTotals.input,
+            output: usageTotals.output,
+            cacheRead: usageTotals.cacheRead,
+            cacheWrite: usageTotals.cacheWrite,
+            total: usageTotals.input + usageTotals.output + usageTotals.cacheRead + usageTotals.cacheWrite,
+        },
+        cost: usageTotals.cost,
+        contextUsage: session.getContextUsage(),
+    };
+}
+export function getContextUsage(session) {
+    const model = session.model;
+    if (!model)
+        return undefined;
+    const contextWindow = model.contextWindow ?? 0;
+    if (contextWindow <= 0)
+        return undefined;
+    // After compaction, the last assistant usage reflects pre-compaction context size.
+    // We can only trust usage from an assistant that responded after the latest compaction.
+    // If no such assistant exists, context token count is unknown until the next LLM response.
+    const branchEntries = session.sessionManager.getBranch();
+    const latestCompaction = getLatestCompactionEntry(branchEntries);
+    if (latestCompaction) {
+        // Check if there's a valid assistant usage after the compaction boundary
+        const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
+        let hasPostCompactionUsage = false;
+        for (let i = branchEntries.length - 1; i > compactionIndex; i--) {
+            const entry = branchEntries[i];
+            if (entry.type === "message" && entry.message.role === "assistant") {
+                const assistant = entry.message;
+                if (assistant.stopReason !== "aborted" && assistant.stopReason !== "error") {
+                    const contextTokens = calculateContextTokens(assistant.usage);
+                    if (contextTokens > 0) {
+                        hasPostCompactionUsage = true;
+                        break;
+                    }
+                }
+            }
+        }
+        if (!hasPostCompactionUsage) {
+            return { tokens: null, contextWindow, percent: null };
+        }
+    }
+    const estimate = estimateContextTokens(session.messages);
+    const percent = (estimate.tokens / contextWindow) * 100;
+    return {
+        tokens: estimate.tokens,
+        contextWindow,
+        percent,
+    };
+}
+/**
+ * Export session to HTML.
+ * @param outputPath Optional output path (defaults to session directory)
+ * @param options Optional export presentation settings
+ * @returns Path to exported file
+ */
+export async function exportToHtml(session, outputPath, options = {}) {
+    const themeName = [options.themeName, session.settingsManager.getTheme()].find((candidate) => candidate !== undefined && getThemeByName(candidate) !== undefined);
+    // Create tool renderer if we have an extension runner (for custom tool HTML rendering)
+    const toolRenderer = createToolHtmlRenderer({
+        getToolDefinition: (name) => session.getToolDefinition(name),
+        theme,
+        cwd: session.sessionManager.getCwd(),
+    });
+    return await exportSessionToHtml(session.sessionManager, session.agent.state, {
+        outputPath,
+        themeName,
+        toolRenderer,
+    });
+}
+/**
+ * Export the current session branch to a JSONL file.
+ * Writes the session header followed by all entries on the current branch path.
+ * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.
+ * @returns The resolved output file path.
+ */
+export function exportToJsonl(session, outputPath) {
+    return exportSessionToJsonl(session.sessionManager, outputPath);
+}
+/**
+ * Get text content of last assistant message.
+ * Useful for /copy command.
+ * @returns Text content, or undefined if no assistant message exists
+ */
+export function getLastAssistantText(session) {
+    const lastAssistant = session.messages
+        .slice()
+        .reverse()
+        .find((m) => {
+        if (m.role !== "assistant")
+            return false;
+        const msg = m;
+        // Skip aborted messages with no content
+        if (msg.stopReason === "aborted" && msg.content.length === 0)
+            return false;
+        return true;
+    });
+    if (!lastAssistant)
+        return undefined;
+    let text = "";
+    for (const content of lastAssistant.content) {
+        if (content.type === "text") {
+            text += content.text;
+        }
+    }
+    return text.trim() || undefined;
+}
+//# sourceMappingURL=agent-session-projection.js.map

package/dist/core/agent-session-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-projection.js","sourceRoot":"","sources":["../../src/core/agent-session-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,qCAAqC,CAAC;AAG5E,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAyB,MAAM,wBAAwB,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAExE;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAA8B,EAA4C;IACnH,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC;IACpD,MAAM,MAAM,GAA6C,EAAE,CAAC;IAE5D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACvC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QAE5C,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACpD,IAAI,IAAI,EAAE,CAAC;YACV,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AAAA,CACd;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAA8B,EAAgB;IAC7E,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAC1B,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,WAAW,GAAG,iBAAiB,EAAE,CAAC;IAExC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,EAAE,CAAC;QACzD,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,gBAAgB,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACrF,gBAAgB,CAAC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACvC,aAAa,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC7B,YAAY,EAAE,CAAC;QAChB,CAAC;aAAM,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC1C,WAAW,EAAE,CAAC;YACd,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBACnB,gBAAgB,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9C,CAAC;QACF,CAAC;aAAM,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACzC,iBAAiB,EAAE,CAAC;YACpB,MAAM,YAAY,GAAG,OAA2B,CAAC;YACjD,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;gBACzC,SAAS,IAAI,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,MAAM,CAAC;YAC/E,CAAC;YACD,gBAAgB,CAAC,WAAW,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACnD,CAAC;IACF,CAAC;IAED,OAAO;QACN,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,YAAY;QACZ,iBAAiB;QACjB,SAAS;QACT,WAAW;QACX,aAAa;QACb,MAAM,EAAE;YACP,KAAK,EAAE,WAAW,CAAC,KAAK;YACxB,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,SAAS,EAAE,WAAW,CAAC,SAAS;YAChC,UAAU,EAAE,WAAW,CAAC,UAAU;YAClC,KAAK,EAAE,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,MAAM,GAAG,WAAW,CAAC,SAAS,GAAG,WAAW,CAAC,UAAU;SAC9F;QACD,IAAI,EAAE,WAAW,CAAC,IAAI;QACtB,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;KACvC,CAAC;AAAA,CACF;AAED,MAAM,UAAU,eAAe,CAAC,OAA8B,EAA4B;IACzF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAE7B,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,CAAC,CAAC;IAC/C,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,mFAAmF;IACnF,wFAAwF;IACxF,2FAA2F;IAC3F,MAAM,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC;IACzD,MAAM,gBAAgB,GAAG,wBAAwB,CAAC,aAAa,CAAC,CAAC;IAEjE,IAAI,gBAAgB,EAAE,CAAC;QACtB,yEAAyE;QACzE,MAAM,eAAe,GAAG,aAAa,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;QACpE,IAAI,sBAAsB,GAAG,KAAK,CAAC;QACnC,KAAK,IAAI,CAAC,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,EAAE,CAAC,EAAE,EAAE,CAAC;YACjE,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YAC/B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBACpE,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC;gBAChC,IAAI,SAAS,CAAC,UAAU,KAAK,SAAS,IAAI,SAAS,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;oBAC5E,MAAM,aAAa,GAAG,sBAAsB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;oBAC9D,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;wBACvB,sBAAsB,GAAG,IAAI,CAAC;wBAC9B,MAAM;oBACP,CAAC;gBACF,CAAC;YACF,CAAC;QACF,CAAC;QAED,IAAI,CAAC,sBAAsB,EAAE,CAAC;YAC7B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACvD,CAAC;IACF,CAAC;IAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,aAAa,CAAC,GAAG,GAAG,CAAC;IAExD,OAAO;QACN,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,aAAa;QACb,OAAO;KACP,CAAC;AAAA,CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,OAA8B,EAC9B,UAAmB,EACnB,OAAO,GAA2B,EAAE,EAClB;IAClB,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAC7E,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,SAAS,IAAI,cAAc,CAAC,SAAS,CAAC,KAAK,SAAS,CACjF,CAAC;IAEF,uFAAuF;IACvF,MAAM,YAAY,GAAqB,sBAAsB,CAAC;QAC7D,iBAAiB,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC;QAC5D,KAAK;QACL,GAAG,EAAE,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE;KACpC,CAAC,CAAC;IAEH,OAAO,MAAM,mBAAmB,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE;QAC7E,UAAU;QACV,SAAS;QACT,YAAY;KACZ,CAAC,CAAC;AAAA,CACH;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAA8B,EAAE,UAAmB,EAAU;IAC1F,OAAO,oBAAoB,CAAC,OAAO,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;AAAA,CAChE;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA8B,EAAsB;IACxF,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ;SACpC,KAAK,EAAE;SACP,OAAO,EAAE;SACT,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC;QACzC,MAAM,GAAG,GAAG,CAAqB,CAAC;QAClC,wCAAwC;QACxC,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3E,OAAO,IAAI,CAAC;IAAA,CACZ,CAAC,CAAC;IAEJ,IAAI,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IAErC,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,MAAM,OAAO,IAAK,aAAkC,CAAC,OAAO,EAAE,CAAC;QACnE,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC7B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AAAA,CAChC","sourcesContent":["/**\n * Read-only session projections for AgentSession: fork selector entries,\n * session stats, context usage, and export entry points.\n *\n * Extracted from `agent-session.ts`. Every function here operates on the\n * internal session facade ({@link AgentSessionInternals}); `AgentSession`\n * keeps same-name delegates so call sites, dynamic dispatch, and test spies\n * keep working unchanged. Method-to-method calls that have a facade member go\n * through the session parameter (not direct function calls) to preserve that\n * dispatch — `getSessionStats` reads context usage through\n * `session.getContextUsage()` and `exportToHtml` resolves tool definitions\n * through `session.getToolDefinition()`.\n */\n\nimport { contentText } from \"@agent-forge/ai\";\nimport type { AssistantMessage } from \"@agent-forge/ai/compat\";\nimport { getThemeByName, theme } from \"../modes/interactive/theme/theme.ts\";\nimport type { SessionStats } from \"./agent-session.ts\";\nimport type { AgentSessionInternals } from \"./agent-session-internal.ts\";\nimport { calculateContextTokens, estimateContextTokens } from \"./compaction/index.ts\";\nimport { exportSessionToHtml, type ToolHtmlRenderer } from \"./export-html/index.ts\";\nimport { createToolHtmlRenderer } from \"./export-html/tool-renderer.ts\";\nimport type { ContextUsage } from \"./extensions/public-api.ts\";\nimport { exportSessionToJsonl } from \"./session-export.ts\";\nimport { getLatestCompactionEntry } from \"./session-manager.ts\";\nimport { addUsageToTotals, createUsageTotals } from \"./usage-totals.ts\";\n\n/**\n * Get all user messages from session for fork selector.\n */\nexport function getUserMessagesForForking(session: AgentSessionInternals): Array<{ entryId: string; text: string }> {\n\tconst entries = session.sessionManager.getEntries();\n\tconst result: Array<{ entryId: string; text: string }> = [];\n\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\") continue;\n\t\tif (entry.message.role !== \"user\") continue;\n\n\t\tconst text = contentText(entry.message.content, \"\");\n\t\tif (text) {\n\t\t\tresult.push({ entryId: entry.id, text });\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Get session statistics. Aggregates over ALL session entries (including\n * history that was compacted away), so token/cost totals reflect what was\n * actually billed across the session.\n */\nexport function getSessionStats(session: AgentSessionInternals): SessionStats {\n\tlet userMessages = 0;\n\tlet assistantMessages = 0;\n\tlet toolResults = 0;\n\tlet totalMessages = 0;\n\tlet toolCalls = 0;\n\tconst usageTotals = createUsageTotals();\n\n\tfor (const entry of session.sessionManager.getEntries()) {\n\t\tif ((entry.type === \"branch_summary\" || entry.type === \"compaction\") && entry.usage) {\n\t\t\taddUsageToTotals(usageTotals, entry.usage);\n\t\t}\n\t\tif (entry.type !== \"message\") continue;\n\t\ttotalMessages++;\n\t\tconst message = entry.message;\n\t\tif (message.role === \"user\") {\n\t\t\tuserMessages++;\n\t\t} else if (message.role === \"toolResult\") {\n\t\t\ttoolResults++;\n\t\t\tif (message.usage) {\n\t\t\t\taddUsageToTotals(usageTotals, message.usage);\n\t\t\t}\n\t\t} else if (message.role === \"assistant\") {\n\t\t\tassistantMessages++;\n\t\t\tconst assistantMsg = message as AssistantMessage;\n\t\t\tif (Array.isArray(assistantMsg.content)) {\n\t\t\t\ttoolCalls += assistantMsg.content.filter((c) => c.type === \"toolCall\").length;\n\t\t\t}\n\t\t\taddUsageToTotals(usageTotals, assistantMsg.usage);\n\t\t}\n\t}\n\n\treturn {\n\t\tsessionFile: session.sessionFile,\n\t\tsessionId: session.sessionId,\n\t\tuserMessages,\n\t\tassistantMessages,\n\t\ttoolCalls,\n\t\ttoolResults,\n\t\ttotalMessages,\n\t\ttokens: {\n\t\t\tinput: usageTotals.input,\n\t\t\toutput: usageTotals.output,\n\t\t\tcacheRead: usageTotals.cacheRead,\n\t\t\tcacheWrite: usageTotals.cacheWrite,\n\t\t\ttotal: usageTotals.input + usageTotals.output + usageTotals.cacheRead + usageTotals.cacheWrite,\n\t\t},\n\t\tcost: usageTotals.cost,\n\t\tcontextUsage: session.getContextUsage(),\n\t};\n}\n\nexport function getContextUsage(session: AgentSessionInternals): ContextUsage | undefined {\n\tconst model = session.model;\n\tif (!model) return undefined;\n\n\tconst contextWindow = model.contextWindow ?? 0;\n\tif (contextWindow <= 0) return undefined;\n\n\t// After compaction, the last assistant usage reflects pre-compaction context size.\n\t// We can only trust usage from an assistant that responded after the latest compaction.\n\t// If no such assistant exists, context token count is unknown until the next LLM response.\n\tconst branchEntries = session.sessionManager.getBranch();\n\tconst latestCompaction = getLatestCompactionEntry(branchEntries);\n\n\tif (latestCompaction) {\n\t\t// Check if there's a valid assistant usage after the compaction boundary\n\t\tconst compactionIndex = branchEntries.lastIndexOf(latestCompaction);\n\t\tlet hasPostCompactionUsage = false;\n\t\tfor (let i = branchEntries.length - 1; i > compactionIndex; i--) {\n\t\t\tconst entry = branchEntries[i];\n\t\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\t\tconst assistant = entry.message;\n\t\t\t\tif (assistant.stopReason !== \"aborted\" && assistant.stopReason !== \"error\") {\n\t\t\t\t\tconst contextTokens = calculateContextTokens(assistant.usage);\n\t\t\t\t\tif (contextTokens > 0) {\n\t\t\t\t\t\thasPostCompactionUsage = true;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (!hasPostCompactionUsage) {\n\t\t\treturn { tokens: null, contextWindow, percent: null };\n\t\t}\n\t}\n\n\tconst estimate = estimateContextTokens(session.messages);\n\tconst percent = (estimate.tokens / contextWindow) * 100;\n\n\treturn {\n\t\ttokens: estimate.tokens,\n\t\tcontextWindow,\n\t\tpercent,\n\t};\n}\n\n/**\n * Export session to HTML.\n * @param outputPath Optional output path (defaults to session directory)\n * @param options Optional export presentation settings\n * @returns Path to exported file\n */\nexport async function exportToHtml(\n\tsession: AgentSessionInternals,\n\toutputPath?: string,\n\toptions: { themeName?: string } = {},\n): Promise<string> {\n\tconst themeName = [options.themeName, session.settingsManager.getTheme()].find(\n\t\t(candidate) => candidate !== undefined && getThemeByName(candidate) !== undefined,\n\t);\n\n\t// Create tool renderer if we have an extension runner (for custom tool HTML rendering)\n\tconst toolRenderer: ToolHtmlRenderer = createToolHtmlRenderer({\n\t\tgetToolDefinition: (name) => session.getToolDefinition(name),\n\t\ttheme,\n\t\tcwd: session.sessionManager.getCwd(),\n\t});\n\n\treturn await exportSessionToHtml(session.sessionManager, session.agent.state, {\n\t\toutputPath,\n\t\tthemeName,\n\t\ttoolRenderer,\n\t});\n}\n\n/**\n * Export the current session branch to a JSONL file.\n * Writes the session header followed by all entries on the current branch path.\n * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.\n * @returns The resolved output file path.\n */\nexport function exportToJsonl(session: AgentSessionInternals, outputPath?: string): string {\n\treturn exportSessionToJsonl(session.sessionManager, outputPath);\n}\n\n/**\n * Get text content of last assistant message.\n * Useful for /copy command.\n * @returns Text content, or undefined if no assistant message exists\n */\nexport function getLastAssistantText(session: AgentSessionInternals): string | undefined {\n\tconst lastAssistant = session.messages\n\t\t.slice()\n\t\t.reverse()\n\t\t.find((m) => {\n\t\t\tif (m.role !== \"assistant\") return false;\n\t\t\tconst msg = m as AssistantMessage;\n\t\t\t// Skip aborted messages with no content\n\t\t\tif (msg.stopReason === \"aborted\" && msg.content.length === 0) return false;\n\t\t\treturn true;\n\t\t});\n\n\tif (!lastAssistant) return undefined;\n\n\tlet text = \"\";\n\tfor (const content of (lastAssistant as AssistantMessage).content) {\n\t\tif (content.type === \"text\") {\n\t\t\ttext += content.text;\n\t\t}\n\t}\n\n\treturn text.trim() || undefined;\n}\n"]}

package/dist/core/agent-session-retry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Auto-retry and overflow classification for AgentSession.
+ *
+ * Extracted from `agent-session.ts`. Every function here operates on the
+ * internal session facade ({@link AgentSessionInternals}); `AgentSession`
+ * keeps same-name private delegates so call sites, dynamic dispatch, and test
+ * spies keep working unchanged. Method-to-method calls go through the session
+ * parameter (not direct function calls) to preserve that dispatch.
+ */
+import type { AgentEvent } from "@agent-forge/agent-core";
+import type { AssistantMessage } from "@agent-forge/ai/compat";
+import type { AgentSessionInternals } from "./agent-session-internal.ts";
+import type { CapabilityRuntime, ExecutionFactsV1 } from "./extensions/index.ts";
+export declare function willRetryAfterAgentEnd(session: AgentSessionInternals, event: Extract<AgentEvent, {
+    type: "agent_end";
+}>, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Check if an error is retryable (overloaded, rate limit, server errors).
+ * Context overflow errors are NOT retryable (handled by compaction instead).
+ */
+export declare function isRetryableError(session: AgentSessionInternals, message: AssistantMessage, execution?: ExecutionFactsV1, signal?: AbortSignal): Promise<boolean>;
+export declare function decideRetry(session: AgentSessionInternals, message: AssistantMessage, execution?: ExecutionFactsV1, signal?: AbortSignal): Promise<import("./extensions/index.ts").RetryPolicyDecision>;
+/**
+ * Prepare a retryable error for continuation with exponential backoff.
+ * @returns true if the caller should continue the agent, false otherwise
+ */
+export declare function prepareRetry(session: AgentSessionInternals, message: AssistantMessage, precomputedDecision?: Awaited<ReturnType<CapabilityRuntime["decideRetry"]>>): Promise<boolean>;
+//# sourceMappingURL=agent-session-retry.d.ts.map

package/dist/core/agent-session-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-retry.d.ts","sourceRoot":"","sources":["../../src/core/agent-session-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,wBAAsB,sBAAsB,CAC3C,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,EACjD,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,OAAO,CAAC,CA8BlB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,gBAAgB,EACzB,SAAS,CAAC,EAAE,gBAAgB,EAC5B,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,wBAAsB,WAAW,CAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,gBAAgB,EACzB,SAAS,CAAC,EAAE,gBAAgB,EAC5B,MAAM,CAAC,EAAE,WAAW,gEAiBpB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,gBAAgB,EACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC,GACzE,OAAO,CAAC,OAAO,CAAC,CA0DlB","sourcesContent":["/**\n * Auto-retry and overflow classification for AgentSession.\n *\n * Extracted from `agent-session.ts`. Every function here operates on the\n * internal session facade ({@link AgentSessionInternals}); `AgentSession`\n * keeps same-name private delegates so call sites, dynamic dispatch, and test\n * spies keep working unchanged. Method-to-method calls go through the session\n * parameter (not direct function calls) to preserve that dispatch.\n */\n\nimport type { AgentEvent } from \"@agent-forge/agent-core\";\nimport { retryDelayMs } from \"@agent-forge/ai\";\nimport type { AssistantMessage } from \"@agent-forge/ai/compat\";\nimport { sleep } from \"../utils/sleep.ts\";\nimport { decideOverflow, executionFacts } from \"./agent-session-compaction.ts\";\nimport type { AgentSessionInternals } from \"./agent-session-internal.ts\";\nimport { dispatchAutoRetryLifecycle } from \"./agent-session-lifecycle.ts\";\nimport type { CapabilityRuntime, ExecutionFactsV1 } from \"./extensions/index.ts\";\n\nexport async function willRetryAfterAgentEnd(\n\tsession: AgentSessionInternals,\n\tevent: Extract<AgentEvent, { type: \"agent_end\" }>,\n\tsignal?: AbortSignal,\n): Promise<boolean> {\n\tif (signal?.aborted) {\n\t\tsession._pendingRetryDecision = undefined;\n\t\treturn false;\n\t}\n\tconst settings = session.settingsManager.getRetrySettings();\n\tif (session._retryAttempt >= settings.maxRetries) {\n\t\tsession._pendingRetryDecision = undefined;\n\t\treturn false;\n\t}\n\n\tfor (let i = event.messages.length - 1; i >= 0; i--) {\n\t\tconst message = event.messages[i];\n\t\tif (message.role === \"assistant\") {\n\t\t\tconst assistantMessage = message as AssistantMessage;\n\t\t\ttry {\n\t\t\t\tconst decision = await decideRetry(session, assistantMessage, undefined, signal);\n\t\t\t\tsession._pendingRetryDecision = { message: assistantMessage, decision };\n\t\t\t\treturn decision.retry;\n\t\t\t} catch (error) {\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\tsession._pendingRetryDecision = undefined;\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t}\n\tsession._pendingRetryDecision = undefined;\n\treturn false;\n}\n\n/**\n * Check if an error is retryable (overloaded, rate limit, server errors).\n * Context overflow errors are NOT retryable (handled by compaction instead).\n */\nexport async function isRetryableError(\n\tsession: AgentSessionInternals,\n\tmessage: AssistantMessage,\n\texecution?: ExecutionFactsV1,\n\tsignal?: AbortSignal,\n): Promise<boolean> {\n\t// Context overflow is handled by compaction, not retry.\n\tif ((await decideOverflow(session, message, execution, signal)).contextOverflow) return false;\n\tconst runtime = session._capabilityRuntime;\n\t// v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在\n\tif (!runtime) throw new Error(\"Capability runtime is not available\");\n\treturn runtime.classifyRetry(session._retryPolicyName, {\n\t\tmessage,\n\t\tsignal,\n\t\tcontext: { version: 1, sessionId: session.sessionId, phase: \"retry\" },\n\t\texecution: execution ?? executionFacts(session, \"retry\"),\n\t});\n}\n\nexport async function decideRetry(\n\tsession: AgentSessionInternals,\n\tmessage: AssistantMessage,\n\texecution?: ExecutionFactsV1,\n\tsignal?: AbortSignal,\n) {\n\tconst settings = session.settingsManager.getRetrySettings();\n\tconst runtime = session._capabilityRuntime;\n\t// v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在\n\tif (!runtime) throw new Error(\"Capability runtime is not available\");\n\treturn runtime.decideRetry(session._retryPolicyName, {\n\t\tretryable: await session._isRetryableError(message, execution, signal),\n\t\tenabled: settings.enabled,\n\t\tattempt: session._retryAttempt + 1,\n\t\tmaxAttempts: settings.maxRetries,\n\t\tbaseDelayMs: settings.baseDelayMs,\n\t\terrorMessage: message.errorMessage,\n\t\tsignal,\n\t\tcontext: { version: 1, sessionId: session.sessionId, phase: \"retry\" },\n\t\texecution: execution ?? executionFacts(session, \"retry\"),\n\t});\n}\n\n/**\n * Prepare a retryable error for continuation with exponential backoff.\n * @returns true if the caller should continue the agent, false otherwise\n */\nexport async function prepareRetry(\n\tsession: AgentSessionInternals,\n\tmessage: AssistantMessage,\n\tprecomputedDecision?: Awaited<ReturnType<CapabilityRuntime[\"decideRetry\"]>>,\n): Promise<boolean> {\n\tconst settings = session.settingsManager.getRetrySettings();\n\tconst decision = precomputedDecision ?? (await decideRetry(session, message));\n\tif (!decision.retry) return false;\n\tsession._retryAttempt++;\n\t// ±10% jitter on the exponential backoff (borrowed from codex's backoff):\n\t// prevents synchronized retry storms when many sessions hit the same outage.\n\t// The effective delay is capped by maxAgentDelayMs before jitter (retryDelayMs\n\t// already caps the exponential path; the min() also clamps policy-provided\n\t// delayMs), so a capped delay can overshoot the cap by at most the jitter band.\n\tconst baseDelayMs = Math.min(\n\t\tdecision.delayMs ?? retryDelayMs(settings, session._retryAttempt),\n\t\tsettings.maxAgentDelayMs,\n\t);\n\tconst delayMs = Math.round(baseDelayMs * (0.9 + Math.random() * 0.2));\n\t// Install the controller before announcing the retry so listeners can cancel\n\t// the pending delay from the auto_retry_start event itself.\n\tsession._retryAbortController = new AbortController();\n\n\tsession._emit({\n\t\ttype: \"auto_retry_start\",\n\t\tattempt: session._retryAttempt,\n\t\tmaxAttempts: settings.maxRetries,\n\t\tdelayMs,\n\t\terrorMessage: message.errorMessage || \"Unknown error\",\n\t});\n\tawait dispatchAutoRetryLifecycle(session, {\n\t\tattempt: session._retryAttempt,\n\t\tmaxAttempts: settings.maxRetries,\n\t\tdelayMs,\n\t\terrorMessage: message.errorMessage || \"Unknown error\",\n\t});\n\n\t// Remove error message from agent state (keep in session for history)\n\tconst messages = session.agent.state.messages;\n\tif (messages.length > 0 && messages[messages.length - 1].role === \"assistant\") {\n\t\tawait session._applyContextTransition(messages.slice(0, -1), \"retry\");\n\t}\n\n\t// Wait with exponential backoff (abortable)\n\ttry {\n\t\tawait sleep(delayMs, session._retryAbortController.signal);\n\t} catch {\n\t\t// Aborted during sleep - emit end event so UI can clean up\n\t\tconst attempt = session._retryAttempt;\n\t\tsession._retryAttempt = 0;\n\t\tsession._emit({\n\t\t\ttype: \"auto_retry_end\",\n\t\t\tsuccess: false,\n\t\t\tattempt,\n\t\t\tfinalError: \"Retry cancelled\",\n\t\t});\n\t\treturn false;\n\t} finally {\n\t\tsession._retryAbortController = undefined;\n\t}\n\n\treturn true;\n}\n"]}

package/dist/core/agent-session-retry.js

@@ -0,0 +1,141 @@
+/**
+ * Auto-retry and overflow classification for AgentSession.
+ *
+ * Extracted from `agent-session.ts`. Every function here operates on the
+ * internal session facade ({@link AgentSessionInternals}); `AgentSession`
+ * keeps same-name private delegates so call sites, dynamic dispatch, and test
+ * spies keep working unchanged. Method-to-method calls go through the session
+ * parameter (not direct function calls) to preserve that dispatch.
+ */
+import { retryDelayMs } from "@agent-forge/ai";
+import { sleep } from "../utils/sleep.js";
+import { decideOverflow, executionFacts } from "./agent-session-compaction.js";
+import { dispatchAutoRetryLifecycle } from "./agent-session-lifecycle.js";
+export async function willRetryAfterAgentEnd(session, event, signal) {
+    if (signal?.aborted) {
+        session._pendingRetryDecision = undefined;
+        return false;
+    }
+    const settings = session.settingsManager.getRetrySettings();
+    if (session._retryAttempt >= settings.maxRetries) {
+        session._pendingRetryDecision = undefined;
+        return false;
+    }
+    for (let i = event.messages.length - 1; i >= 0; i--) {
+        const message = event.messages[i];
+        if (message.role === "assistant") {
+            const assistantMessage = message;
+            try {
+                const decision = await decideRetry(session, assistantMessage, undefined, signal);
+                session._pendingRetryDecision = { message: assistantMessage, decision };
+                return decision.retry;
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    session._pendingRetryDecision = undefined;
+                    return false;
+                }
+                throw error;
+            }
+        }
+    }
+    session._pendingRetryDecision = undefined;
+    return false;
+}
+/**
+ * Check if an error is retryable (overloaded, rate limit, server errors).
+ * Context overflow errors are NOT retryable (handled by compaction instead).
+ */
+export async function isRetryableError(session, message, execution, signal) {
+    // Context overflow is handled by compaction, not retry.
+    if ((await decideOverflow(session, message, execution, signal)).contextOverflow)
+        return false;
+    const runtime = session._capabilityRuntime;
+    // v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在
+    if (!runtime)
+        throw new Error("Capability runtime is not available");
+    return runtime.classifyRetry(session._retryPolicyName, {
+        message,
+        signal,
+        context: { version: 1, sessionId: session.sessionId, phase: "retry" },
+        execution: execution ?? executionFacts(session, "retry"),
+    });
+}
+export async function decideRetry(session, message, execution, signal) {
+    const settings = session.settingsManager.getRetrySettings();
+    const runtime = session._capabilityRuntime;
+    // v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在
+    if (!runtime)
+        throw new Error("Capability runtime is not available");
+    return runtime.decideRetry(session._retryPolicyName, {
+        retryable: await session._isRetryableError(message, execution, signal),
+        enabled: settings.enabled,
+        attempt: session._retryAttempt + 1,
+        maxAttempts: settings.maxRetries,
+        baseDelayMs: settings.baseDelayMs,
+        errorMessage: message.errorMessage,
+        signal,
+        context: { version: 1, sessionId: session.sessionId, phase: "retry" },
+        execution: execution ?? executionFacts(session, "retry"),
+    });
+}
+/**
+ * Prepare a retryable error for continuation with exponential backoff.
+ * @returns true if the caller should continue the agent, false otherwise
+ */
+export async function prepareRetry(session, message, precomputedDecision) {
+    const settings = session.settingsManager.getRetrySettings();
+    const decision = precomputedDecision ?? (await decideRetry(session, message));
+    if (!decision.retry)
+        return false;
+    session._retryAttempt++;
+    // ±10% jitter on the exponential backoff (borrowed from codex's backoff):
+    // prevents synchronized retry storms when many sessions hit the same outage.
+    // The effective delay is capped by maxAgentDelayMs before jitter (retryDelayMs
+    // already caps the exponential path; the min() also clamps policy-provided
+    // delayMs), so a capped delay can overshoot the cap by at most the jitter band.
+    const baseDelayMs = Math.min(decision.delayMs ?? retryDelayMs(settings, session._retryAttempt), settings.maxAgentDelayMs);
+    const delayMs = Math.round(baseDelayMs * (0.9 + Math.random() * 0.2));
+    // Install the controller before announcing the retry so listeners can cancel
+    // the pending delay from the auto_retry_start event itself.
+    session._retryAbortController = new AbortController();
+    session._emit({
+        type: "auto_retry_start",
+        attempt: session._retryAttempt,
+        maxAttempts: settings.maxRetries,
+        delayMs,
+        errorMessage: message.errorMessage || "Unknown error",
+    });
+    await dispatchAutoRetryLifecycle(session, {
+        attempt: session._retryAttempt,
+        maxAttempts: settings.maxRetries,
+        delayMs,
+        errorMessage: message.errorMessage || "Unknown error",
+    });
+    // Remove error message from agent state (keep in session for history)
+    const messages = session.agent.state.messages;
+    if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
+        await session._applyContextTransition(messages.slice(0, -1), "retry");
+    }
+    // Wait with exponential backoff (abortable)
+    try {
+        await sleep(delayMs, session._retryAbortController.signal);
+    }
+    catch {
+        // Aborted during sleep - emit end event so UI can clean up
+        const attempt = session._retryAttempt;
+        session._retryAttempt = 0;
+        session._emit({
+            type: "auto_retry_end",
+            success: false,
+            attempt,
+            finalError: "Retry cancelled",
+        });
+        return false;
+    }
+    finally {
+        session._retryAbortController = undefined;
+    }
+    return true;
+}
+//# sourceMappingURL=agent-session-retry.js.map

package/dist/core/agent-session-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-retry.js","sourceRoot":"","sources":["../../src/core/agent-session-retry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Auto-retry and overflow classification for AgentSession.\n *\n * Extracted from `agent-session.ts`. Every function here operates on the\n * internal session facade ({@link AgentSessionInternals}); `AgentSession`\n * keeps same-name private delegates so call sites, dynamic dispatch, and test\n * spies keep working unchanged. Method-to-method calls go through the session\n * parameter (not direct function calls) to preserve that dispatch.\n */\n\nimport type { AgentEvent } from \"@agent-forge/agent-core\";\nimport { retryDelayMs } from \"@agent-forge/ai\";\nimport type { AssistantMessage } from \"@agent-forge/ai/compat\";\nimport { sleep } from \"../utils/sleep.ts\";\nimport { decideOverflow, executionFacts } from \"./agent-session-compaction.ts\";\nimport type { AgentSessionInternals } from \"./agent-session-internal.ts\";\nimport { dispatchAutoRetryLifecycle } from \"./agent-session-lifecycle.ts\";\nimport type { CapabilityRuntime, ExecutionFactsV1 } from \"./extensions/index.ts\";\n\nexport async function willRetryAfterAgentEnd(\n\tsession: AgentSessionInternals,\n\tevent: Extract<AgentEvent, { type: \"agent_end\" }>,\n\tsignal?: AbortSignal,\n): Promise<boolean> {\n\tif (signal?.aborted) {\n\t\tsession._pendingRetryDecision = undefined;\n\t\treturn false;\n\t}\n\tconst settings = session.settingsManager.getRetrySettings();\n\tif (session._retryAttempt >= settings.maxRetries) {\n\t\tsession._pendingRetryDecision = undefined;\n\t\treturn false;\n\t}\n\n\tfor (let i = event.messages.length - 1; i >= 0; i--) {\n\t\tconst message = event.messages[i];\n\t\tif (message.role === \"assistant\") {\n\t\t\tconst assistantMessage = message as AssistantMessage;\n\t\t\ttry {\n\t\t\t\tconst decision = await decideRetry(session, assistantMessage, undefined, signal);\n\t\t\t\tsession._pendingRetryDecision = { message: assistantMessage, decision };\n\t\t\t\treturn decision.retry;\n\t\t\t} catch (error) {\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\tsession._pendingRetryDecision = undefined;\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t}\n\tsession._pendingRetryDecision = undefined;\n\treturn false;\n}\n\n/**\n * Check if an error is retryable (overloaded, rate limit, server errors).\n * Context overflow errors are NOT retryable (handled by compaction instead).\n */\nexport async function isRetryableError(\n\tsession: AgentSessionInternals,\n\tmessage: AssistantMessage,\n\texecution?: ExecutionFactsV1,\n\tsignal?: AbortSignal,\n): Promise<boolean> {\n\t// Context overflow is handled by compaction, not retry.\n\tif ((await decideOverflow(session, message, execution, signal)).contextOverflow) return false;\n\tconst runtime = session._capabilityRuntime;\n\t// v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在\n\tif (!runtime) throw new Error(\"Capability runtime is not available\");\n\treturn runtime.classifyRetry(session._retryPolicyName, {\n\t\tmessage,\n\t\tsignal,\n\t\tcontext: { version: 1, sessionId: session.sessionId, phase: \"retry\" },\n\t\texecution: execution ?? executionFacts(session, \"retry\"),\n\t});\n}\n\nexport async function decideRetry(\n\tsession: AgentSessionInternals,\n\tmessage: AssistantMessage,\n\texecution?: ExecutionFactsV1,\n\tsignal?: AbortSignal,\n) {\n\tconst settings = session.settingsManager.getRetrySettings();\n\tconst runtime = session._capabilityRuntime;\n\t// v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在\n\tif (!runtime) throw new Error(\"Capability runtime is not available\");\n\treturn runtime.decideRetry(session._retryPolicyName, {\n\t\tretryable: await session._isRetryableError(message, execution, signal),\n\t\tenabled: settings.enabled,\n\t\tattempt: session._retryAttempt + 1,\n\t\tmaxAttempts: settings.maxRetries,\n\t\tbaseDelayMs: settings.baseDelayMs,\n\t\terrorMessage: message.errorMessage,\n\t\tsignal,\n\t\tcontext: { version: 1, sessionId: session.sessionId, phase: \"retry\" },\n\t\texecution: execution ?? executionFacts(session, \"retry\"),\n\t});\n}\n\n/**\n * Prepare a retryable error for continuation with exponential backoff.\n * @returns true if the caller should continue the agent, false otherwise\n */\nexport async function prepareRetry(\n\tsession: AgentSessionInternals,\n\tmessage: AssistantMessage,\n\tprecomputedDecision?: Awaited<ReturnType<CapabilityRuntime[\"decideRetry\"]>>,\n): Promise<boolean> {\n\tconst settings = session.settingsManager.getRetrySettings();\n\tconst decision = precomputedDecision ?? (await decideRetry(session, message));\n\tif (!decision.retry) return false;\n\tsession._retryAttempt++;\n\t// ±10% jitter on the exponential backoff (borrowed from codex's backoff):\n\t// prevents synchronized retry storms when many sessions hit the same outage.\n\t// The effective delay is capped by maxAgentDelayMs before jitter (retryDelayMs\n\t// already caps the exponential path; the min() also clamps policy-provided\n\t// delayMs), so a capped delay can overshoot the cap by at most the jitter band.\n\tconst baseDelayMs = Math.min(\n\t\tdecision.delayMs ?? retryDelayMs(settings, session._retryAttempt),\n\t\tsettings.maxAgentDelayMs,\n\t);\n\tconst delayMs = Math.round(baseDelayMs * (0.9 + Math.random() * 0.2));\n\t// Install the controller before announcing the retry so listeners can cancel\n\t// the pending delay from the auto_retry_start event itself.\n\tsession._retryAbortController = new AbortController();\n\n\tsession._emit({\n\t\ttype: \"auto_retry_start\",\n\t\tattempt: session._retryAttempt,\n\t\tmaxAttempts: settings.maxRetries,\n\t\tdelayMs,\n\t\terrorMessage: message.errorMessage || \"Unknown error\",\n\t});\n\tawait dispatchAutoRetryLifecycle(session, {\n\t\tattempt: session._retryAttempt,\n\t\tmaxAttempts: settings.maxRetries,\n\t\tdelayMs,\n\t\terrorMessage: message.errorMessage || \"Unknown error\",\n\t});\n\n\t// Remove error message from agent state (keep in session for history)\n\tconst messages = session.agent.state.messages;\n\tif (messages.length > 0 && messages[messages.length - 1].role === \"assistant\") {\n\t\tawait session._applyContextTransition(messages.slice(0, -1), \"retry\");\n\t}\n\n\t// Wait with exponential backoff (abortable)\n\ttry {\n\t\tawait sleep(delayMs, session._retryAbortController.signal);\n\t} catch {\n\t\t// Aborted during sleep - emit end event so UI can clean up\n\t\tconst attempt = session._retryAttempt;\n\t\tsession._retryAttempt = 0;\n\t\tsession._emit({\n\t\t\ttype: \"auto_retry_end\",\n\t\t\tsuccess: false,\n\t\t\tattempt,\n\t\t\tfinalError: \"Retry cancelled\",\n\t\t});\n\t\treturn false;\n\t} finally {\n\t\tsession._retryAbortController = undefined;\n\t}\n\n\treturn true;\n}\n"]}

package/dist/core/agent-session-runtime.d.ts

@@ -0,0 +1,181 @@
+import type { ImageContent, TextContent } from "@agent-forge/ai/compat";
+import type { AgentSession } from "./agent-session.ts";
+import type { AgentSessionRuntimeDiagnostic, AgentSessionServices } from "./agent-session-services.ts";
+import type { AgentTaskChildProfileV1 } from "./extensions/public-api.ts";
+import type { CustomMessage } from "./messages.ts";
+import type { CreateAgentSessionResult, PluginRejection } from "./sdk.ts";
+import { SessionManager } from "./session-manager.ts";
+import type { SessionStartMetadata } from "./session-start.ts";
+/**
+ * Result returned by runtime creation.
+ *
+ * The caller gets the created session, its cwd-bound services, and all
+ * diagnostics collected during setup.
+ */
+/**
+ * Fresh session-bound context passed to `withSession()` callbacks on
+ * `newSession()`, `fork()`, and `switchSession()`. It targets the replacement
+ * session: every call routes into the session that became current after the
+ * replacement committed.
+ */
+export interface ReplacedSessionContext {
+    sendMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: {
+        triggerTurn?: boolean;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
+        deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
+    }): Promise<void>;
+}
+export interface CreateAgentSessionRuntimeResult extends CreateAgentSessionResult {
+    services: AgentSessionServices;
+    diagnostics: AgentSessionRuntimeDiagnostic[];
+    /**
+     * 仅当工厂收到 `childProfile` 时存在：叶子会话的**可核验事实**（实际生效的工具面、
+     * 模型、模式）。runner 侧 server 用它与请求档案比对后才允许任务起跑——"要求了但
+     * 没人能证明"与"没要求"是同一风险。
+     */
+    childFacts?: {
+        readonly activeTools: readonly string[];
+        readonly model?: {
+            readonly provider: string;
+            readonly id: string;
+            readonly contextWindow: number;
+            readonly maxTokens: number;
+            readonly reasoning: boolean;
+        };
+        readonly capabilityMode: string;
+        /** 叶子实际思考级别（档案请求了 thinkingLevel 时核验用）。 */
+        readonly thinkingLevel?: string;
+        /** 叶子实际生效的系统提示词追加段（档案请求了 systemPromptAppend 时核验用，已含方案 APPEND_SYSTEM.md 门控结果）。 */
+        readonly systemPromptAppend?: string;
+    };
+}
+/**
+ * Creates a full runtime for a target cwd and session manager.
+ *
+ * The factory closes over process-global fixed inputs, recreates cwd-bound
+ * services for the effective cwd, resolves session options against those
+ * services, and finally creates the AgentSession.
+ */
+export type CreateAgentSessionRuntimeFactory = (options: {
+    cwd: string;
+    agentDir: string;
+    sessionManager: SessionManager;
+    sessionStartEvent?: SessionStartMetadata;
+    /**
+     * 子任务档案（AgentTaskChildProfileV1）：pooled runner 的叶子会话按它收窄
+     * （tools/mode/thinkingLevel）。父会话创建路径不传该字段——档案只服务子任务。
+     */
+    childProfile?: AgentTaskChildProfileV1;
+    /**
+     * 子代理通信面的宿主接线（D-060 S5 pooled parity）：runner 叶子装配注入
+     * post/drainInbox 闭包（身份绑定到叶子会话），叶子会话由此获得
+     * escalate/兄弟消息工具。父会话创建路径不传该字段。
+     */
+    subagentCommunicationWiring?: import("./sdk.ts").CreateAgentSessionOptions["subagentCommunicationWiring"];
+    /**
+     * 档案 model 的目标 id（D-060 pooled parity 补口）：runner 侧把叶子会话模型
+     * 解析到**自己的 scoped models**（档案不能把会话带到 runner 未授权的模型上），
+     * 解析不到即失败并列出可用 id。父会话创建路径不传该字段。
+     */
+    childModelId?: string;
+}) => Promise<CreateAgentSessionRuntimeResult>;
+/**
+ * Thrown when /import references a JSONL file path that does not exist.
+ */
+export declare class SessionImportFileNotFoundError extends Error {
+    readonly filePath: string;
+    constructor(filePath: string);
+}
+/**
+ * Owns the current AgentSession plus its cwd-bound services.
+ *
+ * Session replacement methods tear down the current runtime first, then create
+ * and apply the next runtime. If creation fails, the error is propagated to the
+ * caller. The caller is responsible for user-facing error handling.
+ */
+export declare class AgentSessionRuntime {
+    private rebindSession?;
+    private beforeSessionInvalidate?;
+    private _session;
+    private _services;
+    private readonly createRuntime;
+    private _diagnostics;
+    private _suiteDiagnostics;
+    private _modelFallbackMessage?;
+    private _pluginRejections;
+    constructor(_session: AgentSession, _services: AgentSessionServices, createRuntime: CreateAgentSessionRuntimeFactory, _diagnostics?: AgentSessionRuntimeDiagnostic[], _modelFallbackMessage?: string, _pluginRejections?: readonly PluginRejection[], _suiteDiagnostics?: readonly string[]);
+    get services(): AgentSessionServices;
+    /** /metrics 数据源共享 ref（observability 插件门面，空 = 未挂载）。 */
+    get observabilityGetMetricsRef(): AgentSessionServices["observabilityGetMetricsRef"];
+    get session(): AgentSession;
+    get cwd(): string;
+    get diagnostics(): readonly AgentSessionRuntimeDiagnostic[];
+    /**
+     * Suite assembly findings from the last runtime creation (initial,
+     * /new, /fork, /switch). Surfaced as info-level entries on the
+     * `diagnostics` channel.
+     */
+    get suiteDiagnostics(): readonly string[];
+    get modelFallbackMessage(): string | undefined;
+    get pluginRejections(): readonly PluginRejection[];
+    setRebindSession(rebindSession?: (session: AgentSession) => Promise<void>): void;
+    /**
+     * Set a synchronous callback that runs after `session_shutdown` handlers finish
+     * but before the current session is invalidated.
+     *
+     * This is for host-owned UI teardown that must not yield to the event loop,
+     * such as detaching extension-provided TUI components before the old extension
+     * context becomes stale.
+     */
+    setBeforeSessionInvalidate(beforeSessionInvalidate?: () => void): void;
+    private teardownCurrent;
+    private apply;
+    private finishSessionReplacement;
+    switchSession(sessionPath: string, options?: {
+        cwdOverride?: string;
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    newSession(options?: {
+        parentSession?: string;
+        setup?: (sessionManager: SessionManager) => Promise<void>;
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    fork(entryId: string, options?: {
+        position?: "before" | "at";
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
+        cancelled: boolean;
+        selectedText?: string;
+    }>;
+    /**
+     * Import a session JSONL file and switch runtime state to the imported session.
+     *
+     * @throws {SessionImportFileNotFoundError} When the input path does not exist.
+     * @throws {MissingSessionCwdError} When the imported session cwd cannot be resolved and no override is provided.
+     */
+    importFromJsonl(inputPath: string, cwdOverride?: string): Promise<{
+        cancelled: boolean;
+    }>;
+    dispose(): Promise<void>;
+}
+/**
+ * Create the initial runtime from a runtime factory and initial session target.
+ *
+ * The same factory is stored on the returned AgentSessionRuntime and reused for
+ * later /new, /resume, /fork, and import flows.
+ */
+export declare function createAgentSessionRuntime(createRuntime: CreateAgentSessionRuntimeFactory, options: {
+    cwd: string;
+    agentDir: string;
+    sessionManager: SessionManager;
+    sessionStartEvent?: SessionStartMetadata;
+}): Promise<AgentSessionRuntime>;
+export { type AgentSessionRuntimeDiagnostic, type AgentSessionServices, type CreateAgentSessionFromServicesOptions, type CreateAgentSessionServicesOptions, createAgentSessionFromServices, createAgentSessionServices, } from "./agent-session-services.ts";
+//# sourceMappingURL=agent-session-runtime.d.ts.map