@sema-agent/core 2.2.0 → 2.4.0

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;
@@ -129,5 +130,20 @@ export interface WorkflowTimers {
     setTimeout(fn: () => void, ms: number): unknown;
     clearTimeout(handle: unknown): void;
 }
+export declare const workflowResumeClaimFallback: {
+    acquire(store: WorkflowJournalStore, input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): {
+        granted: boolean;
+        holder?: string;
+    };
+    release(store: WorkflowJournalStore, input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): void;
+};
 export declare function startWorkflow<T>(runner: Runner, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): WorkflowHandle<T>;
 export declare function runWorkflow<T>(runner: Runner, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): Promise<RunWorkflowResult<T>>;

package/dist/orchestration/workflow.js

@@ -20,6 +20,7 @@ const MAX_TRANSCRIPT_CHARS = 4000;
 const WORKFLOW_RESULT_MAX = 4000;
 const WORKFLOW_RESULT_FULL_MAX = 200_000;
 const MAX_ACTIVITY = 30;
+const RUNNING_AGENT_PERSIST_EVERY_BEATS = 4;
 function workflowModelLabel(spec) {
     const model = spec.model;
     if (model === undefined)
@@ -103,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;
@@ -206,6 +222,33 @@ function createSemaphore(max) {
 function clampRunIdText(raw) {
     return raw.replace(/[^A-Za-z0-9_.:-]/g, "").slice(0, 64);
 }
+const fallbackResumeClaimTables = new WeakMap();
+function fallbackResumeClaimKey(scope, sourceRunId) {
+    return JSON.stringify([scope, sourceRunId]);
+}
+export const workflowResumeClaimFallback = {
+    acquire(store, input) {
+        let table = fallbackResumeClaimTables.get(store);
+        if (table === undefined) {
+            table = new Map();
+            fallbackResumeClaimTables.set(store, table);
+        }
+        const key = fallbackResumeClaimKey(input.scope, input.sourceRunId);
+        const holder = table.get(key);
+        if (holder !== undefined && holder !== input.newRunId)
+            return { granted: false, holder };
+        table.set(key, input.newRunId);
+        return { granted: true };
+    },
+    release(store, input) {
+        const table = fallbackResumeClaimTables.get(store);
+        if (table === undefined)
+            return;
+        const key = fallbackResumeClaimKey(input.scope, input.sourceRunId);
+        if (table.get(key) === input.newRunId)
+            table.delete(key);
+    },
+};
 export function startWorkflow(runner, fn, opts = {}, internals) {
     const alsDepth = currentWorkflowDepth();
     const internalDepth = internals?.workflowDepth;
@@ -566,8 +609,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             throw err;
         }
     };
-    const createActivityCapture = (callKey, label, groupId) => {
+    const createActivityCapture = (callKey, label, groupId, rec) => {
         const tail = [];
+        let beatCount = 0;
         const onActivity = (a) => {
             if (finalized)
                 return;
@@ -587,6 +631,13 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             tail.push(a);
             if (tail.length > MAX_ACTIVITY)
                 tail.shift();
+            if (a.phase === "start")
+                rec.toolCalls = (rec.toolCalls ?? 0) + 1;
+            rec.activity = tail;
+            beatCount += 1;
+            if (beatCount === 1 || beatCount % RUNNING_AGENT_PERSIST_EVERY_BEATS === 0) {
+                void persist("update");
+            }
         };
         return { tail, onActivity };
     };
@@ -664,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);
@@ -734,8 +786,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             if (budgetTotal !== null && spent() >= budgetTotal) {
                 throw new WorkflowBudgetExceededError(spent(), budgetTotal);
             }
-            const { tail: activityTail, onActivity } = createActivityCapture(callKey, label, groupId);
             const rec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(model !== undefined ? { model } : {}), status: "running", queuedAt: now() };
+            const { tail: activityTail, onActivity } = createActivityCapture(callKey, label, groupId, rec);
             run.agents.push(rec);
             if (phaseInstance)
                 agentPhaseOf.set(rec, phaseInstance);
@@ -792,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
@@ -1035,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);
@@ -1047,8 +1105,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             const model = workflowModelLabel(specForIdentity);
             noteDivergence(run.agents.length, "ctx.agentStream results are never replayed");
             diverged = true;
-            const { tail: activityTail, onActivity } = createActivityCapture(callKey, label, groupId);
             const rec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(model !== undefined ? { model } : {}), status: "running", queuedAt: now() };
+            const { tail: activityTail, onActivity } = createActivityCapture(callKey, label, groupId, rec);
             run.agents.push(rec);
             if (phaseInstance)
                 agentPhaseOf.set(rec, phaseInstance);
@@ -1079,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);
@@ -1121,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. ` +
@@ -1388,18 +1453,19 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         try {
             const runBody = async () => {
                 if (opts.resumeFromRunId !== undefined && journalStore) {
-                    if (journalStore.resumeClaim) {
-                        const verdict = journalStore.resumeClaim({ sourceRunId: opts.resumeFromRunId, newRunId: runId, scope });
-                        resumeClaim = { sourceRunId: opts.resumeFromRunId, verdict };
-                        const decision = await verdict;
-                        if (!decision.granted) {
-                            const holder = decision.holder !== undefined ? clampRunIdText(decision.holder) : "";
-                            throw new Error(`startWorkflow: resume from "${clampRunIdText(opts.resumeFromRunId)}" was REFUSED — ` +
-                                `another run already holds the resume claim on it${holder ? ` (holder: ${holder})` : " (holder unknown to the store)"}. ` +
-                                "Two concurrent resumes of one source run fork its execution: both replay the same prefix and then " +
-                                "re-run the whole suffix live, duplicating every side effect. Wait for the holder to reach a terminal " +
-                                "state (or stop it) and resume again.");
-                        }
+                    const usingFallback = journalStore.resumeClaim === undefined;
+                    const verdict = usingFallback
+                        ? Promise.resolve(workflowResumeClaimFallback.acquire(journalStore, { sourceRunId: opts.resumeFromRunId, newRunId: runId, scope }))
+                        : journalStore.resumeClaim({ sourceRunId: opts.resumeFromRunId, newRunId: runId, scope });
+                    resumeClaim = { sourceRunId: opts.resumeFromRunId, verdict, fallback: usingFallback };
+                    const decision = await verdict;
+                    if (!decision.granted) {
+                        const holder = decision.holder !== undefined ? clampRunIdText(decision.holder) : "";
+                        throw new Error(`startWorkflow: resume from "${clampRunIdText(opts.resumeFromRunId)}" was REFUSED — ` +
+                            `another run already holds the resume claim on it${holder ? ` (holder: ${holder})` : " (holder unknown to the store)"}. ` +
+                            "Two concurrent resumes of one source run fork its execution: both replay the same prefix and then " +
+                            "re-run the whole suffix live, duplicating every side effect. Wait for the holder to reach a terminal " +
+                            "state (or stop it) and resume again.");
                     }
                     const entries = await journalStore.load(opts.resumeFromRunId, scope);
                     for (const e of entries)
@@ -1501,13 +1567,20 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         finally {
             finalized = true;
             await journalTail.catch(() => undefined);
-            if (resumeClaim !== undefined && journalStore?.releaseResumeClaim) {
+            if (resumeClaim !== undefined) {
                 const granted = await finalizeWithin(timers, resumeClaim.verdict.then((v) => v.granted, () => false), false);
                 if (granted) {
-                    try {
-                        await finalizeWithin(timers, journalStore.releaseResumeClaim({ sourceRunId: resumeClaim.sourceRunId, newRunId: runId, scope }), undefined);
+                    if (resumeClaim.fallback) {
+                        if (journalStore) {
+                            workflowResumeClaimFallback.release(journalStore, { sourceRunId: resumeClaim.sourceRunId, newRunId: runId, scope });
+                        }
                     }
-                    catch {
+                    else if (journalStore?.releaseResumeClaim) {
+                        try {
+                            await finalizeWithin(timers, journalStore.releaseResumeClaim({ sourceRunId: resumeClaim.sourceRunId, newRunId: runId, scope }), undefined);
+                        }
+                        catch {
+                        }
                     }
                 }
             }

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;