@sema-agent/core 7.55.0 → 7.57.0

package/dist/prompt-assembly/catalog/sections.js

@@ -90,7 +90,6 @@ export const SECTIONS = [
             ],
         },
     },
-    { id: "core/behavior.model-guidance", band: "behavior", rank: 450, block: { id: "model.guidance" }, body: { renderer: "model-guidance" } },
     { id: "core/discovery.mcp-instructions", band: "discovery", rank: 500, block: { id: "mcp.instructions" }, body: { renderer: "mcp-instructions" } },
     { id: "core/harness.reminder-mark", band: "constitution", rank: 590, block: { id: "harness.reminder-mark" }, body: { renderer: "reminder-mark" } },
     { id: "core/environment.context", band: "environment", rank: 600, block: { id: "env.context" }, body: { renderer: "environment" } },

package/dist/prompt-assembly/composer.d.ts

@@ -1,4 +1,4 @@
-import type { HostForm, HostRole, PromptCatalog } from "./catalog/schema.js";
+import type { HostForm, HostRole, PromptCatalog, PromptTraitName } from "./catalog/schema.js";
 import { type SourcedOverlay, type SupersededOverlay } from "./overlay.js";
 import type { CompiledSystemBlock, ComposedPrompt, SectionRenderInputs, SystemLayout } from "./types.js";
 /** What one composition renders: the catalog, the host selector values, and the overlays in application order. */
@@ -11,6 +11,8 @@ export interface CompositionPlan {
     };
     /** The run's binding (`TaskSpec.promptBinding`; absent ⇒ none) — what every overlay's `when.binding` reads. */
     readonly binding?: string;
+    /** The run's effective traits (`effectiveTraitsOf`; absent ⇒ those of a model that declares none). */
+    readonly traits?: ReadonlySet<PromptTraitName>;
     /** Validated overlays, already in application order (`bundled < task < center < deploy`, then declaration order). */
     readonly overlays?: readonly SourcedOverlay[];
 }

package/dist/prompt-assembly/composer.js

@@ -91,7 +91,7 @@ function renderAdded(e, fold) {
     };
 }
 export function composeCatalog(plan, inputs) {
-    const s = selectorsOf(inputs.facts, plan.host, plan.binding);
+    const s = selectorsOf(inputs.facts, plan.host, plan.binding, plan.traits);
     const bases = basesOf(plan.catalog, inputs, s);
     const selectedText = selectedTextOf(plan.catalog, bases);
     const overlayText = (o) => {

package/dist/prompt-assembly/event-registry.js

@@ -11,6 +11,7 @@ export const EVENT_PROMPT_REGISTRY = new Map([
     { kind: "total_tokens_reminder", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderTotalTokensReminder" },
     { kind: "background_tasks", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderBackgroundTasks" },
     { kind: "tools_delta", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderToolsDelta" },
+    { kind: "mcp_unavailable", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderMcpUnavailable" },
     { kind: "agent_listing", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderAgentListingDelta" },
     { kind: "skills_listing", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderSkillsListingDelta" },
     { kind: "mcp_instructions", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderMcpInstructionsDelta" },

package/dist/prompt-assembly/overlay.js

@@ -3,7 +3,7 @@ import { describeFault, isPlainRecord, receive } from "../core/mods/kernel/recei
 import { egressText } from "../core/untrusted-egress.js";
 import { bandOf, isBandId } from "./bands.js";
 import { SEMA_DEFAULT_CATALOG, catalogMessage } from "./catalog/index.js";
-import { HOST_FORMS, HOST_ROLES, OVERLAY_OPS, PROMPT_FACT_NAMES, PROMPT_TRAITS, isHostRole, isWordOf, } from "./catalog/schema.js";
+import { HOST_FORMS, HOST_ROLES, OVERLAY_OPS, PROMPT_FACT_NAMES, PROMPT_TRAITS, PROMPT_TRAIT_BUNDLES, isHostRole, isPromptTraitName, isWordOf, } from "./catalog/schema.js";
 import { RENDERERS } from "./renderers.js";
 import { canonicalWhen } from "./select.js";
 export const OVERLAY_SOURCE_ORDER = Object.freeze(["bundled", "task", "center", "deploy"]);
@@ -116,8 +116,8 @@ function whenViolation(when) {
             if (!Array.isArray(list))
                 return `"when.traits.${k}" is not an array`;
             for (const name of list)
-                if (!isWordOf(PROMPT_TRAITS, name))
-                    return `"when.traits.${k}" names ${str(name)}, not a trait (${PROMPT_TRAITS.join(", ")})`;
+                if (!isPromptTraitName(name))
+                    return `"when.traits.${k}" names ${str(name)}, not a trait (${PROMPT_TRAITS.join(", ")}; a bundle: ${Object.keys(PROMPT_TRAIT_BUNDLES).join(", ")}; or a deployment's own "x-<namespace>-<name>")`;
         }
     }
     if (w["host"] !== undefined) {

package/dist/prompt-assembly/renderers.d.ts

@@ -5,7 +5,7 @@ export interface RendererSpec {
     readonly id: RendererId;
     readonly version: number;
     readonly stability: "static" | "session" | "leg";
-    readonly reads: "inputs" | "facts" | "env" | "memory" | "mcp" | "mark" | "selectors";
+    readonly reads: "facts" | "env" | "memory" | "mcp" | "mark" | "selectors";
     readonly external: boolean;
     /** The catalog messages this renderer's output is (an overlay targets them). */
     readonly messages?: readonly string[];

package/dist/prompt-assembly/renderers.js

@@ -4,7 +4,6 @@ import { catalogMessage } from "./catalog/index.js";
 import { selectVariant } from "./select.js";
 export const RENDERERS = {
     "role-base": { id: "role-base", version: 2, stability: "session", reads: "selectors", external: false, messages: ["core/role.base"] },
-    "model-guidance": { id: "model-guidance", version: 1, stability: "session", reads: "inputs", external: false },
     "mcp-instructions": { id: "mcp-instructions", version: 1, stability: "session", reads: "mcp", external: true },
     "reminder-mark": { id: "reminder-mark", version: 1, stability: "session", reads: "mark", external: false },
     environment: { id: "environment", version: 2, stability: "leg", reads: "env", external: false },
@@ -25,8 +24,6 @@ export function runRenderer(id, inputs, selectors) {
             const sections = renderCoworkBase({ tools: inputs.toolNames ?? [], workspaceFolder: inputs.workspaceFolder });
             return sections.length === 0 ? undefined : { text: sections.map((s) => s.text).join("\n\n"), variant: v.id };
         }
-        case "model-guidance":
-            return plain(inputs.modelGuidance);
         case "mcp-instructions":
             return plain(inputs.mcpInstructionsBlock);
         case "reminder-mark":

package/dist/prompt-assembly/role-base.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The role base's one decision rule (a leaf): of an ordered list of sources — the task, the requested model role's
+ * preset, an engine spawner's child persona — the first that names a role base decides it wholly (the sugar's header).
+ */
+import type { HostRole } from "./catalog/schema.js";
+/** A source's statement of the role base — its word (the host role; selects the `core/role.base` variant), its text
+ *  (replaces that base), or both. `TaskSpec`, a role preset and the delegation tool's options have this shape. */
+export interface RoleBaseDeclaration {
+    readonly promptRole?: HostRole;
+    readonly systemPrompt?: string;
+}
+/** Whether a source names a role base — the one reading of "this seat has spoken". */
+export declare function namesRoleBase(d: RoleBaseDeclaration | undefined): boolean;
+/** The first source that names a role base, whole; `undefined` ⇒ none did. */
+export declare function roleBaseOf(sources: readonly (RoleBaseDeclaration | undefined)[]): RoleBaseDeclaration | undefined;

package/dist/prompt-assembly/role-base.js

@@ -0,0 +1,9 @@
+export function namesRoleBase(d) {
+    return d !== undefined && (d.promptRole !== undefined || d.systemPrompt !== undefined);
+}
+export function roleBaseOf(sources) {
+    for (const source of sources)
+        if (namesRoleBase(source))
+            return source;
+    return undefined;
+}

package/dist/prompt-assembly/select.d.ts

@@ -3,8 +3,8 @@
  * whether an overlay's `when` applies to this run (every source class alike). Four dimensions, each with exactly one
  * writer, so no value ever needs a precedence order:
  *
- * - `traits` — derived from the run's two prompt-shape axes by {@link promptTraitsOf} (the prompt profile and the
- *   fable-family model); catalog data reads traits, never the axes.
+ * - `traits` — the model's declared traits (`Model.promptTraits`) with the task's one switch on `lean_prompt`
+ *   (`TaskSpec.promptLean`), bundles expanded: {@link effectiveTraitsOf}. The engine reads no model id to choose text.
  * - `host` — `role` (which role base the run is assembled for; `TaskSpec.promptRole`, absent ⇒ `general`) and
  *   `form` (`TaskSpec.promptForm`, which every engine-built child receives through the parent spec seat; absent ⇒
  *   `standard`).
@@ -15,11 +15,11 @@
  * fact equal, the binding inside its `anyOf` (or outside its `noneOf`). No disjunction across dimensions.
  */
 import type { PromptManifestSelectors } from "../core/trace.js";
-import { type CatalogMessage, type FactConjunction, type HostForm, type HostRole, type PromptFactName, type PromptTrait, type Variant, type VariantWhen } from "./catalog/schema.js";
+import { type CatalogMessage, type FactConjunction, type HostForm, type HostRole, type PromptFactName, type PromptTraitName, type TraitCondition, type Variant, type VariantWhen } from "./catalog/schema.js";
 import type { PromptRuntimeFacts } from "./types.js";
 /** The run's selector values, resolved once per assembly. */
 export interface PromptSelectors {
-    readonly traits: ReadonlySet<PromptTrait>;
+    readonly traits: ReadonlySet<PromptTraitName>;
     readonly host: {
         readonly role: HostRole;
         readonly form: HostForm;
@@ -28,17 +28,29 @@ export interface PromptSelectors {
     readonly binding?: string;
 }
 /**
- * The run's prompt traits, derived from the two prompt-shape axes the engine resolves today: the simple
- * profile is `lean_prompt`, a fable-family model is `fable_5_mitigations`. This is the only place those
- * axes become traits.
+ * The run's effective traits — the one place a trait set is formed: the model's declared set (exact: nothing is added
+ * to what it lists; absent ⇒ `["lean_prompt"]`), then the task's one switch (`promptLean`: `true` adds `lean_prompt`,
+ * `false` removes it, absent leaves the model's answer), then each declared bundle's members. The task can move
+ * nothing else: a model-family trait stays the model's.
  */
-export declare function promptTraitsOf(facts: Pick<PromptRuntimeFacts, "promptProfile" | "fableMitigations">): ReadonlySet<PromptTrait>;
+export declare function effectiveTraitsOf(declared: readonly PromptTraitName[] | undefined, lean: boolean | undefined): ReadonlySet<PromptTraitName>;
+/**
+ * The model door's reading of `Model.promptTraits`: absent, or a list whose every entry is a trait name
+ * ({@link isPromptTraitName}). Anything else is refused by name (`config.prompt_trait_unknown`), never read as the
+ * default — a model that names a trait the engine cannot read would silently receive another prompt shape.
+ */
+export declare function readModelPromptTraits(model: {
+    readonly id?: unknown;
+    readonly promptTraits?: unknown;
+}): readonly PromptTraitName[] | undefined;
 /** The predicate facts a condition may test; optional runtime facts read as false when absent. */
 export declare function catalogFactsOf(facts: PromptRuntimeFacts): Readonly<Record<PromptFactName, boolean>>;
 /**
- * The host selector's two values as their one writer gave them: the task (`TaskSpec.promptRole` /
- * `TaskSpec.promptForm`; an engine-built child's spec carries its parent's form through the parent spec seat).
- * A value outside the closed set is refused by name (`config.prompt_selector_invalid`), never read as the default.
+ * The task seat's two host values as its door judges them (`TaskSpec.promptRole` / `TaskSpec.promptForm`; an
+ * engine-built child's spec carries its parent's form through the parent spec seat). The form is the run's; the role
+ * word is the task's statement of its role base, the first source of the role-base decision (`roleBaseOf`, the
+ * request-body sugar), which gives the run's host role. A value outside the closed set is refused by name
+ * (`config.prompt_selector_invalid`), never read as the default.
  */
 export declare function resolveHost(task: {
     readonly promptRole?: unknown;
@@ -47,16 +59,29 @@ export declare function resolveHost(task: {
     readonly role?: HostRole;
     readonly form?: HostForm;
 };
-/** The run's selectors — their one mint: traits and facts from the runtime facts, the host from its two writers' values,
- *  the binding as the task's door validated it. */
+/** The task's switch on the lean shape as its one writer gave it (`TaskSpec.promptLean`): a boolean or absent; any other
+ *  value is refused by name (`config.prompt_selector_invalid`), never read as absent. */
+export declare function resolvePromptLean(task: {
+    readonly promptLean?: unknown;
+}): boolean | undefined;
+/** A role-base seat's role word as its writer gave it — the one door every seat that may name a role base passes
+ *  (`TaskSpec.promptRole`, a role preset's `promptRole`, the delegation tool's `promptRole`; `seat` names where it was
+ *  written): absent, or a word of {@link HOST_ROLES}; anything else is refused by name (`config.prompt_selector_invalid`). */
+export declare function readPromptRole(seat: string, value: unknown): HostRole | undefined;
+/** The run's selectors — their one mint: the facts from the runtime facts, the host from its two writers' values, the
+ *  binding as the task's door validated it, and the effective traits ({@link effectiveTraitsOf}; absent ⇒ those of a
+ *  model that declares none, with no task switch). */
 export declare function selectorsOf(facts: PromptRuntimeFacts, host?: {
     readonly role?: HostRole;
     readonly form?: HostForm;
-}, binding?: string): PromptSelectors;
+}, binding?: string, traits?: ReadonlySet<PromptTraitName>): PromptSelectors;
 /** The selectors' plain form (traits sorted): what the manifest shows, the identity's `binding` element digests and the
  *  `prompt.compose` event carries — one record. */
 export declare function selectorRecordOf(s: PromptSelectors): PromptManifestSelectors;
 export declare function factsHold(conj: FactConjunction | undefined, facts: Readonly<Record<PromptFactName, boolean>>): boolean;
+/** Whether a trait condition holds over a trait set — every `allOf` present, no `noneOf` present. The one trait reading:
+ *  a catalog variant's, an overlay's and a tool description variant's condition all go through it. */
+export declare function traitsHold(cond: TraitCondition | undefined, traits: ReadonlySet<PromptTraitName>): boolean;
 /** Whether a `when` holds under the run's selectors. */
 export declare function whenHolds(when: VariantWhen | undefined, s: PromptSelectors): boolean;
 /**

package/dist/prompt-assembly/select.js

@@ -1,12 +1,36 @@
-import { HOST_ROLES, isHostRole } from "./catalog/schema.js";
-export function promptTraitsOf(facts) {
-    const traits = new Set();
-    if (facts.promptProfile !== "classic")
+import { bundleMembersOf, HOST_ROLES, isHostRole, isPromptTraitName } from "./catalog/schema.js";
+const UNDECLARED_MODEL_TRAITS = Object.freeze(["lean_prompt"]);
+export function effectiveTraitsOf(declared, lean) {
+    const traits = new Set(declared ?? UNDECLARED_MODEL_TRAITS);
+    if (lean === true)
         traits.add("lean_prompt");
-    if (facts.fableMitigations === true)
-        traits.add("fable_5_mitigations");
+    else if (lean === false)
+        traits.delete("lean_prompt");
+    for (const name of [...traits])
+        for (const member of bundleMembersOf(name))
+            traits.add(member);
     return traits;
 }
+export function readModelPromptTraits(model) {
+    const raw = model.promptTraits;
+    if (raw === undefined)
+        return undefined;
+    const refuse = (why) => {
+        throw Object.assign(new Error(`Model.promptTraits of model ${JSON.stringify(String(model.id)).slice(0, 80)} ${why}; a trait is one of the reference's prompt capability names, a bundle name, or a deployment's own "x-<namespace>-<name>"`), {
+            code: "config.prompt_trait_unknown",
+        });
+    };
+    if (!Array.isArray(raw))
+        return refuse(`is ${raw === null ? "null" : typeof raw}, not a list`);
+    const out = [];
+    const names = raw;
+    for (const name of names) {
+        if (!isPromptTraitName(name))
+            return refuse(`names ${typeof name === "string" ? JSON.stringify(name.slice(0, 64)) : typeof name}, not a trait`);
+        out.push(name);
+    }
+    return Object.freeze(out);
+}
 export function catalogFactsOf(facts) {
     return {
         policyEnabled: facts.policyEnabled,
@@ -27,18 +51,25 @@ export function catalogFactsOf(facts) {
     };
 }
 export function resolveHost(task) {
-    const refuse = (key, value, allowed) => {
-        throw Object.assign(new Error(`TaskSpec.${key} is ${typeof value === "string" ? JSON.stringify(value.slice(0, 64)) : typeof value}; it is one of ${allowed.map((a) => `"${a}"`).join(", ")} (or absent)`), {
-            code: "config.prompt_selector_invalid",
-        });
-    };
-    const role = task.promptRole === undefined ? undefined : isHostRole(task.promptRole) ? task.promptRole : refuse("promptRole", task.promptRole, HOST_ROLES);
-    const form = task.promptForm === undefined ? undefined : task.promptForm === "minimal" ? "minimal" : refuse("promptForm", task.promptForm, ["minimal"]);
+    const role = readPromptRole("TaskSpec.promptRole", task.promptRole);
+    const form = task.promptForm === undefined ? undefined : task.promptForm === "minimal" ? "minimal" : refuseSelector("TaskSpec.promptForm", task.promptForm, ['"minimal"']);
     return Object.freeze({ ...(role !== undefined ? { role } : {}), ...(form !== undefined ? { form } : {}) });
 }
-export function selectorsOf(facts, host = {}, binding) {
+export function resolvePromptLean(task) {
+    const v = task.promptLean;
+    return v === undefined || v === true || v === false ? v : refuseSelector("TaskSpec.promptLean", v, ["true", "false"]);
+}
+export function readPromptRole(seat, value) {
+    return value === undefined ? undefined : isHostRole(value) ? value : refuseSelector(seat, value, HOST_ROLES.map((a) => `"${a}"`));
+}
+function refuseSelector(seat, value, allowed) {
+    throw Object.assign(new Error(`${seat} is ${typeof value === "string" ? JSON.stringify(value.slice(0, 64)) : typeof value}; it is one of ${allowed.join(", ")} (or absent)`), {
+        code: "config.prompt_selector_invalid",
+    });
+}
+export function selectorsOf(facts, host = {}, binding, traits = effectiveTraitsOf(undefined, undefined)) {
     return Object.freeze({
-        traits: promptTraitsOf(facts),
+        traits,
         host: Object.freeze({ role: host.role ?? "general", form: host.form ?? "standard" }),
         facts: Object.freeze(catalogFactsOf(facts)),
         ...(binding !== undefined ? { binding } : {}),
@@ -60,7 +91,7 @@ export function factsHold(conj, facts) {
             return false;
     return true;
 }
-function traitsHold(cond, traits) {
+export function traitsHold(cond, traits) {
     if (cond === undefined)
         return true;
     return (cond.allOf ?? []).every((t) => traits.has(t)) && !(cond.noneOf ?? []).some((t) => traits.has(t));

package/dist/prompt-assembly/sugar.d.ts

@@ -1,31 +1,37 @@
 /**
  * The request-body sugar: the one place the task's role-layer prompt inputs are read and turned into overlays of
- * the `task` source class. Three inputs, one expression each:
+ * the `task` source class. Two inputs, one reading each:
  *
- * - the role base — `TaskSpec.systemPrompt ?? resolvedRole.systemPrompt ?? internals.defaultSystemPrompt` (the
- *   task's own text, else the role preset the task named, else the persona a core spawner hands its child) — a
- *   `replace` of `core/role.base`, applied after the selector chose the role base's variant;
- * - the appended block — `TaskSpec.appendSystemPrompt` — an `add` to the `task-append` band (entry
- *   `core/role.append`);
+ * - the role base — the first of three sources that names one decides it ({@link roleBaseOf}): the task (its door-judged
+ *   `promptRole` and its `systemPrompt`), then the requested model role's preset, then the persona a core spawner hands
+ *   its child (`internals.defaultSystemPrompt`). The deciding source's word is the run's host role; its text, when it
+ *   names one, is a `replace` of `core/role.base`, applied after the selector chose the variant;
+ * - the appended block — `TaskSpec.appendSystemPrompt` — an `add` to the `task-append` band (entry `core/role.append`);
  *
  * and nothing else reads them for assembly (`gate:sugar-single-site`). The sugar is applied first within its class,
  * the task-seat mods after it. Its one possible violation is locked text: a role-layer input carrying, verbatim,
  * the canonical text of a `constitution` entry is an already-assembled prompt, and the task is refused by name
  * (`prompt.assembled_role_refused`) — never passed through, never silently dropped.
  */
+import type { HostRole } from "./catalog/schema.js";
 import { type SourcedOverlay } from "./overlay.js";
+import { type RoleBaseDeclaration } from "./role-base.js";
 /** The task's role-layer prompt inputs, as prepare holds them. */
 export interface SugarInputs {
     readonly spec: {
         readonly systemPrompt?: string;
         readonly appendSystemPrompt?: string;
     };
-    readonly resolvedRole: {
-        readonly systemPrompt?: string;
-    };
+    /** The task seat's role word as its door judged it (`TaskSpec.promptRole`, `resolveHost`). */
+    readonly taskRole?: HostRole;
+    readonly resolvedRole: RoleBaseDeclaration;
     readonly internals?: {
         readonly defaultSystemPrompt?: string;
     };
 }
-/** The task-class overlays the request body carries, in application order (role base, then the appended block). */
-export declare function sugarOverlays(inputs: SugarInputs): readonly SourcedOverlay[];
+/** The task class's first overlays (role base, then the appended block) and the run's host role, from ONE decision. */
+export interface RequestBodySugar {
+    readonly overlays: readonly SourcedOverlay[];
+    readonly hostRole?: HostRole;
+}
+export declare function requestBodySugar(inputs: SugarInputs): RequestBodySugar;

package/dist/prompt-assembly/sugar.js

@@ -1,7 +1,12 @@
 import { assembledRoleRefused, lockedTextIn } from "./overlay.js";
+import { roleBaseOf } from "./role-base.js";
 const SUGAR = { source: "task", by: "sugar" };
-export function sugarOverlays(inputs) {
-    const roleBase = inputs.spec.systemPrompt ?? inputs.resolvedRole.systemPrompt ?? inputs.internals?.defaultSystemPrompt;
+export function requestBodySugar(inputs) {
+    const taskText = inputs.spec.systemPrompt;
+    const task = { ...(inputs.taskRole !== undefined ? { promptRole: inputs.taskRole } : {}), ...(taskText !== undefined ? { systemPrompt: taskText } : {}) };
+    const engineText = inputs.internals?.defaultSystemPrompt;
+    const decided = roleBaseOf([task, inputs.resolvedRole, engineText !== undefined ? { systemPrompt: engineText } : undefined]);
+    const roleBase = decided?.systemPrompt;
     const append = inputs.spec.appendSystemPrompt;
     const out = [];
     if (roleBase !== undefined) {
@@ -16,5 +21,5 @@ export function sugarOverlays(inputs) {
             throw assembledRoleRefused("the task's appendSystemPrompt", hits);
         out.push({ overlay: Object.freeze({ id: "core/role.append", op: "add", target: "task-append", text: append }), origin: SUGAR });
     }
-    return Object.freeze(out);
+    return Object.freeze({ overlays: Object.freeze(out), ...(decided?.promptRole !== undefined ? { hostRole: decided.promptRole } : {}) });
 }

package/dist/prompt-assembly/tool-catalog.d.ts

@@ -1,12 +1,15 @@
 import type { TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ProtocolId } from "../core/protocol-table.js";
+import { type PromptTraitName } from "./catalog/schema.js";
 /** The protocol slice comes from the protocol table — adding a protocol extends ProtocolId and this
  *  union follows automatically (the origin projection is table-driven, prepare-task). */
 export type ToolOrigin = "core" | "caller" | "synthetic" | ProtocolId;
 /** The origin a declared contract id names: a `core.` id is one of the engine's own contracts, any other id a caller's. The one
- *  reading of the prefix — the definition factory attaches by it, and the caller-tool door refuses a caller spec that declares one. */
+ *  reading of the prefix — the definition factory labels a descriptor by it, and the caller-tool door refuses a caller entry (a
+ *  spec's `contract`, a product's descriptor) that claims one the engine did not mint. */
 export declare function contractOriginOf(contractId: string): "core" | "caller";
+export declare function isEngineDescriptor(value: unknown): boolean;
 export interface ToolContractDescriptor {
     /** Stable contract identity, e.g. `core.read@2`. Versioned independently of the wire name. */
     contractId: string;
@@ -21,7 +24,9 @@ export interface ToolContractDescriptor {
     shapeDigest: string;
     /** Full materialized schema digest (incl. descriptions) — the model-visible wire face. */
     wireSchemaDigest: string;
-    /** The presentation card in effect. v1: `builtin:<wireName>` (the factory's inline text). */
+    /** The presentation card in effect ({@link cardIdOf}): `builtin:<wireName>` for a declared contract's card, the
+     *  undeclared-contract prefix for any other tool's, and `#<variant id>` after it when the mount chose one of the
+     *  description's variants (`descriptionVariants`) over its unconditional text. */
     cardId: string;
 }
 /**
@@ -47,6 +52,28 @@ export interface ToolManifestRow {
 }
 export declare function computeShapeDigest(schema: TSchema | undefined): string;
 export declare function computeWireSchemaDigest(schema: TSchema | undefined, description: string): string;
+/**
+ * The judge of a caller roster's card declarations where the roster enters, every entry the caller handed, mounted or not: the
+ * config-door phase (over the snapshot's faces) and a resume's screen before its claim (one function, so a resume's row stays
+ * pending). A description variant table the engine cannot read is refused (`config.tool_face_invalid`); an entry still carrying
+ * the retired `descriptionClassic` as plain data is refused by name (`config.deps_retired_key`) — the door and the sentence the
+ * snapshot gives the key on the LIVE entry under every reading of it (a prototype's getter, a non-enumerable member), so a face
+ * never carries one and the resume's screen is where this line fires. What the receipt cannot take without running the caller's
+ * code (an accessor, a Proxy, an entry of another prototype, a non-enumerable member) is not judged here: a variant table is
+ * judged again at the mount ({@link mountDescriptionVariant}), a retired member by the snapshot — on a resume, after the claim.
+ */
+export declare function assertToolCardDeclarations(tools: unknown): void;
+/**
+ * The face a run mounts for a tool under its prompt traits: the first of the tool's description variants whose trait
+ * condition holds over the run's traits replaces its description (a shallow copy carrying the chosen variant's id, so the
+ * card id reports it); none holds, or the tool declares none, ⇒ the card's unconditional text. A face some run already
+ * mounted is judged from its card again, never from the text that run chose. The selection reads traits through the
+ * catalog's own trait reading ({@link traitsHold}). A variant the engine cannot read refuses the task by name
+ * (`config.tool_face_invalid`) — never mounted as if the tool had one form. One function ({@link descriptionVariantsProblem})
+ * judges a table at both places: {@link assertToolCardDeclarations} over the entries the receipt can read as data, and here over
+ * every tool the run keeps after the exclusion valve — so a table the door could not read is judged when it is mounted.
+ */
+export declare function mountDescriptionVariant(tool: AgentTool, traits: ReadonlySet<PromptTraitName>): AgentTool;
 export interface AttachContractInput {
     contractId: string;
     implementationRevision: string;
@@ -54,8 +81,15 @@ export interface AttachContractInput {
     aliases?: string[];
 }
 /** Attach a contract descriptor to a materialized tool (factory exit point). Digests are computed
- *  from the tool's REAL mounted schema/description, so they always reflect the wire face. */
+ *  from the tool's REAL mounted schema/description, so they always reflect the wire face. A descriptor attached here is the
+ *  caller's word, whatever its `origin`: it is never the engine's mint ({@link attachEngineToolContract}). */
 export declare function attachToolContract(tool: AgentTool, input: AttachContractInput): void;
+/** The factory's attach for a contract the engine's catalog minted: the descriptor is itself recorded as the engine's mint, frozen
+ *  (its alias list included), so a roster door can tell a product the engine built from a definition from one a host dressed in a
+ *  `core.` id. Internal — not exported from the package root. */
+export declare function attachEngineToolContract(tool: AgentTool, input: AttachContractInput): void;
+/** The descriptor `tool` carries, as attached — no shape judgment and no copy. Internal: the caller-roster door reads the claim here. */
+export declare function attachedContractOf(tool: object): ToolContractDescriptor | undefined;
 /**
  * Resolve a tool's descriptor. Undeclared tools get a deterministic legacy descriptor derived from
  * their shape (`legacy:<shapeDigest>`), origin per the mount channel — an external tool NEVER

package/dist/prompt-assembly/tool-catalog.js

@@ -1,7 +1,16 @@
 import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { isPlainRecord, receive } from "../core/mods/kernel/receive.js";
+import { assertNoRetiredKeys, RETIRED_TOOL_SPEC_KEYS } from "../core/retired-keys.js";
+import { isPromptTraitName } from "./catalog/schema.js";
+import { traitsHold } from "./select.js";
 export function contractOriginOf(contractId) {
     return contractId.startsWith("core.") ? "core" : "caller";
 }
+const ENGINE_DESCRIPTORS = new WeakSet();
+export function isEngineDescriptor(value) {
+    return typeof value === "object" && value !== null && ENGINE_DESCRIPTORS.has(value);
+}
 const PRESENTATION_KEYWORDS = new Set(["description", "title", "examples", "$id"]);
 const SCHEMA_NAME_MAPS = new Set([
     "properties",
@@ -48,8 +57,96 @@ export function computeWireSchemaDigest(schema, description) {
     return sha(`${canonical(schema ?? null)}\u0000${description}`);
 }
 const TOOL_CONTRACT = Symbol("sema.toolContract");
-export function attachToolContract(tool, input) {
-    const descriptor = {
+const CARD_VARIANT = Symbol("sema.toolCardVariant");
+function cardIdOf(base, tool) {
+    const chosen = tool[CARD_VARIANT];
+    return chosen === undefined ? base : `${base}#${chosen.id}`;
+}
+const VARIANT_ID = /^[A-Za-z0-9._-]{1,64}$/;
+function descriptionVariantsProblem(variants) {
+    if (variants === undefined)
+        return undefined;
+    if (!Array.isArray(variants))
+        return "is not a list";
+    const ids = new Set();
+    const table = variants;
+    for (const [i, v] of table.entries()) {
+        const at = `descriptionVariants[${i}]`;
+        if (v === null || typeof v !== "object" || Array.isArray(v))
+            return `${at} is not an object`;
+        const r = v;
+        for (const k of Object.keys(r))
+            if (k !== "id" && k !== "traits" && k !== "text")
+                return `${at} carries ${JSON.stringify(k).slice(0, 40)} (id, traits, text only)`;
+        if (typeof r.id !== "string" || !VARIANT_ID.test(r.id))
+            return `${at}.id is not 1–64 characters of [A-Za-z0-9._-]`;
+        if (ids.has(r.id))
+            return `${at}.id ${JSON.stringify(r.id)} repeats an earlier variant's`;
+        ids.add(r.id);
+        if (typeof r.text !== "string" || r.text.trim() === "")
+            return `${at}.text is not a non-blank string`;
+        const t = r.traits;
+        if (t === null || typeof t !== "object" || Array.isArray(t))
+            return `${at}.traits is not an object`;
+        const lists = Object.entries(t);
+        if (lists.length === 0)
+            return `${at}.traits is empty (use \`description\`)`;
+        for (const [k, list] of lists) {
+            if (k !== "allOf" && k !== "noneOf")
+                return `${at}.traits carries ${JSON.stringify(k).slice(0, 40)} (allOf, noneOf only)`;
+            if (!Array.isArray(list) || list.length === 0)
+                return `${at}.traits.${k} is not a non-empty list`;
+            const names = list;
+            for (const name of names)
+                if (!isPromptTraitName(name))
+                    return `${at}.traits.${k} names ${typeof name === "string" ? JSON.stringify(name.slice(0, 64)) : typeof name}, not a trait`;
+        }
+    }
+    return undefined;
+}
+function descriptionVariantsRefusal(toolName, problem) {
+    const named = typeof toolName === "string" ? JSON.stringify(toolName.slice(0, 80)) : `(a ${typeof toolName} name)`;
+    return Object.assign(new Error(`tool ${named}: its ${problem.startsWith("descriptionVariants") ? problem : `descriptionVariants ${problem}`}`), { code: "config.tool_face_invalid" });
+}
+const ROSTER_CARD_RECEIPT = Object.freeze({ accessors: "refuse", depth: 6, others: "as-is", contain: true, isProxy: (v) => types.isProxy(v) });
+export function assertToolCardDeclarations(tools) {
+    const got = receive(tools, ROSTER_CARD_RECEIPT);
+    if (!got.ok || !Array.isArray(got.value))
+        return;
+    const unread = new Set();
+    for (const f of got.faults ?? []) {
+        const [at, member] = f.path;
+        if (at !== undefined && (member === "name" || member === "descriptionVariants" || member === "descriptionClassic"))
+            unread.add(at);
+    }
+    got.value.forEach((t, i) => {
+        if (!isPlainRecord(t) || unread.has(String(i)))
+            return;
+        assertNoRetiredKeys(t, RETIRED_TOOL_SPEC_KEYS, "ToolSpec");
+        const problem = descriptionVariantsProblem(t["descriptionVariants"]);
+        if (problem !== undefined)
+            throw descriptionVariantsRefusal(t["name"], problem);
+    });
+}
+export function mountDescriptionVariant(tool, traits) {
+    const variants = tool.descriptionVariants;
+    const problem = descriptionVariantsProblem(variants);
+    if (problem !== undefined)
+        throw descriptionVariantsRefusal(tool.name, problem);
+    const earlier = tool[CARD_VARIANT];
+    const unconditional = earlier?.unconditional ?? tool.description;
+    const chosen = tool.descriptionVariants?.find((v) => traitsHold(v.traits, traits));
+    if (chosen === undefined && earlier === undefined)
+        return tool;
+    const face = { ...tool, description: chosen?.text ?? unconditional };
+    if (chosen !== undefined)
+        face[CARD_VARIANT] = Object.freeze({ id: chosen.id, unconditional });
+    else
+        delete face[CARD_VARIANT];
+    return face;
+}
+function descriptorOf(tool, input) {
+    return {
         contractId: input.contractId,
         implementationRevision: input.implementationRevision,
         wireName: tool.name,
@@ -59,8 +156,20 @@ export function attachToolContract(tool, input) {
         wireSchemaDigest: computeWireSchemaDigest(tool.parameters, tool.description ?? ""),
         cardId: `builtin:${tool.name}`,
     };
+}
+export function attachToolContract(tool, input) {
+    tool[TOOL_CONTRACT] = descriptorOf(tool, input);
+}
+export function attachEngineToolContract(tool, input) {
+    const descriptor = descriptorOf(tool, input);
+    if (descriptor.aliases !== undefined)
+        descriptor.aliases = Object.freeze([...descriptor.aliases]);
+    ENGINE_DESCRIPTORS.add(Object.freeze(descriptor));
     tool[TOOL_CONTRACT] = descriptor;
 }
+export function attachedContractOf(tool) {
+    return tool[TOOL_CONTRACT];
+}
 export function getToolContract(tool, fallbackOrigin = "caller") {
     const attached = tool[TOOL_CONTRACT];
     if (attached) {
@@ -74,7 +183,7 @@ export function getToolContract(tool, fallbackOrigin = "caller") {
                 origin: attached.origin,
                 shapeDigest: mountedShape,
                 wireSchemaDigest: computeWireSchemaDigest(tool.parameters, tool.description ?? ""),
-                cardId: `legacy:${tool.name}`,
+                cardId: cardIdOf(`legacy:${tool.name}`, tool),
             };
         }
         return {
@@ -82,6 +191,7 @@ export function getToolContract(tool, fallbackOrigin = "caller") {
             wireName: tool.name,
             shapeDigest: mountedShape,
             wireSchemaDigest: computeWireSchemaDigest(tool.parameters, tool.description ?? ""),
+            cardId: cardIdOf(attached.cardId, tool),
         };
     }
     const shapeDigest = computeShapeDigest(tool.parameters);
@@ -93,7 +203,7 @@ export function getToolContract(tool, fallbackOrigin = "caller") {
         origin: fallbackOrigin,
         shapeDigest,
         wireSchemaDigest: computeWireSchemaDigest(tool.parameters, tool.description ?? ""),
-        cardId: `legacy:${tool.name}`,
+        cardId: cardIdOf(`legacy:${tool.name}`, tool),
     };
 }
 export function hasToolContract(tool) {