@sema-agent/core 7.33.8 → 7.35.0

package/dist/agents/cross-session-judge.d.ts

@@ -1,5 +1,7 @@
 import type { AskEffective } from "../core/wiring-manifest.js";
 import { type PermissionModeClass } from "./cross-session-envelope.js";
+/** The permission-mode words the fold reads (the engine's closed set, as the wire spells it). */
+import type { PermissionMode } from "../core/ask-origin.js";
 /**
  * The explicit values of `crossSessionInbound`, loosest first: `wake` (deliver, and the HOST may start
  * a turn on this session when its box grows), `next-turn` (deliver at the session's next turn
@@ -100,14 +102,21 @@ export interface CrossSessionInboundInput {
  */
 export declare function judgeCrossSessionInbound(input: CrossSessionInboundInput): CrossSessionInboundVerdict;
 /**
- * design/385 §4.4 — sema's two-class fold of its own permission posture, read off the ONE derivation
- * the wiring manifest already owns ({@link AskEffective}): `bypass` = no human decides an ask
- * (`auto_allow`); `prompting` = an ask reaches a human or parks for one (`human_reachable`,
- * `park_only`), and — CC's literal rule for a never-prompting-never-bypassing mode — `auto_deny`;
- * `unresolved` ⇒ `"unknown"` (the judge fails closed on it). Single source: a host must not
- * re-derive the class from spec shape.
+ * design/385 §4.4 — sema's two-class fold of its own permission posture, from the session's EFFECTIVE
+ * permission mode (the engine's own resolution — never the requested one, never re-derived from spec shape)
+ * and the wiring manifest's ask derivation ({@link AskEffective}):
+ *  · `bypass` — the effective mode is `bypassPermissions`, OR no human decides an ask (`auto_allow`, a
+ *    blanket answering seat — the adapter's own reading of "nobody is watching");
+ *  · `"unknown"` — otherwise, when the ask derivation is `unresolved` (the judge fails closed on it);
+ *  · `prompting` — otherwise: an ask reaches a human or parks for one (`human_reachable`, `park_only`),
+ *    and — CC's literal rule for a never-prompting-never-bypassing mode — `auto_deny`.
+ * `effective` absent (a leg with no mode fact) reads the ask derivation alone.
+ *
+ * WHAT THE CLASS IS: `fromMode` is a presence LABEL — whether a person is watching this session's approvals —
+ * attested to a peer so a bypass session does not park work where nobody watches. It is not a permission
+ * authority and authorizes no execution; the permission mode itself is read only from `effective`.
  */
-export declare function foldPermissionModeClass(askEffective: AskEffective): PermissionModeClass | "unknown";
+export declare function foldPermissionModeClass(effective: PermissionMode | undefined, askEffective: AskEffective): PermissionModeClass | "unknown";
 /** The synchronous send outcomes a sender can observe at the send point (CC's ten classes on sema's
  *  codes; `sender_paced` is expressed by the admission gate's `rate_limited` and is deliberately not a
  *  second code). `parked_offline` is a DISPOSITION (durable append succeeded, recipient offline) and

package/dist/agents/cross-session-judge.js

@@ -154,22 +154,25 @@ export function judgeCrossSessionInbound(input) {
     }
     return selfModeClass === "bypass" ? holdFor("no-mode-asserted") : { verdict: "deliver" };
 }
-export function foldPermissionModeClass(askEffective) {
-    switch (askEffective) {
-        case "auto_allow":
-            return "bypass";
-        case "human_reachable":
-        case "park_only":
-        case "auto_deny":
-            return "prompting";
-        case "unresolved":
-            return "unknown";
-        default: {
-            const _exhaustive = askEffective;
-            void _exhaustive;
-            throw new Error(`unreachable ask effective ${String(askEffective)}`);
+export function foldPermissionModeClass(effective, askEffective) {
+    const byAsk = (() => {
+        switch (askEffective) {
+            case "auto_allow":
+                return "bypass";
+            case "human_reachable":
+            case "park_only":
+            case "auto_deny":
+                return "prompting";
+            case "unresolved":
+                return "unknown";
+            default: {
+                const _exhaustive = askEffective;
+                void _exhaustive;
+                throw new Error(`unreachable ask effective ${String(askEffective)}`);
+            }
         }
-    }
+    })();
+    return effective === "bypassPermissions" ? "bypass" : byAsk;
 }
 export const PEER_SEND_VERDICT_CODES = Object.freeze([
     "peer_send.stale_socket",

package/dist/agents/peer-session-drain.d.ts

@@ -7,6 +7,7 @@ import { type CrossSessionInboundSettingLayers } from "./cross-session-judge.js"
 import { type PeerLaneConfig } from "./peer-admission.js";
 import { type PeerDirectory } from "./peer-directory.js";
 import { createListAgentsTool } from "./list-agents-tool.js";
+import { foldPermissionModeClass } from "./cross-session-judge.js";
 import type { AskEffective } from "../core/wiring-manifest.js";
 import type { SendMessageToolOptions } from "./send-message-tool.js";
 import { type PeerClock, type PeerHeldQueue } from "./peer-held-queue.js";
@@ -175,6 +176,9 @@ export declare function createPeerSessionDrain(opts: PeerSessionDrainOptions): P
  *  before it — both read this one cell. */
 export interface PeerLaneRefs {
     askEffective?: AskEffective;
+    /** The session's EFFECTIVE permission mode, read live (it follows a mid-run mode change); absent on a leg
+     *  that carries no mode fact. Paired with `askEffective` in the one mode-class fold. */
+    permissionMode?: () => Parameters<typeof foldPermissionModeClass>[0];
     /** The bound drain's pull face (filled by {@link bindPeerLaneDrain}); the `ReadInbox` tool reads it late. */
     pull?: (limit?: number, toolCallId?: string, charBudget?: number) => Promise<PulledInbox>;
     /** #1036 — the bound drain's BOUNDARY pass (filled by {@link bindPeerLaneDrain}); the leg's

package/dist/agents/peer-session-drain.js

@@ -655,6 +655,9 @@ export function createPeerSessionDrain(opts) {
         idleMachine,
     };
 }
+function peerModeClassOf(refs) {
+    return refs.askEffective !== undefined ? foldPermissionModeClass(refs.permissionMode?.(), refs.askEffective) : "unknown";
+}
 export function announcePeerLaneMount(deps, leg) {
     const verdict = judgePeerLaneMount(deps, leg.sessionId);
     if (verdict === undefined)
@@ -676,7 +679,7 @@ export function peerLaneSendMessageSeats(args) {
             sessionId: args.sessionId,
             scope: args.scope,
             ...(args.name !== undefined ? { name: args.name } : {}),
-            modeClass: () => (args.refs.askEffective !== undefined ? foldPermissionModeClass(args.refs.askEffective) : "unknown"),
+            modeClass: () => peerModeClassOf(args.refs),
         },
     };
 }
@@ -753,7 +756,7 @@ export function bindPeerLaneDrain(harness, args) {
         ...(deps.peerLane !== undefined ? { lane: deps.peerLane } : {}),
         ownTokens: args.ownTokens,
         settingLayers: () => (typeof deps.crossSessionInbound === "function" ? deps.crossSessionInbound() : deps.crossSessionInbound),
-        selfModeClass: () => (args.refs.askEffective !== undefined ? foldPermissionModeClass(args.refs.askEffective) : "unknown"),
+        selfModeClass: () => peerModeClassOf(args.refs),
         dialogExpiry: () => (typeof deps.crossSessionDialogExpiry === "function" ? deps.crossSessionDialogExpiry() : deps.crossSessionDialogExpiry),
         selfName: () => rowName ?? args.selfName?.(),
         warmup: lookupRowName,

package/dist/agents/repair-loop.d.ts

@@ -142,7 +142,7 @@ export interface RepairLoopConfig {
      * instead of the bare reference-identity check, and surfaces {@link RepairResult.isolationClass}. Omit it (the
      * default) to keep the existing necessary-not-sufficient reference-identity check (the merged Slice-1 posture).
      *
-     * The real isolated grader env is SERVICE-provided ({@link import("../core/types.js").RunnerDeps.graderEnvFactory});
+     * The real isolated grader env is SERVICE-provided (the trusted control plane mints it; the engine has no seat for it);
      * `graderEnv` here is its `.env`, and the control-plane `provenance` brand is reattached internally for the
      * assertion. The assertion only matters for the (mandate-OFF) auto-accept path: `isolationClass` caps a
      * non-`out_of_process` grader at `candidate_only`. SAFE-tier never auto-accepts regardless.

package/dist/agents/subagent.d.ts

@@ -210,6 +210,9 @@ export interface SubagentWorktreeIsolation {
  * parent's own (possibly factory-owned) env.
  */
 export declare function createSubagentWorktreeHelper(baseEnv: ExecutionEnv, repoRoot: string): SubagentWorktreeIsolation;
+/** Names an `AgentDefinition.name` must not collide with (would confuse the enum vs a real tool name). Includes the
+ *  default delegation tool name itself, so a child agent can't be named "Agent" even when a custom `opts.name` is set. */
+export declare const RESERVED_AGENT_NAMES: ReadonlySet<string>;
 /** Cap for the inline-defused worker-controlled report metadata lines (blocked_reason / error). Matches the
  *  ask-question.ts inline-value convention (300) — a one-line operator-facing reason, not a bulk payload. */
 export declare const REPORT_FIELD_MAX = 300;

package/dist/agents/subagent.js

@@ -350,7 +350,7 @@ function resumabilityClaim(f) {
     return f.durableRow && f.named;
 }
 const BG_AGENT_COLLATERAL_REAP_REASON = "its parent run ended";
-const RESERVED_AGENT_NAMES = new Set([OUTPUT_TOOL_NAME, TOOL_SEARCH_NAME, OFFLOAD_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME, DEFAULT_SUBAGENT_TOOL_NAME]);
+export const RESERVED_AGENT_NAMES = new Set([OUTPUT_TOOL_NAME, TOOL_SEARCH_NAME, OFFLOAD_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME, DEFAULT_SUBAGENT_TOOL_NAME]);
 export const REPORT_FIELD_MAX = 300;
 const ROSTER_ECHO_MAX = 400;
 function configError(message, code) {
@@ -1930,8 +1930,17 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     if (!isObserverTaskId(sid))
                         throw new ObserverStoppedByUserError("observer identity revoked — delivery refused");
                     const pickedRef = observerModelPick().modelRef;
-                    const observerInternals = ctx.interactionPosture !== undefined || pickedRef !== undefined
-                        ? { ...(ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : {}), ...(pickedRef !== undefined ? { inheritedModelRef: pickedRef } : {}) }
+                    const parentGate = ctx.inheritedGateForChildren?.();
+                    const observerGate = parentGate === undefined
+                        ? undefined
+                        : {
+                            ...(parentGate.permissionMode !== undefined ? { permissionMode: parentGate.permissionMode } : {}),
+                            ...(parentGate.permissionModeCeiling !== undefined ? { permissionModeCeiling: parentGate.permissionModeCeiling } : {}),
+                            ...(parentGate.shellGate !== undefined ? { shellGate: parentGate.shellGate } : {}),
+                            admittedOrgScopes: parentGate.admittedOrgScopes,
+                        };
+                    const observerInternals = ctx.interactionPosture !== undefined || pickedRef !== undefined || observerGate !== undefined
+                        ? { ...(ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : {}), ...(pickedRef !== undefined ? { inheritedModelRef: pickedRef } : {}), ...(observerGate !== undefined ? { inheritedGate: observerGate } : {}) }
                         : undefined;
                     const r = await opts.runner.runTask(spec, observerInternals);
                     if (r.terminal.kind !== "completed") {

package/dist/brain/anthropic.js

@@ -240,6 +240,7 @@ export function createAnthropicBrain(config = {}) {
             signal: options?.signal,
             config,
             httpLabel: "anthropic",
+            maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
                 const root = resolveRequestRoot(model.baseUrl, config.baseUrl, "https://api.anthropic.com");

package/dist/brain/errors.d.ts

@@ -70,11 +70,33 @@ export declare class BrainError extends Error {
         apiError?: boolean;
     });
 }
+/**
+ * The shape a provider ECHO field must have to be carried: the request id a provider states on a response
+ * header (`AssistantMessage.requestId`, projected as `TaskResult.apiFailure.requestId`) and the model name it
+ * reports answering (`AssistantMessage.responseModel`). Both are UPSTREAM BYTES that end up persisted in a
+ * transcript and rendered by a UI, so one alphabet governs both: visible ASCII (0x21–0x7E — no space, no
+ * control byte, no non-ASCII), 1–128 characters. A value outside it is dropped (the field is absent), never
+ * truncated or rewritten; the empty string is outside it. No flags, so `test` is stateless. This object is the
+ * consumer's copy: the engine judges with its own instance built from the same source, so recompiling or
+ * otherwise mutating this one cannot change what the engine admits.
+ */
+export declare const PROVIDER_ECHO_SHAPE: RegExp;
+/** Does `value` fit {@link PROVIDER_ECHO_SHAPE}? A non-string answers `false` (a JS caller's number is not an echo). */
+export declare function isProviderEchoShape(value: string): boolean;
+/** How the brains read one provider echo value: a non-string or the empty string states nothing (`absent` — no field,
+ *  nothing counted); a string in {@link isProviderEchoShape} is `carried`; any other string is `refused` (dropped and
+ *  counted as `echo_dropped`). */
+export declare function providerEchoReading(value: unknown): "absent" | "carried" | "refused";
 /**
  * Lift the provider's own request identifier off a response, when it stated one in a shape worth
- * carrying (see {@link REQUEST_ID_RE}). This is the handle a provider's support channel asks for, and
+ * carrying ({@link isProviderEchoShape}). This is the handle a provider's support channel asks for, and
  * without it a failed turn's only evidence is prose the operator cannot correlate upstream.
  *
+ * A response whose header values were all refused by the shape yields no id and one `echo_dropped`
+ * telemetry event (`field: "requestId"`, bridged to the `brain.echo_dropped` trace frame) — one per
+ * response, whichever header was refused; a response that states no id at all (no header, or an empty one:
+ * {@link providerEchoReading}) yields none.
+ *
  * Duck-typed on `headers.get` rather than requiring a real `Response`: the engine's transport is a
  * caller-injected `fetch`, so a deployment (or a test) may hand back any response-shaped object, and
  * a missing/throwing header bag must degrade to "no id" instead of failing the call it is describing.

package/dist/brain/errors.js

@@ -1,4 +1,5 @@
 import { isErrorLike, readMember, thrownText } from "../core/thrown-value.js";
+import { emitBrainTelemetry } from "./status-sink.js";
 export const ZERO_USAGE = {
     input: 0,
     output: 0,
@@ -30,20 +31,36 @@ export class BrainError extends Error {
     }
 }
 const REQUEST_ID_HEADERS = ["request-id", "x-request-id"];
-const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const PROVIDER_ECHO_SOURCE = "^[\\x21-\\x7E]{1,128}$";
+const providerEchoShape = new RegExp(PROVIDER_ECHO_SOURCE);
+export const PROVIDER_ECHO_SHAPE = new RegExp(PROVIDER_ECHO_SOURCE);
+export function isProviderEchoShape(value) {
+    return typeof value === "string" && providerEchoShape.test(value);
+}
+export function providerEchoReading(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return "absent";
+    return isProviderEchoShape(value) ? "carried" : "refused";
+}
 export function readProviderRequestId(res) {
+    let refused = false;
     try {
         const get = res?.headers?.get;
         if (typeof get !== "function")
             return undefined;
         for (const name of REQUEST_ID_HEADERS) {
             const raw = get.call(res.headers, name);
-            if (typeof raw === "string" && REQUEST_ID_RE.test(raw))
+            const reading = providerEchoReading(raw);
+            if (reading === "carried")
                 return raw;
+            if (reading === "refused")
+                refused = true;
         }
     }
     catch {
     }
+    if (refused)
+        emitBrainTelemetry({ kind: "echo_dropped", field: "requestId" });
     return undefined;
 }
 export function namesTheFailure(status) {

package/dist/brain/open-responses.js

@@ -234,6 +234,7 @@ export function createOpenResponsesBrain(config = {}) {
             signal: options?.signal,
             config,
             httpLabel: "responses",
+            maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
                 const root = resolveRequestRoot(model.baseUrl, config.baseUrl);

package/dist/brain/openai.js

@@ -297,6 +297,7 @@ export function createOpenAIBrain(config = {}) {
             signal: options?.signal,
             config,
             httpLabel: "gateway",
+            maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
                 const root = resolveRequestRoot(model.baseUrl, config.baseUrl);

package/dist/brain/status-sink.d.ts

@@ -31,7 +31,7 @@ export declare function emitBrainStatus(status: BrainStatus): void;
  * Silent-fallback telemetry (C1/C4/C5/C6) — the brain→runner TELEMETRY channel, a
  * SECOND ALS sink parallel to the status one. Statuses are user-facing liveness frames (wire
  * `status` events); telemetry is operator-facing fallback accounting the Runner bridges to trace
- * events (`brain.failover` / `breaker.transition` / `brain.retry` / `vision.placeholder`). Kept
+ * events (`brain.failover` / `breaker.transition` / `brain.retry` / `vision.placeholder` / `brain.echo_dropped`). Kept
  * separate so widening telemetry never bloats the shell-visible status vocabulary. Same contract:
  * fire-and-forget, no-op outside a {@link runWithBrainTelemetry} scope, MUST NOT throw.
  */
@@ -66,6 +66,12 @@ export type BrainTelemetry = {
  | {
     kind: "document_placeholder";
     count: number;
+}
+/** A provider echo field ({@link import("./errors.js").PROVIDER_ECHO_SHAPE}) refused by its shape: the value was dropped
+ *  and the field is absent. One event per provider response per field. */
+ | {
+    kind: "echo_dropped";
+    field: "requestId" | "responseModel";
 };
 /** Run `fn` with a per-task brain-telemetry sink in scope (Runner-side; compose with runWithStatusSink). */
 export declare function runWithBrainTelemetry<T>(emit: (t: BrainTelemetry) => void, fn: () => Promise<T>): Promise<T>;

package/dist/brain/stream-engine.d.ts

@@ -243,4 +243,7 @@ export declare function runStreamingBrain(args: {
         firstTokenMs?: number;
         idleMs?: number;
     };
+    /** Per-call CAP on the transient retry budget (`StreamOptions.maxRetries`): the call retries at most this many times
+     *  and never more than the brain's own budget ({@link resolveMaxRetries}); a non-finite or negative value caps nothing. */
+    maxRetries?: number;
 }): ReturnType<typeof createAssistantMessageEventStream>;

package/dist/brain/stream-engine.js

@@ -265,6 +265,7 @@ function firstByteTimeoutMessage(windowsMs) {
 }
 export function runStreamingBrain(args) {
     const { model, doFetch, signal, config, httpLabel, buildRequest, makeParser, stallTimeouts } = args;
+    const callRetryCap = args.maxRetries !== undefined && Number.isFinite(args.maxRetries) && args.maxRetries >= 0 ? Math.floor(args.maxRetries) : Infinity;
     const out = createAssistantMessageEventStream();
     let cleanup;
     let announcedRetry = false;
@@ -326,7 +327,7 @@ export function runStreamingBrain(args) {
         let req = buildRequest();
         req.onCommitted?.();
         let maxOutputTokensOverride;
-        const maxRetries = resolveMaxRetries(config.maxRetries);
+        const maxRetries = Math.min(resolveMaxRetries(config.maxRetries), callRetryCap);
         const baseDelay = config.retryDelayMs ?? 500;
         const deterministicConnectBudget = Math.min(resolveDeterministicConnectRetries(config.deterministicConnectRetries), maxRetries);
         const deterministicLaneActive = deterministicConnectBudget < maxRetries;

package/dist/brain/stream-shared.d.ts

@@ -47,7 +47,9 @@ export declare function createRepetitionPoll(): RepetitionPoll;
  *  message every lane spreads `...partial` into) — ONE rule for the three lanes' spellings (`chunk.model` /
  *  `message_start.message.model` / `response.model`), WRITE twin of `providerReportedModel`
  *  (`core/message-utils.ts`). The LAST frame that NAMES a model decides and the seat carries it only when it
- *  differs; naming nothing is not an update, naming the REQUESTED id RETRACTS an earlier substitution. */
+ *  differs; naming nothing (no name, or the empty string — {@link providerEchoReading}) is not an update, naming the
+ *  REQUESTED id RETRACTS an earlier substitution. A name outside {@link isProviderEchoShape} is dropped — not an
+ *  update — and counted once per response (`echo_dropped`, `field: "responseModel"`). */
 export declare function noteResponseModel(partial: {
     responseModel?: string;
 }, reported: unknown, requestedId: string): void;

package/dist/brain/stream-shared.js

@@ -1,4 +1,6 @@
+import { isProviderEchoShape, providerEchoReading } from "./errors.js";
 import { inspectDegenerate } from "./repetition.js";
+import { emitBrainTelemetry } from "./status-sink.js";
 export const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
 export function parseStreamedToolArgs(json) {
     if (!json)
@@ -40,11 +42,21 @@ export function createRepetitionPoll() {
         },
     };
 }
+const refusedModelCounted = new WeakSet();
 export function noteResponseModel(partial, reported, requestedId) {
-    if (typeof reported !== "string" || reported === "")
+    const reading = providerEchoReading(reported);
+    if (reading === "absent")
         return;
-    if (reported === requestedId)
+    if (reported === requestedId) {
         delete partial.responseModel;
-    else
-        partial.responseModel = reported;
+        return;
+    }
+    if (reading === "refused") {
+        if (!refusedModelCounted.has(partial)) {
+            refusedModelCounted.add(partial);
+            emitBrainTelemetry({ kind: "echo_dropped", field: "responseModel" });
+        }
+        return;
+    }
+    partial.responseModel = reported;
 }

package/dist/core/a2a.d.ts

@@ -8,7 +8,7 @@ export declare const A2A_SKILL_DESCRIPTION_MAX_CHARS = 2048;
  *
  * Unlike MCP there is no server-hint leg to merge: the protocol has no per-skill annotation vocabulary,
  * and a remote agent's self-declaration would not be trustworthy if it had one. Every A2A tool therefore
- * starts at the ruled default (`egress:true`, `effect:"write"`) and the CALLER's
+ * starts at the ruled default (`egress:true`, the effect undeclared — read as `write` everywhere) and the CALLER's
  * {@link A2aServerSpec.toolAxes} is the only thing that can lower it (design F: caller = trust root).
  */
 export interface A2aToolAxis {
@@ -20,6 +20,8 @@ export interface A2aToolAxis {
     /** `false` appears ONLY via an explicit caller override — same posture: enforcement ignores it,
      *  the report face consumes it (an explicit negative is a judgment, not silence). */
     egress?: boolean;
+    /** Present ONLY when the caller's override declares it; absent is the repeat-unsafe `write` every reader applies (and
+     *  the roster names `default` provenance — a default is not a declaration). */
     effect?: ToolEffect;
 }
 /** design/99 §E9 equivalent for A2A — a per-peer projection of THIS materialization. A2A holds no

package/dist/core/a2a.js

@@ -321,7 +321,7 @@ function skillDescription(peerLabel, skill) {
     return lines.join("\n");
 }
 function a2aAxisFor(name, override) {
-    const axis = { name, egress: true, effect: "write" };
+    const axis = { name, egress: true };
     if (override === undefined)
         return axis;
     if (override.effect !== undefined)