@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/hooks.d.ts

@@ -668,14 +668,13 @@ export interface PersistedRuleHitRule {
  * the whole command is a one-element set (the historical case); a compound admitted by the conjunction
  * of per-segment rules (design/375 §5.1) is the set of those rules, in segment order. For a `deny` or an
  * `ask` the set is the one rule of that behavior that reaches the call (the lane's precedence walk —
- * deny > ask > allow — already chose it). `rules` is non-empty by contract — an empty set covers nothing
- * and is not a hit (the normalizer reads it as a clean negative).
+ * deny > ask > allow — already chose it). `rules` is non-empty by contract: a lane with no rule for the call answers
+ * `undefined`, and an empty set is an answer the gate cannot read (`unreadable`).
  *
  * Why dots and not an id: a persisted rule HAS no scalar id — it is a (behavior, text, scope) group whose identity is
  * the set of add dots that redeemed it, and two concurrently approved records for one text each carry their own.
  *
- * The pre-375 single-rule object shape (`{ rule, dots? }`) and the pre-behavior `{ rules }` shape are NOT accepted:
- * on this loosening seam an unrecognized answer degrades to a clean negative (more asks), never to a match.
+ * The pre-375 `{ rule, dots? }` and the pre-behavior `{ rules }` shapes are NOT accepted: they read as `unreadable`.
  */
 export interface PersistedRuleHit {
     /** What the deciding rule(s) say about the call — the closed set's word. */
@@ -699,7 +698,8 @@ export interface PersistedRuleUnreadable {
     /** WHY the lane could not read: absent for a store (or partition) read failure — the store form, a real-approval ask of
      *  class `rule_unreadable`; for a CALL the lane could not read against the person's standing deny/ask rows (an
      *  expansion where a rule reads a word, an unterminated quote, a syntax error) the lexer's reason — the call form, an allow
-     *  tightens to a real-approval ask of the same class. Both carry the origin `rule_store_unavailable`. */
+     *  tightens to a real-approval ask of the same class — also the gate's reading of a lane answer it cannot read (the reason
+     *  then names this seat and the failed field). Both carry the origin `rule_store_unavailable`. */
     readonly reason?: string;
 }
 /**
@@ -714,8 +714,8 @@ export interface PersistedRuleUnreadable {
 export interface PersistedRuleCoverage {
     readonly segmentCoverage: readonly import("./permission-rule-model.js").SegmentCoverage[];
 }
-/** Every shape a lane may answer with. The retired bare-string form (a single allow rule's text) is read
- *  by the normalizer as a clean negative, like every other unrecognized shape. */
+/** Every shape a lane may answer with: `undefined` and the coverage answer say "no rule speaks"; any other value (`null`, a
+ *  bare string, a `behavior` outside the closed set, …) is read by the normalizer as `unreadable`, naming the field. */
 export type PersistedRuleAnswer = PersistedRuleHit | PersistedRuleCoverage | PersistedRuleUnreadable | undefined;
 /** Inputs to the two-phase tool gate. `adjudicate`/`resolveAsk` are pre-bound to the task abort
  *  signal; when the caller also supplies {@link ToolGateInput.callSignal}, the Runner's closures
@@ -1099,7 +1099,7 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
      * notice is composed from (`ask-unresolvable-notice.ts`); `parkLaneExisted` = a park lane was armed for this run; `remedy` = the
      * caller-side change that would have let the call run, present for the causes that say nobody could be asked (`approver_unavailable`,
      * `no_approver_wired`) — for arguments no approval can be bound to, the binding's own sentence (the remedy's approver half would not
-     * let them run). Observe-only: a throwing seat never alters the deny. Absent ⇒ the deny stands silently (no notice sink).
+     * let them run); `remedies` = its ways out as data, beside `remedy`. Observe-only: a throwing seat never alters the deny. Absent ⇒ the deny stands silently (no notice sink).
      */
     onAskUnresolvable?: (info: {
         toolName: string;
@@ -1107,6 +1107,7 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
         cause: import("./ask-unresolvable-notice.js").AskUnresolvableCause;
         parkLaneExisted: boolean;
         remedy?: string;
+        remedies?: readonly import("./ask-origin.js").ApprovalRemedy[];
     }) => void;
     /**
      * design/153 §2/§7.4 (件4 复审, MED): true means this call's ask is MARKED — an inherited ancestor
@@ -1173,7 +1174,7 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
     persistedRules?: {
         /** The lane's verdict for this call — a {@link PersistedRuleHit} naming the behavior that spoke and
          *  the rule set it stands on, a coverage-carrying clean negative, an unreadable report, or
-         *  `undefined` (the store was READ and no rule speaks). Must not throw — and a store (or a partition of it) that cannot
+         *  `undefined` (the store was READ and no rule speaks; `null` is not that word). Must not throw — and a store (or a partition of it) that cannot
          *  be read answers `{ unreadable: true }`, not `undefined`: it fails closed (a row nobody could read may forbid the call;
          *  the decision becomes a real-approval ask) and the evidence records `"unavailable"`, not `"no_match"`; the lane owns
          *  announcing the skip. A call unreadable against the rows answers `{ unreadable: true, reason }` (the call form).
@@ -1183,9 +1184,9 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
          *  per-segment conjunction (design/375 §5.1) is the set of the covering rules. The dots are a rule's
          *  durable identity, and the text is not one (it reaches a card sanitized and capped); a lane that
          *  can name them lets the shadowed-ask evidence say WHICH stored rules matched rather than merely
-         *  what they looked like. The retired shapes — a bare rule TEXT, the pre-375 `{ rule, dots? }` object,
-         *  a `{ rules }` hit without its behavior — are read as a clean negative by the normalizer: a stale
-         *  lane degrades toward asking, never toward an allow. Consulted on EVERY decision (a deny/ask row
+         *  what they looked like. Every answer outside the shapes above (`null`, a bare rule TEXT, the pre-375 `{ rule, dots? }`
+         *  object, a hit without a closed-set `behavior` or a non-empty `rules`) reads as `{ unreadable: true, reason }` — the
+         *  call form, naming this seat and the failed field: a real-approval ask, never "no rule". Consulted on EVERY decision (a deny/ask row
          *  must be able to tighten an allow), so the lane pays one store read per call on the tools it
          *  speaks for; the runner's lane hands the org layer's read to it, so a governed deployment still
          *  pays one. */
@@ -1251,8 +1252,8 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
     /**
      * F-012 L2 — the SANDBOX ADMISSION leg. Present ONLY when the runner armed the mode: the execution
      * env DECLARES isolation (`RemoteExecutionEnv.capabilities.isolation === true` — a Runner-resolved
-     * fact, never caller self-report) AND the park prerequisites hold (durable park configured + a
-     * checkpoint store that explicitly declares `redecision.reopen`). Absent ⇒ the whole step does not
+     * fact, never caller self-report) AND the park prerequisites hold (durable park configured + a wired
+     * checkpoint store — every store carries the required `reopen`, read at its seat). Absent ⇒ the whole step does not
      * exist and the decision path is byte-identical to a build without it.
      *
      * Semantics (the ruling): inside a declared sandbox, an engine-authored "confirm a potentially
@@ -1394,10 +1395,10 @@ export declare function askCarryRowMembers(carry: AskCarry | undefined): {
  *  2. **adjudicate** — run the tool policy on the FINAL `currentInput` (never the model's stale args),
  *     fold it with any remembered hook-ask via `deny > ask > allow`, and resolve a surviving `ask`
  *     through `onAsk`. The policy ALWAYS runs regardless of the hook's verdict. A policy `allow` may
- *     itself carry an `updatedInput` rewrite (redact/clamp), applied last over any hook rewrite.
+ *     itself carry an `updatedInput` rewrite (redact/clamp), applied last over any hook rewrite — which the hook, having
+ *     judged the earlier bytes, judges once (rewrite-rejudge.ts: a deny or yet another form there refuses the call).
  *
- * Because both phases run in this one linear function, the ordering — and the "policy is final"
- * invariant — is enforced by the call stack, not by registration convention. Returns the gate result
- * for the harness `tool_call` hook plus the PreToolUse context to attach to the tool result.
+ * Both phases run in this one linear function, so the ordering — and the "policy is final" invariant — is the call stack's,
+ * not a registration convention. Returns the gate result for the `tool_call` hook plus the PreToolUse context for the result.
  */
 export declare function runToolGate(input: ToolGateInput): Promise<ToolGateResult>;

package/dist/core/hooks.js

@@ -98,6 +98,7 @@ function preToolUseAnswerViolation(answer) {
         return undefined;
     return typeof r.message === "string" ? r.message : "the PreToolUse answer was refused by the engine";
 }
+const PRE_TOOL_USE_RANKS = Object.freeze({ of: (a) => { const r = a === ENGINE_CORE_ANSWER ? undefined : screenPreToolUseResult(a); return !r ? 0 : r.action === "deny" ? 3 : r.action === "ask" ? (r.requiresRealApproval === true ? 2 : 1) : 0; }, top: 3 });
 function preToolUseRefusedReason(subject, failed) {
     if (failed === undefined) {
         return `the task was cancelled while a PreToolUse hook was still screening ${subject}; the call was NOT executed ` + `(fail-closed). No verdict was reached — this is the run ending, not the tool failing.`;
@@ -130,7 +131,7 @@ export function createPreToolUseScreening(input) {
         screen: async (args, subject) => {
             let outcome;
             try {
-                outcome = await dispatchClassic(bus, "classic.PreToolUse", eventOf(args), { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), checkAnswer: preToolUseAnswerViolation });
+                outcome = await dispatchClassic(bus, "classic.PreToolUse", eventOf(args), { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), checkAnswer: preToolUseAnswerViolation, ranks: PRE_TOOL_USE_RANKS });
             }
             catch (err) {
                 return { kind: "refused", reason: preToolUseRefusedReason(subject, { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the screening: ${describeThrown(err)}`, skipped: [] }) };
@@ -162,6 +163,7 @@ export function createPreToolUseConstraintPolicy(chain, env) {
                     participant: judges,
                     ...(signal !== undefined ? { signal } : {}),
                     checkAnswer: (a) => (a === ENGINE_CORE_ANSWER ? undefined : preToolUseAnswerViolation(a)),
+                    ranks: PRE_TOOL_USE_RANKS,
                 });
             }
             catch (err) {

package/dist/core/host-floor.d.ts

@@ -0,0 +1,128 @@
+import { type HostReading } from "./host-target.js";
+import type { ToolPolicy } from "./tool-policy.js";
+/**
+ * Is this host obviously internal — loopback / private ranges / link-local incl. cloud metadata / CGNAT / IPv6 ULA, site-local,
+ * unspecified, IPv4-mapped, NAT64? Classifies with `net.isIP` rather than a string-prefix regex (a prefix regex both under-matches
+ * — `::ffff:`, NAT64, CGNAT, `::` — and over-matches any DNS name starting `fc`/`fd`). Numeric IPv4 forms (decimal/octal/hex) are
+ * normalized to dotted-decimal by `URL` before this is called. Checks the LITERAL host: it does NOT resolve DNS, so a name that
+ * resolves to a private address is not caught here (a connection-layer concern).
+ */
+export declare function isPrivateHost(host: string): boolean;
+/**
+ * `RunnerDeps.hostFloor` — the hosts this deployment's structured egress may reach, read by the gate and by every engine executor
+ * that opens a connection (the fetch tool, task images, MCP http servers, A2A peers, WebSearch's SearXNG backend). Entries are host patterns: `example.com` (that
+ * host) or `*.example.com` (every host below it, never itself).
+ */
+export interface HostFloorDeclaration {
+    /** Hosts this deployment never reaches. */
+    readonly deny?: readonly string[];
+    /** Present ⇒ the ONLY hosts this deployment reaches (`[]` = none, legal and explicit). An entry that names a private address (or
+     *  `localhost`) also lifts the private-network floor for it — the deployment named it. */
+    readonly only?: readonly string[];
+}
+/** Where a host stands on the floor. */
+export type HostFloorReach = "denied" | "outside_only" | "admitted";
+/** The floor's posture — what the wiring manifest reports (counts, never the entries' text). */
+export interface HostFloorPosture {
+    readonly onlyMode: boolean;
+    readonly denyCount: number;
+    readonly onlyCount: number;
+}
+/** A compiled host floor (frozen). */
+export interface HostFloor {
+    /** The entries in their one spelling (`example.com`, `*.example.com`) — what an enforcement point outside the engine (an egress
+     *  proxy, a container policy) is generated from. */
+    readonly entries: {
+        readonly deny: readonly string[];
+        readonly only?: readonly string[];
+    };
+    readonly posture: HostFloorPosture;
+    /** Where this host (as `hostOfUrl` reads it) stands: a `deny` entry reaches it ⇒ `denied`; an `only` list that reaches it not ⇒
+     *  `outside_only`; else `admitted`. */
+    reach(host: string): HostFloorReach;
+    /** Does an `only` entry name this host — the one way a private host becomes reachable? */
+    lifts(host: string): boolean;
+}
+/** The code a host floor that does not read refuses the prepare with (and a resume before its claim). */
+export declare const HOST_FLOOR_INVALID_CODE = "config.host_floor_invalid";
+/**
+ * The declaration as the engine holds it: read ONCE through the engine's declaration receipt (`DECLARATION_RECEIPT_MODE`: every own
+ * member off its captured descriptor, a getter called once, every level copied and frozen; a Proxy at any level, a non-plain object —
+ * a `Map`, a class instance, an object of another prototype — and anything that is not data refused). A frozen copy received again is
+ * the same data, so the Runner's construction (which keeps this copy) and every prepare after it read one declaration.
+ */
+export declare function receiveHostFloor(declared: unknown): unknown;
+/**
+ * Compile `RunnerDeps.hostFloor` once (absent ⇒ undefined: no floor), from the declaration's receipt ({@link receiveHostFloor}). A
+ * declaration that does not read — not plain data, not a record, a member other than `deny` / `only`, a member that is not a list,
+ * an entry that is no host pattern, an `only` entry every host of which a `deny` entry also reaches (it could never admit anything)
+ * — throws {@link HOST_FLOOR_INVALID_CODE}, naming the member and entry.
+ */
+export declare function compileHostFloor(declared: HostFloorDeclaration | undefined): HostFloor | undefined;
+/** The floor's half of the judge, on a host reading: a host it does not admit, or no host it can read, is refused (the sentence);
+ *  undefined when the floor admits it. The gate's narrowing layer reads this half alone (the private-network floor is the
+ *  connecting executor's). */
+export declare function floorRefusal(reading: HostReading, floor: HostFloor): string | undefined;
+/**
+ * The gate's reader of the floor — a deny-only narrowing layer core owns (no rule, mode or approver clears it): a call whose URL slot
+ * (`callHostTargetOf`, the protective reading) names a host the floor does not admit, or names no host it can read, is refused before
+ * anything else is asked; a call with no URL slot is not this layer's. Composed by the policy chain like the other narrowing layers, so
+ * it also re-judges a rewritten call and an approved call on resume.
+ */
+export declare function hostFloorPolicy(floor: HostFloor): ToolPolicy;
+/**
+ * THE judge of one egress hop, before it is requested: the URL must be http(s) and name a host the rules can read (`hostOfUrl`), the
+ * deployment's floor must admit that host, and — for an executor that holds the private-network floor (`privateFloor`: the fetch
+ * tool and task images) — a private host must be one an `only` entry names. Returns the refusal sentence, or undefined.
+ */
+export declare function hopRefusal(url: URL, floor: HostFloor | undefined, privateFloor: boolean): string | undefined;
+/** The code a protocol peer's request is refused with when the hop judge refuses its URL — the declared endpoint at a dial, an A2A
+ *  card's endpoint, a redirect target (a `config.*` word: the deployment named a peer its own floor does not admit — and, floor or
+ *  none, a peer's redirect that names credentials or whose Location does not read gets it too). */
+export declare const HOST_FLOOR_REFUSED_CODE = "config.host_floor_refused";
+/** The refusal a protocol request carries when {@link hopRefusal} refuses its URL (no private-network floor: an MCP endpoint and an
+ *  A2A peer's declared URL are the deployment's own declaration; an A2A card's endpoint and a redirect target are the peer's words and get none
+ *  today). `what` names the request (`mcp: server "x"`, `a2a: peer "y"`). */
+export declare function peerRequestRefusal(what: string, url: URL, floor: HostFloor | undefined): (Error & {
+    code: string;
+}) | undefined;
+/** How a transport follows redirects: its hop judge, whether it takes a judged redirect, and its hop budget. */
+export interface FollowLaw {
+    /** The hop judge (each transport binds {@link hopRefusal} to its floor and its private-network posture). */
+    readonly refusal: (url: URL) => string | undefined;
+    /** Whether a redirect the judge admitted is followed (else it is handed back as `unfollowed`). */
+    readonly follows: (from: URL, to: URL) => boolean;
+    /** Redirects followed at most (the request after the last one is refused as `too_many`). */
+    readonly maxRedirects: number;
+    /** Every hop's response, 3xx included, as it arrives. */
+    readonly onResponse?: (res: Response) => void;
+}
+/** One request's outcome under a {@link FollowLaw}. */
+export type FollowOutcome = {
+    readonly kind: "answered";
+    readonly res: Response;
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+} | {
+    readonly kind: "unfollowed";
+    readonly res: Response;
+    readonly from: URL;
+    readonly to: URL;
+} | {
+    readonly kind: "too_many";
+};
+/** The request init a followed hop is sent with. */
+export interface FollowInit {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * ONE request, following redirects by hand: every hop is judged ({@link FollowLaw.refusal}) BEFORE it is requested — the first URL
+ * and every redirect target — so a hop the judge refuses is never contacted; a judged redirect the transport does not take is handed
+ * back with its response; a status outside the fetch standard's redirect set (301, 302, 303, 307, 308), or one of them without a
+ * Location, is the answer. A Location that does not parse is a refusal. A redirect's response that is followed or refused is released.
+ */
+export declare function fetchFollowing(doFetch: typeof fetch, start: URL, init: FollowInit, law: FollowLaw): Promise<FollowOutcome>;

package/dist/core/host-floor.js

@@ -0,0 +1,206 @@
+import { isIP } from "node:net";
+import { HOST_UNREADABLE_SENTENCE, callHostTargetOf, hostOfUrl, hostPatternAdmits, readHostPattern, spelledHostPattern } from "./host-target.js";
+import { inlineUntrusted } from "./untrusted-text.js";
+import { describeFault, isPlainRecord, receive } from "./mods/kernel/receive.js";
+import { DECLARATION_RECEIPT_MODE } from "./own-property-receipt.js";
+function isPrivateV4(ip) {
+    const o = ip.split(".").map(Number);
+    if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return true;
+    const [a = -1, b = -1] = o;
+    return (a === 127 ||
+        a === 10 ||
+        a === 0 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254) ||
+        (a === 100 && b >= 64 && b <= 127));
+}
+function embeddedV4(h) {
+    const fromHex = (hi, lo) => {
+        const a = parseInt(hi, 16), c = parseInt(lo, 16);
+        return `${(a >> 8) & 255}.${a & 255}.${(c >> 8) & 255}.${c & 255}`;
+    };
+    let m = /^(?:::ffff:|64:ff9b::)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(h);
+    if (m)
+        return m[1];
+    m = /^(?:::ffff:|64:ff9b::)([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(h);
+    const [, hi, lo] = m ?? [];
+    return hi !== undefined && lo !== undefined ? fromHex(hi, lo) : undefined;
+}
+export function isPrivateHost(host) {
+    const h = host
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.+$/, "")
+        .toLowerCase();
+    if (h === "localhost")
+        return true;
+    const fam = isIP(h);
+    if (fam === 0)
+        return false;
+    if (fam === 4)
+        return isPrivateV4(h);
+    const v4 = embeddedV4(h);
+    if (v4)
+        return isPrivateV4(v4);
+    if (h === "::1" || h === "::")
+        return true;
+    return /^fe[89ab]/.test(h) || /^f[cd]/.test(h) || /^fe[c-f]/.test(h);
+}
+export const HOST_FLOOR_INVALID_CODE = "config.host_floor_invalid";
+const FLOOR_MEMBERS = ["deny", "only"];
+function floorInvalid(what) {
+    return Object.assign(new Error(`RunnerDeps.hostFloor ${what} — a host floor that does not read is refused whole, never half-armed (an entry is a host pattern: \`example.com\` or \`*.example.com\`).`), { code: HOST_FLOOR_INVALID_CODE });
+}
+function readEntries(value, member) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw floorInvalid(`.${member} must be a list of host patterns (got ${value === null ? "null" : typeof value})`);
+    const list = value;
+    const patterns = [];
+    for (let i = 0; i < list.length; i++) {
+        const entry = list[i];
+        if (typeof entry !== "string")
+            throw floorInvalid(`.${member}[${i}] must be a string (got ${entry === null ? "null" : typeof entry})`);
+        const read = readHostPattern(entry);
+        if ("problem" in read) {
+            const why = read.problem === "every_host" ? "names every host"
+                : read.problem === "inner_wildcard" ? "carries a `*` other than a leading `*.`"
+                    : read.problem === "below_address" ? "names hosts below an address, which has none"
+                        : read.problem === "empty_label" ? "names a host with an empty label (a leading or doubled dot) — write the host itself, and every host below a domain as `*.<domain>`"
+                            : "is more or less than a host (a scheme, a port, a path, credentials or whitespace)";
+            throw floorInvalid(`.${member}[${i}] "${inlineUntrusted(entry, 120)}" ${why}`);
+        }
+        patterns.push(read.pattern);
+    }
+    return patterns;
+}
+function covers(d, o) {
+    if (d.match === "host")
+        return o.match === "host" && o.host === d.host;
+    return o.host === d.host ? o.match === "subdomain" : hostPatternAdmits(d, o.host);
+}
+export function receiveHostFloor(declared) {
+    if (declared === undefined)
+        return undefined;
+    const received = receive(declared, DECLARATION_RECEIPT_MODE);
+    if (!received.ok)
+        throw floorInvalid(`could not be read as plain data — ${describeFault(received.fault)}`);
+    return received.value;
+}
+export function compileHostFloor(declared) {
+    const value = receiveHostFloor(declared);
+    if (value === undefined)
+        return undefined;
+    if (!isPlainRecord(value))
+        throw floorInvalid(`must be a record { deny?, only? } (got ${value === null ? "null" : Array.isArray(value) ? "a list" : typeof value})`);
+    const unknownMember = Object.keys(value).find((k) => !FLOOR_MEMBERS.includes(k));
+    if (unknownMember !== undefined)
+        throw floorInvalid(`has a member "${inlineUntrusted(unknownMember, 60)}" — its members are \`deny\` and \`only\``);
+    const deny = readEntries(value.deny, "deny") ?? [];
+    const only = readEntries(value.only, "only");
+    for (const o of only ?? []) {
+        const d = deny.find((candidate) => covers(candidate, o));
+        if (d !== undefined)
+            throw floorInvalid(`.only entry "${spelledHostPattern(o)}" is wholly denied by the .deny entry "${spelledHostPattern(d)}" — it could never admit a host`);
+    }
+    const reach = (host) => deny.some((d) => hostPatternAdmits(d, host)) ? "denied" : only !== undefined && !only.some((o) => hostPatternAdmits(o, host)) ? "outside_only" : "admitted";
+    return Object.freeze({
+        entries: Object.freeze({ deny: Object.freeze(deny.map(spelledHostPattern)), ...(only !== undefined ? { only: Object.freeze(only.map(spelledHostPattern)) } : {}) }),
+        posture: Object.freeze({ onlyMode: only !== undefined, denyCount: deny.length, onlyCount: only?.length ?? 0 }),
+        reach,
+        lifts: (host) => only !== undefined && reach(host) === "admitted",
+    });
+}
+export function floorRefusal(reading, floor) {
+    if ("unreadable" in reading)
+        return `${HOST_UNREADABLE_SENTENCE[reading.unreadable]}, and this deployment's host floor admits only a host it can read`;
+    const reach = floor.reach(reading.host);
+    if (reach === "admitted")
+        return undefined;
+    const host = inlineUntrusted(reading.host, 253);
+    return reach === "denied" ? `host "${host}" is denied by this deployment's host floor (hostFloor.deny)` : `host "${host}" is outside the hosts this deployment reaches (hostFloor.only)`;
+}
+export function hostFloorPolicy(floor) {
+    return {
+        check: (req) => {
+            const reading = callHostTargetOf(req, "tighten");
+            const refused = reading === undefined ? undefined : floorRefusal(reading, floor);
+            return refused === undefined ? { action: "allow" } : { action: "deny", message: `${refused} — no rule, mode or approval clears the deployment's host floor`, decisionReason: "rule" };
+        },
+    };
+}
+export function hopRefusal(url, floor, privateFloor) {
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return `a non-http(s) URL (${inlineUntrusted(url.protocol, 40)}) was refused`;
+    const reading = hostOfUrl(url.toString());
+    if ("unreadable" in reading)
+        return `${HOST_UNREADABLE_SENTENCE[reading.unreadable]}; refused`;
+    const floored = floor !== undefined ? floorRefusal(reading, floor) : undefined;
+    if (floored !== undefined)
+        return `${floored}; refused`;
+    if (privateFloor && isPrivateHost(reading.host) && floor?.lifts(reading.host) !== true) {
+        return `host "${inlineUntrusted(reading.host, 253)}" is private/internal; refused (SSRF guard — reachable only when this deployment's hostFloor.only names it)`;
+    }
+    return undefined;
+}
+export const HOST_FLOOR_REFUSED_CODE = "config.host_floor_refused";
+export function peerRequestRefusal(what, url, floor) {
+    const reason = hopRefusal(url, floor, false);
+    return reason === undefined ? undefined : Object.assign(new Error(`${what} is not contacted — ${reason}`), { code: HOST_FLOOR_REFUSED_CODE });
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function release(res) {
+    const body = res.body;
+    if (typeof body?.cancel === "function")
+        void body.cancel().catch(() => undefined);
+}
+function followedInit(status, init) {
+    if (!(status === 303 || ((status === 301 || status === 302) && init.method === "POST")) || init.method === "GET" || init.method === "HEAD")
+        return init;
+    const BODY_HEADERS = ["content-type", "content-encoding", "content-language", "content-location", "content-length"];
+    const headers = Object.fromEntries(Object.entries(init.headers).filter(([k]) => !BODY_HEADERS.includes(k.toLowerCase())));
+    return { method: "GET", headers, ...(init.signal !== undefined ? { signal: init.signal } : {}) };
+}
+export async function fetchFollowing(doFetch, start, init, law) {
+    let current = start;
+    let hopInit = init;
+    for (let hop = 0; hop <= law.maxRedirects; hop++) {
+        const refused = law.refusal(current);
+        if (refused !== undefined)
+            return { kind: "refused", reason: refused };
+        const res = await doFetch(current.toString(), {
+            method: hopInit.method,
+            headers: hopInit.headers,
+            redirect: "manual",
+            ...(hopInit.body !== undefined ? { body: hopInit.body } : {}),
+            ...(hopInit.signal !== undefined ? { signal: hopInit.signal } : {}),
+        });
+        law.onResponse?.(res);
+        if (!REDIRECT_STATUSES.has(res.status))
+            return { kind: "answered", res };
+        const location = res.headers.get("location");
+        if (!location)
+            return { kind: "answered", res };
+        let next;
+        try {
+            next = new URL(location, current);
+        }
+        catch {
+            release(res);
+            return { kind: "refused", reason: `invalid redirect Location: ${inlineUntrusted(location, 200)}` };
+        }
+        const nextRefused = law.refusal(next);
+        if (nextRefused !== undefined) {
+            release(res);
+            return { kind: "refused", reason: nextRefused };
+        }
+        if (!law.follows(current, next))
+            return { kind: "unfollowed", res, from: current, to: next };
+        release(res);
+        hopInit = followedInit(res.status, hopInit);
+        current = next;
+    }
+    return { kind: "too_many" };
+}

package/dist/core/host-target.d.ts

@@ -11,12 +11,47 @@
  * Leaf module: it reads the catalog's host slots (the protective floor) and the name-reading seat, nothing else.
  */
 import { type ToolCallLike } from "./tool-registry.js";
-/** The host a spelling names as the URL parser reads it (trailing dots read off), or undefined when the spelling is more or
- *  less than a host: empty, carrying whitespace or a separator a URL reads as something else, a port (a `:` outside an
- *  address's brackets), credentials, a path. */
+/**
+ * THE reading of a host's spelling: the host as the URL parser reads it (lower case, IDN in its ASCII form, a full-width dot
+ * folded, an IPv4 shorthand expanded, trailing dots read off), or why it names none — `empty_label` for a name with an empty
+ * label once its trailing dots are read off (`.evil.test`, `a..test`: no host has one, and nothing a rule or a floor entry is
+ * matched against ever does), `not_a_host` for a spelling that is more or less than a host (empty, carrying whitespace or a
+ * separator a URL reads as something else, a port — a `:` outside an address's brackets —, credentials, a path).
+ */
+export declare function readSpelledHost(spelled: string): {
+    readonly host: string;
+} | {
+    readonly problem: "empty_label" | "not_a_host";
+};
+/** The host a spelling names ({@link readSpelledHost}), or undefined when it names none. */
 export declare function hostOfSpelling(spelled: string): string | undefined;
 /** Is this host (as {@link hostOfUrl} reads it) an address — the URL parser's IPv4 form or a bracketed IPv6? */
 export declare function isAddressHost(host: string): boolean;
+/** A host pattern: one exact host (`host`), or every host BELOW a domain at any depth, never the domain itself (`subdomain`). */
+export interface HostPattern {
+    readonly match: "host" | "subdomain";
+    readonly host: string;
+}
+/** Why a spelling is no host pattern: `*` alone (every host), a `*` other than a leading `*.`, a host with an empty label (a
+ *  leading or doubled dot — "this domain and every host below" is two patterns, `example.com` and `*.example.com`), more or less
+ *  than a host, a `*.` over an address (an address has no subdomains). */
+export type HostPatternProblem = "every_host" | "inner_wildcard" | "empty_label" | "not_a_host" | "below_address";
+/**
+ * THE reader of a host pattern's spelling — `example.com` or `*.example.com` — for every place one is written: the content of a
+ * `<Tool>(domain:<pattern>)` rule and an entry of the deployment's host floor. The `*.` operator is the spelling's leading two
+ * characters; the host after it is read by {@link readSpelledHost}, must hold no `*` as read (a full-width or small asterisk the
+ * parser folds included) and must read back as itself; each caller words its own refusal from the problem.
+ */
+export declare function readHostPattern(spelled: string): {
+    readonly pattern: HostPattern;
+} | {
+    readonly problem: HostPatternProblem;
+};
+/** A pattern as it is written back: the host, or `*.` and the domain. */
+export declare function spelledHostPattern(pattern: HostPattern): string;
+/** Does the pattern reach this host (as {@link hostOfUrl} reads it)? `host`: equal; `subdomain`: a name ending in `.<domain>` with
+ *  at least one label before it and no empty label. */
+export declare function hostPatternAdmits(pattern: HostPattern, host: string): boolean;
 /** Why a URL names no host a rule can be judged on — the closed set the fetch tool maps to its own refusal sentences:
  *  not a string; not a URL; not http(s); credentials in it; a host that does not read back as itself once its trailing dots
  *  are read off (`https://2130706433../` — the parser keeps the name, the rule side reads `127.0.0.1`). */

package/dist/core/host-target.js

@@ -1,23 +1,56 @@
 import { hostTargetOf } from "./tool-registry.js";
 import { seatOf } from "./tool-name-readings.js";
-export function hostOfSpelling(spelled) {
+export function readSpelledHost(spelled) {
     if (spelled === "" || /[\s/\\@?#%]/.test(spelled) || (spelled.includes(":") && !/^\[[^\]]+\]$/.test(spelled)))
-        return undefined;
+        return { problem: "not_a_host" };
     let url;
     try {
         url = new URL(`https://${spelled}/`);
     }
     catch {
-        return undefined;
+        return { problem: "not_a_host" };
     }
     if (url.port !== "" || url.username !== "" || url.password !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "")
-        return undefined;
+        return { problem: "not_a_host" };
     const host = url.hostname.replace(/\.+$/, "");
-    return host === "" ? undefined : host;
+    if (host === "")
+        return { problem: "not_a_host" };
+    return !host.startsWith("[") && host.split(".").includes("") ? { problem: "empty_label" } : { host };
+}
+export function hostOfSpelling(spelled) {
+    const read = readSpelledHost(spelled);
+    return "host" in read ? read.host : undefined;
 }
 export function isAddressHost(host) {
     return host.startsWith("[") || /^\d+\.\d+\.\d+\.\d+$/.test(host);
 }
+export function readHostPattern(spelled) {
+    if (spelled === "*")
+        return { problem: "every_host" };
+    const below = spelled.startsWith("*.");
+    const read = readSpelledHost(below ? spelled.slice(2) : spelled);
+    if ("problem" in read)
+        return read;
+    const host = read.host;
+    if (host.includes("*"))
+        return { problem: "inner_wildcard" };
+    if (hostOfSpelling(host) !== host)
+        return { problem: "not_a_host" };
+    if (below && isAddressHost(host))
+        return { problem: "below_address" };
+    return { pattern: { match: below ? "subdomain" : "host", host } };
+}
+export function spelledHostPattern(pattern) {
+    return pattern.match === "subdomain" ? `*.${pattern.host}` : pattern.host;
+}
+export function hostPatternAdmits(pattern, host) {
+    if (pattern.match === "host")
+        return host === pattern.host;
+    if (isAddressHost(host) || !host.endsWith(`.${pattern.host}`))
+        return false;
+    const labels = host.slice(0, -(pattern.host.length + 1));
+    return labels !== "" && !labels.split(".").includes("");
+}
 export const HOST_UNREADABLE_REASONS = Object.freeze(["not_text", "not_url", "not_http", "credentials", "unstable"]);
 export const HOST_UNREADABLE_SENTENCE = Object.freeze({
     not_text: "the URL argument is not a string",