@sema-agent/core 2.4.0 → 2.5.0

package/dist/core/task-registry-agent.js

@@ -706,6 +706,8 @@ export function settleBackgroundAgentLane(core, id, outcome) {
             handle.errorCode = outcome.errorCode;
         if (outcome.retryable !== undefined)
             handle.errorRetryable = outcome.retryable;
+        if (outcome.errorKind !== undefined)
+            handle.errorKind = outcome.errorKind;
     }
     handle.updatedAt = Date.now();
     if (outcome.seq !== undefined)
@@ -844,6 +846,9 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.resultFull = undefined;
     handle.spillRef = undefined;
     handle.error = undefined;
+    handle.errorCode = undefined;
+    handle.errorRetryable = undefined;
+    handle.errorKind = undefined;
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
     handle.completionId = undefined;
@@ -1030,6 +1035,7 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
             ...(row.resultIsPartial ? { partial_result: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
         },
+        ...(row.status === "failed" ? { isError: true } : {}),
     };
 }
 export async function spillClippedAgentResult(handle, full, clipped, store, sessionId) {
@@ -1065,6 +1071,9 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
     }
     const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
     const resultText = fullResult !== undefined ? await spillClippedAgentResult(handle, fullResult, clipTaskOutput(fullResult, handle.outputFile), store, sessionId) : undefined;
+    const kindClause = handle.status === "failed" && handle.errorKind !== undefined && handle.errorRetryable !== undefined
+        ? ` (error_kind: ${handle.errorKind}, retryable: ${handle.errorRetryable})`
+        : "";
     const body = running
         ? oneShot === true
             ? `status: running
@@ -1072,7 +1081,7 @@ This is a ONE-SHOT submission — there is no later turn for a background notifi
             : `status: running
 The agent is still working — you will be notified when it completes.`
         : `status: ${handle.status}
-${handle.error ? `error: ${handle.error}
+${handle.error ? `error: ${handle.error}${kindClause}
 ` : ""}${handle.result ? `--- result${handle.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${resultText}` : "(no result text)"}`;
     return {
@@ -1092,6 +1101,7 @@ ${resultText}` : "(no result text)"}`;
             ...(handle.resultIsPartial ? { partial_result: true } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
         },
+        ...(handle.status === "failed" ? { isError: true } : {}),
     };
 }
 export async function stopBackgroundAgentLane(core, handle) {

package/dist/core/task-registry-shared.d.ts

@@ -139,6 +139,7 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     error?: string;
     errorCode?: string;
     errorRetryable?: boolean;
+    errorKind?: string;
     resultIsPartial?: boolean;
     stopSource?: StopSource;
     stoppedBy?: StopSource;

package/dist/core/task-registry.d.ts

@@ -135,6 +135,7 @@ export declare class TaskRegistry {
         error?: string;
         errorCode?: string;
         retryable?: boolean;
+        errorKind?: string;
         stoppedBy?: StopSource;
         seq?: number;
     }): "completed" | "failed" | "killed" | undefined;
@@ -170,6 +171,7 @@ export declare class TaskRegistry {
         error?: string;
         errorCode?: string;
         retryable?: boolean;
+        errorKind?: string;
     }): "completed" | "failed" | "killed" | undefined;
     unmarkRetainedContinuation(id: string): void;
     attachAgentNotify(id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;

package/dist/core/task-registry.js

@@ -368,6 +368,17 @@ export class TaskRegistry {
     async settleKilledForOwner(access, opts) {
         const source = opts?.source ?? "parent";
         const clause = (by) => by === "user" ? "stopped by user" : by === "parent" ? "its parent run ended" : `stopped by ${by}`;
+        if (source === "user") {
+            for (const handle of this.handles.values()) {
+                if (handle.type !== "background_agent" || handle.status !== "running")
+                    continue;
+                if (!canAccess(handle, { owner: access.owner, scope: access.scope }))
+                    continue;
+                if (opts?.skipSessionScoped && handle.sessionScoped)
+                    continue;
+                this.markStopSource(handle.id, source);
+            }
+        }
         let settled = 0;
         for (const handle of this.handles.values()) {
             if (handle.type !== "background_bash" && handle.type !== "monitor")

package/dist/core/types.d.ts

@@ -47,6 +47,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     offload?: boolean;
     offloadThresholdChars?: number;
     defer?: boolean;
+    alwaysLoad?: boolean;
     contract?: {
         contractId: string;
         implementationRevision: string;
@@ -256,6 +257,7 @@ export interface TaskSpec {
     tools?: ToolSpec[];
     excludeTools?: string[];
     deferTools?: string[];
+    alwaysLoadTools?: string[];
     promptProfile?: "simple" | "classic";
     agents?: AgentDefinition[];
     toolPolicy?: import("./tool-policy.js").ToolPolicy;
@@ -514,9 +516,9 @@ export type TaskEvent = ({
     };
     usageMissing?: true;
     stopReason?: string;
-} & TaskEventIdentity) | {
+} & TaskEventIdentity) | ({
     type: "compacted";
-    trigger: "auto" | "manual";
+    trigger: "auto" | "manual" | "forced";
     tokensBefore: number;
     tokensAfter?: number;
     triggerTokensBefore?: number;
@@ -534,7 +536,12 @@ export type TaskEvent = ({
     clampedRatio?: number;
     clampReason?: "budget" | "walltime" | "tolerance";
     phaseDurations?: import("./auto-compaction.js").CompactionPhaseDurations;
-} | ({
+} & TaskEventIdentity) | ({
+    type: "compaction_outcome";
+    outcome: Exclude<CompactOutcome, "compacted"> | "suppressed";
+    trigger: "auto" | "manual" | "forced";
+    reason?: string;
+} & TaskEventIdentity) | ({
     type: "steering_injected";
     source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
     preview: string;

package/dist/engine/compaction/compaction.d.ts

@@ -8,6 +8,9 @@ export interface CompactionDetails {
     modifiedFiles: string[];
     modifiedFilesByRecency?: string[];
     invokedSkills?: InvokedSkillRetention[];
+    elidedMessages?: number;
+    persistedOutputRefs?: string[];
+    activeTools?: string[];
 }
 export interface CompactionResult<T = unknown> {
     summary: string;
@@ -68,6 +71,8 @@ export interface CompactionPreparation {
     previousSummary?: string;
     fileOps: FileOperations;
     invokedSkills: InvokedSkillRetention[];
+    persistedOutputRefs?: string[];
+    elidedMessages?: number;
     settings: CompactionSettings;
 }
 export declare function prepareCompaction(pathEntries: SessionTreeEntry[], settings: CompactionSettings, charsPerToken?: number, windowTokens?: number): Result<CompactionPreparation | undefined, CompactionError>;

package/dist/engine/compaction/compaction.js

@@ -2,7 +2,7 @@ import { resolveAgentCoreCompleteFn, } from "../loop/runtime-deps.js";
 import { asAgentMessage, convertToLlm, createCompactionSummaryMessage, createCustomMessage, } from "../harness/messages.js";
 import { buildSessionContext } from "../session/session.js";
 import { CompactionError, err, ok, } from "../harness/types.js";
-import { budgetInvokedSkillsRetention, computeFileLists, createFileOps, extractFileOpsFromMessage, extractInvokedSkills, formatFileOperations, readRetainedInvokedSkills, replaceInvokedSkillBodiesForSummary, serializeConversation, stripFileOperationsFooter, } from "./utils.js";
+import { budgetInvokedSkillsRetention, computeFileLists, createFileOps, extractFileOpsFromMessage, extractInvokedSkills, extractPersistedOutputRefs, formatFileOperations, formatPersistedOutputRefs, PERSISTED_OUTPUT_REFS_MAX_ENTRIES, readElidedMessages, readPersistedOutputRefs, readRetainedInvokedSkills, replaceInvokedSkillBodiesForSummary, serializeConversation, stripFileOperationsFooter, } from "./utils.js";
 function safeJsonStringify(value) {
     try {
         return JSON.stringify(value) ?? "undefined";
@@ -256,6 +256,51 @@ export function findTurnStartIndex(entries, entryIndex, startIndex) {
     }
     return -1;
 }
+function enforceToolPairContainment(entries, startIndex, endIndex, cutIndex) {
+    const callSites = new Map();
+    for (let i = startIndex; i < endIndex; i++) {
+        const entry = entries[i];
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        if (msg.role !== "assistant" || !Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type === "toolCall" && typeof block.id === "string") {
+                const at = callSites.get(block.id);
+                if (at === undefined)
+                    callSites.set(block.id, [i]);
+                else
+                    at.push(i);
+            }
+        }
+    }
+    if (callSites.size === 0)
+        return cutIndex;
+    for (let i = cutIndex; i < endIndex; i++) {
+        const entry = entries[i];
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        if (msg.role !== "toolResult")
+            continue;
+        const sites = callSites.get(msg.toolCallId);
+        if (sites === undefined)
+            continue;
+        let site = -1;
+        for (const s of sites) {
+            if (s < i)
+                site = s;
+            else
+                break;
+        }
+        if (site === -1 || site >= cutIndex)
+            continue;
+        cutIndex = site;
+        i = site;
+    }
+    return cutIndex;
+}
 export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens, charsPerToken = DEFAULT_CHARS_PER_TOKEN) {
     const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
     if (cutPoints.length === 0) {
@@ -290,6 +335,7 @@ export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens, ch
             break;
         }
     }
+    cutIndex = enforceToolPairContainment(entries, startIndex, endIndex, cutIndex);
     const cutEntry = entries[cutIndex];
     const isUserMessage = cutEntry.type === "message" && cutEntry.message.role === "user";
     const turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
@@ -721,6 +767,21 @@ export function prepareCompaction(pathEntries, settings, charsPerToken = DEFAULT
         ? Math.max(0, windowTokens - settings.reserveTokens - settings.keepRecentTokens) * charsPerToken
         : undefined;
     const invokedSkills = budgetInvokedSkillsRetention(extractInvokedSkills([...messagesToSummarize, ...turnPrefixMessages], prevRetainedSkills), retentionBudgetChars);
+    const refSet = new Set();
+    if (prevCompactionIndex >= 0 && !pathEntries[prevCompactionIndex].fromHook) {
+        for (const r of readPersistedOutputRefs(pathEntries[prevCompactionIndex].details)) {
+            refSet.add(r);
+        }
+    }
+    extractPersistedOutputRefs(messagesToSummarize, refSet);
+    if (cutPoint.isSplitTurn) {
+        extractPersistedOutputRefs(turnPrefixMessages, refSet);
+    }
+    const persistedOutputRefs = [...refSet].slice(-PERSISTED_OUTPUT_REFS_MAX_ENTRIES);
+    const prevElided = prevCompactionIndex >= 0 && !pathEntries[prevCompactionIndex].fromHook
+        ? readElidedMessages(pathEntries[prevCompactionIndex].details)
+        : undefined;
+    const elidedMessages = (prevElided ?? 0) + messagesToSummarize.length + turnPrefixMessages.length;
     const [summarizeReady, prefixReady] = replaceInvokedSkillBodiesForSummary([messagesToSummarize, turnPrefixMessages], new Set(invokedSkills.map((s) => s.name)));
     return ok({
         firstKeptEntryId,
@@ -731,6 +792,8 @@ export function prepareCompaction(pathEntries, settings, charsPerToken = DEFAULT
         previousSummary,
         fileOps,
         invokedSkills,
+        persistedOutputRefs,
+        elidedMessages,
         settings,
     });
 }
@@ -750,7 +813,7 @@ Summarize the prefix to provide context for the retained suffix:
 Be concise. Focus on what's needed to understand the kept suffix.`;
 export { computeFileLists, serializeConversation } from "./utils.js";
 export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, streamFn, runtime, charsPerToken, onInputTruncated, onPtlRetry) {
-    const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, invokedSkills, settings, } = preparation;
+    const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, invokedSkills, persistedOutputRefs, elidedMessages, settings, } = preparation;
     if (!firstKeptEntryId) {
         return err(new CompactionError("invalid_session", "First kept entry has no UUID - session may need migration"));
     }
@@ -784,6 +847,7 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
     }
     const { readFiles, modifiedFiles, modifiedFilesByRecency } = computeFileLists(fileOps);
     summary += formatFileOperations(readFiles, modifiedFiles);
+    summary += formatPersistedOutputRefs(persistedOutputRefs ?? []);
     return ok({
         summary,
         firstKeptEntryId,
@@ -793,6 +857,8 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
             modifiedFiles,
             modifiedFilesByRecency,
             ...(invokedSkills !== undefined && invokedSkills.length > 0 ? { invokedSkills } : {}),
+            ...(persistedOutputRefs !== undefined && persistedOutputRefs.length > 0 ? { persistedOutputRefs } : {}),
+            ...(elidedMessages !== undefined && elidedMessages > 0 ? { elidedMessages } : {}),
         },
     });
 }

package/dist/engine/compaction/utils.d.ts

@@ -21,6 +21,12 @@ export declare function budgetInvokedSkillsRetention(newestFirst: InvokedSkillRe
 export declare function replaceInvokedSkillBodiesForSummary(groups: AgentMessage[][], retainedNames: ReadonlySet<string>): AgentMessage[][];
 export declare function readRetainedInvokedSkills(details: unknown): InvokedSkillRetention[];
 export declare function renderInvokedSkillsRetention(skills: InvokedSkillRetention[]): string;
+export declare const PERSISTED_OUTPUT_REFS_MAX_ENTRIES = 50;
+export declare function extractPersistedOutputRefs(messages: AgentMessage[], into: Set<string>): void;
+export declare function readElidedMessages(details: unknown): number | undefined;
+export declare function readCompactionActiveTools(details: unknown): string[];
+export declare function readPersistedOutputRefs(details: unknown): string[];
+export declare function formatPersistedOutputRefs(refs: string[]): string;
 export declare function computeFileLists(fileOps: FileOperations): {
     readFiles: string[];
     modifiedFiles: string[];

package/dist/engine/compaction/utils.js

@@ -182,6 +182,52 @@ export function renderInvokedSkillsRetention(skills) {
         `If a skill's content was truncated, invoke the Skill tool again for the full text.\n\n` +
         `${sections.join("\n\n")}\n</invoked-skills>`);
 }
+const PERSISTED_OUTPUT_REF_RE = /<persisted-output ref="([^"]+)"/g;
+const OFFLOAD_TOOL_NAME_LITERAL = "ReadToolResult";
+export const PERSISTED_OUTPUT_REFS_MAX_ENTRIES = 50;
+export function extractPersistedOutputRefs(messages, into) {
+    for (const msg of messages) {
+        if (msg.role !== "toolResult" || !Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type !== "text" || typeof block.text !== "string")
+                continue;
+            for (const m of block.text.matchAll(PERSISTED_OUTPUT_REF_RE)) {
+                into.add(m[1]);
+            }
+        }
+    }
+}
+export function readElidedMessages(details) {
+    if (details === null || typeof details !== "object")
+        return undefined;
+    const raw = details.elidedMessages;
+    return typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 0 ? raw : undefined;
+}
+export function readCompactionActiveTools(details) {
+    if (details === null || typeof details !== "object")
+        return [];
+    const raw = details.activeTools;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((n) => typeof n === "string" && n.length > 0);
+}
+export function readPersistedOutputRefs(details) {
+    if (details === null || typeof details !== "object")
+        return [];
+    const raw = details.persistedOutputRefs;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((r) => typeof r === "string" && r.length > 0);
+}
+export function formatPersistedOutputRefs(refs) {
+    if (refs.length === 0)
+        return "";
+    return (`\n\n<persisted-tool-outputs>\n` +
+        `Tool outputs elided by compaction were persisted in full and remain retrievable — call ` +
+        `${OFFLOAD_TOOL_NAME_LITERAL} with a ref to read one back:\n` +
+        `${capList(refs)}\n</persisted-tool-outputs>`);
+}
 function touchModified(fileOps, path) {
     fileOps.modifiedOrder.delete(path);
     fileOps.modifiedOrder.add(path);
@@ -217,9 +263,13 @@ export function formatFileOperations(readFiles, modifiedFiles) {
     return `\n\n${sections.join("\n\n")}`;
 }
 export function stripFileOperationsFooter(summary) {
-    return summary
-        .replace(/\n\n<read-files>\n[\s\S]*?\n<\/read-files>(\n\n<modified-files>\n[\s\S]*?\n<\/modified-files>)?\s*$/, "")
-        .replace(/\n\n<modified-files>\n[\s\S]*?\n<\/modified-files>\s*$/, "");
+    let out = summary;
+    for (;;) {
+        const next = out.replace(/\n\n<(read-files|modified-files|persisted-tool-outputs)>\n[\s\S]*?\n<\/\1>\s*$/, "");
+        if (next === out)
+            return out;
+        out = next;
+    }
 }
 const TOOL_RESULT_MAX_CHARS = 2000;
 function safeJsonStringify(value) {

package/dist/engine/harness/messages.d.ts

@@ -6,7 +6,7 @@ export declare function asAgentMessage(message: HarnessMessage): AgentMessage;
 export declare const COMPACTION_SUMMARY_PREFIX = "This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.\n\n<summary>\n";
 export declare const COMPACTION_SUMMARY_SUFFIX = "\n</summary>\n\nRecent messages are preserved verbatim below. Continue the conversation from where it left off without asking the user any further questions. Resume directly \u2014 do not acknowledge the summary, do not recap what was happening, do not preface with \"I'll continue\" or similar. Pick up the last task as if the break never happened.";
 export declare function bashExecutionToText(msg: BashExecutionMessage): string;
-export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string): CompactionSummaryMessage;
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, elidedMessages?: number): CompactionSummaryMessage;
 export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown, timestamp: string): CustomMessage;
 export declare const NORMALIZED_CONTENT_PREFIX = "[invalid content block normalized to text]";
 export declare function normalizeLlmMessageContent<T extends Message>(message: T): T;

package/dist/engine/harness/messages.js

@@ -36,12 +36,13 @@ export function bashExecutionToText(msg) {
     }
     return text;
 }
-export function createCompactionSummaryMessage(summary, tokensBefore, timestamp) {
+export function createCompactionSummaryMessage(summary, tokensBefore, timestamp, elidedMessages) {
     return {
         role: "compactionSummary",
         summary,
         tokensBefore,
         timestamp: requireSessionTimestampMs(timestamp, "compaction summary timestamp"),
+        ...(elidedMessages !== undefined ? { elidedMessages } : {}),
     };
 }
 export function createCustomMessage(customType, content, display, details, timestamp) {
@@ -128,17 +129,24 @@ export function convertToLlm(messages) {
                     ...(message.provenance === "engine-note" ? { provenance: "engine-note" } : {}),
                 });
             }
-            case "compactionSummary":
+            case "compactionSummary": {
+                const n = message.elidedMessages;
+                const disclosure = n !== undefined && n > 0
+                    ? `\n\n(For scale: this summary stands in for ${n} earlier message${n === 1 ? "" : "s"}${message.tokensBefore > 0
+                        ? ` — approximately ${message.tokensBefore} tokens of context before compaction`
+                        : ""}.)`
+                    : "";
                 return {
                     role: "user",
                     content: [
                         {
                             type: "text",
-                            text: COMPACTION_SUMMARY_PREFIX + message.summary + COMPACTION_SUMMARY_SUFFIX,
+                            text: COMPACTION_SUMMARY_PREFIX + message.summary + COMPACTION_SUMMARY_SUFFIX + disclosure,
                         },
                     ],
                     timestamp: normalizeCompactionSummaryTimestamp(message.timestamp),
                 };
+            }
             case "user":
             case "assistant":
             case "toolResult":

package/dist/engine/loop/types.d.ts

@@ -129,6 +129,7 @@ export interface CompactionSummaryMessage {
     summary: string;
     tokensBefore: number;
     timestamp: number | string;
+    elidedMessages?: number;
     tokensAfter?: number;
     firstKeptEntryId?: string;
     details?: unknown;
@@ -161,6 +162,7 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
     execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
     executionMode?: ToolExecutionMode;
     mcpMaxResultSizeChars?: number;
+    mcpAlwaysLoad?: boolean;
     isConcurrencySafe?: (args: unknown) => boolean;
 }
 export interface AgentContext {

package/dist/engine/session/import-validate.js

@@ -3,11 +3,14 @@ import { leafIdAfterEntry } from "./storage-base.js";
 import { parseSessionTimestampMs } from "./timestamps.js";
 import { flattenableUserText, normalizeEngineSegments } from "../../core/untrusted-text.js";
 import { normalizePromptEpoch } from "../../prompt-assembly/epoch.js";
-import { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, } from "../compaction/utils.js";
+import { PERSISTED_OUTPUT_REFS_MAX_ENTRIES, SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, } from "../compaction/utils.js";
 const PATH_LIST_MAX_CHARS = 4096;
 const PATH_LIST_MAX_ENTRIES = 1000;
 const INVOKED_SKILLS_MAX_ENTRIES = 1000;
 const INVOKED_SKILL_NAME_MAX_CHARS = 1024;
+const PERSISTED_REF_MAX_CHARS = 256;
+const ACTIVE_TOOL_NAME_MAX_CHARS = 1024;
+const ACTIVE_TOOLS_MAX_ENTRIES = 1000;
 export class StreamingImportValidator {
     seen = new Set();
     parentOf = new Map();
@@ -157,6 +160,32 @@ export class StreamingImportValidator {
                     throw new SessionError("invalid_session", `compaction "${e.id}" carries an invokedSkills area of ${totalChars} chars (max ${SKILL_RETENTION_TOTAL_MAX_CHARS})`);
                 }
             }
+            const elided = e.details?.elidedMessages;
+            if (elided !== undefined && !(typeof elided === "number" && Number.isSafeInteger(elided) && elided >= 0)) {
+                throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid elidedMessages count (non-negative integer)`);
+            }
+            const refs = e.details?.persistedOutputRefs;
+            if (refs !== undefined) {
+                if (!Array.isArray(refs) || refs.length > PERSISTED_OUTPUT_REFS_MAX_ENTRIES) {
+                    throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid persistedOutputRefs list (array of at most ${PERSISTED_OUTPUT_REFS_MAX_ENTRIES} refs)`);
+                }
+                for (const r of refs) {
+                    if (typeof r !== "string" || r.length === 0 || r.length > PERSISTED_REF_MAX_CHARS) {
+                        throw new SessionError("invalid_session", `compaction "${e.id}" carries a persistedOutputRefs entry that is not a non-empty string of at most ${PERSISTED_REF_MAX_CHARS} chars`);
+                    }
+                }
+            }
+            const activeToolsCarrier = e.details?.activeTools;
+            if (activeToolsCarrier !== undefined) {
+                if (!Array.isArray(activeToolsCarrier) || activeToolsCarrier.length > ACTIVE_TOOLS_MAX_ENTRIES) {
+                    throw new SessionError("invalid_session", `compaction "${e.id}" carries a structurally invalid activeTools list (array of at most ${ACTIVE_TOOLS_MAX_ENTRIES} names)`);
+                }
+                for (const n of activeToolsCarrier) {
+                    if (typeof n !== "string" || n.length === 0 || n.length > ACTIVE_TOOL_NAME_MAX_CHARS) {
+                        throw new SessionError("invalid_session", `compaction "${e.id}" carries an activeTools entry that is not a non-empty string of at most ${ACTIVE_TOOL_NAME_MAX_CHARS} chars`);
+                    }
+                }
+            }
         }
         this.parentOf.set(e.id, e.parentId);
         this.seen.add(e.id);

package/dist/engine/session/session.js

@@ -1,7 +1,7 @@
 import { asAgentMessage, createCompactionSummaryMessage, createCustomMessage, } from "../harness/messages.js";
-import { SessionError, normalizeAnnouncedListing, normalizeCompactionStateCarrier, normalizeWorkspaceState } from "../harness/types.js";
+import { SessionError, isValidModelChange, normalizeAnnouncedListing, normalizeCompactionStateCarrier, normalizeWorkspaceState } from "../harness/types.js";
 import { normalizePromptEpoch } from "../../prompt-assembly/epoch.js";
-import { budgetInvokedSkillsRetention, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../compaction/utils.js";
+import { budgetInvokedSkillsRetention, readElidedMessages, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../compaction/utils.js";
 const RETENTION_CLAMP_DEFAULT_CHARS_PER_TOKEN = 4;
 const RETENTION_CLAMP_WINDOW_FRACTION = 0.5;
 export function buildSessionContext(pathEntries, opts) {
@@ -25,7 +25,9 @@ export function buildSessionContext(pathEntries, opts) {
             model = { provider: entry.provider, modelId: entry.modelId };
         }
         else if (entry.type === "message" && entry.message.role === "assistant") {
-            model = { provider: entry.message.provider, modelId: entry.message.model };
+            if (isValidModelChange({ provider: entry.message.provider, modelId: entry.message.model })) {
+                model = { provider: entry.message.provider, modelId: entry.message.model };
+            }
         }
         else if (entry.type === "compaction") {
             compaction = entry;
@@ -64,7 +66,7 @@ export function buildSessionContext(pathEntries, opts) {
             retainedSkills = budgetInvokedSkillsRetention(retainedSkills, budgetChars);
         }
         const retainedSkillsBlock = renderInvokedSkillsRetention(retainedSkills);
-        messages.push(asAgentMessage(createCompactionSummaryMessage(compaction.summary + retainedSkillsBlock, compaction.tokensBefore, compaction.timestamp)));
+        messages.push(asAgentMessage(createCompactionSummaryMessage(compaction.summary + retainedSkillsBlock, compaction.tokensBefore, compaction.timestamp, readElidedMessages(compaction.details))));
         const compactionIdx = pathEntries.findIndex((e) => e.type === "compaction" && e.id === compaction.id);
         let foundFirstKept = false;
         for (let i = 0; i < compactionIdx; i++) {
@@ -242,7 +244,7 @@ export class StoredSession {
         const carried = await (async () => {
             try {
                 const ctx = buildSessionContext(await this.getBranch());
-                return { thinkingLevel: ctx.thinkingLevel, model: ctx.model };
+                return { thinkingLevel: ctx.thinkingLevel, ...(ctx.model !== null ? { model: ctx.model } : {}) };
             }
             catch {
                 return undefined;

package/dist/index.d.ts

@@ -151,6 +151,13 @@ export { PRESENT_PLAN_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME } from "./core/presen
 export { type WorkflowRunStore, type WorkflowRunSummary, summarizeWorkflowRun, isTerminalWorkflowStatus, WorkflowRunStoreError, InMemoryWorkflowRunStore, } from "./core/workflow-run-store.js";
 export { FileWorkflowRunStore, type FileWorkflowRunStoreOptions } from "./stores/file/workflow-run-store.js";
 export { workflowRunStoreContract } from "./core/workflow-run-store-contract.js";
+export { CONTRACT_KIT_ENGINE_VERSION } from "./core/store-contracts/contract-kit-version.js";
+export { type ContractAssertionRunner } from "./core/store-contracts/contract-harness.js";
+export { checkpointStoreContract } from "./core/store-contracts/checkpoint-store-contract.js";
+export { sessionRepoContract } from "./core/store-contracts/session-repo-contract.js";
+export { toolResultStoreContract } from "./core/store-contracts/tool-result-store-contract.js";
+export { fileSnapshotStoreContract } from "./core/store-contracts/file-snapshot-store-contract.js";
+export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, } from "./core/store-contracts/mailbox-store-contract.js";
 export { type BackgroundAgentStore, type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentUsage, canAccessAgentRecord, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, } from "./core/background-agent-store.js";
 export { FileBackgroundAgentStore, type FileBackgroundAgentStoreOptions } from "./stores/file/background-agent-store.js";
 export { type WorkflowJournalStore, type WorkflowJournalEntry, InMemoryWorkflowJournalStore, callKeyOrdinal, JOURNAL_OVERSIZE_ERROR_CODE, } from "./core/workflow-journal-store.js";

package/dist/index.js

@@ -138,6 +138,13 @@ export { PRESENT_PLAN_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME } from "./core/presen
 export { summarizeWorkflowRun, isTerminalWorkflowStatus, WorkflowRunStoreError, InMemoryWorkflowRunStore, } from "./core/workflow-run-store.js";
 export { FileWorkflowRunStore } from "./stores/file/workflow-run-store.js";
 export { workflowRunStoreContract } from "./core/workflow-run-store-contract.js";
+export { CONTRACT_KIT_ENGINE_VERSION } from "./core/store-contracts/contract-kit-version.js";
+export {} from "./core/store-contracts/contract-harness.js";
+export { checkpointStoreContract } from "./core/store-contracts/checkpoint-store-contract.js";
+export { sessionRepoContract } from "./core/store-contracts/session-repo-contract.js";
+export { toolResultStoreContract } from "./core/store-contracts/tool-result-store-contract.js";
+export { fileSnapshotStoreContract } from "./core/store-contracts/file-snapshot-store-contract.js";
+export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, } from "./core/store-contracts/mailbox-store-contract.js";
 export { canAccessAgentRecord, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, } from "./core/background-agent-store.js";
 export { FileBackgroundAgentStore } from "./stores/file/background-agent-store.js";
 export { InMemoryWorkflowJournalStore, callKeyOrdinal, JOURNAL_OVERSIZE_ERROR_CODE, } from "./core/workflow-journal-store.js";

package/dist/internal/harness.d.ts

@@ -2,7 +2,7 @@ export * from "./harness-types.js";
 export { AgentHarness } from "../engine/harness/agent-harness.js";
 export { CompactionError, ExecutionError, FileError, ok, err } from "../engine/harness/types.js";
 export { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, prepareCompaction, shouldCompact, summaryOutputBudgetTokens, } from "../engine/compaction/compaction.js";
-export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
+export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
 export { NodeExecutionEnv } from "../engine/execution-env/node-execution-env.js";
 export { StoredSession, buildSessionContext } from "../engine/session/session.js";
 export { getEntriesToFork } from "../engine/session/repo-utils.js";

package/dist/internal/harness.js

@@ -2,7 +2,7 @@ export * from "./harness-types.js";
 export { AgentHarness } from "../engine/harness/agent-harness.js";
 export { CompactionError, ExecutionError, FileError, ok, err } from "../engine/harness/types.js";
 export { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, prepareCompaction, shouldCompact, summaryOutputBudgetTokens, } from "../engine/compaction/compaction.js";
-export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
+export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
 export { NodeExecutionEnv } from "../engine/execution-env/node-execution-env.js";
 export { StoredSession, buildSessionContext } from "../engine/session/session.js";
 export { getEntriesToFork } from "../engine/session/repo-utils.js";

package/dist/orchestration/workflow-types.d.ts

@@ -43,6 +43,7 @@ export interface WorkflowAgentRun {
     attempts?: number;
     lastAttemptReason?: string;
     sessionId?: string;
+    worktreeDir?: string;
 }
 export interface WorkflowRunStats {
     tokens: number;

package/dist/orchestration/workflow.js

@@ -641,6 +641,14 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         };
         return { tail, onActivity };
     };
+    const createWorkspaceObserver = (rec) => (workspace) => {
+        if (finalized)
+            return;
+        if (!workspace.isolated || rec.worktreeDir === workspace.cwd)
+            return;
+        rec.worktreeDir = workspace.cwd;
+        void persist("update");
+    };
     let currentPhase;
     let openMarkerPhase;
     let currentGroup;
@@ -815,7 +823,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         opts.onForwardEvent(e.type === "task_progress" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
                     }
                     : undefined;
-                const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd } : {}), ...spawnAttribution, ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), agentName: label };
+                const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd } : {}), ...spawnAttribution, ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), agentName: label, onWorkspaceResolved: createWorkspaceObserver(rec) };
                 let attempts = 0;
                 let throttleRetried = false;
                 let lastAttemptReason;
@@ -1160,6 +1168,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     ...(enrichedForwardS !== undefined ? { onForwardEvent: enrichedForwardS } : {}),
                     agentName: label,
                     onActivity,
+                    onWorkspaceResolved: createWorkspaceObserver(rec),
                     ...(bceSink !== undefined
                         ? {
                             onForwardEvent: (e) => {