@sema-agent/core 2.3.0 → 2.5.0

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/lsp/node-lsp-manager.d.ts

@@ -28,6 +28,7 @@ export declare class NodeLspManager implements LspServerManager {
     private sweepTimer?;
     private readonly cache;
     private readonly opening;
+    private readonly failed;
     private disposed;
     constructor(opts?: NodeLspManagerOptions);
     private sweepIdle;
@@ -35,6 +36,7 @@ export declare class NodeLspManager implements LspServerManager {
     private open;
     private evictOverCap;
     evict(root: string): Promise<void>;
+    clearFailed(root?: string): void;
     private openSession;
     private serverCmd;
     dispose(): Promise<void>;

package/dist/engine/lsp/node-lsp-manager.js

@@ -59,6 +59,7 @@ export class NodeLspManager {
     sweepTimer;
     cache = new Map();
     opening = new Map();
+    failed = new Map();
     disposed = false;
     constructor(opts = {}) {
         this.servers = { ...DEFAULT_LSP_SERVERS, ...opts.servers };
@@ -96,6 +97,11 @@ export class NodeLspManager {
             cached.lastUsed = Date.now();
             return cached.session;
         }
+        const neg = this.failed.get(key);
+        if (neg !== undefined) {
+            neg.attempts += 1;
+            return undefined;
+        }
         if (cached) {
             this.cache.delete(key);
             const carry = cached.session.openedFiles();
@@ -163,6 +169,14 @@ export class NodeLspManager {
         }
         await Promise.all(closing);
     }
+    clearFailed(root) {
+        for (const [key, e] of [...this.failed]) {
+            if (root !== undefined && e.root !== root)
+                continue;
+            this.failed.delete(key);
+            this.log("lsp_negative_cache_cleared", { key, attempts: e.attempts });
+        }
+    }
     async openSession(language, root, signal, _env) {
         const cmd = this.serverCmd(language);
         if (!cmd)
@@ -171,6 +185,8 @@ export class NodeLspManager {
         const [command, ...args] = tokens.length > 0 ? tokens : [""];
         const child = await this.spawnFn(command, args, root, signal).catch(() => undefined);
         if (!child) {
+            if (signal?.aborted !== true)
+                this.failed.set(`${language} ${root}`, { root, attempts: 1 });
             this.log("lsp_spawn_degraded", { language, root, command });
             return undefined;
         }

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

@@ -66,6 +66,7 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type ResourceLedger, type ResourceLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
@@ -150,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

@@ -57,6 +57,7 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
@@ -137,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/builtin-workflows.d.ts

@@ -1,6 +1,6 @@
 import type { NamedWorkflowListing } from "./workflow-script-store.js";
 export declare const TEAM_DISCUSSION_WORKFLOW_NAME = "team-discussion";
-export declare const TEAM_DISCUSSION_SCRIPT = "export const meta = {\n  name: \"team-discussion\",\n  description: \"Round-based team discussion: configurable members debate a topic across rounds (each member sees the transcript so far), then a finalizer synthesizes a structured verdict.\",\n  whenToUse: \"Use for a genuinely contested question that benefits from several perspectives arguing across rounds - design trade-offs, plan or risk reviews, adversarial critique of a proposal. Do NOT use it for a single factual question, a task with one obvious answer, or a budget-sensitive run: every round costs one agent call per member, so a discussion is never cheaper than asking once. args (all optional): { topic, members?: [{ role, prompt?, model? }], rounds?, finalizer?: { prompt?, model? } }.\",\n  phases: [\n    { title: \"Discussion\" },\n    { title: \"Synthesis\" },\n  ],\n};\n// Zero-config runnable (design/140 \u00A76 1c): every arg has an opinionated fallback.\nconst raw = args;\nconst a = raw !== null && typeof raw === \"object\" && !Array.isArray(raw) ? raw : {};\nconst topic =\n  typeof a.topic === \"string\" && a.topic.trim() !== \"\"\n    ? a.topic\n    : typeof raw === \"string\" && raw.trim() !== \"\"\n      ? raw // ergonomic form: a bare string args IS the topic\n      : \"No topic was provided. Discuss: what information should a caller supply to make a team discussion like this productive, and when should they NOT convene one?\";\nconst defaultMembers = [\n  { role: \"advocate\", prompt: \"Make the strongest constructive case. Propose concrete options and argue their benefits with specifics.\" },\n  { role: \"skeptic\", prompt: \"Stress-test every claim made so far. Surface risks, hidden costs, failure modes, and cheaper alternatives.\" },\n];\nconst rawMembers = Array.isArray(a.members) && a.members.length > 0 ? a.members : defaultMembers;\nconst members = rawMembers.slice(0, 6).map((m, i) => {\n  const mm = m !== null && typeof m === \"object\" ? m : {};\n  const member = {\n    role: typeof mm.role === \"string\" && mm.role.trim() !== \"\" ? mm.role : \"member-\" + (i + 1),\n    prompt: typeof mm.prompt === \"string\" && mm.prompt.trim() !== \"\" ? mm.prompt : \"Contribute your own distinct perspective: be concrete, give reasons, and engage with what others said.\",\n  };\n  if (typeof mm.model === \"string\" && mm.model.trim() !== \"\") member.model = mm.model;\n  // Slot-tools carrier (design/140 \u2461-3 + F4): a member may BE a registered agent type ({agent:\"reviewer\"}) \u2014\n  // persona/tools/model then come from the deployment's AgentDefinition (role library), args stay thin.\n  if (typeof mm.agent === \"string\" && mm.agent.trim() !== \"\") member.agent = mm.agent;\n  return member;\n});\n// Deterministic budget truncation (design/140 \u00A71 \u9884\u7B97 row): a HARD rounds ceiling + member cap \u2014 never an\n// evaluator agent. The engine's budget/maxAgents hard stops remain the backstop.\nconst requestedRounds = Math.floor(Number(a.rounds));\nconst rounds = Math.min(Number.isFinite(requestedRounds) && requestedRounds >= 1 ? requestedRounds : 2, 5);\nconst fin = a.finalizer !== null && typeof a.finalizer === \"object\" && !Array.isArray(a.finalizer) ? a.finalizer : {};\nconst finalizerPrompt = typeof fin.prompt === \"string\" && fin.prompt.trim() !== \"\"\n  ? fin.prompt\n  : \"You are the synthesis lead. Read the full discussion transcript and produce the final verdict: the decision/answer, the key supporting points, and the strongest unresolved dissent (if any). Do not introduce new arguments of your own.\";\nconst clip = (s) => { const t = String(s); return t.length > 4000 ? t.slice(0, 4000) + \" ...[truncated]\" : t; };\nconst isBudgetStop = (e) => e !== null && typeof e === \"object\" && e.code === \"workflow.budget_exceeded\";\n\nphase(\"Discussion\");\nconst transcript = [];\nlet truncated = null;\nfor (let r = 1; r <= rounds && truncated === null; r++) {\n  // Deterministic early stop on an exhausted budget (a live read of the engine budget; the engine's\n  // hard WorkflowBudgetExceededError remains the backstop if a member call itself crosses the line).\n  if (budget.total !== null && budget.remaining() <= 0) { truncated = \"budget exhausted before round \" + r; break; }\n  for (const m of members) {\n    const history = transcript.length === 0 ? \"(none yet - you open the discussion)\" : transcript.join(\"\\n\\n\");\n    const spec = {\n      objective:\n        \"Team discussion on: \" + topic + \"\\n\\n\" +\n        'You are \"' + m.role + '\" in round ' + r + \" of \" + rounds + \".\\n\" +\n        \"Your brief: \" + m.prompt + \"\\n\\n\" +\n        \"Transcript so far:\\n\" + history + \"\\n\\n\" +\n        \"Respond to the strongest points others made (do not repeat yourself), then advance your own position. Be concise: a few tight paragraphs at most.\",\n    };\n    if (m.model !== undefined) spec.modelName = m.model;\n    let res;\n    try {\n      res = await agent(spec, m.agent !== undefined ? { label: m.role + \"-r\" + r, phase: \"Discussion\", agentType: m.agent } : { label: m.role + \"-r\" + r, phase: \"Discussion\" });\n    } catch (e) {\n      // The engine's budget hard stop: keep what the discussion already produced instead of failing the run.\n      if (isBudgetStop(e)) { truncated = \"budget exhausted at \" + m.role + \", round \" + r; break; }\n      throw e;\n    }\n    const text = res && res.status === \"completed\" ? clip(res.result) : \"(no contribution - agent ended \" + (res ? res.status : \"unknown\") + \")\";\n    transcript.push(m.role + \" (round \" + r + \"): \" + text);\n  }\n}\n\nphase(\"Synthesis\");\nconst finalSpec = {\n  objective:\n    finalizerPrompt + \"\\n\\nTopic: \" + topic + \"\\n\\nFull transcript:\\n\" +\n    (transcript.length === 0 ? \"(the discussion produced no contributions)\" : transcript.join(\"\\n\\n\")) +\n    (truncated ? \"\\n\\nNote: the discussion was cut short (\" + truncated + \").\" : \"\"),\n};\nif (typeof fin.model === \"string\" && fin.model.trim() !== \"\") finalSpec.modelName = fin.model;\nlet verdict = null;\ntry {\n  verdict = await agent(finalSpec, {\n    label: \"finalizer\",\n    phase: \"Synthesis\",\n    schema: {\n      type: \"object\",\n      properties: {\n        decision: { type: \"string\", description: \"The final answer/decision, one paragraph.\" },\n        keyPoints: { type: \"array\", items: { type: \"string\" }, description: \"The strongest supporting points from the discussion.\" },\n        dissent: { type: \"string\", description: \"The strongest unresolved counter-position, if any.\" },\n      },\n      required: [\"decision\", \"keyPoints\"],\n    },\n  });\n} catch (e) {\n  // Budget died before synthesis: return the transcript honestly rather than failing the whole run.\n  if (!isBudgetStop(e)) throw e;\n  truncated = truncated === null ? \"budget exhausted before synthesis\" : truncated;\n}\n\nreturn {\n  topic,\n  rounds,\n  members: members.map((m) => m.role),\n  ...(truncated ? { truncated } : {}),\n  transcript,\n  verdict: verdict && verdict.structuredOutput !== undefined ? verdict.structuredOutput : (verdict ? verdict.result : null),\n};\n";
+export declare const TEAM_DISCUSSION_SCRIPT = "export const meta = {\n  name: \"team-discussion\",\n  description: \"Round-based team discussion: configurable members debate a topic across rounds (each member sees the transcript so far), then a finalizer synthesizes a structured verdict.\",\n  whenToUse: \"Use for a genuinely contested question that benefits from several perspectives arguing across rounds - design trade-offs, plan or risk reviews, adversarial critique of a proposal. Do NOT use it for a single factual question, a task with one obvious answer, or a budget-sensitive run: every round costs one agent call per member, so a discussion is never cheaper than asking once. args (all optional): { topic, members?: [{ role, prompt?, model? }], rounds?, finalizer?: { prompt?, model? } }. Hard ceilings: members is capped at 6 and rounds is capped at 5 regardless of what you pass; the run reports it via log() and a capped field on the result when a request exceeds either.\",\n  phases: [\n    { title: \"Discussion\" },\n    { title: \"Synthesis\" },\n  ],\n};\n// Zero-config runnable (design/140 \u00A76 1c): every arg has an opinionated fallback.\nconst raw = args;\nconst a = raw !== null && typeof raw === \"object\" && !Array.isArray(raw) ? raw : {};\nconst topic =\n  typeof a.topic === \"string\" && a.topic.trim() !== \"\"\n    ? a.topic\n    : typeof raw === \"string\" && raw.trim() !== \"\"\n      ? raw // ergonomic form: a bare string args IS the topic\n      : \"No topic was provided. Discuss: what information should a caller supply to make a team discussion like this productive, and when should they NOT convene one?\";\nconst defaultMembers = [\n  { role: \"advocate\", prompt: \"Make the strongest constructive case. Propose concrete options and argue their benefits with specifics.\" },\n  { role: \"skeptic\", prompt: \"Stress-test every claim made so far. Surface risks, hidden costs, failure modes, and cheaper alternatives.\" },\n];\nconst rawMembers = Array.isArray(a.members) && a.members.length > 0 ? a.members : defaultMembers;\nconst members = rawMembers.slice(0, 6).map((m, i) => {\n  const mm = m !== null && typeof m === \"object\" ? m : {};\n  const member = {\n    role: typeof mm.role === \"string\" && mm.role.trim() !== \"\" ? mm.role : \"member-\" + (i + 1),\n    prompt: typeof mm.prompt === \"string\" && mm.prompt.trim() !== \"\" ? mm.prompt : \"Contribute your own distinct perspective: be concrete, give reasons, and engage with what others said.\",\n  };\n  if (typeof mm.model === \"string\" && mm.model.trim() !== \"\") member.model = mm.model;\n  // Slot-tools carrier (design/140 \u2461-3 + F4): a member may BE a registered agent type ({agent:\"reviewer\"}) \u2014\n  // persona/tools/model then come from the deployment's AgentDefinition (role library), args stay thin.\n  if (typeof mm.agent === \"string\" && mm.agent.trim() !== \"\") member.agent = mm.agent;\n  return member;\n});\n// Deterministic budget truncation (design/140 \u00A71 \u9884\u7B97 row): a HARD rounds ceiling + member cap \u2014 never an\n// evaluator agent. The engine's budget/maxAgents hard stops remain the backstop.\nconst requestedRounds = Math.floor(Number(a.rounds));\nconst normalizedRounds = Number.isFinite(requestedRounds) && requestedRounds >= 1 ? requestedRounds : 2;\nconst rounds = Math.min(normalizedRounds, 5);\n// RB-380 disclosure: the member/round slices above are silent by construction (Array.prototype.slice /\n// Math.min just drop the excess) \u2014 record + surface it instead of a caller finding out only by counting\n// transcript entries. Fires only when a request actually exceeded a ceiling (never on the common path).\nconst capNotes = [];\nif (rawMembers.length > 6) capNotes.push(\"requested \" + rawMembers.length + \" members, capped at 6\");\nif (normalizedRounds > 5) capNotes.push(\"requested \" + normalizedRounds + \" rounds, capped at 5\");\nfor (const note of capNotes) log(\"team-discussion: \" + note);\nconst fin = a.finalizer !== null && typeof a.finalizer === \"object\" && !Array.isArray(a.finalizer) ? a.finalizer : {};\nconst finalizerPrompt = typeof fin.prompt === \"string\" && fin.prompt.trim() !== \"\"\n  ? fin.prompt\n  : \"You are the synthesis lead. Read the full discussion transcript and produce the final verdict: the decision/answer, the key supporting points, and the strongest unresolved dissent (if any). Do not introduce new arguments of your own.\";\nconst clip = (s) => { const t = String(s); return t.length > 4000 ? t.slice(0, 4000) + \" ...[truncated]\" : t; };\nconst isBudgetStop = (e) => e !== null && typeof e === \"object\" && e.code === \"workflow.budget_exceeded\";\n\nphase(\"Discussion\");\nconst transcript = [];\nlet truncated = null;\nfor (let r = 1; r <= rounds && truncated === null; r++) {\n  // Deterministic early stop on an exhausted budget (a live read of the engine budget; the engine's\n  // hard WorkflowBudgetExceededError remains the backstop if a member call itself crosses the line).\n  if (budget.total !== null && budget.remaining() <= 0) { truncated = \"budget exhausted before round \" + r; break; }\n  for (const m of members) {\n    const history = transcript.length === 0 ? \"(none yet - you open the discussion)\" : transcript.join(\"\\n\\n\");\n    const spec = {\n      objective:\n        \"Team discussion on: \" + topic + \"\\n\\n\" +\n        'You are \"' + m.role + '\" in round ' + r + \" of \" + rounds + \".\\n\" +\n        \"Your brief: \" + m.prompt + \"\\n\\n\" +\n        \"Transcript so far:\\n\" + history + \"\\n\\n\" +\n        \"Respond to the strongest points others made (do not repeat yourself), then advance your own position. Be concise: a few tight paragraphs at most.\",\n    };\n    if (m.model !== undefined) spec.modelName = m.model;\n    let res;\n    try {\n      res = await agent(spec, m.agent !== undefined ? { label: m.role + \"-r\" + r, phase: \"Discussion\", agentType: m.agent } : { label: m.role + \"-r\" + r, phase: \"Discussion\" });\n    } catch (e) {\n      // The engine's budget hard stop: keep what the discussion already produced instead of failing the run.\n      if (isBudgetStop(e)) { truncated = \"budget exhausted at \" + m.role + \", round \" + r; break; }\n      throw e;\n    }\n    const text = res && res.status === \"completed\" ? clip(res.result) : \"(no contribution - agent ended \" + (res ? res.status : \"unknown\") + \")\";\n    transcript.push(m.role + \" (round \" + r + \"): \" + text);\n  }\n}\n\nphase(\"Synthesis\");\nconst finalSpec = {\n  objective:\n    finalizerPrompt + \"\\n\\nTopic: \" + topic + \"\\n\\nFull transcript:\\n\" +\n    (transcript.length === 0 ? \"(the discussion produced no contributions)\" : transcript.join(\"\\n\\n\")) +\n    (truncated ? \"\\n\\nNote: the discussion was cut short (\" + truncated + \").\" : \"\"),\n};\nif (typeof fin.model === \"string\" && fin.model.trim() !== \"\") finalSpec.modelName = fin.model;\nlet verdict = null;\ntry {\n  verdict = await agent(finalSpec, {\n    label: \"finalizer\",\n    phase: \"Synthesis\",\n    schema: {\n      type: \"object\",\n      properties: {\n        decision: { type: \"string\", description: \"The final answer/decision, one paragraph.\" },\n        keyPoints: { type: \"array\", items: { type: \"string\" }, description: \"The strongest supporting points from the discussion.\" },\n        dissent: { type: \"string\", description: \"The strongest unresolved counter-position, if any.\" },\n      },\n      required: [\"decision\", \"keyPoints\"],\n    },\n  });\n} catch (e) {\n  // Budget died before synthesis: return the transcript honestly rather than failing the whole run.\n  if (!isBudgetStop(e)) throw e;\n  truncated = truncated === null ? \"budget exhausted before synthesis\" : truncated;\n}\n\nreturn {\n  topic,\n  rounds,\n  members: members.map((m) => m.role),\n  ...(capNotes.length > 0 ? { capped: capNotes } : {}),\n  ...(truncated ? { truncated } : {}),\n  transcript,\n  verdict: verdict && verdict.structuredOutput !== undefined ? verdict.structuredOutput : (verdict ? verdict.result : null),\n};\n";
 export interface BuiltinWorkflowDefinition {
     name: string;
     script: string;

package/dist/orchestration/builtin-workflows.js

@@ -3,7 +3,7 @@ export const TEAM_DISCUSSION_WORKFLOW_NAME = "team-discussion";
 export const TEAM_DISCUSSION_SCRIPT = `export const meta = {
   name: "team-discussion",
   description: "Round-based team discussion: configurable members debate a topic across rounds (each member sees the transcript so far), then a finalizer synthesizes a structured verdict.",
-  whenToUse: "Use for a genuinely contested question that benefits from several perspectives arguing across rounds - design trade-offs, plan or risk reviews, adversarial critique of a proposal. Do NOT use it for a single factual question, a task with one obvious answer, or a budget-sensitive run: every round costs one agent call per member, so a discussion is never cheaper than asking once. args (all optional): { topic, members?: [{ role, prompt?, model? }], rounds?, finalizer?: { prompt?, model? } }.",
+  whenToUse: "Use for a genuinely contested question that benefits from several perspectives arguing across rounds - design trade-offs, plan or risk reviews, adversarial critique of a proposal. Do NOT use it for a single factual question, a task with one obvious answer, or a budget-sensitive run: every round costs one agent call per member, so a discussion is never cheaper than asking once. args (all optional): { topic, members?: [{ role, prompt?, model? }], rounds?, finalizer?: { prompt?, model? } }. Hard ceilings: members is capped at 6 and rounds is capped at 5 regardless of what you pass; the run reports it via log() and a capped field on the result when a request exceeds either.",
   phases: [
     { title: "Discussion" },
     { title: "Synthesis" },
@@ -38,7 +38,15 @@ const members = rawMembers.slice(0, 6).map((m, i) => {
 // Deterministic budget truncation (design/140 §1 预算 row): a HARD rounds ceiling + member cap — never an
 // evaluator agent. The engine's budget/maxAgents hard stops remain the backstop.
 const requestedRounds = Math.floor(Number(a.rounds));
-const rounds = Math.min(Number.isFinite(requestedRounds) && requestedRounds >= 1 ? requestedRounds : 2, 5);
+const normalizedRounds = Number.isFinite(requestedRounds) && requestedRounds >= 1 ? requestedRounds : 2;
+const rounds = Math.min(normalizedRounds, 5);
+// RB-380 disclosure: the member/round slices above are silent by construction (Array.prototype.slice /
+// Math.min just drop the excess) — record + surface it instead of a caller finding out only by counting
+// transcript entries. Fires only when a request actually exceeded a ceiling (never on the common path).
+const capNotes = [];
+if (rawMembers.length > 6) capNotes.push("requested " + rawMembers.length + " members, capped at 6");
+if (normalizedRounds > 5) capNotes.push("requested " + normalizedRounds + " rounds, capped at 5");
+for (const note of capNotes) log("team-discussion: " + note);
 const fin = a.finalizer !== null && typeof a.finalizer === "object" && !Array.isArray(a.finalizer) ? a.finalizer : {};
 const finalizerPrompt = typeof fin.prompt === "string" && fin.prompt.trim() !== ""
   ? fin.prompt
@@ -110,6 +118,7 @@ return {
   topic,
   rounds,
   members: members.map((m) => m.role),
+  ...(capNotes.length > 0 ? { capped: capNotes } : {}),
   ...(truncated ? { truncated } : {}),
   transcript,
   verdict: verdict && verdict.structuredOutput !== undefined ? verdict.structuredOutput : (verdict ? verdict.result : null),

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

@@ -25,5 +25,10 @@ export interface WorkflowChildCaps {
     childMaxTokens?: number;
     childMaxTurns?: number;
 }
+export interface ResourceClampNote {
+    field: "maxCostUsd" | "maxTokens" | "timeoutSec" | "maxTurns";
+    requested: number | undefined;
+    applied: number;
+}
 export declare function resolveModelName(name: string, allowlist: string[] | undefined, models: Record<string, Model> | undefined): Model;
-export declare function buildGovernedChildSpec(scriptSpec: unknown, baseline: WorkflowGovernanceBaseline, models: Record<string, Model> | undefined, caps?: WorkflowChildCaps): TaskSpec;
+export declare function buildGovernedChildSpec(scriptSpec: unknown, baseline: WorkflowGovernanceBaseline, models: Record<string, Model> | undefined, caps?: WorkflowChildCaps, onResourceClamp?: (notes: ResourceClampNote[]) => void): TaskSpec;

package/dist/orchestration/workflow-governance.js

@@ -99,26 +99,46 @@ function pickWhitelist(scriptSpec) {
     return { safe, modelName };
 }
 function clampResourceLimits(safe, base, caps) {
+    const notes = [];
+    const requestedCost = safe.maxCostUsd;
     const cost = minDefined(safe.maxCostUsd, base.maxCostUsd, caps?.childMaxCostUsd);
-    if (cost !== undefined)
+    if (cost !== undefined) {
+        if (cost !== requestedCost)
+            notes.push({ field: "maxCostUsd", requested: requestedCost, applied: cost });
         safe.maxCostUsd = cost;
+    }
+    const requestedTokens = safe.maxTokens;
     const tokens = minDefined(safe.maxTokens, base.maxTokens, caps?.childMaxTokens);
-    if (tokens !== undefined)
+    if (tokens !== undefined) {
+        if (tokens !== requestedTokens)
+            notes.push({ field: "maxTokens", requested: requestedTokens, applied: tokens });
         safe.maxTokens = tokens;
+    }
+    const requestedTimeoutSec = safe.limits?.timeoutSec;
+    const requestedMaxTurns = safe.limits?.maxTurns;
     const timeoutSec = minDefined(safe.limits?.timeoutSec, base.limits?.timeoutSec, caps?.perAgentTimeoutSec);
     const maxTurns = minDefined(safe.limits?.maxTurns, base.limits?.maxTurns, caps?.childMaxTurns);
+    if (timeoutSec !== undefined && timeoutSec !== requestedTimeoutSec) {
+        notes.push({ field: "timeoutSec", requested: requestedTimeoutSec, applied: timeoutSec });
+    }
+    if (maxTurns !== undefined && maxTurns !== requestedMaxTurns) {
+        notes.push({ field: "maxTurns", requested: requestedMaxTurns, applied: maxTurns });
+    }
     if (timeoutSec !== undefined || maxTurns !== undefined) {
         safe.limits = {
             ...(maxTurns !== undefined ? { maxTurns } : {}),
             ...(timeoutSec !== undefined ? { timeoutSec } : {}),
         };
     }
+    return notes;
 }
-export function buildGovernedChildSpec(scriptSpec, baseline, models, caps) {
+export function buildGovernedChildSpec(scriptSpec, baseline, models, caps, onResourceClamp) {
     const { safe, modelName } = pickWhitelist(scriptSpec);
     if (modelName !== undefined) {
         safe.model = resolveModelName(modelName, baseline.workflowModelAllowlist, models);
     }
-    clampResourceLimits(safe, baseline.base, caps);
+    const clampNotes = clampResourceLimits(safe, baseline.base, caps);
+    if (clampNotes.length > 0 && onResourceClamp)
+        onResourceClamp(clampNotes);
     return tightenTaskSpec(baseline.base, safe);
 }

package/dist/orchestration/workflow-primitives.js

@@ -1,3 +1,4 @@
+import { assertSupportedAgentIsolation } from "./workflow.js";
 import { buildGovernedChildSpec } from "./workflow-governance.js";
 function safeAgentOptions(opts) {
     if (typeof opts !== "object" || opts === null)
@@ -12,10 +13,15 @@ function safeAgentOptions(opts) {
         out.schema = o.schema;
     if (typeof o.agentType === "string")
         out.agentType = o.agentType;
+    assertSupportedAgentIsolation(o.isolation);
     if (o.isolation === "worktree")
         out.isolation = "worktree";
     return out;
 }
+function formatResourceClampNote(notes) {
+    const parts = notes.map((n) => `${n.field}: requested ${n.requested === undefined ? "unset" : n.requested} → applied ${n.applied}`);
+    return `workflow governance tightened this agent's resource limits (${parts.join("; ")})`;
+}
 export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThinking, parentPrincipal) {
     const agent = (spec, opts) => {
         if (typeof spec === "string")
@@ -23,7 +29,7 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThi
         const agentOpts = safeAgentOptions(opts);
         const effectiveBaseline = (b) => agentOpts.isolation === "worktree" && b.worktreeBase !== undefined ? { ...b, base: { ...b.base, ...b.worktreeBase } } : b;
         const childSpec = governance
-            ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps)
+            ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)))
             : { ...spec };
         if (childSpec.thinking === undefined && parentThinking) {
             const inherited = parentThinking();

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.d.ts

@@ -18,6 +18,7 @@ export declare function workflowAgentCallKey(ordinal: number, spec: TaskSpec, op
     schema?: TSchema;
     isolation?: "worktree";
 }): string;
+export declare function assertSupportedAgentIsolation(isolation: unknown): asserts isolation is "worktree" | undefined;
 export interface WorkflowFanOutSlotError {
     index: number;
     kind: string;