@sema-agent/core 7.1.0 → 7.3.0

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

@@ -0,0 +1,184 @@
+import { isPermissionModeClass } from "./cross-session-envelope.js";
+export const CROSS_SESSION_INBOUND_SETTINGS = Object.freeze(["accept", "hold", "refuse"]);
+export function isCrossSessionInboundSetting(value) {
+    return typeof value === "string" && CROSS_SESSION_INBOUND_SETTINGS.includes(value);
+}
+const RANK = { accept: 0, hold: 1, refuse: 2 };
+function readLayer(v) {
+    if (v === undefined || v === null || v === "default")
+        return undefined;
+    return isCrossSessionInboundSetting(v) ? v : "invalid";
+}
+export function resolveCrossSessionInboundSetting(layers) {
+    const invalidLayers = [];
+    let value;
+    let decidedBy;
+    for (const [name, raw] of [
+        ["managed", layers.managed],
+        ["user", layers.user],
+    ]) {
+        const v = readLayer(raw);
+        if (v === "invalid") {
+            invalidLayers.push(name);
+            continue;
+        }
+        if (v !== undefined && value === undefined) {
+            value = v;
+            decidedBy = name;
+        }
+    }
+    for (const raw of layers.repo ?? []) {
+        const v = readLayer(raw);
+        if (v === "invalid") {
+            invalidLayers.push("repo");
+            continue;
+        }
+        if (v === undefined)
+            continue;
+        if (RANK[v] > RANK[value ?? "accept"]) {
+            value = v;
+            decidedBy = "repo";
+        }
+        else if (v !== "accept" && value !== undefined && RANK[v] === RANK[value] && decidedBy !== "managed") {
+            decidedBy = "repo";
+        }
+    }
+    if (invalidLayers.length > 0 && RANK[value ?? "accept"] < RANK.hold) {
+        value = "hold";
+        decidedBy = "invalid";
+    }
+    return { ...(value !== undefined ? { value } : {}), ...(decidedBy !== undefined ? { decidedBy } : {}), invalidLayers };
+}
+export const CROSS_SESSION_HOLD_CAUSES = Object.freeze([
+    "mode-mismatch",
+    "no-mode-asserted",
+    "explicit-setting",
+    "managed-setting",
+    "repo-setting",
+    "invalid-setting",
+    "bypass-default",
+    "mode-unknown",
+    "invalid-mode-attestation",
+]);
+export function describeCrossSessionHoldCause(cause) {
+    switch (cause) {
+        case "mode-mismatch":
+            return "The sending session's permission mode class doesn't match this session's, so it wasn't delivered automatically.";
+        case "no-mode-asserted":
+            return "The sender did not attest its permission mode, and this session bypasses permission prompts.";
+        case "explicit-setting":
+            return 'Your "crossSessionInbound" setting is "hold".';
+        case "managed-setting":
+            return `Your organization's managed settings set "crossSessionInbound" to "hold".`;
+        case "repo-setting":
+            return `This repository's settings set "crossSessionInbound" to "hold" (your own "accept" cannot override a repo tightening).`;
+        case "invalid-setting":
+            return 'A settings file has an unrecognized "crossSessionInbound" value (see the settings warning), so messages are held while it is present.';
+        case "bypass-default":
+            return "This session is not prompting for permissions.";
+        case "mode-unknown":
+            return "This session's permission mode could not be determined.";
+        case "invalid-mode-attestation":
+            return "The sender attested an unrecognized permission mode, so the message is held for your review.";
+        default: {
+            const _exhaustive = cause;
+            void _exhaustive;
+            throw new Error(`unreachable hold cause ${String(cause)}`);
+        }
+    }
+}
+function describeUnknown(value) {
+    try {
+        const text = typeof value === "string" ? JSON.stringify(value) : typeof value === "bigint" ? `${value}n` : typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+        return text.length > 80 ? `${text.slice(0, 80)}…` : text;
+    }
+    catch {
+        return `[unrenderable ${typeof value}]`;
+    }
+}
+function holdFor(cause, warning) {
+    return { verdict: "hold", cause, message: describeCrossSessionHoldCause(cause), ...(warning !== undefined ? { warning } : {}) };
+}
+function causeOf(decidedBy) {
+    switch (decidedBy) {
+        case "managed":
+            return "managed-setting";
+        case "repo":
+            return "repo-setting";
+        case "invalid":
+            return "invalid-setting";
+        case "user":
+        case undefined:
+            return "explicit-setting";
+        default: {
+            const _exhaustive = decidedBy;
+            void _exhaustive;
+            throw new Error(`unreachable setting source ${String(decidedBy)}`);
+        }
+    }
+}
+export function judgeCrossSessionInbound(input) {
+    const { setting, selfModeClass, sender } = input;
+    if (setting.value !== undefined) {
+        switch (setting.value) {
+            case "accept":
+                return { verdict: "deliver" };
+            case "refuse":
+                return { verdict: "refuse", cause: "opt-out" };
+            case "hold": {
+                const cause = causeOf(setting.decidedBy);
+                return holdFor(cause, cause === "invalid-setting" ? `unrecognized "crossSessionInbound" value in: ${setting.invalidLayers.join(", ")}` : undefined);
+            }
+            default: {
+                const _exhaustive = setting.value;
+                void _exhaustive;
+                throw new Error(`unreachable setting value ${String(setting.value)}`);
+            }
+        }
+    }
+    if (sender?.selfSent === true)
+        return { verdict: "deliver" };
+    if (selfModeClass === "unknown")
+        return holdFor("mode-unknown");
+    if (sender === undefined)
+        return selfModeClass === "bypass" ? holdFor("bypass-default") : { verdict: "deliver" };
+    if (sender.fromMode !== undefined) {
+        if (!isPermissionModeClass(sender.fromMode)) {
+            return holdFor("invalid-mode-attestation", `sender attested from-mode=${describeUnknown(sender.fromMode)} (expected bypass|prompting)`);
+        }
+        return sender.fromMode === selfModeClass ? { verdict: "deliver" } : holdFor("mode-mismatch");
+    }
+    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 const PEER_SEND_VERDICT_CODES = Object.freeze([
+    "peer_send.stale_socket",
+    "peer_send.socket_busy",
+    "peer_send.too_large",
+    "peer_send.invalid_target",
+    "peer_send.timeout",
+    "peer_send.recipient_refuses",
+    "peer_send.not_reachable",
+    "peer_send.subscription_cap",
+    "peer_send.send_uncertain",
+    "peer_send.other",
+]);
+export function peerSendVerdictSeverity(code) {
+    return code === "peer_send.send_uncertain" || code === "peer_send.recipient_refuses" || code === "peer_send.subscription_cap" ? "degraded" : "error";
+}

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

@@ -0,0 +1,52 @@
+/** CC `aa` / `bmn`: a ref is 6..12 hex characters — the shortest prefix of `sha256(kind:id)` that is
+ *  unique against its sorted neighbours in the LISTING that minted it. */
+export declare const PEER_REF_MIN = 6;
+export declare const PEER_REF_MAX = 12;
+/** CC `Mz`. */
+export declare const PEER_REF_RE: RegExp;
+export interface PeerRefEntry {
+    /** The identity kind (`session`, `agent`, …): part of the hash input so two kinds with the same id
+     *  never share a ref. */
+    kind: string;
+    /** The durable id (a `session.<id>` box handle, an a* agent handle, …). */
+    id: string;
+}
+/**
+ * CC `K8` transcribed on sha256: mint the ref of EVERY entry of one listing. Refs are minted by the
+ * listing side and are valid only against that listing (a ref the model did not just read from a
+ * listing or a disambiguation error will not resolve). The optional `self` entry joins the
+ * disambiguation set (so no ref collides with the caller's own identity) but is not returned.
+ * The hash choice is local to this engine: a ref never crosses a process boundary, so the value
+ * domain (`[0-9a-f]{6,12}`) is what interoperates, not the digest.
+ */
+export declare function mintPeerRef<T extends PeerRefEntry>(entries: readonly T[], self?: PeerRefEntry): Array<T & {
+    ref: string;
+}>;
+/** CC `qN` — the display token. */
+export declare function formatPeerNameRef(name: string, ref: string): string;
+/** CC `V8`/`DO` — split a `name [ref]` token; `undefined` when no ref suffix is present. */
+export declare function parsePeerNameRef(text: string): {
+    name: string;
+    ref: string;
+} | undefined;
+/**
+ * CC `dr` — the MATCHING key of a peer/session name: NFKC → strip control/format code points → trim →
+ * lower-case → collapse whitespace runs to `-`. Every terminal resolves and compares names on this
+ * key (a display name is never the key).
+ */
+export declare function normalizePeerName(name: string): string;
+/** The box-address prefixes of design/385 (`session.<id>` per-session box, `principal.<…>` the
+ *  cross-principal inbox family). Reserved: a NAME may never spell an address. */
+export declare const PEER_ADDRESS_PREFIXES: readonly string[];
+/**
+ * design/385 §2.2 namespace protection (CC `qd` in spirit): a candidate spawn/session name is refused
+ * when its normalized key would shadow an explicit address — a reserved box prefix, a transport
+ * scheme (`uds:` / `bridge:` / `did:`), a socket path, an `@`-bearing team form, or the `*`
+ * broadcast token. Returns the reason, or `undefined` when the name is admissible. Registration-side
+ * check (loud refusal at write time); the resolution ladder ranks explicit addresses first regardless.
+ *
+ * The socket-path arm is judged on the RAW name AND on its normalized key (CC `QHe` runs its
+ * classifier over both): a name that is a socket path in either spelling is refused, since the
+ * resolution ladder would read the raw spelling as an address.
+ */
+export declare function reservedPeerNameReason(name: string): "empty" | "address_prefix" | "transport_scheme" | "socket_path" | "at_sign" | "wildcard" | undefined;

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

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+export const PEER_REF_MIN = 6;
+export const PEER_REF_MAX = 12;
+export const PEER_REF_RE = /^[0-9a-f]{6,12}$/;
+function refHash(e) {
+    return createHash("sha256").update(`${e.kind}:${e.id}`).digest("hex");
+}
+function commonPrefixLen(a, b) {
+    let n = 0;
+    while (n < a.length && n < b.length && a[n] === b[n])
+        n++;
+    return n;
+}
+export function mintPeerRef(entries, self) {
+    const hashes = entries.map(refHash);
+    const universe = [...new Set([...hashes, ...(self !== undefined ? [refHash(self)] : [])])].sort();
+    const lengths = new Map();
+    for (let i = 0; i < universe.length; i++) {
+        const h = universe[i];
+        const shared = Math.max(i > 0 ? commonPrefixLen(h, universe[i - 1]) : 0, i + 1 < universe.length ? commonPrefixLen(h, universe[i + 1]) : 0);
+        lengths.set(h, Math.min(h.length, Math.max(PEER_REF_MIN, shared + 1)));
+    }
+    return entries.map((e, i) => {
+        const h = hashes[i];
+        return { ...e, ref: h.slice(0, Math.min(lengths.get(h), PEER_REF_MAX)) };
+    });
+}
+export function formatPeerNameRef(name, ref) {
+    return `${name} [${ref}]`;
+}
+export function parsePeerNameRef(text) {
+    const m = /^(.*\S)\s*\[([0-9a-f]{6,12})\]$/.exec(text.trim());
+    return m === null ? undefined : { name: m[1], ref: m[2] };
+}
+export function normalizePeerName(name) {
+    return name
+        .normalize("NFKC")
+        .replace(/[\p{Cc}\p{Cf}]/gu, "")
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-");
+}
+export const PEER_ADDRESS_PREFIXES = Object.freeze(["session.", "principal."]);
+const SOCKET_PATH_RE = /^\/\S*\.sock/;
+const NAMED_PIPE_RE = /^[\\/]{2}[.?][\\/]pipe[\\/]/i;
+function isSocketPathSpelling(text) {
+    return SOCKET_PATH_RE.test(text) || NAMED_PIPE_RE.test(text);
+}
+export function reservedPeerNameReason(name) {
+    const key = normalizePeerName(name);
+    if (key === "")
+        return "empty";
+    if (key === "*")
+        return "wildcard";
+    if (key.includes("@"))
+        return "at_sign";
+    if (PEER_ADDRESS_PREFIXES.some((p) => key.startsWith(p)))
+        return "address_prefix";
+    if (/^(?:uds|bridge|did):/.test(key))
+        return "transport_scheme";
+    if (isSocketPathSpelling(name) || isSocketPathSpelling(key))
+        return "socket_path";
+    return undefined;
+}

package/dist/agents/list-agents-tool.d.ts

@@ -0,0 +1,55 @@
+import { Type } from "typebox";
+import type { TaskAccess } from "../core/task-registry.js";
+import { type RosterEntry } from "./roster-store.js";
+import { type PeerDirectory } from "./peer-directory.js";
+export declare const LIST_AGENTS_TOOL_NAME = "ListAgents";
+export declare const LIST_AGENTS_TOOL_ALIAS = "ListPeers";
+/** CC `maxResultSizeChars` for this tool. */
+export declare const LIST_AGENTS_MAX_RESULT_CHARS = 10000;
+export interface ListAgentsToolOptions {
+    /** The peer-session directory (the mount reason; without it the tool is not mounted). */
+    peerDirectory: PeerDirectory;
+    /** This session's own identity — excluded from the peer listing, included in ref disambiguation. */
+    self: {
+        sessionId: string;
+        scope: string;
+    };
+    /** The live registry + this caller's access axes (same axes the SendMessage mount reads). */
+    registry?: {
+        list(access: TaskAccess, opts?: {
+            limit?: number;
+        }): Array<{
+            task_id: string;
+            type: string;
+            status: string;
+            description?: string;
+        }>;
+        getAccessibleTask(id: string, access: TaskAccess): {
+            name?: string;
+            status: string;
+        } | undefined;
+    };
+    access?: TaskAccess;
+    /** design/147 S3a parity — a delegated child's TRUSTED parent view (owner = the parent's task id,
+     *  sessionId = the parent's session), so the siblings SendMessage can reach by name are listed too.
+     *  Unioned with {@link access}, de-duplicated by id; the scope axis is never widened. */
+    parentAccess?: TaskAccess;
+    /** The durable roster (names recorded by earlier processes). Rows are filtered by the caller's
+     *  {@link access} with the store's own predicate (`entryAccessible`) BEFORE anything is listed — a
+     *  shared roster holds other owners'/scopes' names, and a listing is a disclosure face. */
+    roster?: {
+        list(): RosterEntry[] | Promise<RosterEntry[]>;
+    };
+    /** Include dead (offline) peer sessions in the listing. Default false (CC observable form). */
+    includeOffline?: boolean;
+}
+/** One rendered row. `kind` names the lane; `address` is what SendMessage accepts. */
+export interface ListAgentsRow {
+    kind: "peer_session" | "background_agent" | "roster";
+    name: string;
+    /** Peer rows only: the listing-minted ref. */
+    ref?: string;
+    address: string;
+    state: "busy" | "idle" | "offline" | "running" | "finished" | "unknown";
+}
+export declare function createListAgentsTool(opts: ListAgentsToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{}>, unknown>;

package/dist/agents/list-agents-tool.js

@@ -0,0 +1,94 @@
+import { Type } from "typebox";
+import { defineTool } from "../core/tools.js";
+import { inlineUntrusted } from "../core/untrusted-text.js";
+import { formatPeerNameRef } from "./cross-session-ref.js";
+import { entryAccessible } from "./roster-store.js";
+import { mintPeerSessionCandidates, peerSessionBoxHandle } from "./peer-directory.js";
+export const LIST_AGENTS_TOOL_NAME = "ListAgents";
+export const LIST_AGENTS_TOOL_ALIAS = "ListPeers";
+export const LIST_AGENTS_MAX_RESULT_CHARS = 10_000;
+export function createListAgentsTool(opts) {
+    return defineTool({
+        name: LIST_AGENTS_TOOL_NAME,
+        aliases: [LIST_AGENTS_TOOL_ALIAS],
+        contract: { contractId: "core.list_agents@1", implementationRevision: "1" },
+        effect: "read",
+        isConcurrencySafe: () => true,
+        description: `List the agents and peer sessions you can message with SendMessage. Peer sessions are other sessions of this ` +
+            `engine running for the same user on this machine, shown as \`name [ref]\`; send to one with its name (or \`name [ref]\` ` +
+            `when a name is ambiguous, or its \`session.<id>\` address). A peer that is offline still accepts messages — they are parked ` +
+            `durably in its session box and delivered when it next runs. Background agents you spawned are listed with their task_id. ` +
+            `A ref is only valid against the listing (or disambiguation error) you read it from — do not invent one.`,
+        parameters: Type.Object({}),
+        execute: async () => {
+            const rows = [];
+            let peerRows = [];
+            let directoryFault;
+            try {
+                peerRows = await opts.peerDirectory.listPeerSessions({ scope: opts.self.scope });
+            }
+            catch (e) {
+                directoryFault = e instanceof Error ? e.message : String(e);
+            }
+            for (const c of mintPeerSessionCandidates(peerRows, { sessionId: opts.self.sessionId })) {
+                const r = c.record;
+                if (r.sessionId.toLowerCase() === opts.self.sessionId.toLowerCase())
+                    continue;
+                if (r.liveness === "deleted")
+                    continue;
+                if (r.liveness === "dead" && opts.includeOffline !== true)
+                    continue;
+                rows.push({
+                    kind: "peer_session",
+                    name: r.name,
+                    ref: c.ref,
+                    address: peerSessionBoxHandle(r.sessionId),
+                    state: r.liveness === "dead" ? "offline" : r.tempo === "active" || r.tempo === "blocked" ? "busy" : "idle",
+                });
+            }
+            let registryCapped = false;
+            const views = [opts.access, opts.parentAccess].filter((a) => a !== undefined);
+            const seenIds = new Set();
+            if (opts.registry !== undefined) {
+                for (const view of views) {
+                    const listed = opts.registry.list(view, { limit: 500 });
+                    registryCapped ||= listed.length >= 500;
+                    for (const t of listed) {
+                        if (t.type !== "background_agent" || seenIds.has(t.task_id))
+                            continue;
+                        seenIds.add(t.task_id);
+                        const full = opts.registry.getAccessibleTask(t.task_id, view);
+                        rows.push({ kind: "background_agent", name: full?.name ?? t.description ?? t.task_id, address: t.task_id, state: t.status === "running" || t.status === "pending" ? "running" : "finished" });
+                    }
+                }
+            }
+            if (opts.roster !== undefined && views.length > 0) {
+                try {
+                    for (const e of await opts.roster.list()) {
+                        const view = views.find((v) => entryAccessible(e, v));
+                        if (view === undefined || seenIds.has(e.agentId))
+                            continue;
+                        seenIds.add(e.agentId);
+                        const live = opts.registry?.getAccessibleTask(e.agentId, view);
+                        rows.push({ kind: "roster", name: e.name, address: e.agentId, state: live === undefined ? "unknown" : live.status === "running" || live.status === "pending" ? "running" : "finished" });
+                    }
+                }
+                catch {
+                }
+            }
+            const lines = rows.map((r) => {
+                const label = r.kind === "peer_session" ? formatPeerNameRef(inlineUntrusted(r.name, 64), r.ref) : inlineUntrusted(r.name, 64);
+                return `${label}  ·  ${r.state}  ·  ${r.kind === "peer_session" ? "peer session" : r.kind === "roster" ? "agent (durable record)" : "agent"}  ·  ${r.address}`;
+            });
+            const finishedCount = rows.filter((r) => r.state === "finished").length;
+            const header = rows.length === 0 ? "No agents or peer sessions are listed right now." : `${rows.length} listed:`;
+            const finishedNote = finishedCount > 0 ? `\n(${finishedCount} finished agent(s): continuable by SendMessage only while its session is retained or a durable record exists — otherwise SendMessage answers with an honest refusal)` : "";
+            const fault = (directoryFault !== undefined ? `\n(peer-session directory unreadable: ${inlineUntrusted(directoryFault, 200)} — peer rows may be missing)` : "") +
+                (registryCapped ? "\n(the live task list is at its 500-row window: older background agents may be missing from this listing — address them by task_id)" : "");
+            let content = `${header}${lines.length > 0 ? `\n${lines.join("\n")}` : ""}${finishedNote}${fault}`;
+            if (content.length > LIST_AGENTS_MAX_RESULT_CHARS)
+                content = `${content.slice(0, LIST_AGENTS_MAX_RESULT_CHARS)}\n[listing truncated: ${content.length} chars total]`;
+            return { content, details: { type: "list-agents", rows, ...(directoryFault !== undefined ? { directoryFault: true } : {}) } };
+        },
+    });
+}

package/dist/agents/peer-admission.d.ts

@@ -86,6 +86,10 @@ export interface PeerInboundChainRef {
     current: string[];
 }
 export declare function createPeerInboundChainRef(seed?: readonly string[]): PeerInboundChainRef;
+/** design/385 §4.6 — how many admitted (seq → body) pairs a sender's replay ledger keeps: more than
+ *  any one leased batch a drain injects between two acks (a batch is at most the queued-message bound,
+ *  50 by default), so an ack fault re-presents every message of the batch as a re-presentation. */
+export declare const REPLAY_LEDGER_MAX = 128;
 export interface PeerAdmissionRequest {
     /** The sender's canonical identity key ({@link PeerIdentity.key}), or undefined for an
      *  identity-less direct mount — rate/dedup are then SKIPPED (there is no honest bucket key),
@@ -99,6 +103,11 @@ export interface PeerAdmissionRequest {
     prospectiveChain: readonly string[];
     /** The RECIPIENT's self-token set, as knowable at this entry point. */
     ownTokens: readonly string[];
+    /** design/385 §4.6 — the mailbox seq of a DRAIN-stage re-check (absent at the send point). Dedup
+     *  judges body+seq: same body, same seq ⇒ a re-presentation of an already-admitted message (pass);
+     *  same body, other seq inside the window ⇒ duplicate. No shared state across consumers is needed:
+     *  a different consumer process holds a fresh gate and admits the redelivery by construction. */
+    seq?: number;
 }
 export type PeerAdmissionVerdict = {
     ok: true;
@@ -135,7 +144,14 @@ export declare function peerAdmissionFor(scope: string | undefined, recipientKey
  * always commits a seat, which is right for a host asking for the instance itself, and wrong at a
  * gate that has not admitted anything yet).
  */
-export declare function judgePeerAdmission(scope: string | undefined, recipientKey: string, req: PeerAdmissionRequest, config: PeerAdmissionConfig, options?: PeerAdmissionOptions): PeerAdmissionVerdict;
+/** design/385 §4.6 — the two-point gate's STAGE discriminator. The cross-session lane judges a message
+ *  twice, in two processes or (single-process hosts) in one: at the SEND point before the append, and at
+ *  the recipient's DRAIN point before injection. The registry is process-global and keyed by
+ *  (scope, recipient), so without a stage in the key the drain re-check of a message this same process
+ *  sent would read the send-point body record and refuse its own message as `duplicate`. Two gate
+ *  instances, one per stage; the stage-less key is the pre-385 spelling and stays byte-identical. */
+export type PeerAdmissionStage = "send" | "drain";
+export declare function judgePeerAdmission(scope: string | undefined, recipientKey: string, req: PeerAdmissionRequest, config: PeerAdmissionConfig, options?: PeerAdmissionOptions, stage?: PeerAdmissionStage): PeerAdmissionVerdict;
 /** Test seam ONLY (module-level registry hygiene between test files — same posture as the lane map,
  *  which drains itself; this one is long-lived by design so tests reset it explicitly). */
 export declare function resetPeerAdmissionRegistryForTests(): void;

package/dist/agents/peer-admission.js

@@ -60,6 +60,7 @@ export function createPeerSelfRef(scope) {
 export function createPeerInboundChainRef(seed) {
     return { current: seed !== undefined ? [...seed] : [] };
 }
+export const REPLAY_LEDGER_MAX = 128;
 function bodyFingerprint(body) {
     return createHash("sha256").update(body).digest("hex");
 }
@@ -95,6 +96,8 @@ export function createPeerAdmission(options) {
         const existing = senders.get(req.senderKey);
         const s = existing ?? { tokens: config.bucketCapacity, lastRefillAt: t };
         const fingerprint = bodyFingerprint(req.body);
+        if (req.seq !== undefined && s.replay?.get(req.seq) === fingerprint)
+            return { ok: true };
         if (config.dedupWindowMs > 0 && s.lastBodyHash === fingerprint && s.lastBodyAt !== undefined && t - s.lastBodyAt < config.dedupWindowMs) {
             refusals.duplicate++;
             return { ok: false, reason: "duplicate" };
@@ -109,6 +112,17 @@ export function createPeerAdmission(options) {
         s.lastRefillAt = t;
         s.lastBodyHash = fingerprint;
         s.lastBodyAt = t;
+        if (req.seq !== undefined) {
+            s.replay ??= new Map();
+            s.replay.delete(req.seq);
+            s.replay.set(req.seq, fingerprint);
+            while (s.replay.size > Math.max(REPLAY_LEDGER_MAX, config.maxQueuedPeerMessages, config.bucketCapacity)) {
+                const oldest = s.replay.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                s.replay.delete(oldest);
+            }
+        }
         senders.delete(req.senderKey);
         senders.set(req.senderKey, s);
         while (senders.size > config.maxTrackedSenders) {
@@ -145,8 +159,11 @@ export function peerAdmissionFor(scope, recipientKey, config, options) {
     }
     return inst;
 }
-export function judgePeerAdmission(scope, recipientKey, req, config, options) {
-    const key = JSON.stringify([scope ?? "", recipientKey]);
+function peerAdmissionRegistryKey(scope, recipientKey, stage) {
+    return stage === undefined ? JSON.stringify([scope ?? "", recipientKey]) : JSON.stringify([scope ?? "", recipientKey, stage]);
+}
+export function judgePeerAdmission(scope, recipientKey, req, config, options, stage) {
+    const key = peerAdmissionRegistryKey(scope, recipientKey, stage);
     const resident = peerAdmissionRegistry.get(key);
     const inst = resident ?? createPeerAdmission(options);
     const verdict = inst.admit(req, config);