@sema-agent/core 7.48.0 → 7.49.1

package/dist/brain/stream-engine.js

@@ -3,9 +3,10 @@ import { STREAM_TORN_WARNING } from "./stream-shared.js";
 import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } from "./context-overflow.js";
 import { abortLikeName, BrainError, brainErrorCodeOf, classifyFetchThrow, classifyHttp, describeNetworkError, isProviderEchoShape, namesTheFailure, proxyTunnelRefusedSentence, readConnectFailure, readProviderErrorCode, readProviderRequestId, refusedTheRequest } from "./errors.js";
 import { stripUrlCredentials } from "./route-adjudicator.js";
-import { classifyInputTooLong } from "./input-too-long.js";
+import { admittedRequestRoute } from "./request-route.js";
+import { isTransientStatus, isProviderCondition, isProviderConditionSource, judgeHttpFailure, PROVIDER_CONDITION_TRAITS, resolveProviderDialect, } from "./provider-dialect.js";
 import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
-import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
+import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry, reportExtraBodyDropped } from "./status-sink.js";
 import { createAttemptController, firstByteWindow, refuseRetiredTimeoutKnobs, resolveFirstByteRetries, resolveWatchdogMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, } from "./timeout.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
 import { redactSecrets } from "../core/untrusted-egress.js";
@@ -204,6 +205,10 @@ const EMPTY_USAGE = {
     totalTokens: 0,
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 };
+function reportRequestStrip(model, req) {
+    if (req.extraBodyDropped !== undefined && req.extraBodyDropped.length > 0)
+        reportExtraBodyDropped({ api: model.api, modelId: model.id, keys: req.extraBodyDropped });
+}
 function emptyAssistant(model) {
     return {
         role: "assistant",
@@ -250,9 +255,20 @@ async function sleepAnnouncingRetry(totalMs, signal, frame) {
             return;
     }
 }
+const RETRY_PHASE_OF_ERR_CLASS = {
+    connect_refused: "reconnecting",
+    transport: "reconnecting",
+    stall: "reconnecting",
+    rate_limit: "rate_limited",
+    server: "retrying",
+    http: "retrying",
+    output_cap: "retrying",
+};
+Object.freeze(RETRY_PHASE_OF_ERR_CLASS);
+const TRANSPORT_RETRY_DETAIL = "connection lost, reconnecting";
 function retryAnnouncement(failure) {
     if (failure.kind !== "stalled")
-        return { errClass: "transport", detail: "connection lost, reconnecting" };
+        return { errClass: "transport", detail: TRANSPORT_RETRY_DETAIL };
     const knob = failure.allowanceMs !== undefined && failure.allowanceMs > 0
         ? `${failure.knob} ${failure.timeoutMs - failure.allowanceMs} + ${failure.allowanceMs} upload allowance`
         : failure.knob;
@@ -276,6 +292,8 @@ export function runStreamingBrain(args) {
     let terminalRetryDetail = "recovered after retrying";
     let requestIdSeen;
     let attemptPartial;
+    let attemptOutput;
+    let routeSeen;
     void run()
         .catch((err) => {
         const aborted = signal?.aborted === true || isAbortError(err);
@@ -289,6 +307,11 @@ export function runStreamingBrain(args) {
                 ? "cancelled while waiting for the first token"
                 : "the first-token wait ended in failure";
         const errorMsg = emptyAssistant(model);
+        const kept = aborted ? undefined : attemptOutput;
+        if (kept !== undefined) {
+            errorMsg.content = kept.content;
+            errorMsg.usage = kept.usage;
+        }
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = thrownText(err);
         if (!aborted && brainErrorCodeOf(err) !== undefined) {
@@ -296,6 +319,8 @@ export function runStreamingBrain(args) {
                 errorMsg.errorKind = "input_too_long";
             else if (readMember(err, "inputTooLongRuledOut") === true)
                 errorMsg.inputTooLongRuledOut = true;
+            if (readMember(err, "errorBodyIncomplete") === true)
+                errorMsg.errorBodyIncomplete = true;
             if (readMember(err, "apiError") === true) {
                 errorMsg.isApiErrorMessage = true;
                 const status = readMember(err, "status");
@@ -304,12 +329,24 @@ export function runStreamingBrain(args) {
                     errorMsg.apiErrorStatus = statusNum;
                 if (requestIdSeen !== undefined)
                     errorMsg.requestId = requestIdSeen;
+                if (routeSeen !== undefined)
+                    errorMsg.apiErrorRoute = routeSeen;
                 const providerCode = readMember(err, "providerCode");
-                if (refusedTheRequest(statusNum) && typeof providerCode === "string" && isProviderEchoShape(providerCode))
+                if ((statusNum === undefined || refusedTheRequest(statusNum)) && typeof providerCode === "string" && isProviderEchoShape(providerCode))
                     errorMsg.apiErrorCode = providerCode;
+                const condition = readMember(err, "providerCondition");
+                const source = readMember(err, "providerConditionSource");
+                if (isProviderCondition(condition) && isProviderConditionSource(source)) {
+                    errorMsg.providerCondition = condition;
+                    errorMsg.providerConditionSource = source;
+                    const resetAtMs = readMember(err, "providerResetAtMs");
+                    if (typeof resetAtMs === "number" && Number.isFinite(resetAtMs))
+                        errorMsg.providerResetAtMs = resetAtMs;
+                }
             }
         }
-        errorMsg.usageMissing = true;
+        if (kept === undefined || kept.usageMissing === true)
+            errorMsg.usageMissing = true;
         const seenResponseModel = attemptPartial?.responseModel;
         if (seenResponseModel !== undefined)
             errorMsg.responseModel = seenResponseModel;
@@ -328,7 +365,13 @@ export function runStreamingBrain(args) {
     return out;
     async function run() {
         let req = buildRequest();
-        req.onCommitted?.();
+        const commit = (r) => {
+            r.onCommitted?.();
+            reportRequestStrip(model, r);
+            routeSeen = admittedRequestRoute(r.route);
+        };
+        commit(req);
+        const dialect = resolveProviderDialect(req.url, model.api);
         let maxOutputTokensOverride;
         const maxRetries = Math.min(resolveMaxRetries(config.maxRetries), callRetryCap);
         const baseDelay = config.retryDelayMs ?? 500;
@@ -399,6 +442,7 @@ export function runStreamingBrain(args) {
                 let firstByteStall;
                 requestIdSeen = undefined;
                 attemptPartial = undefined;
+                attemptOutput = undefined;
                 const stalledAtFirstByte = () => {
                     firstByteWindowsWaited.push(window.windowMs);
                     return {
@@ -462,7 +506,7 @@ export function runStreamingBrain(args) {
                         cc.abort();
                         cc.dispose();
                         await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
-                            phase: "reconnecting",
+                            phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
                             detail: announcement.detail,
                             retryInSec: Math.ceil(remainingMs / 1000),
                             retryInMs: remainingMs,
@@ -472,11 +516,11 @@ export function runStreamingBrain(args) {
                         }));
                         continue;
                     }
-                    let overflowBody;
+                    let errorBody;
                     let overflowDeclineNote = "";
                     if (r !== undefined && r.status === 400) {
                         const read = await readErrorBody(r, signal);
-                        overflowBody = read.text;
+                        errorBody = read;
                         const report = read.endedNormally ? parseContextOverflow(r.status, read.text) : undefined;
                         if (report !== undefined) {
                             const plan = planOutputCapAdjustment(report, [maxOutputTokensOverride, req.outputCapTokens]);
@@ -499,11 +543,11 @@ export function runStreamingBrain(args) {
                                     const previousCap = plan.current;
                                     maxOutputTokensOverride = plan.maxOutputTokens;
                                     req = rebuilt;
-                                    req.onCommitted?.();
+                                    commit(req);
                                     emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect", errClass: "output_cap", nextDelayMs: 0 });
                                     announcedRetry = true;
                                     emitBrainStatus({
-                                        phase: "retrying",
+                                        phase: RETRY_PHASE_OF_ERR_CLASS.output_cap,
                                         detail: `output limit lowered from ${previousCap} to ${plan.maxOutputTokens} tokens, retrying`,
                                         attempt: attempt + 1,
                                         maxRetries,
@@ -528,9 +572,12 @@ export function runStreamingBrain(args) {
                             }
                         }
                     }
-                    const retryableByStatus = netErr !== undefined ||
-                        (r !== undefined && (r.status >= 500 || r.status === 429 || r.status === 408 || r.status === 409));
-                    const retryable = shouldRetryHeaderVerdict(r) ?? retryableByStatus;
+                    if (r !== undefined && errorBody === undefined && namesTheFailure(r.status) && !isTransientStatus(r.status))
+                        errorBody = await readErrorBody(r, signal);
+                    const judge = () => r !== undefined && namesTheFailure(r.status) ? judgeHttpFailure({ dialect, status: r.status, headers: r.headers, body: errorBody }) : undefined;
+                    const verdict = judge();
+                    const retryableByCondition = netErr !== undefined || (verdict !== undefined && PROVIDER_CONDITION_TRAITS[verdict.condition].retryable);
+                    const retryable = shouldRetryHeaderVerdict(r) ?? retryableByCondition;
                     const connectReading = netErr !== undefined ? readConnectFailure(netErr) : undefined;
                     const deterministicConnect = connectReading?.verdict === "deterministic";
                     const fastLane = deterministicConnect && deterministicLaneActive;
@@ -552,20 +599,20 @@ export function runStreamingBrain(args) {
                         const truncationNote = waitHint?.rawMs !== undefined
                             ? ` (the requested wait was longer than the cap; honoring ${Math.ceil(waitHint.ms / 1000)}s instead of ${Math.ceil(waitHint.rawMs / 1000)}s)`
                             : "";
-                        const statusPhase = r?.status === 429 ? "rate_limited" : netErr !== undefined ? "reconnecting" : "retrying";
                         const refusedSubject = connectReading?.proxyRefusal !== undefined ? "proxy refused the tunnel" : "no endpoint answering";
-                        const reconnectDetail = errClass !== "connect_refused" ? "connection lost, reconnecting" : fastLane ? `${refusedSubject}, retrying briefly` : `${refusedSubject}, retrying`;
+                        const reconnectDetail = errClass !== "connect_refused" ? TRANSPORT_RETRY_DETAIL : fastLane ? `${refusedSubject}, retrying briefly` : `${refusedSubject}, retrying`;
                         emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect", errClass, nextDelayMs: delayMs });
                         announcedRetry = true;
                         discardResponseBody(r);
                         cc.abort();
                         cc.dispose();
                         const retryStatus = namesTheFailure(r?.status) ? r.status : undefined;
+                        const phase = RETRY_PHASE_OF_ERR_CLASS[errClass];
                         await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
-                            phase: statusPhase,
-                            detail: statusPhase === "rate_limited"
+                            phase,
+                            detail: phase === "rate_limited"
                                 ? `rate limited, backing off${truncationNote}`
-                                : statusPhase === "reconnecting"
+                                : phase === "reconnecting"
                                     ? reconnectDetail
                                     : `transient error, retrying${truncationNote}`,
                             retryInSec: Math.ceil(remainingMs / 1000),
@@ -574,6 +621,7 @@ export function runStreamingBrain(args) {
                             maxRetries: laneMaxRetries,
                             errClass,
                             ...(retryStatus !== undefined ? { errorStatus: retryStatus } : {}),
+                            ...(verdict !== undefined ? { providerCondition: verdict.condition, providerConditionSource: verdict.source } : {}),
                         }));
                         attempt++;
                         continue;
@@ -583,14 +631,19 @@ export function runStreamingBrain(args) {
                         const proxyRefusal = connectReading?.proxyRefusal;
                         throw new BrainError("network", proxyRefusal === undefined ? chain : `${proxyTunnelRefusedSentence(proxyRefusal.status)} — ${chain}`, undefined, { apiError: true });
                     }
-                    const detail = overflowBody ?? (r ? (await readErrorBody(r, signal)).text : "");
+                    if (r !== undefined && errorBody === undefined)
+                        errorBody = await readErrorBody(r, signal);
+                    const terminalVerdict = judge();
+                    const detail = errorBody?.text ?? "";
                     const status = r?.status ?? 0;
-                    const itl = classifyInputTooLong(status, detail);
-                    const providerCode = refusedTheRequest(status) ? readProviderErrorCode(detail) : undefined;
+                    const itl = terminalVerdict?.inputTooLong ?? "no";
+                    const providerCode = refusedTheRequest(status) ? readProviderErrorCode(errorBody) : undefined;
                     throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}${overflowDeclineNote}`, status, {
                         apiError: true,
                         ...(itl === "yes" ? { inputTooLong: true } : itl === "no" ? { inputTooLongRuledOut: true } : {}),
                         ...(providerCode !== undefined ? { providerCode } : {}),
+                        ...(terminalVerdict !== undefined ? { verdict: { condition: terminalVerdict.condition, source: terminalVerdict.source, ...(terminalVerdict.resetAtMs !== undefined ? { resetAtMs: terminalVerdict.resetAtMs } : {}) } } : {}),
+                        ...(errorBody !== undefined && !errorBody.endedNormally ? { errorBodyIncomplete: true } : {}),
                     });
                 }
                 finally {
@@ -673,6 +726,10 @@ export function runStreamingBrain(args) {
                 partial,
                 sawContentToken,
                 cancel: () => void reader.cancel().catch(() => undefined),
+                dialect,
+                keepOutput: (output) => {
+                    attemptOutput = output;
+                },
             });
             const INBAND_OVERLOAD_WARNING = "API overloaded mid-response. The response above may be incomplete.";
             const onLineOverloadTierA = (line) => {
@@ -780,7 +837,7 @@ export function runStreamingBrain(args) {
                 emitBrainTelemetry({ kind: "retry", attempt: thinkingRetries, phase: "midstream", errClass: announcement.errClass, nextDelayMs: delayMs });
                 announcedRetry = true;
                 await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
-                    phase: "reconnecting",
+                    phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
                     detail: announcement.detail,
                     retryInSec: Math.ceil(remainingMs / 1000),
                     retryInMs: remainingMs,
@@ -797,7 +854,7 @@ export function runStreamingBrain(args) {
             emitBrainTelemetry({ kind: "retry", attempt, phase: "midstream", errClass: announcement.errClass, nextDelayMs: delayMs });
             announcedRetry = true;
             await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
-                phase: "reconnecting",
+                phase: RETRY_PHASE_OF_ERR_CLASS[announcement.errClass],
                 detail: announcement.detail,
                 retryInSec: Math.ceil(remainingMs / 1000),
                 retryInMs: remainingMs,

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

@@ -1,5 +1,5 @@
 import { type RepetitionEvent } from "./repetition.js";
-import { type AssistantMessage, type StreamDropCause } from "../internal/llm.js";
+import { type AssistantMessage, type ModelOutputInvalid, type StreamDropCause } from "../internal/llm.js";
 /**
  * design/157 A10 — stream-parser pieces that the anthropic and openai SSE lanes carried BYTE-IDENTICALLY
  * (verified by diff at 1469481: a 16-line repetition-telemetry closure). Provider-agnostic policy, so it
@@ -14,21 +14,51 @@ import { type AssistantMessage, type StreamDropCause } from "../internal/llm.js"
  *
  * Internal module: not re-exported from `src/index.ts`.
  */
+/** The CC-verbatim warning stamped beside `partialFinalized` when a stream ended before its close — by the
+ *  mid-stream promotion (the body threw) and by the parsers' own finalize (content arrived, no finish frame). */
+export declare const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
+/** A provider word as a stream-end seat carries it: the word in the provider echo shape, else `?` — the fact that a
+ *  word arrived survives, bytes outside the shape do not (the echo discipline: dropped, never rewritten). */
+export declare function echoFoldedWord(raw: string): string;
+/**
+ * The record of what arrived after a stream's first terminal statement — the one ordering rule both wire parsers
+ * apply: the first ending (a finish / stop reason, a message stop, an in-band error) decides the turn; after it the
+ * turn is frozen, only the usage trailer is read, and every later ending or content frame is refused and counted
+ * here. Rides `AssistantMessage.streamEndIgnored` (the first refused frame's kind and word, how many came); the
+ * Runner announces it (`route.stream_end_ignored`).
+ */
+export declare function createStreamEndLedger(): {
+    note(statement: StreamEndStatement, word: string): void;
+    readonly ignored: AssistantMessage["streamEndIgnored"];
+};
+type StreamEndStatement = NonNullable<AssistantMessage["streamEndIgnored"]>["statement"];
 /**
- * REF-B1 — turn a streamed tool call's accumulated argument bytes into its arguments object, FAIL-CLOSED.
+ * REF-B1 — turn a streamed tool call's accumulated argument bytes into its arguments object, FAIL-CLOSED. The ONE
+ * judge of a streamed call's arguments: a call runs only with arguments that are a complete JSON object.
  *
- * - no bytes (`""`) → `{}`: genuinely a no-argument call (the provider's frame carried no arguments);
- * - valid JSON **object** → that object;
+ * - valid JSON **object** → that object (a complete `{}` included);
+ * - no bytes (`""`) → `{}` when the wire closed the call — the provider's frame carried no arguments, a no-argument
+ *   call; `undefined` when it did not — the stream stopped before the call's first argument byte arrived, and nothing
+ *   says it was a no-argument call rather than a cut one;
  * - anything else (truncated/invalid JSON, or a top-level string/array/number/null) → `undefined`.
  *
+ * `closed` is the lane's evidence that the wire ended THIS call, with no default (a lane that does not state it does
+ * not compile): the call's own close frame, or a stream end that says the model finished its turn (not the output-cap
+ * stop, not no stop at all). Another call opening is no evidence — a gateway may open several calls before any
+ * argument byte arrives. One reading in the three lanes; each lane states which of these it has.
+ *
  * bug-hunt #6 (kept from finalize): a non-object must never reach `tool.execute` / the MCP wire. `undefined`
  * means "do not emit a `toolcall_end` for this call"; callers must NOT cache that outcome — finalize retries
  * the parse against the complete accumulation.
  */
-/** The CC-verbatim warning stamped beside `partialFinalized` when a stream ended before its close — by the
- *  mid-stream promotion (the body threw) and by the parsers' own finalize (content arrived, no finish frame). */
-export declare const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
-export declare function parseStreamedToolArgs(json: string): Record<string, unknown> | undefined;
+export declare function parseStreamedToolArgs(json: string, closed: boolean): Record<string, unknown> | undefined;
+/**
+ * The cause of a call slot that never received its NAME — the other component of a call, judged by the same evidence as
+ * its arguments ({@link parseStreamedToolArgs}'s `closed`): a slot the wire closed has no name because none was sent
+ * (`unnamed`); a slot nothing closed was cut before its name arrived (`truncated`). A call is whole only with both parts;
+ * a missing part on an unclosed call is a cut call, whichever part is missing.
+ */
+export declare function nameMissingCause(closed: boolean): "unnamed" | "truncated";
 /** One drop note of a turn: what was dropped, how many, and the sentence the model reads. */
 export interface TurnNote {
     readonly cause: StreamDropCause;
@@ -51,12 +81,27 @@ export declare function placeTurnNotes(message: Pick<AssistantMessage, "diagnost
  * without its stop frame names the transport instead; any other stop adds nothing (naming the cap there sent a reader
  * after a budget that was never reached). One rule for the lanes that carry the clause.
  */
-export declare function truncationCauseClause(facts: {
+export declare function truncationCauseClause(facts: TurnCapFacts & {
+    terminalFrameSeen: boolean;
+}): string;
+/** One turn's output-cap facts as the lane holds them — the record {@link truncationCauseClause} words and
+ *  {@link modelOutputInvalidOf} carries: the lane's cap stop, the provider's output count (as reported), the cap the
+ *  committed request carried. */
+export interface TurnCapFacts {
     capStop: boolean;
     outputTokens: number | undefined;
     capTokens: number | undefined;
-    terminalFrameSeen: boolean;
-}): string;
+}
+/**
+ * The structured account of a turn that FAILED for its dropped tool calls (`AssistantMessage.modelOutputInvalid`) —
+ * the lane calls it on the arm whose message is the dropped-calls sentence. `cause` is `truncated` when any call's
+ * arguments were cut (the sentence's first part), else `unnamed`; `outputLimit` rides with `truncated`, read off the
+ * same {@link TurnCapFacts} the sentence's cap clause reads. One rule for the three lanes.
+ */
+export declare function modelOutputInvalidOf(drops: {
+    truncated: number;
+    unnamed: number;
+}, cap: TurnCapFacts): ModelOutputInvalid | undefined;
 /** Repetition telemetry for ONE stream — the cut event plus the allowance-spared hits. */
 export interface RepetitionPoll {
     /** Inspect the accumulated text; returns whether it is degenerate (the caller trips its own cut). */
@@ -82,3 +127,4 @@ export declare function createRepetitionPoll(): RepetitionPoll;
 export declare function noteResponseModel(partial: {
     responseModel?: string;
 }, reported: unknown, requestedId: string): void;
+export {};

package/dist/brain/stream-shared.js

@@ -3,9 +3,23 @@ import { inspectDegenerate } from "./repetition.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { stampStreamDrops } from "../internal/llm.js";
 export const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
-export function parseStreamedToolArgs(json) {
+export function echoFoldedWord(raw) {
+    return isProviderEchoShape(raw) ? raw : "?";
+}
+export function createStreamEndLedger() {
+    let ignored;
+    return {
+        note(statement, word) {
+            ignored = ignored === undefined ? { statement, word: echoFoldedWord(word), frames: 1 } : { ...ignored, frames: ignored.frames + 1 };
+        },
+        get ignored() {
+            return ignored;
+        },
+    };
+}
+export function parseStreamedToolArgs(json, closed) {
     if (!json)
-        return {};
+        return closed ? {} : undefined;
     let parsed;
     try {
         parsed = JSON.parse(json);
@@ -17,6 +31,9 @@ export function parseStreamedToolArgs(json) {
         return undefined;
     return parsed;
 }
+export function nameMissingCause(closed) {
+    return closed ? "unnamed" : "truncated";
+}
 export function placeTurnNotes(message, content, notes) {
     if (notes.length === 0)
         return;
@@ -31,6 +48,15 @@ export function truncationCauseClause(facts) {
     }
     return terminalFrameSeen ? "" : "; the stream ended before its stop frame — the connection closed mid-response";
 }
+const countOf = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : undefined);
+export function modelOutputInvalidOf(drops, cap) {
+    if (drops.truncated > 0) {
+        const outputTokens = countOf(cap.outputTokens);
+        const capTokens = countOf(cap.capTokens);
+        return { cause: "truncated", outputLimit: { capStop: cap.capStop, ...(outputTokens !== undefined ? { outputTokens } : {}), ...(capTokens !== undefined ? { capTokens } : {}) } };
+    }
+    return drops.unnamed > 0 ? { cause: "unnamed" } : undefined;
+}
 export function createRepetitionPoll() {
     let repCut;
     const repSpared = new Map();

package/dist/core/a2a.d.ts

@@ -66,6 +66,7 @@ export interface MaterializedA2a {
     /** One entry per peer that could not be materialized and was SKIPPED (fail-open, design/29): the task
      *  runs with the healthy peers' tools. The Runner forwards these to `onError(phase:"a2a")`. */
     warnings: Error[];
+    /** One entry per DECLARED peer, in declaration order, ready or failed — the declaration as this materialization read it once. */
     statuses: A2aPeerStatus[];
     /** Re-read one peer's card (or every declared peer) and re-derive its tools. Unlike the MCP refresh
      *  this dials nothing new — every A2A call is a fresh request anyway — so a peer that failed at

package/dist/core/agent-config-dir.js

@@ -1,5 +1,6 @@
 import { statSync } from "node:fs";
-import { isAbsolutePathForm, normalizeAbsPathLexically } from "../tools/fs/safety.js";
+import { normalizeAbsPathLexically } from "../tools/fs/safety.js";
+import { validatePath } from "./effective-path-target.js";
 export const AGENT_CONFIG_DIR_SEGMENT = ".sema";
 export const AGENT_CONFIG_DIR_INVALID_CODE = "config.agent_config_dir_invalid";
 export function agentConfigDirTail(run, caseSensitive = false) {
@@ -33,7 +34,7 @@ export function checkedAgentConfigDir(value, seat) {
         throw invalidAgentConfigDir(seat, value, `is a ${value === null ? "null" : typeof value}, not a string`);
     if (value.length === 0)
         throw invalidAgentConfigDir(seat, value, "is an empty string");
-    if (!isAbsolutePathForm(value))
+    if (validatePath(value, { intent: "validate-coordinate" }) === undefined)
         throw invalidAgentConfigDir(seat, value, "is not an absolute path");
     let isDirectory;
     try {

package/dist/core/allow-entry.d.ts

@@ -3,12 +3,12 @@ import type { ToolCallRequest } from "./tool-policy.js";
 import { type AllowRuleMember, type AllowRuleShadow } from "./allow-rule-shadow.js";
 import { type PathRuleBases, type PersistedRule } from "./permission-rule-model.js";
 import { type AskClass, type AssertAllKeysHandled, type PermissionMode, type PersistedRuleMandate } from "./ask-origin.js";
-import { type ToolNameListReading } from "../agents/tool-filter.js";
+import { type ToolNameListReading } from "./tool-name-list.js";
 import { type EngineNotice } from "./engine-notice.js";
 /** Why an entry grants (or refuses) nothing — the closed set the start-of-run notice names, for every list. `tool_name`: the
  *  entry's tool name is one the name judgment reads as stale against the run's roster (`verdict` says which); `near_miss`: the
  *  run mounts no tool of that exact name but mounts one that differs only by case (`currentName` is its spelling). */
-export declare const ALLOW_ENTRY_INERT_REASONS: readonly ["wildcard_all", "namespace_wildcard", "path_pattern", "domain", "content_unsupported", "grammar", "tool_name", "near_miss"];
+export declare const ALLOW_ENTRY_INERT_REASONS: readonly ["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss"];
 export type AllowEntryInertReason = (typeof ALLOW_ENTRY_INERT_REASONS)[number];
 /** The facts beside a reason: for `tool_name` / `near_miss` the judgment's word and the spelling to write instead when there is
  *  one; for a list member that is not a string (`grammar`) the TYPE of the value (`a number`, `null`, `an object`…) — `entry` then
@@ -35,8 +35,9 @@ export type AllowEntryInert = {
     readonly entry: string;
     readonly reason: AllowEntryInertReason;
 } & AllowEntryInertDetail;
-/** One entry the grammar reads (kind closed): a whole non-shell tool; a protocol namespace; the whole shell tool; a shell
- *  command rule; the Read directory form; a deny-side path pattern (a skill's `disallowed-tools`). */
+/** One entry the grammar reads (kind closed): a whole non-shell tool; a protocol namespace; the whole shell tool; and one
+ *  kind per rule grammar (`ruleToolGrammarOf`) — a shell command rule, a path rule, a name rule, a host rule — each the row
+ *  the persisted grammar parses, its `behavior` the list's direction. */
 export type CompiledAllowEntry = {
     readonly kind: "tool";
     readonly name: string;
@@ -50,10 +51,13 @@ export type CompiledAllowEntry = {
     readonly kind: "command";
     readonly rule: PersistedRule;
 } | {
-    readonly kind: "read_dir";
+    readonly kind: "path";
     readonly rule: PersistedRule;
 } | {
-    readonly kind: "path";
+    readonly kind: "name";
+    readonly rule: PersistedRule;
+} | {
+    readonly kind: "domain";
     readonly rule: PersistedRule;
 };
 /**
@@ -104,11 +108,13 @@ export interface AllowEntryJudgeContext {
     readonly anchors: PathRuleBases;
 }
 /**
- * The ONE list matcher, both directions — the rows that speak for the call, or undefined. ALLOW: the first name row that
- * reaches the call, else the command rows' coverage (the persisted allow matcher — the whole command, or each segment
- * covered by a row or read-only by itself), else the Read directory rows. DENY: a name row, a command row whose program run
- * the call performs (the wide tightening reading; a call that cannot be read against the row is refused too), or a path row
- * the call's target reaches.
+ * The ONE list matcher, both directions — the rows that speak for the call, or undefined. A tool-name row first (the first
+ * that reaches the call); then the content rows, each family by the predicate the stored rows of that grammar meet:
+ * COMMAND — allow: the persisted allow matcher's coverage (the whole command, or each segment covered by a row or read-only
+ * by itself); deny: a row whose program run the call performs (the wide tightening reading; a call that cannot be read
+ * against the row is refused too). PATH — the persisted path adjudication (allow: the narrow reading, every view of the
+ * target inside what the row names; deny: any view reaching it). NAME / DOMAIN — the one predicate of each (the name the
+ * call names, the host it fetches).
  */
 export declare function judgeAllowEntries<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, behavior: "allow" | "deny", ctx: AllowEntryJudgeContext): readonly R[] | undefined;
 /** The allow rows of a list, as the allow layer reads them in `mode`: the strip applied BEFORE the match (in `auto`). */
@@ -157,6 +163,8 @@ export declare class AllowEntryTable {
     seed(entries: readonly string[], roster?: ReadonlySet<string>): readonly AllowEntryInert[];
     /** The entries held, as written (a copy) — what a delegated child is handed. */
     entries(): readonly string[];
+    /** Does the table hold a path row — must the leg read each call's target views for it? */
+    holdsPathRows(): boolean;
     /** The lane over this table, bound to the leg's call facts. */
     lane(ctx: AllowEntryJudgeContext): AllowEntryLane;
 }
@@ -209,6 +217,7 @@ declare const SHADOW_REASON: {
     readonly ancestor: "the task that delegated this one owns this question";
     readonly dangerous_delete: "this removal targets a protected location (the filesystem root, a top-level directory, a home directory, or a workspace directory or one of its ancestors) — it is cleared by confirming this call, never by an allow rule";
     readonly unverifiable_delete: "this removal could not be verified safe — it is cleared by confirming this call, never by an allow rule";
+    readonly unverifiable_shell_text: "the text this shell will run cannot be read by the engine — it is cleared by confirming this call, never by an allow rule";
     readonly transcript_write: "this write targets the session transcript — it is cleared by confirming this call, never by an allow rule";
     readonly org_rule: "an organization policy rule requires approval for this call";
     readonly governance_unavailable: "this deployment is org-governed and cannot currently read its organization policy";
@@ -219,7 +228,7 @@ declare const SHADOW_REASON: {
     readonly requires_user_interaction: "this tool's server declares that a call must be put to a person";
     readonly operator_forced: "this call arrived already marked as requiring confirmation (an earlier layer of this run, or the task that delegated it, judged it so) — it is cleared by confirming this call, never by a standing allow rule";
     readonly shell_floor: string;
-    readonly write_protection_unresolved: string;
+    readonly target_unresolved: string;
     readonly probe: string;
     readonly write_protection: string;
     readonly tool_marks_mcp: string;