@sema-agent/core 7.0.2 → 7.2.0

package/dist/orchestration/builtin-workflows.d.ts

@@ -22,12 +22,17 @@ import type { NamedWorkflowListing } from "./workflow-script-store.js";
 /** The built-in round-based discussion workflow's registered name. */
 export declare const DISCUSSION_WORKFLOW_NAME = "discussion";
 /**
- * The registered name this built-in carried before the C-R14 vocabulary ruling (2026-08-16), kept
- * resolvable for ONE minor: "team" now names the agent-teams family (persistent named teammates) only,
- * and a one-off multi-agent debate is a "discussion".
+ * The registered name this built-in carried before the C-R14 vocabulary ruling (2026-08-16): "team" now
+ * names the agent-teams family (persistent named teammates) only, and a one-off multi-agent debate is a
+ * "discussion".
  *
- * @deprecated Use {@link DISCUSSION_WORKFLOW_NAME}. Removed in the next minor; the retired spelling still
- * RESOLVES via {@link canonicalWorkflowName} until then, but the listing/card face shows the new name only.
+ * RETENTION, as a fact rather than a plan: the ruling's original "kept resolvable for ONE minor" window
+ * LAPSED. The alias has stayed on the public export surface from the 5.37.0 window through 7.x, across
+ * BOTH the 6.0.0 and 7.0.0 BREAKING windows. It is therefore retained until a removal is announced in a
+ * named BREAKING window's ship post — no minor removes it by default.
+ *
+ * @deprecated Use {@link DISCUSSION_WORKFLOW_NAME}. The retired spelling still RESOLVES via
+ * {@link canonicalWorkflowName}, but the listing/card face shows the new name only.
  */
 export declare const TEAM_DISCUSSION_WORKFLOW_NAME = "discussion";
 /**
@@ -35,7 +40,8 @@ export declare const TEAM_DISCUSSION_WORKFLOW_NAME = "discussion";
  * retired alias. The canonical name is the authority: a resolution reached through an alias returns the
  * canonical definition (its `meta.name`, hence every run/card projection, is the new name).
  *
- * @deprecated together with the alias table — this becomes an identity function next minor (C-R14).
+ * @deprecated together with the alias table — it becomes an identity function when that table is removed
+ * in an announced BREAKING window (C-R14).
  */
 export declare function canonicalWorkflowName(name: string): string;
 /**
@@ -72,7 +78,8 @@ export declare function retiredWorkflowNameAliases(canonicalName: string): strin
  * Callers must apply the deployment's `builtinWorkflows` opt-out BEFORE using this: the equivalence is a
  * fact about the built-in registry, so a deployment that removed the built-ins removed the alias with them.
  *
- * @deprecated together with the alias table — collapses to `[requested]` next minor (C-R14).
+ * @deprecated together with the alias table — collapses to `[requested]` when that table is removed in an
+ * announced BREAKING window (C-R14).
  */
 export declare function workflowNameProbeOrder(requested: string): string[];
 /**
@@ -82,8 +89,9 @@ export declare function workflowNameProbeOrder(requested: string): string[];
  */
 export declare const DISCUSSION_SCRIPT = "export const meta = {\n  name: \"discussion\",\n  description: \"Round-based 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 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(\"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        \"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";
 /**
- * @deprecated Use {@link DISCUSSION_SCRIPT}. Retired spelling kept for one minor (C-R14) so a deployment
- * importing the constant by its old name keeps compiling; the value is the SAME script (its `meta.name`
+ * @deprecated Use {@link DISCUSSION_SCRIPT}. Retired spelling retained (C-R14; the original one-minor
+ * window lapsed — removal needs an announced BREAKING window) so a deployment importing the constant by
+ * its old name keeps compiling; the value is the SAME script (its `meta.name`
  * is the new `discussion`).
  */
 export declare const TEAM_DISCUSSION_SCRIPT = "export const meta = {\n  name: \"discussion\",\n  description: \"Round-based 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 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(\"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        \"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";

package/dist/orchestration/run-workflow-tool.js

@@ -332,8 +332,13 @@ export async function createRunWorkflowTool(d) {
             "body (equivalently, pass { phase: 'Fix' } in an agent's opts). Give each stage a phase so progress " +
             "renders as stage groups; use the same titles you declared in meta.phases.\n" +
             "• spec.modelName works only when the deployment configured a workflow model allowlist, and its legal " +
-            "values are that deployment's own model CATALOG KEYS — not generic tier words (a bare 'opus'/'sonnet'/" +
-            "'haiku' is a name the catalog almost certainly does not hold, and is refused rather than approximated). " +
+            "values are the names on THAT allowlist which the deployment's model CATALOG KEYS also hold — a name " +
+            "off the allowlist, and a listed name the catalog lacks, are both refused rather than approximated. " +
+            "Generic tier words ('opus'/'sonnet'/'haiku'/'pro'/'flash'/'best') are not a separate namespace: on a " +
+            "deployment that configured tier bindings they become ordinary catalog keys, but only the ones its " +
+            "bindings actually resolve; on one that did not they are simply absent, unless its catalog happens to " +
+            "declare that literal name. Either way the allowlist is the gate, so a tier word is legal here only " +
+            "when this deployment allowlisted it, never as a shortcut around it. " +
             "It also goes on the SPEC (the first argument), never in an agent()'s options object; `model` is accepted " +
             "there as an alias for the same field. If unsure, omit it and the agent runs on the deployment's default " +
             "role.\n" +

package/dist/orchestration/workflow-governance.js

@@ -99,7 +99,7 @@ export function resolveModelName(name, allowlist, models) {
     if (!allowlist.includes(name)) {
         throw new WorkflowModelNotAllowedError(name, `not in the workflow model allowlist [${allowlist.join(", ")}]`);
     }
-    const model = models?.[name];
+    const model = models !== undefined && Object.hasOwn(models, name) ? models[name] : undefined;
     if (!model) {
         throw new WorkflowModelNotAllowedError(name, "allowed by name but not present in RunnerDeps.models");
     }

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

@@ -392,6 +392,7 @@ export type WorkflowEvent = {
     output?: string;
     errorCode?: string;
     toolCalls?: number;
+    modelResolved?: string;
     replayed?: boolean;
     ts: number;
 } | {

package/dist/orchestration/workflow.js

@@ -60,7 +60,7 @@ function workflowModelLabel(spec, catalog) {
         return undefined;
     if (typeof model !== "string")
         return model.id ?? model.name;
-    const served = catalog?.[model]?.id;
+    const served = catalog !== undefined && Object.hasOwn(catalog, model) ? catalog[model]?.id : undefined;
     return served ?? resolveModelDisplayLabel(model);
 }
 export const WORKFLOW_SUBAGENT_PROMPT = `You are a subagent spawned by a workflow orchestration script. Use the tools available to complete the task.

package/dist/stores/file/mailbox-store.d.ts

@@ -30,7 +30,8 @@ export declare class FileMailboxStore implements MailboxStore {
      * file can never disagree. Before this, `AgentOne` and `agentone` produced two DIFFERENT shared-state
      * keys but the SAME file on a case-insensitive filesystem (macOS/Windows default) — one recipient read
      * the other's messages after a restart. Folding is also the semantically correct answer, not just the
-     * safe one: the addressing layer's `normalizeAgentName` (task-registry.ts:621) already lowercases, so
+     * safe one: the addressing layer's `normalizeAgentName` (defined in core/task-registry-shared.ts and
+     * re-exported by task-registry.ts) already lowercases, so
      * two case-variant handles ARE the same agent; this makes the storage layer say so explicitly instead of
      * depending on an upstream coincidence, and behave identically on case-SENSITIVE filesystems (Linux),
      * where the old code silently split one logical agent's mail across two boxes.

package/package.json

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