@sema-agent/core 7.24.0 → 7.24.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 7.24.1 — 2026-09-19
+
+### The model-role vocabulary ships its runtime twin (#965; P3; additive export `MODEL_ROLES`; @server @client-core)
+- **Before.** `ModelRole` was a nine-word string-literal union with no runtime value beside it, so every consumer that needed the members at runtime transcribed them by hand — server's settings-schema parity test carries its own `CORE_MODEL_ROLES` nine-word mirror, and a settings schema that wants to validate a role name has nothing to import.
+- **After.** `MODEL_ROLES` (`as const`, declaration order `default … consolidate`) is the source; `ModelRole` derives from it; both ride the root export. Nine words spelled once. `advisor` is in the tuple (it has always been in the type); a downstream schema that omits it is a downstream choice, now visible as a set difference instead of a transcription slip.
+- **Reach.** Additive export (+1, tier advanced); no wire key; no behaviour change. `test/backlog965-model-roles-tuple.test.ts` pins the tuple, its uniqueness and the type derivation (a hand-written union that drops a word fails at `tsc`).
+
 ## 7.24.0 — 2026-09-19
 
 ### The stream engine's last two `instanceof BrainError` reads (#935, follow-on; P2; no wire key)

package/dist/core/model-seat.d.ts

@@ -36,7 +36,10 @@ export type ModelRef = string | Model;
  *   this role wants (note the summarize DEFAULT rationale — prompt-cache forking — does not
  *   apply here: consolidation is an offline independent request with no shared prefix).
  */
-export type ModelRole = "default" | "summarize" | "subagent" | "team" | "synthesize" | "advisor" | "verifier" | "classifier" | "consolidate";
+export declare const MODEL_ROLES: readonly ["default", "summarize", "subagent", "team", "synthesize", "advisor", "verifier", "classifier", "consolidate"];
+/** The role vocabulary, derived from {@link MODEL_ROLES} — one source; a consumer that needs the members at
+ *  runtime (a settings schema, a parity pin, a doctor line) reads the tuple instead of transcribing it. */
+export type ModelRole = (typeof MODEL_ROLES)[number];
 /**
  * A role's model: a `ModelRef`, or a config object that pins a `model`, **selects** one by
  * capability/price (`select`, design/11 Layer 2), and/or sets a default `thinking` level.

package/dist/core/model-seat.js

@@ -1 +1 @@
-export {};
+export const MODEL_ROLES = ["default", "summarize", "subagent", "team", "synthesize", "advisor", "verifier", "classifier", "consolidate"];

package/dist/core/roles.d.ts

@@ -2,6 +2,7 @@ import type { ThinkingLevel } from "../internal/harness-types.js";
 import type { Model } from "../internal/llm.js";
 import type { ModelRef, ModelRole, ModelRoles, RoleSpec } from "./types.js";
 export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
+export { MODEL_ROLES } from "./types.js";
 /** Resolve a string ModelRef against the catalog (a Model object passes through). */
 export declare function resolveModel(ref: ModelRef, models?: Record<string, Model>): Model;
 /** 档位降档链(强→弱)。解析某档无绑定时沿链向后找第一个有绑定的档(fail-open 可用性优先;绑定缺口

package/dist/core/roles.js

@@ -1,4 +1,5 @@
 import { selectModel } from "./select-model.js";
+export { MODEL_ROLES } from "./types.js";
 export function resolveModel(ref, models) {
     if (typeof ref !== "string") {
         return ref;

package/dist/core/types.d.ts

@@ -12,6 +12,7 @@
 import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict } from "../internal/harness.js";
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
+export { MODEL_ROLES } from "./model-seat.js";
 export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine } from "./task-spec.js";
 export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";

package/dist/core/types.js

@@ -1,3 +1,4 @@
+export { MODEL_ROLES } from "./model-seat.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
 export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, settleOwedUserInput, undrainedUserInputNotices } from "./engine-notice.js";

package/dist/index.d.ts

@@ -40,7 +40,7 @@ export { LspDiagnosticsRegistry, formatDiagnosticsBlock, formatDiagnosticsSummar
 export { NodeLspManager, DEFAULT_LSP_SERVERS, languageFor, defaultLspSpawn, type NodeLspManagerOptions, type LspSpawn, } from "./engine/lsp/node-lsp-manager.js";
 export { StdioLspTransport, type LspChildProcess } from "./engine/lsp/stdio-lsp-transport.js";
 export { encodeFrame, createFrameDecoder } from "./engine/lsp/frame-decoder.js";
-export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, type ModelRole, type RoleSpec, type ModelRoles, type ResolvedRole, type ModelMention, } from "./core/roles.js";
+export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, MODEL_ROLES, type ModelRole, type RoleSpec, type ModelRoles, type ResolvedRole, type ModelMention, } from "./core/roles.js";
 export { selectModel, selectModelOrThrow, type ModelCriteria, type ModelTier } from "./core/select-model.js";
 export { BrainError, classifyHttp, type BrainErrorCode } from "./brain/errors.js";
 export { looksDegenerate, inspectDegenerate, trimDegenerateTail } from "./brain/repetition.js";

package/dist/index.js

@@ -27,7 +27,7 @@ export { LspDiagnosticsRegistry, formatDiagnosticsBlock, formatDiagnosticsSummar
 export { NodeLspManager, DEFAULT_LSP_SERVERS, languageFor, defaultLspSpawn, } from "./engine/lsp/node-lsp-manager.js";
 export { StdioLspTransport } from "./engine/lsp/stdio-lsp-transport.js";
 export { encodeFrame, createFrameDecoder } from "./engine/lsp/frame-decoder.js";
-export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, } from "./core/roles.js";
+export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, MODEL_ROLES, } from "./core/roles.js";
 export { selectModel, selectModelOrThrow } from "./core/select-model.js";
 export { BrainError, classifyHttp } from "./brain/errors.js";
 export { looksDegenerate, inspectDegenerate, trimDegenerateTail } from "./brain/repetition.js";

package/package.json

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

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2397,
+  "count": 2398,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -679,6 +679,7 @@
     "MEMORY_SAFETY": "variable",
     "MEMORY_SEARCH_SUPERSEDED_TAG": "variable",
     "MEMORY_SEARCH_TOOL_NAME": "variable",
+    "MODEL_ROLES": "variable",
     "MONITOR_BATCH_WINDOW_MS": "variable",
     "MONITOR_DEFAULT_TIMEOUT_MS": "variable",
     "MONITOR_MAX_BATCHES_PER_MINUTE": "variable",
@@ -3078,6 +3079,7 @@
     "MEMORY_SAFETY": "advanced",
     "MEMORY_SEARCH_SUPERSEDED_TAG": "advanced",
     "MEMORY_SEARCH_TOOL_NAME": "advanced",
+    "MODEL_ROLES": "advanced",
     "MONITOR_BATCH_WINDOW_MS": "advanced",
     "MONITOR_DEFAULT_TIMEOUT_MS": "advanced",
     "MONITOR_MAX_BATCHES_PER_MINUTE": "advanced",

package/wire-changes/core@7.24.1.json

@@ -0,0 +1,85 @@
+{
+  "repo": "core",
+  "version": "7.24.1",
+  "from": "f87928e73c4b748d4e8de91f591cb08c659a2c69",
+  "to": "v7.24.1",
+  "added": [
+    {
+      "name": "MODEL_ROLES",
+      "kind": "variable",
+      "tier": "advanced",
+      "at": [
+        "src/core/model-seat.ts:41",
+        "src/core/roles.ts:7",
+        "src/core/types.ts:21",
+        "src/index.ts:242"
+      ],
+      "criteriaCovered": false,
+      "breaking": false
+    }
+  ],
+  "removed": [],
+  "changed": [],
+  "narrowed": [],
+  "closedSetMembers": [
+    {
+      "set": "MODEL_ROLES",
+      "at": [
+        "src/core/model-seat.ts:41"
+      ],
+      "newSet": true,
+      "added": [
+        "advisor",
+        "classifier",
+        "consolidate",
+        "default",
+        "subagent",
+        "summarize",
+        "synthesize",
+        "team",
+        "verifier"
+      ],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    }
+  ],
+  "closedSetsUnreadable": [
+    {
+      "set": "ModelRole",
+      "from": "literal",
+      "to": "declared",
+      "unreadable": true,
+      "at": [
+        "src/core/model-seat.ts:44",
+        "src/core/roles.ts:6",
+        "src/core/types.ts:20",
+        "src/index.ts:243"
+      ],
+      "reason": "no longer a spelled-out vocabulary (declared at src/core/model-seat.ts:44, src/core/roles.ts:6, src/core/types.ts:20, src/index.ts:243)"
+    }
+  ],
+  "typeKeys": [],
+  "declarationMoves": [],
+  "mintMoves": [],
+  "criteriaObserves": [
+    {
+      "kind": "typeMember",
+      "name": "RunnerDeps.roles",
+      "assertions": [
+        "G1.a"
+      ]
+    }
+  ],
+  "consumersHint": {
+    "cli": [
+      "MODEL_ROLES"
+    ],
+    "server": [],
+    "sdk": [],
+    "note": "scanned cli@ae64fcaf server@277e6a15 sdk@5ded40c — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it"
+  },
+  "breakingCount": 0,
+  "breakingItems": [],
+  "toResolvedAt": "d552b285c747d987758c66504ec8cba98fab04de"
+}