@sema-agent/core 2.4.0 → 2.6.0

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

@@ -3,6 +3,7 @@ export { SESSION_LOG_DIGEST_SCHEME, sessionEntryDigest, sessionLogDigest, sessio
 export type { ResumeTaskConfig } from "./core/runner/runtask.js";
 export { defineTool } from "./core/tools.js";
 export { SKILL_TOOL_NAME } from "./core/runner/synthetic-tools.js";
+export { createSkillsFromDirectory, type SkillsDirectoryOptions, type SkillsDirectoryWarning, type SkillsDirectoryWarningCode, } from "./core/skills-directory.js";
 export { REPORT_FINDINGS_TOOL_NAME, type ReportedFinding } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
 export type { WorkerErrorClass } from "./core/tool-errors.js";
@@ -151,6 +152,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

@@ -2,6 +2,7 @@ export { Runner, runTask, DEFAULT_MAX_TURNS } from "./core/runner/runtask.js";
 export { SESSION_LOG_DIGEST_SCHEME, sessionEntryDigest, sessionLogDigest, sessionLogDigestsComparable, } from "./engine/session/log-digest.js";
 export { defineTool } from "./core/tools.js";
 export { SKILL_TOOL_NAME } from "./core/runner/synthetic-tools.js";
+export { createSkillsFromDirectory, } from "./core/skills-directory.js";
 export { REPORT_FINDINGS_TOOL_NAME } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
 export { createWebFetchTool, webFetchToolSpec, htmlToText, createWebSearchTool, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
@@ -138,6 +139,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) => {

package/dist/tools/fs/fs-bash.js

@@ -173,7 +173,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
             const rawRemainSec = Math.floor((deadline - Date.now()) / 1000);
             const maxSec = Math.max(1, rawRemainSec);
             if (maxSec < timeout) {
-                execClamp.onClamp?.(timeout, maxSec);
+                execClamp.onClamp?.(requestedSec, maxSec);
                 timeout = maxSec;
                 clampedByDeadline = true;
                 deadlineExhausted = rawRemainSec < 1;
@@ -310,6 +310,9 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
             cwdOutsideNote = `NOTE: working directory is now outside the task root(s) (${cwdRef.current}); relative paths in the structured file tools (Read/Edit/Write/Grep/Glob) will resolve there and may be refused. Pass absolute in-root paths, or \`cd\` back inside.`;
         }
     }
+    const survivedCapNote = cappedByMaxTimeout
+        ? `NOTE: requested timeout ${requestedSec}s was capped to the ${caps.maxSec}s engine ceiling (requests above the max are reduced to it) — no effect on this run (the command completed in time); use run_in_background for work that needs longer.`
+        : "";
     const clippedStdout = clipShellOutput(stdout);
     const clippedStderr = clipShellOutput(stderr);
     const stdoutImage = dataUriImageFromStdout(stdout);
@@ -319,9 +322,9 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
         return {
             content: [
                 { type: "image", data: stdoutImage.data, mimeType: stdoutImage.mime },
-                { type: "text", text: `exit code: ${exitCode}\n[Image data detected in stdout and shown above]${stderr.trim() !== "" ? `\n--- stderr ---\n${clippedStderr}` : ""}${imgOverflowNote}${cwdOutsideNote ? `\n${cwdOutsideNote}` : ""}` },
+                { type: "text", text: `exit code: ${exitCode}\n[Image data detected in stdout and shown above]${stderr.trim() !== "" ? `\n--- stderr ---\n${clippedStderr}` : ""}${imgOverflowNote}${cwdOutsideNote ? `\n${cwdOutsideNote}` : ""}${survivedCapNote ? `\n${survivedCapNote}` : ""}` },
             ],
-            details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}) },
+            details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}), ...(cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec, cappedToMaxTimeoutSec: caps.maxSec } : {}) },
         };
     }
     const cleanOverflowFile = stdout.length > bashMaxOutputChars() || stderr.length > bashMaxOutputChars() ? await writeShellOverflowFile(env, stdout, stderr) : undefined;
@@ -334,6 +337,8 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
         parts.push(overflowNote.trim());
     if (cwdOutsideNote)
         parts.push(cwdOutsideNote);
+    if (survivedCapNote)
+        parts.push(survivedCapNote);
     return {
         content: parts.join("\n"),
         details: {
@@ -343,6 +348,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
             exitCode,
             ...(exit1Note ? { returnCodeInterpretation: exit1Note } : {}),
             ...(cleanOverflowFile !== undefined ? { output_file: cleanOverflowFile } : {}),
+            ...(cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec, cappedToMaxTimeoutSec: caps.maxSec } : {}),
         },
     };
 }
@@ -379,7 +385,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         description: bashDescription(coAuthor, timeoutCaps, bgNotifies, bgRetained),
         parameters: Type.Object({
             command: Type.String({ description: "The command to execute" }),
-            timeout: Type.Optional(Type.Number({ description: `Optional timeout in milliseconds (max ${timeoutCaps.maxMs})` })),
+            timeout: Type.Optional(Type.Number({ description: `Optional timeout in milliseconds (max ${timeoutCaps.maxMs}; requests above the max are capped to it)` })),
             description: Type.Optional(Type.String({
                 description: 'Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does.\n' +
                     "\n" +
@@ -632,7 +638,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, tim
             "allowlisted commands run. Still subject to the deployment's approval policy.",
         parameters: Type.Object({
             command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
-            timeout: Type.Optional(Type.Number({ description: `Timeout in milliseconds (default ${timeoutCaps.defaultMs}, max ${timeoutCaps.maxMs}).` })),
+            timeout: Type.Optional(Type.Number({ description: `Timeout in milliseconds (default ${timeoutCaps.defaultMs}, max ${timeoutCaps.maxMs}; requests above the max are capped to it).` })),
         }),
         effect: "read",
         execute: async (args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",