@sema-agent/core 2.3.0 → 2.4.0

package/dist/core/tool-result-store.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
+import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
 export function assertSafeToolResultRef(ref) {
     const bad = ref === "" ||
         ref === "." ||
@@ -92,6 +93,13 @@ export function isVolatileOffloadStore(store) {
     return store instanceof InMemoryToolResultStore;
 }
 export const OFFLOAD_TOOL_NAME = "ReadToolResult";
+export function offloadPagebackHint(ref, form, reachableTools) {
+    const activate = reachableTools !== undefined && !reachableTools.has(OFFLOAD_TOOL_NAME)
+        ? `${OFFLOAD_TOOL_NAME} is not active yet — call ${TOOL_SEARCH_NAME} with {"query":"select:${OFFLOAD_TOOL_NAME}"} to activate it, then `
+        : "";
+    const core = `${activate === "" && form === "preview" ? "Call" : `${activate}call`} ${OFFLOAD_TOOL_NAME} with ref`;
+    return form === "preview" ? `${core}="${ref}" (offset, limit) to read more.` : `full text persisted; ${core} "${ref}" to read it back`;
+}
 export const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20_000;
 export function firstPartyOffloadPolicy(toolName) {
@@ -122,7 +130,7 @@ function totalTextChars(content) {
             n += b.text.length;
     return n;
 }
-export function buildPreview(full, ref, sizes) {
+export function buildPreview(full, ref, sizes, reachableTools) {
     const total = full.length;
     const headChars = sizes?.head ?? PREVIEW_HEAD_CHARS;
     const tailChars = sizes?.tail ?? PREVIEW_TAIL_CHARS;
@@ -131,11 +139,11 @@ export function buildPreview(full, ref, sizes) {
     const tail = full.slice(tailStart);
     return (`${PERSISTED_OUTPUT_PREFIX}"${ref}" chars="${total}">\n` +
         `${head}\n` +
-        `…[truncated — ${total} chars total. Call ${OFFLOAD_TOOL_NAME} with ref="${ref}" (offset, limit) to read more.]\n` +
+        `…[truncated — ${total} chars total. ${offloadPagebackHint(ref, "preview", reachableTools)}]\n` +
         `${tail}\n` +
         `</persisted-output>`);
 }
-export function withToolResultOffload(tool, store, thresholdChars, sessionId) {
+export function withToolResultOffload(tool, store, thresholdChars, sessionId, reachableTools) {
     const wrappedExecute = async (toolCallId, params, signal, onUpdate) => {
         const res = await tool.execute(toolCallId, params, signal, onUpdate);
         if (totalTextChars(res.content) <= thresholdChars)
@@ -149,7 +157,7 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId) {
         const ref = buildToolResultRef(sessionId, toolCallId);
         await store.put(ref, full);
         const images = res.content.filter((b) => b.type !== "text");
-        return { ...res, content: [{ type: "text", text: buildPreview(full, ref) }, ...images] };
+        return { ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] };
     };
     return { ...tool, execute: wrappedExecute };
 }

package/dist/core/trace.d.ts

@@ -104,6 +104,13 @@ export type TraceEvent = {
     }>;
     overrideReasons?: Record<string, string>;
     ts: number;
+} | {
+    kind: "config.additional_directory_skipped";
+    version: 1;
+    taskId: string;
+    entry: string;
+    reason: string;
+    ts: number;
 } | {
     kind: "task.end";
     version: 1;

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/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";

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";

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.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;

package/dist/orchestration/workflow.js

@@ -104,6 +104,21 @@ export function workflowAgentCallKey(ordinal, spec, opts) {
     };
     return `${ordinal}:${boundInputHashOf(identity)}`;
 }
+function resolveChildSessionIdAtSpawn(spec) {
+    if (spec.sessionId)
+        return spec.sessionId;
+    if (spec.requireExistingSession === true || spec.resumeAt !== undefined)
+        return undefined;
+    return randomUUID();
+}
+export function assertSupportedAgentIsolation(isolation) {
+    if (isolation !== undefined && isolation !== "worktree") {
+        const shown = typeof isolation === "string" ? JSON.stringify(isolation) : String(isolation);
+        const e = new Error(`isolation ${shown} is not supported in workflow agents — only "worktree" (omit the option to run in the shared working tree). The agent was not started (fail-closed: an unrecognized isolation value must never silently run in the shared working tree).`);
+        e.code = "isolation.invalid";
+        throw e;
+    }
+}
 function rethrowIfMaxAgents(e) {
     if (e instanceof WorkflowMaxAgentsError)
         throw e;
@@ -700,6 +715,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if ("error" in compiled)
                     throw new TypeError(`agent({schema}) received an invalid JSON Schema: ${compiled.error}`);
             }
+            assertSupportedAgentIsolation(agentOpts.isolation);
             const label = agentOpts.label ?? `agent-${run.agents.length + 1}`;
             const phase = agentOpts.phase ?? currentPhase?.title;
             const phaseInstance = resolveAgentPhase(agentOpts.phase);
@@ -828,7 +844,12 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     const onCallerAbort = () => attemptCtl.abort(new Error("workflow aborted"));
                     effectiveSignal?.addEventListener("abort", onCallerAbort, { once: true });
                     armWatchdog();
-                    const attemptSpec = { ...runSpec, signal: attemptCtl.signal };
+                    const attemptSessionId = resolveChildSessionIdAtSpawn(runSpec);
+                    const attemptSpec = attemptSessionId !== undefined ? { ...runSpec, sessionId: attemptSessionId, signal: attemptCtl.signal } : { ...runSpec, signal: attemptCtl.signal };
+                    if (attemptSessionId !== undefined && !finalized) {
+                        rec.sessionId = attemptSessionId;
+                        void persist("update");
+                    }
                     const attemptInternals = {
                         ...baseInternals,
                         ...(bceSink !== undefined
@@ -1071,6 +1092,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if ("error" in compiled)
                     throw new TypeError(`agent({schema}) received an invalid JSON Schema: ${compiled.error}`);
             }
+            assertSupportedAgentIsolation(agentOpts.isolation);
             const label = agentOpts.label ?? `agent-${run.agents.length + 1}`;
             const phase = agentOpts.phase ?? currentPhase?.title;
             const phaseInstance = resolveAgentPhase(agentOpts.phase);
@@ -1115,14 +1137,17 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             rec.startedAt = now();
             bceSpawn(callKey, label, agentOpts.agentType, false);
             let stream;
+            let childSessionId;
             try {
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
                 const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
                 const authInherit = framedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
-                const runSpec = agentOpts.schema
+                const baseRunSpec = agentOpts.schema
                     ? { ...framedSpec, ...authInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
                     : { ...framedSpec, ...authInherit, signal: effectiveSignal };
+                childSessionId = resolveChildSessionIdAtSpawn(baseRunSpec);
+                const runSpec = childSessionId !== undefined ? { ...baseRunSpec, sessionId: childSessionId } : baseRunSpec;
                 const enrichedForwardS = opts.onForwardEvent !== undefined
                     ? (e) => {
                         opts.onForwardEvent(e.type === "task_progress" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
@@ -1157,6 +1182,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 bceTerminal(callKey, "failed", err instanceof Error ? err.message : String(err), undefined, undefined);
                 throw err;
             }
+            if (childSessionId !== undefined && !finalized) {
+                rec.sessionId = childSessionId;
+                void persist("update");
+            }
             const steer = async (content) => {
                 const marker = `steer-${++steerMarkerSeq}`;
                 const framed = `[operator steer ${marker}] An operator/leader sent guidance for your task. Take it into account on your NEXT step. ` +

package/dist/tools/fs/fs-bash.d.ts

@@ -26,7 +26,13 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
     execClamp?: ExecClampOption;
     autoBackgroundOnTimeout?: boolean;
     oneShot?: boolean;
+    additionalRoots?: readonly string[];
+    bashDefaultTimeoutMs?: number;
+    bashMaxTimeoutMs?: number;
+}): AgentTool;
+export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption, timeoutOpts?: {
+    bashDefaultTimeoutMs?: number;
+    bashMaxTimeoutMs?: number;
 }): AgentTool;
-export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption): AgentTool;
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;
 export declare function createEnvTaskStopTool(env: ExecutionEnv, registry?: TaskRegistry): AgentTool;