@sema-agent/core 7.55.0 → 7.57.0

package/dist/orchestration/workflow.js

@@ -1,4 +1,4 @@
-import { resolveModelDisplayLabel } from "../core/roles.js";
+import { presetRoleBaseOf, resolveModelDisplayLabel } from "../core/roles.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import { availableParallelism } from "node:os";
@@ -9,7 +9,8 @@ import { terminalProjection } from "../core/runner/terminal-projection.js";
 import { steeringError } from "../core/runner/steer-admission.js";
 import { builtinAgentDefinitions } from "../agents/builtin-agents.js";
 import { GENERAL_PURPOSE_SUBAGENT_TYPE, markerFragment } from "../agents/subagent.js";
-import { deploymentSubagentSystemPrompt, runnerRoleMap } from "../agents/child-model-seat.js";
+import { runnerRoleMap } from "../agents/child-model-seat.js";
+import { namesRoleBase } from "../prompt-assembly/role-base.js";
 import { combinePolicies, createAllowDenyPolicy } from "../core/tool-policy.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
 import { callKeyOrdinal, clampRunIdText, oversizeJournalResult, journalOversizeTombstone, readWorkflowJournalEntry, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES, WorkflowJournalIncompatibleError, } from "../core/workflow-journal-store.js";
@@ -21,6 +22,7 @@ import { boundedRedactedSummary, egressThrownText } from "../core/untrusted-egre
 import { delimitUntrusted } from "../core/untrusted-text.js";
 import { OUTPUT_TOOL_NAME } from "../core/tool-catalog-entries.js";
 import { deniedToolNamesOf, judgeHostToolCeiling } from "../core/runner/sub-agent-deny-lists.js";
+import { namesEveryTool } from "../agents/tool-filter.js";
 import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
 import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
@@ -104,7 +106,7 @@ export function applyWorkflowAgentType(spec, agentType, registry) {
         throw new Error(`agent(): unknown agentType "${agentType}". Known types: ${known}. Pass a registered agent type, or omit agentType for the default workflow subagent.`);
     }
     const out = { ...spec };
-    if (out.systemPrompt === undefined && def.systemPrompt !== undefined)
+    if (!namesRoleBase(out) && def.systemPrompt !== undefined)
         out.systemPrompt = def.systemPrompt;
     if (out.model === undefined && def.model !== undefined)
         out.model = def.model;
@@ -120,7 +122,8 @@ export function applyWorkflowAgentType(spec, agentType, registry) {
     if (out.memoryPersistenceCapable === undefined && def.memoryPersistenceCapable !== undefined)
         out.memoryPersistenceCapable = def.memoryPersistenceCapable;
     if (def.allowTools !== undefined || def.denyTools !== undefined) {
-        const perType = createAllowDenyPolicy({ ...(def.allowTools ? { allow: def.allowTools } : {}), ...(def.denyTools ? { deny: deniedToolNamesOf(`workflow agentType "${def.name}"`, def.denyTools) } : {}) });
+        const allow = def.allowTools !== undefined && !def.allowTools.some(namesEveryTool) ? def.allowTools : undefined;
+        const perType = createAllowDenyPolicy({ ...(allow ? { allow } : {}), ...(def.denyTools ? { deny: deniedToolNamesOf(`workflow agentType "${def.name}"`, def.denyTools) } : {}) });
         out.toolPolicy = out.toolPolicy ? combinePolicies(out.toolPolicy, perType) : perType;
     }
     return out;
@@ -132,21 +135,29 @@ export function workflowAgentRegistry(opts) {
     return [...deployment, ...builtins];
 }
 function withWorkflowChildPersona(spec, schema) {
-    if (spec.systemPrompt === undefined) {
+    if (!namesRoleBase(spec)) {
         return { ...spec, systemPrompt: schema ? WORKFLOW_SUBAGENT_PROMPT_SCHEMA : WORKFLOW_SUBAGENT_PROMPT };
     }
     const note = schema ? WORKFLOW_SUBAGENT_APPEND_SCHEMA : WORKFLOW_SUBAGENT_APPEND;
     return { ...spec, appendSystemPrompt: spec.appendSystemPrompt ? `${spec.appendSystemPrompt}\n\n${note}` : note };
 }
 function withWorkflowChildSeats(typed, inheritedModelSnap, inheritedThinkingSnap, roles) {
-    const statedPersona = deploymentSubagentSystemPrompt(roles);
-    return {
+    const seated = {
         ...typed,
         modelRole: typed.modelRole === undefined ? "subagent" : typed.modelRole,
         ...(typed.model === undefined && inheritedModelSnap !== undefined ? { model: inheritedModelSnap } : {}),
         ...(typed.thinking === undefined && inheritedThinkingSnap !== undefined ? { thinking: inheritedThinkingSnap } : {}),
-        ...(typed.systemPrompt === undefined && statedPersona !== undefined ? { systemPrompt: statedPersona } : {}),
     };
+    if (namesRoleBase(seated))
+        return seated;
+    let preset;
+    try {
+        preset = presetRoleBaseOf(seated, { roles });
+    }
+    catch {
+        preset = undefined;
+    }
+    return { ...seated, ...preset };
 }
 export function workflowAgentCallKey(ordinal, spec, opts) {
     const identity = {
@@ -525,6 +536,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     }
     const now = opts.now ?? (() => Date.now());
     const scope = opts.scope ?? "default";
+    const parkedResume = opts.parkedResume, claimHolder = opts.holder;
     const runId = opts.runId ?? randomUUID();
     if (opts.runId !== undefined && isWorkflowRunActive(opts.runId)) {
         throw new Error(`startWorkflow: runId "${opts.runId}" is already an active workflow run in this process`);
@@ -870,7 +882,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         const p = parkedLeg;
         return new WorkflowAgentParkedError(p.label, p.paused.terminal.gate.kind, p.paused.terminal.checkpointId);
     };
-    const parkedResumeFor = (token) => opts.parkedResume?.find((d) => d.token === token);
+    const parkedResumeFor = (token) => parkedResume?.find((d) => d.token === token);
     const parkedCallChangedError = (ordinal) => Object.assign(new Error(`workflow resume: ordinal ${ordinal} is PARKED on an approval checkpoint, but the call at that ordinal changed (its call key differs from the journaled one) ` +
         (divergence === undefined
             ? "while no earlier call diverged from the record — the difference is in this call's own inputs (the script, its args, or a host input folded into the call identity). "
@@ -949,6 +961,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
         terminal: { kind: "paused", gate: cp.gate, token: cp.token, ...(cp.checkpointId !== undefined ? { checkpointId: cp.checkpointId } : {}) },
     });
+    const driveInternals = (base, drive) => ({ ...base, ...(drive.inheritedGate !== undefined ? { inheritedGate: drive.inheritedGate } : {}), ...(claimHolder !== undefined ? { holder: claimHolder } : {}) });
+    const driveRefusalText = (err, drive) => {
+        const text = withoutToken(errText(err), drive.token);
+        return claimHolder === undefined || claimHolder === "" ? text : text.split(claimHolder).join("<holder>");
+    };
     const disposeParkedOrdinal = (truth, ordinal, callKey) => {
         if (truth.key.callKey !== callKey)
             throw parkedCallChangedError(ordinal);
@@ -965,7 +982,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     code: "workflow.park_not_pending",
                     message: `the approval checkpoint this call was parked on is ${truth.status}${truth.checkpointId !== undefined ? ` (checkpoint ${truth.checkpointId})` : ""} — decided, expired or reaped outside this workflow; settled as failed on the resume's acknowledgement. The call did not run.`,
                 },
-                result: "",
+                result: "", resultEntryIds: [],
                 stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
             };
             return { kind: "settle", result };
@@ -1433,6 +1450,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     objective,
                     tools: toolNames,
                     ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+                    ...(runSpec.promptRole !== undefined ? { promptRole: runSpec.promptRole } : {}),
                     ...(schemaText !== undefined ? { outputSchema: schemaText } : {}),
                     ...(imageCount > 0 ? { uninspectedImageAttachments: imageCount } : {}),
                     ...(remoteSources.length > 0 ? { externalCapabilitySources: shownSources } : {}),
@@ -1749,7 +1767,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                                 ? runner.runTaskStream(attemptSpec, undefined, attemptInternals)
                                 : await (() => {
                                     const { objective: _o, sessionId: _s, ...resumeConfig } = attemptSpec;
-                                    return runner.resumeStream(drive.token, drive.outcome, resumeConfig, { ...attemptInternals, ...(drive.inheritedGate !== undefined ? { inheritedGate: drive.inheritedGate } : {}) });
+                                    return runner.resumeStream(drive.token, drive.outcome, resumeConfig, driveInternals(attemptInternals, drive));
                                 })();
                             for await (const ev of stream) {
                                 if (ev.type === "text_delta" || ev.type === "reasoning_delta")
@@ -1849,7 +1867,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             catch (err) {
                 if (drive !== undefined && !finalized && !thrownIs(err, WorkflowAgentParkedError)) {
-                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${withoutToken(errText(err), drive.token)}); the park stands.`);
+                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before this run consumed the checkpoint (${driveRefusalText(err, drive)}); the park stands on this run's record.`);
                     release();
                     return await parkAgentLeg(rec, drive.paused, activityTail, false);
                 }
@@ -1893,7 +1911,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     const journaled = journalAppend(callKey, salvaged ?? {
                         taskId: callKey,
                         sessionId: "",
-                        result: boundedRedactedSummary(thrownText(err), 500),
+                        result: boundedRedactedSummary(thrownText(err), 500), resultEntryIds: [],
                         terminal: {
                             kind: "failed",
                             ...(thrownIs(err, WorkflowAgentBlockedError) ? { code: WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } : thrownIs(err, WorkflowBudgetExceededError) ? { code: err.code } : {}),
@@ -1993,7 +2011,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     taskId: callKey,
                     sessionId: "",
                     terminal: { kind: "failed", code: refusal.code, message: boundedRedactedSummary(refusal.message, 500) },
-                    result: boundedRedactedSummary(refusal.message, 500),
+                    result: boundedRedactedSummary(refusal.message, 500), resultEntryIds: [],
                     stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
                 }).catch(() => undefined);
                 throw refusal;
@@ -2052,12 +2070,12 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     : await workflowDepthStore.run({ depth: depth + 1 }, () => {
                         const d = drive;
                         const { objective: _o, sessionId: _s, ...resumeConfig } = runSpec;
-                        return runner.resumeStream(d.token, d.outcome, resumeConfig, { ...runInternals, ...(d.inheritedGate !== undefined ? { inheritedGate: d.inheritedGate } : {}) });
+                        return runner.resumeStream(d.token, d.outcome, resumeConfig, driveInternals(runInternals, d));
                     });
             }
             catch (err) {
                 if (drive !== undefined && !finalized) {
-                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${withoutToken(errText(err), drive.token)}); the park stands.`);
+                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before this run consumed the checkpoint (${driveRefusalText(err, drive)}); the park stands on this run's record.`);
                     releaseLeg();
                     return await parkAgentLeg(rec, drive.paused, [], false);
                 }
@@ -2076,7 +2094,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         taskId: callKey,
                         sessionId: "",
                         terminal: { kind: "failed", code: WORKFLOW_SPAWN_BLOCKED_ERROR_CODE, message: boundedRedactedSummary(refusal.message, 500) },
-                        result: boundedRedactedSummary(refusal.message, 500),
+                        result: boundedRedactedSummary(refusal.message, 500), resultEntryIds: [],
                         stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
                     }).catch(() => undefined);
                 }
@@ -2124,7 +2142,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         taskId: callKey,
                         sessionId: "",
                         terminal: { kind: "failed", message: boundedRedactedSummary(thrownText(err), 500) },
-                        result: boundedRedactedSummary(thrownText(err), 500),
+                        result: boundedRedactedSummary(thrownText(err), 500), resultEntryIds: [],
                         stats: { turns: partialSpend?.turns ?? 0, tokens: partialSpend?.tokens ?? 0, costMicroUsd: partialSpend?.costMicroUsd ?? 0 },
                     }).catch(() => undefined);
                     bceTerminal(callKey, "failed", thrownText(err), undefined, rec.stats);

package/dist/primitives/credential-ref.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The credential reference: how a declaration names a credential without carrying one. This module says which references
+ * exist and whether a value is one, so the engine's door, an acceptance gate, a settings validator and an admin form read
+ * one closed set through one function. It resolves nothing, reads no environment and holds no state.
+ * Zero dependencies: no builtin, no import, so the same file runs in Node and in a browser.
+ */
+/** The closed set of kinds. A value whose `kind` is not in it is refused, never guessed at. */
+export declare const CREDENTIAL_REF_KINDS: readonly ["env", "vault", "handle", "assertion"];
+export type CredentialRefKind = (typeof CREDENTIAL_REF_KINDS)[number];
+/**
+ * A reference, by kind. `env` names variables of the resolver's environment (header name → variable name for an http
+ * peer, child variable → variable name for a stdio peer; the maps have no prototype); `vault` names a stored entry;
+ * `handle` is an opaque id the deployment minted; `assertion` names the audience a short-lived assertion is requested for.
+ */
+export type CredentialRef = {
+    readonly kind: "env";
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly env?: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "vault";
+    readonly entry: string;
+} | {
+    readonly kind: "handle";
+    readonly id: string;
+} | {
+    readonly kind: "assertion";
+    readonly audience: string;
+};
+/** What an acceptance gate may do with a reference that arrives on the request surface (the deployment may write any kind). */
+export type CredentialRefRequestAdmission = "refused" | "own_entry";
+type TrustRow = {
+    readonly request: CredentialRefRequestAdmission;
+};
+/**
+ * Where each kind may come from. `refused`: a request surface may not carry it (an environment name would read any
+ * variable of the resolver's process, a handle names someone else's credential, an assertion is minted by the deployment);
+ * `own_entry`: only for an entry that belongs to the submitting principal. A row per kind and nothing else (no prototype);
+ * look a kind up only after `readCredentialRef` accepted the value. A shape for a gate to read; it authenticates nothing.
+ */
+export declare const CREDENTIAL_REF_TRUST: Readonly<Record<CredentialRefKind, TrustRow>>;
+/** The longest text member (entry, id, audience, header name, variable name) a reference may carry, in UTF-16 code units. */
+export declare const CREDENTIAL_REF_TEXT_MAX = 2048;
+/** The most entries one name map (`headers`, `env`) of an `env` reference may hold. */
+export declare const CREDENTIAL_REF_MAP_MAX = 64;
+/** Why a value is not a reference; each reason is its own exit. */
+export declare const CREDENTIAL_REF_PROBLEM_REASONS: readonly ["not_a_record", "unknown_kind", "missing_field", "extra_field", "bad_value"];
+export type CredentialRefProblemReason = (typeof CREDENTIAL_REF_PROBLEM_REASONS)[number];
+/**
+ * The first fault found, in this order: not an ordinary record; `kind` missing, not text or outside the set; a member the
+ * kind does not have; a member it needs (for `env`, one of `headers` and `env`, written `headers|env`); a member of the
+ * wrong form. A `kind` or `field` read off the caller's value is untrusted text, cut to 64 characters with unsafe
+ * characters replaced; fence it before rendering it where markup is interpreted.
+ */
+export type CredentialRefProblem = {
+    readonly reason: "not_a_record";
+} | {
+    readonly reason: "unknown_kind";
+    readonly kind: string;
+} | {
+    readonly reason: "missing_field";
+    readonly kind?: CredentialRefKind;
+    readonly field: string;
+} | {
+    readonly reason: "extra_field";
+    readonly kind: CredentialRefKind;
+    readonly field: string;
+} | {
+    readonly reason: "bad_value";
+    readonly kind?: CredentialRefKind;
+    readonly field: string;
+};
+export type CredentialRefReading = {
+    readonly ok: true;
+    readonly ref: CredentialRef;
+} | {
+    readonly ok: false;
+    readonly problem: CredentialRefProblem;
+};
+/**
+ * The one reader of a credential reference: a fresh frozen copy that the caller's later writes cannot reach (forward the
+ * copy, never the value read), or the first problem. Nothing inside it throws: a value whose members cannot be read (a
+ * revoked or throwing Proxy) is `not_a_record`, or the `bad_value` of the map that holds it. A getter is refused and never
+ * called, no prototype is read for a member, and a Proxy's own traps (on the value, its maps or its prototype) are the
+ * caller's code and run as for any property read. Text is compared as written: nothing is normalised, and visually
+ * confusable text is not judged. With no stack left a valid value may be refused (any reason), never an invalid one
+ * accepted, and the call itself may throw a `RangeError` before it is entered.
+ */
+export declare function readCredentialRef(value: unknown): CredentialRefReading;
+export {};

package/dist/primitives/credential-ref.js

@@ -0,0 +1,125 @@
+export const CREDENTIAL_REF_KINDS = Object.freeze(["env", "vault", "handle", "assertion"]);
+export const CREDENTIAL_REF_TRUST = trustTable();
+function trustTable() {
+    const rows = Object.create(null);
+    rows.env = Object.freeze({ request: "refused" });
+    rows.vault = Object.freeze({ request: "own_entry" });
+    rows.handle = Object.freeze({ request: "refused" });
+    rows.assertion = Object.freeze({ request: "refused" });
+    return Object.freeze(rows);
+}
+export const CREDENTIAL_REF_TEXT_MAX = 2048;
+export const CREDENTIAL_REF_MAP_MAX = 64;
+export const CREDENTIAL_REF_PROBLEM_REASONS = Object.freeze(["not_a_record", "unknown_kind", "missing_field", "extra_field", "bad_value"]);
+const MEMBERS = {
+    env: ["headers", "env"],
+    vault: ["entry"],
+    handle: ["id"],
+    assertion: ["audience"],
+};
+const TEXT_MEMBER = { vault: "entry", handle: "id", assertion: "audience" };
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ECHO_MAX = 64;
+const UNSAFE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{DI}\p{NChar}\p{Co}\ud800-\udfff]/u;
+const UNSAFE_ALL = new RegExp(UNSAFE.source, "gu");
+const ABSENT = Object.freeze({ found: "absent" });
+const ACCESSOR = Object.freeze({ found: "accessor" });
+const NOT_A_RECORD = Object.freeze({ ok: false, problem: Object.freeze({ reason: "not_a_record" }) });
+function isRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || Object.getPrototypeOf(proto) === null;
+}
+function member(record, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (descriptor === undefined || descriptor.enumerable !== true)
+        return ABSENT;
+    return Object.hasOwn(descriptor, "value") ? { found: "value", value: descriptor.value } : ACCESSOR;
+}
+const echo = (text) => text.slice(0, ECHO_MAX).replace(UNSAFE_ALL, "?");
+const refused = (problem) => Object.freeze({ ok: false, problem: Object.freeze(problem) });
+const accepted = (ref) => Object.freeze({ ok: true, ref });
+const isText = (value) => typeof value === "string" && value.length > 0 && value.length <= CREDENTIAL_REF_TEXT_MAX && !UNSAFE.test(value) && value === value.trim();
+const isName = (value, form) => value.length <= CREDENTIAL_REF_TEXT_MAX && form.test(value);
+function nameMap(value, keyForm, foldCase) {
+    try {
+        if (!isRecord(value))
+            return undefined;
+        const names = Object.keys(value);
+        if (names.length === 0 || names.length > CREDENTIAL_REF_MAP_MAX)
+            return undefined;
+        const out = Object.create(null);
+        const folded = new Set();
+        for (const name of names) {
+            const found = member(value, name);
+            if (found.found !== "value" || typeof found.value !== "string")
+                return undefined;
+            if (!isName(name, keyForm) || !isName(found.value, ENV_NAME))
+                return undefined;
+            if (foldCase) {
+                const key = name.toLowerCase();
+                if (folded.has(key))
+                    return undefined;
+                folded.add(key);
+            }
+            out[name] = found.value;
+        }
+        return Object.freeze(out);
+    }
+    catch {
+        return undefined;
+    }
+}
+const mapOf = (found, keyForm, foldCase) => (found.found === "value" ? nameMap(found.value, keyForm, foldCase) : undefined);
+function envRef(record) {
+    const given = { headers: member(record, "headers"), env: member(record, "env") };
+    if (given.headers.found === "absent" && given.env.found === "absent")
+        return refused({ reason: "missing_field", kind: "env", field: "headers|env" });
+    const headers = mapOf(given.headers, HEADER_NAME, true);
+    if (given.headers.found !== "absent" && headers === undefined)
+        return refused({ reason: "bad_value", kind: "env", field: "headers" });
+    const env = mapOf(given.env, ENV_NAME, false);
+    if (given.env.found !== "absent" && env === undefined)
+        return refused({ reason: "bad_value", kind: "env", field: "env" });
+    return accepted(Object.freeze({ kind: "env", ...(headers === undefined ? {} : { headers }), ...(env === undefined ? {} : { env }) }));
+}
+function read(value) {
+    if (!isRecord(value))
+        return NOT_A_RECORD;
+    const named = member(value, "kind");
+    if (named.found === "absent")
+        return refused({ reason: "missing_field", field: "kind" });
+    if (named.found !== "value" || typeof named.value !== "string")
+        return refused({ reason: "bad_value", field: "kind" });
+    const text = named.value;
+    const kind = CREDENTIAL_REF_KINDS.find((k) => k === text);
+    if (kind === undefined)
+        return refused({ reason: "unknown_kind", kind: echo(text) });
+    for (const key of Object.keys(value)) {
+        if (key !== "kind" && !MEMBERS[kind].includes(key))
+            return refused({ reason: "extra_field", kind, field: echo(key) });
+    }
+    if (kind === "env")
+        return envRef(value);
+    const field = TEXT_MEMBER[kind];
+    const found = member(value, field);
+    if (found.found === "absent")
+        return refused({ reason: "missing_field", kind, field });
+    if (found.found !== "value" || !isText(found.value))
+        return refused({ reason: "bad_value", kind, field });
+    if (kind === "vault")
+        return accepted(Object.freeze({ kind, entry: found.value }));
+    if (kind === "handle")
+        return accepted(Object.freeze({ kind, id: found.value }));
+    return accepted(Object.freeze({ kind, audience: found.value }));
+}
+export function readCredentialRef(value) {
+    try {
+        return read(value);
+    }
+    catch {
+        return NOT_A_RECORD;
+    }
+}

package/dist/primitives/index.d.ts

@@ -0,0 +1,2 @@
+/** The package entry of `@sema-agent/primitives`; core reads the same modules directly. */
+export { CREDENTIAL_REF_KINDS, CREDENTIAL_REF_TRUST, CREDENTIAL_REF_TEXT_MAX, CREDENTIAL_REF_MAP_MAX, CREDENTIAL_REF_PROBLEM_REASONS, readCredentialRef, type CredentialRef, type CredentialRefKind, type CredentialRefRequestAdmission, type CredentialRefProblem, type CredentialRefProblemReason, type CredentialRefReading, } from "./credential-ref.js";

package/dist/primitives/index.js

@@ -0,0 +1 @@
+export { CREDENTIAL_REF_KINDS, CREDENTIAL_REF_TRUST, CREDENTIAL_REF_TEXT_MAX, CREDENTIAL_REF_MAP_MAX, CREDENTIAL_REF_PROBLEM_REASONS, readCredentialRef, } from "./credential-ref.js";

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

@@ -1,4 +1,4 @@
-import { type OverlayOp, type PromptTrait } from "./catalog/schema.js";
+import { type OverlayOp, type PromptTraitName } from "./catalog/schema.js";
 import { type PromptOverlay, type SourcedOverlay } from "./overlay.js";
 /** What an artifact needs from the engine that composes it: the targets it names (each with what kind of target it
  *  is), the operations it uses, the traits its `when` conditions read, and the bindings they name. */
@@ -8,7 +8,7 @@ export interface PromptArtifactRequires {
         readonly kind: "message" | "section" | "band";
     }[];
     readonly ops: readonly OverlayOp[];
-    readonly traits: readonly PromptTrait[];
+    readonly traits: readonly PromptTraitName[];
     readonly bindings: readonly string[];
 }
 /** Why the artifact exists: an intent sentence (required) and references to the evaluations or goldens behind it. */

package/dist/prompt-assembly/artifact.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { isBandId } from "./bands.js";
 import { SEMA_DEFAULT_CATALOG } from "./catalog/index.js";
-import { OVERLAY_OPS, PROMPT_TRAITS, isWordOf } from "./catalog/schema.js";
+import { OVERLAY_OPS, PROMPT_TRAIT_BUNDLES, PROMPT_TRAITS, isPromptTraitName, isWordOf } from "./catalog/schema.js";
 import { canonical } from "./epoch.js";
 import { codePointsOver, sectionOfMessage, validateOverlay } from "./overlay.js";
 export const ARTIFACT_LIMITS = Object.freeze({
@@ -41,10 +41,12 @@ export function requiresOf(overlays) {
             bindings.add(b);
     }
     const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    const vocabulary = [...PROMPT_TRAITS, ...Object.keys(PROMPT_TRAIT_BUNDLES)];
+    const rank = (t) => (vocabulary.includes(t) ? vocabulary.indexOf(t) : vocabulary.length);
     return {
         targets: [...targets.values()].sort((a, b) => byText(`${a.kind}:${a.id}`, `${b.kind}:${b.id}`)),
         ops: OVERLAY_OPS.filter((op) => ops.has(op)),
-        traits: PROMPT_TRAITS.filter((t) => traits.has(t)),
+        traits: [...traits].sort((a, b) => rank(a) - rank(b) || byText(a, b)),
         bindings: [...bindings].sort(byText),
     };
 }
@@ -59,7 +61,7 @@ export function unmetRequirements(requires) {
         if (!isWordOf(OVERLAY_OPS, op))
             unmet.push(`op "${String(op)}"`);
     for (const tr of requires.traits)
-        if (!isWordOf(PROMPT_TRAITS, tr))
+        if (!isPromptTraitName(tr))
             unmet.push(`trait "${String(tr)}"`);
     return unmet;
 }

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

@@ -9,7 +9,7 @@
  * skipped).
  */
 import type { AgentTool } from "../internal/harness-types.js";
-import type { HostForm, HostRole } from "./catalog/schema.js";
+import type { HostForm, HostRole, PromptTraitName } from "./catalog/schema.js";
 import { type SourcedOverlay, type SupersededOverlay } from "./overlay.js";
 import type { CompiledSection, CompiledSystemBlock, PromptRuntimeFacts } from "./types.js";
 export interface AssembleInputs {
@@ -26,6 +26,8 @@ export interface AssembleInputs {
     };
     /** The run's binding (`TaskSpec.promptBinding`), read by every overlay's `when.binding`. */
     binding?: string;
+    /** The run's effective traits (the model's declared set, the task's `promptLean`, bundles expanded). */
+    traits: ReadonlySet<PromptTraitName>;
     tools: readonly AgentTool[];
     facts: PromptRuntimeFacts;
     /** The task's working directory (the Cowork role base's `{{workspaceFolder}}`). */
@@ -36,7 +38,6 @@ export interface AssembleInputs {
     buildEnvBlock: (date: string) => string | undefined;
     /** The leg's frozen date — the initial render input. */
     date: string;
-    modelGuidance?: string;
     /** Structured warning channel (maps to deps.onError with a phase). */
     onWarn?: (message: string, phase: "prompt-constitution") => void;
 }

package/dist/prompt-assembly/assemble.js

@@ -18,6 +18,7 @@ export function assemblePrompt(inputs) {
         catalog: SEMA_DEFAULT_CATALOG,
         ...(inputs.host !== undefined ? { host: inputs.host } : {}),
         ...(inputs.binding !== undefined ? { binding: inputs.binding } : {}),
+        traits: inputs.traits,
         overlays: [...inputs.taskOverlays, ...inputs.centerOverlays, ...inputs.deployOverlays],
     };
     const toolNames = inputs.tools.map((t) => t.name);
@@ -28,7 +29,6 @@ export function assemblePrompt(inputs) {
         mcpInstructionsBlock: inputs.mcpInstructionsBlock,
         environmentBlock: inputs.buildEnvBlock(date),
         memoryBlock: inputs.memoryBlock,
-        modelGuidance: inputs.modelGuidance,
     });
     let last = composeCatalog(plan, renderInputs(inputs.date));
     const named = new Set();

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

@@ -45,13 +45,39 @@ export interface HostCondition {
     readonly form?: HostForm;
 }
 /**
- * The model-capability traits a variant may be selected on — the reference's capability names, spelled
- * as the reference spells them, so an anchor upgrade can be diffed mechanically. The producer
- * ({@link import("../select.js").promptTraitsOf}) yields exactly these two today; a name joins this set when a
- * producer can yield it, never before.
+ * The model-capability traits a variant may be selected on: the reference's capability names that gate
+ * model-visible text, spelled as the reference spells them so an anchor upgrade diffs mechanically
+ * (cli296.js B[7451052,7451700) `fvo` is the reference's whole capability list; its members that gate no text —
+ * effort, thinking, context-management, fast-mode, refusal-fallback and org-lock bits — are not prompt traits).
+ * A model declares the traits it would light in the reference (`Model.promptTraits`); the engine never derives
+ * them from a model id. Order is meaning only for the artifact requirement list (`requiresOf`), which lists the
+ * names it needs in this order, so a name is appended here, never inserted.
  */
-export declare const PROMPT_TRAITS: readonly ["lean_prompt", "fable_5_mitigations"];
+export declare const PROMPT_TRAITS: readonly ["lean_prompt", "fable_5_mitigations", "thrifty_sonic", "turn_updates", "bash_output_audience_note", "silent_turn_reminder", "thinking_display_updates", "quizzical_shore", "lucky_cerf", "amber_astrolabe", "bison_cairn", "larch_cistern", "haiku_5_5_early_stopping_guidance", "elapsed_time_reminder"];
 export type PromptTrait = (typeof PROMPT_TRAITS)[number];
+/**
+ * The reference's bundle capabilities and the traits each lights (cli296.js B[10825000,10826100) `t$` — its three
+ * member sets). A model may declare a bundle by name; its effective trait set holds the bundle name and every member.
+ * No remote switch turns a member off here: a deployment that wants one member off declares the members it wants.
+ */
+export declare const PROMPT_TRAIT_BUNDLES: Readonly<Record<"fable_5_1_prompt_bundle" | "opus_5_prompt_bundle" | "opus_5_5_prompt_bundle", readonly PromptTrait[]>>;
+export type PromptTraitBundle = keyof typeof PROMPT_TRAIT_BUNDLES;
+/** A deployment's own trait: `x-<namespace>-<name>`. The engine checks the spelling and gives it no meaning — an
+ *  overlay whose `when.traits` names it is what makes it select anything. */
+export type DeploymentPromptTrait = `x-${string}-${string}`;
+/** Every name a model may declare and an overlay's `when.traits` may name. */
+export type PromptTraitName = PromptTrait | PromptTraitBundle | DeploymentPromptTrait;
+/** The names a bundled catalog variant may select on: the reference's (a deployment's own trait has no meaning in
+ *  the engine's text). */
+export type CatalogPromptTrait = PromptTrait | PromptTraitBundle;
+/** The longest trait name the engine accepts. */
+export declare const PROMPT_TRAIT_NAME_MAX = 64;
+/** Whether a value is a trait name — the one reading the model door (`Model.promptTraits`), the overlay grammar
+ *  (`when.traits`) and the artifact requirement check share: a reference trait, a bundle, or a deployment's own
+ *  `x-<namespace>-<name>` of at most {@link PROMPT_TRAIT_NAME_MAX} characters. */
+export declare function isPromptTraitName(v: unknown): v is PromptTraitName;
+/** The members a trait name lights besides itself (a bundle's members; none for any other name). */
+export declare function bundleMembersOf(name: PromptTraitName): readonly PromptTrait[];
 /** The boolean facts a section admit or a variant `when` may test. All but the last are runtime facts the
  *  prepare phase produces; `executionEnvironmentDeclared` is derived once from two of them, so no `when`
  *  ever needs a disjunction. An optional fact that is absent reads as `false`. */
@@ -60,8 +86,8 @@ export type PromptFactName = (typeof PROMPT_FACT_NAMES)[number];
 /** A conjunction of fact equalities — the whole predicate language. No disjunction, no expressions. */
 export type FactConjunction = Readonly<Partial<Record<PromptFactName, boolean>>>;
 export interface TraitCondition {
-    readonly allOf?: readonly PromptTrait[];
-    readonly noneOf?: readonly PromptTrait[];
+    readonly allOf?: readonly PromptTraitName[];
+    readonly noneOf?: readonly PromptTraitName[];
 }
 /** How a text relates to the reference. `cc` entries use the byte-span locator grammar the anchor gate resolves
  *  (scripts/verify-anchor-claims.mjs): corpus file, byte span, and a backticked identifier that occurs in it. */
@@ -91,10 +117,15 @@ export interface VariantWhen {
     readonly facts?: FactConjunction;
     readonly binding?: BindingCondition;
 }
-/** The condition a BUNDLED catalog variant is chosen on: a {@link VariantWhen} without the binding. A binding is a
- *  deployment's own vocabulary (scenario names the engine cannot know), so no catalog variant can name one — the type
- *  refuses it where the catalog data is written. */
-export type CatalogVariantWhen = Omit<VariantWhen, "binding">;
+/** The condition a BUNDLED catalog variant is chosen on: a {@link VariantWhen} without the binding, its traits the
+ *  reference's. A binding and an `x-` trait are a deployment's own vocabulary (names the engine cannot know), so no
+ *  catalog variant can name one — the type refuses it where the catalog data is written. */
+export type CatalogVariantWhen = Omit<VariantWhen, "binding" | "traits"> & {
+    readonly traits?: {
+        readonly allOf?: readonly CatalogPromptTrait[];
+        readonly noneOf?: readonly CatalogPromptTrait[];
+    };
+};
 export interface CatalogMessage {
     /** `core/<area>.<name>`. */
     readonly id: string;
@@ -104,7 +135,7 @@ export interface CatalogMessage {
 }
 /** The renderers the catalog may place by id — data here, so the catalog checks its sections without loading the
  *  renderer code; renderers.ts holds the code and the version table, one row per id (its record type is total). */
-export declare const RENDERER_IDS: readonly ["role-base", "model-guidance", "mcp-instructions", "reminder-mark", "environment", "memory"];
+export declare const RENDERER_IDS: readonly ["role-base", "mcp-instructions", "reminder-mark", "environment", "memory"];
 export type RendererId = (typeof RENDERER_IDS)[number];
 export type SectionBody = {
     readonly message: string;

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

@@ -7,7 +7,39 @@ export function isHostRole(v) {
     return isWordOf(HOST_ROLES, v);
 }
 export const HOST_FORMS = Object.freeze(["standard", "minimal"]);
-export const PROMPT_TRAITS = Object.freeze(["lean_prompt", "fable_5_mitigations"]);
+export const PROMPT_TRAITS = Object.freeze([
+    "lean_prompt",
+    "fable_5_mitigations",
+    "thrifty_sonic",
+    "turn_updates",
+    "bash_output_audience_note",
+    "silent_turn_reminder",
+    "thinking_display_updates",
+    "quizzical_shore",
+    "lucky_cerf",
+    "amber_astrolabe",
+    "bison_cairn",
+    "larch_cistern",
+    "haiku_5_5_early_stopping_guidance",
+    "elapsed_time_reminder",
+]);
+export const PROMPT_TRAIT_BUNDLES = Object.freeze({
+    fable_5_1_prompt_bundle: Object.freeze(["turn_updates", "bash_output_audience_note", "silent_turn_reminder", "thinking_display_updates"]),
+    opus_5_prompt_bundle: Object.freeze(["bison_cairn", "larch_cistern"]),
+    opus_5_5_prompt_bundle: Object.freeze(["silent_turn_reminder", "quizzical_shore"]),
+});
+const DEPLOYMENT_TRAIT = /^x-[a-z0-9]+-[a-z0-9][a-z0-9._-]*$/;
+export const PROMPT_TRAIT_NAME_MAX = 64;
+export function isPromptTraitName(v) {
+    if (typeof v !== "string")
+        return false;
+    if (isWordOf(PROMPT_TRAITS, v) || Object.prototype.hasOwnProperty.call(PROMPT_TRAIT_BUNDLES, v))
+        return true;
+    return v.length <= PROMPT_TRAIT_NAME_MAX && DEPLOYMENT_TRAIT.test(v);
+}
+export function bundleMembersOf(name) {
+    return Object.prototype.hasOwnProperty.call(PROMPT_TRAIT_BUNDLES, name) ? PROMPT_TRAIT_BUNDLES[name] : [];
+}
 export const PROMPT_FACT_NAMES = Object.freeze([
     "policyEnabled",
     "hooksEnabled",
@@ -25,4 +57,4 @@ export const PROMPT_FACT_NAMES = Object.freeze([
     "isSubagent",
     "executionEnvironmentDeclared",
 ]);
-export const RENDERER_IDS = Object.freeze(["role-base", "model-guidance", "mcp-instructions", "reminder-mark", "environment", "memory"]);
+export const RENDERER_IDS = Object.freeze(["role-base", "mcp-instructions", "reminder-mark", "environment", "memory"]);