@nelsonlongxiang/dsh-open-a2a-net 0.6.38 → 0.6.39

package/lib/task-auth.js

@@ -32,7 +32,11 @@ export const VIA_OF = {
 /** The refusal text of a decision, or undefined when admitted — the shape the faces have always read. */
 export const refusalOf = (admission) => (admission.ok ? undefined : admission.refusal);
 const admitted = (rule, basis = []) => ({ ok: true, via: VIA_OF[rule], rule, basis });
-const refused = (refusal) => ({ ok: false, refusal });
+/** #282 S1: a refusal may carry the one step the caller (or this host's operator) can take next. */
+const refused = (refusal, next) => ({ ok: false, refusal, ...(next !== undefined ? { next } : {}) });
+/** The next step of a refused decision, or undefined. */
+export const nextOf = (a) => (a.ok ? undefined : a.next);
+const linkNext = (caller, target) => `ask this host's operator to put ${caller} in a canvas team${target !== undefined ? ` with ${target}` : ''} in the A2A workbench, or route through a member of a team you already share`;
 const ZONE_ID8 = /^[a-z0-9-]+\/[0-9a-f]{8}$/i;
 const teamlessText = (caller) => `caller "${caller}" declares no team membership on this host's roster — a teamless node has no network (S3 phase-3 admission). Declare a shared team on both ends, or route through a teamed member.`;
 /**
@@ -178,7 +182,7 @@ export function sameZoneAdmission(r, caller, targetTeam) {
                 return hit;
             return refused(declared.size === 0
                 ? teamlessText(caller)
-                : `caller "${caller}" shares no team with target "${targetTeam}" — declared [${[...declared.keys()].join(', ')}], target links [${[...links].join(', ')}] (F5 target-level admission: a host-level link alone does not open every session team).`);
+                : `caller "${caller}" shares no team with target "${targetTeam}" — declared [${[...declared.keys()].join(', ')}], target links [${[...links].join(', ')}] (F5 target-level admission: a host-level link alone does not open every session team).`, linkNext(caller, targetTeam));
         }
     }
     const hit = pass(t => routable.has(t) || otherLocalDeclarations.has(t));
@@ -186,7 +190,7 @@ export function sameZoneAdmission(r, caller, targetTeam) {
         return hit;
     return refused(declared.size === 0
         ? teamlessText(caller)
-        : `caller "${caller}" declares teams [${[...declared.keys()].join(', ')}] — none is routable on this node (shared-team admission). Declare a shared team on both ends, or route through a teamed member.`);
+        : `caller "${caller}" declares teams [${[...declared.keys()].join(', ')}] — none is routable on this node (shared-team admission). Declare a shared team on both ends, or route through a teamed member.`, linkNext(caller, targetTeam));
 }
 /**
  * W1: the joined-face gate for the LOCAL dispatch candidate — only a
@@ -216,7 +220,7 @@ export function callerAdmission(r, caller, targetTeam, cliProof) {
     if (!r.teamScopeRouting)
         return admitted('scope-off');
     if (caller === '') {
-        return refused('caller_session is required — anonymous deliveries are refused (S3 phase-3b). Pass caller_session as <zone>/<id8>.');
+        return refused('caller_session is required — anonymous deliveries are refused (S3 phase-3b). Pass caller_session as <zone>/<id8>.', 'send caller_session as your <zone>/<id8> handle (a2a-net does this for you)');
     }
     if (caller === r.zone)
         return admitted('host-face');
@@ -228,21 +232,21 @@ export function callerAdmission(r, caller, targetTeam, cliProof) {
         const basis = r.canvasNames().filter(name => r.canvasRemoteMembersOf(name).includes(caller)).map(name => r.canvasTeamOf(name));
         if (basis.length > 0)
             return admitted('remote-ref-foreign', basis);
-        return refused(`caller "${caller}" has no operator-established link on this node — cross-host admission requires a canvas remote membership this host's operator added (N3/N4: the caller's own card claims are self-description, not links). Ask this host's operator to add the member in the A2A workbench, or route through a linked member.`);
+        return refused(`caller "${caller}" has no operator-established link on this node — cross-host admission requires a canvas remote membership this host's operator added (N3/N4: the caller's own card claims are self-description, not links). Ask this host's operator to add the member in the A2A workbench, or route through a linked member.`, linkNext(caller, targetTeam));
     }
     // A foreign CLI handle is never a free-form node fact: its operator link,
     // pinned home, bound signer, and fresh online row must ALL hold.
     if (CLI_HANDLE_RE.test(caller) && !r.cliDeposited(caller)) {
         const basis = r.canvasNames().filter(name => r.canvasRemoteMembersOf(name).includes(caller)).map(name => r.canvasTeamOf(name));
         if (basis.length === 0)
-            return refused(`remote CLI ${caller} has no operator-established canvas link`);
+            return refused(`remote CLI ${caller} has no operator-established canvas link`, linkNext(caller, targetTeam));
         const home = r.cliHomeOf?.(caller);
         if (home === undefined)
-            return refused(`remote CLI ${caller} home is not pinned`);
+            return refused(`remote CLI ${caller} home is not pinned`, `ask this host's operator to pin ${caller}'s home host when adding it to the canvas team (workbench member dialog)`);
         if (cliProof?.bound !== true || cliHomeOrigin(cliProof.origin) !== home || cliHomeOrigin(cliProof.viaUrl) !== home)
-            return refused(`remote CLI ${caller} signer does not match pinned home`);
+            return refused(`remote CLI ${caller} signer does not match pinned home`, `send through ${caller}'s pinned home host only`);
         if (cliProof.online !== true)
-            return refused(`remote CLI ${caller} is offline or home card could not be read`);
+            return refused(`remote CLI ${caller} is offline or home card could not be read`, 'run `a2a-net publish` on the home host, then send again with a new task id');
         return admitted('remote-ref-cli', basis);
     }
     // Free-form label: only this host's own node facts (V3).
@@ -257,7 +261,7 @@ export function callerAdmission(r, caller, targetTeam, cliProof) {
     // gh#45: a deposited CLI handle is a published node fact of this host.
     if (r.cliDeposited(caller))
         return admitted('cli-deposit');
-    return refused(`caller_session "${caller}" matches no node fact on this host (joined session id, live node label, or deposited CLI handle) — free-form caller labels are self-description and are not admissible (N3). Pass caller_session as <zone>/<id8> with an operator-established link.`);
+    return refused(`caller_session "${caller}" matches no node fact on this host (joined session id, live node label, or deposited CLI handle) — free-form caller labels are self-description and are not admissible (N3). Pass caller_session as <zone>/<id8> with an operator-established link.`, 'send caller_session as a <zone>/<id8> handle this host has linked; free-form labels are never admitted');
 }
 /** Revalidate only mutable operator authority, not already-verified birth-time identity or liveness. */
 export function recheckRemoteCliAuthorization(r, auth) {

package/lib/types/canvas-id.d.ts

@@ -0,0 +1,9 @@
+/** First 8 hex of sha256 over the base64 SPKI DER public key; '' when there is no key. */
+export declare function canvasOwnerFingerprint(publicKey: string | undefined): string;
+/** Split `<zone>/canvas/<name>@<fp8>` into the plain team and the owner fingerprint. */
+export declare function splitCanvasOwner(team: string): {
+    team: string;
+    owner?: string;
+};
+/** The display/routing id of a canvas team owned by the card holding `publicKey`. */
+export declare function qualifiedCanvasId(team: string, publicKey: string | undefined): string;

package/lib/types/config.d.ts

@@ -0,0 +1,278 @@
+/** The plugin row's configuration: the `Config` interface and its Schemastery schema (moved out of index.ts, #77). */
+import s from '@deepseek-ai/schemastery';
+import type { SettlementMode } from './task-auth.ts';
+/** One signed zone delegation published on this node's agent card. */
+export interface DelegateConfig {
+    /** The delegated name; resolves zone-relatively at route time. */
+    readonly name: string;
+    /** Base URL of the zone the name resolves in. */
+    readonly url: string;
+    /** Base64 SPKI DER binding to the target zone's card key; `''` leaves the delegation unbound. */
+    readonly publicKey: string;
+}
+/** Deployment-varying A2A node facts; every field has a declared default. */
+export interface Config {
+    /** `X-API-Key` value sent on peer requests and required by the control routes; empty disables the header. */
+    readonly apiKey: string;
+    /**
+     * This node's caller label. `''` (the default) derives `dsh-host-<8 hex>`
+     * from a per-home node id created on first use, so two deployments mounting
+     * defaults do not collide while a persisted home keeps the label stable
+     * across restarts.
+     */
+    readonly session: string;
+    /** Team name this node exposes for direct routing. */
+    readonly team: string;
+    /** S4 fix 3: audit (default) or refuse host-side (agent-less) routing calls. */
+    readonly gateAgentLessCalls: 'audit' | 'refuse';
+    /** #114 S4: settlement authorization — off, observe (record would-refuse, settle as before), enforce. */
+    readonly settlementAuth: SettlementMode;
+    /**
+     * Publish this node's `/.well-known/agent-card.json` on the shared web
+     * server (peer discovery). Requires the web server in the composition;
+     * the card carries this node's team, capabilities, referral list, and
+     * joined session teams so peers find it without a central directory.
+     */
+    readonly announce: boolean;
+    /**
+     * gh#193: send nothing to any peer. Every outbound peer request — card
+     * reads, directory sweeps, routes, log reads, canvas pings and canvas-op
+     * relays — goes through one fetch that refuses while this is on, so a
+     * test host stays dark even with learned peers in `a2a/peers.json`
+     * (which is left untouched). Inbound faces keep answering. Default false.
+     */
+    readonly isolated: boolean;
+    /** Forward online local CLI deliveries one hop after a local miss. Default on from 0.6.38; explicit false opts out. */
+    readonly forwardDirect: boolean;
+    /** Human-facing name published on the agent card. */
+    readonly agentName: string;
+    /**
+     * Base URLs of seed peer nodes. `a2a_teams` lists teams discovered from
+     * the peers' agent cards and `a2a_route` connects to the owning peer's
+     * `/a2a/direct` endpoint. The list is a seed set: referral URLs learned
+     * from fetched cards join a bounded, quality-scored peer store persisted
+     * at `<dsh-home>/a2a/peers.json`.
+     */
+    readonly peers: string[];
+    /**
+     * Zone delegation records published (signed) on this node's agent card:
+     * each entry publishes `name` as resolvable in the zone at `url`, so a
+     * route for `name` walks the delegation chain (at most 5 hops, cycles
+     * fail closed).
+     */
+    readonly delegates: DelegateConfig[];
+    /**
+     * gh#9+gh#10 OriginClaim window (docs/protocol/delivery-origin-auth.md §4):
+     * while true (default), a delivery/log request with NO envelope still
+     * walks N3 admission and increments the legacyInbound warn metric; when
+     * the operator closes it (post fleet flip), an absent envelope rejects
+     * `untrusted-origin` — same code as a failed signature (M1: a
+     * self-asserted already-linked name must not pass on shape alone).
+     */
+    readonly originClaimWindow: boolean;
+    /**
+     * OriginClaim unbound window (docs/protocol/delivery-origin-auth.md §2.1):
+     * while true (default), this host also signs the legacy unbound form and
+     * accepts a peer's unbound-only envelope (counted as unboundInbound);
+     * closed, it signs and accepts the audience-bound form only.
+     */
+    readonly originClaimUnboundWindow: boolean;
+    /**
+     * Extra origins this host answers to as an OriginClaim audience, beyond
+     * its card URL and the address a request arrives on (port-mapped or
+     * proxied hosts name the URL peers dial).
+     */
+    readonly originClaimAudiences: string[];
+    /**
+     * #19 D2: card-face sessionTeams excerpt exposure — 'full' | 'masked'
+     * | 'off' (owner-level; default full). See the schema comment.
+     */
+    readonly exposureExcerpt: 'full' | 'masked' | 'off';
+    /**
+     * Override for the OriginClaim callerUrl anchor. Loopback-bound hosts
+     * behind a pocket tunnel must name the card URL peers can actually
+     * fetch (e.g. http://192.168.3.157:13080); empty uses the web server's
+     * own address.
+     */
+    readonly originClaimUrl: string;
+    /**
+     * gh#8 (N9) escape hatch: when true, team-name resolution also considers
+     * the referral-learned peer tail (the legacy whole-store basis) instead
+     * of the seeded/delegate subset only. Default false — a team name binds
+     * to hosts the operator linked; fleets relying on referral discovery for
+     * routing migrate by adding explicit seeds, then leave this off.
+     */
+    readonly referralTeamResolution: boolean;
+    /**
+     * Harness home slice for the node keypair and peer store; `''` (the
+     * default) uses the process DSH home. The Ed25519 key lives at
+     * `<home>/a2a/node-key.pem` and is generated on first announce; a
+     * persisted key keeps the node's card identity stable across restarts.
+     */
+    readonly dshHome: string;
+    /**
+     * Agent-card validity. Announce re-signs at TTL/4 so three lost refreshes
+     * still leave a live card; a node silent for one TTL disappears from every
+     * peer's discovery without manual eviction.
+     */
+    readonly cardTtlMs: number;
+    /**
+     * Enable per-session A2A nodes: each live top-level session can join the
+     * network explicitly — label `<session>-<agentId8>`, team
+     * `<team>/<agentId8>`, node facts carrying the session title and a
+     * recent-activity excerpt. Joining is opt-in through the sidebar control's
+     * host routes; joined teams ride this node's card and dispatch through
+     * its `/a2a/direct` endpoint.
+     */
+    readonly sessionNodes: boolean;
+    /**
+     * Prewarm every cold joined session's agent after the plugin mounts (dev
+     * boxes and always-on collaboration hosts that restart often: the network
+     * state returns without opening each session). Each wake materializes a
+     * full agent — a main-thread log replay — so the prewarm is deferred,
+     * foreground-yielding, and cancellable (see `wakePrewarmDelayMs` /
+     * `wakePrewarmQuietMs`); the default stays off for deployments that would
+     * rather pay on demand (wake-on-route and the sidebar's wake button remain
+     * available either way).
+     */
+    readonly wakeJoinedOnBoot: boolean;
+    /**
+     * Idle delay between loader settlement and the first boot prewarm wake:
+     * boot traffic gets a clear window before any log replay starts. `0`
+     * restores the old fire-at-settle behavior.
+     */
+    readonly wakePrewarmDelayMs: number;
+    /**
+     * Foreground quiet window: a wake/route demand inside this window (or any
+     * outbound route still in flight) postpones the next prewarm step. Panel
+     * polls never count. `0` disables the yield.
+     */
+    readonly wakePrewarmQuietMs: number;
+    /**
+     * Pause between consecutive boot prewarm wakes. Each wake replays a full
+     * session log — the zstd decode yields the event loop only every 500ms —
+     * so unbounded concurrent wakes of several huge logs starve every request
+     * for tens of seconds after a restart. The serial queue with this pause
+     * keeps the preheat while capping decode saturation, and wake-on-route
+     * never waits on this queue.
+     */
+    readonly wakeBootStaggerMs: number;
+    /**
+     * F8: continuous desired-state reconciliation. The boot prewarm is a
+     * one-shot queue; the reconciler re-derives the due set every tick and
+     * wakes one cold intent per pass — covering post-boot drift, failed
+     * wakes, and gateways that mounted late. Default on.
+     */
+    readonly wakeReconcile: boolean;
+    /** Cadence between reconciliation ticks (floored at 50ms). */
+    readonly wakeReconcileIntervalMs: number;
+    /** First-retry delay after a failed reconcile wake; doubles per attempt. */
+    readonly wakeReconcileBackoffBaseMs: number;
+    /** Backoff ceiling; corrupt-log rows park as needs-repair and never retry. */
+    readonly wakeReconcileMaxBackoffMs: number;
+    /**
+     * S4 (gh#11 N7, operator directive: team creation is a human act): the
+     * joinable-team curation list for a2a_team_join. ONLY an EXACT entry
+     * authorizes a join; trailing-`*` pattern entries stay readable here
+     * (whoami shows them) but carry no mint rights — a pattern that
+     * pre-authorized every future name under it would let a model mint teams
+     * nobody created. Empty list denies every join (default).
+     */
+    readonly teamJoinAllowlist: string[];
+    /** Human-owned stable display labels keyed by full local session id; never a routing identity. */
+    readonly seatNames: Record<string, unknown>;
+    /**
+     * S3 (phase-2 default-ON, owner ruling 2026-09-01): route dispatch checks
+     * caller↔target shared team membership before addressing; set false to
+     * restore the open outbound seam. (Kept in sync with the schema comment.)
+     */
+    readonly teamScopeRouting: boolean;
+    /**
+     * S5 (owner directive 2026-10-20): information-plane scoping — the
+     * read-only fleet tools (a2a_teams / a2a_status / a2a_probe) disclose
+     * only teams joined by this host's nodes (the union of local roster
+     * declarations). [this host] rows stay visible; a2a_tasks (this host's
+     * own ledger) stays unscoped. Set false for the open plane.
+     */
+    readonly teamScopeInfo: boolean;
+    /**
+     * Peer boundary model (docs/design/peer-boundary-model.md) — connection
+     * layer: an empty list keeps the historical open-referral posture; a
+     * non-empty list admits a referral only when its host matches an entry
+     * (exact host[:port], bare domain suffix, or full URL). Seeds from
+     * `peers` are owner-configured and unaffected.
+     */
+    readonly peerAllowlist: string[];
+    /**
+     * Peer boundary model — connection layer: when false, referral URLs are
+     * neither learned nor offered; the tracked set stays the configured seed
+     * set for the lifetime of the config that named them.
+     */
+    readonly referralLearning: boolean;
+    /**
+     * v0.5.23 (async-stall): see the schema comment on asyncNudgeDelayMs.
+     */
+    readonly asyncNudgeDelayMs: number;
+    /** gh#224: receipt-owing tasks one target may queue on this host before new deliveries are refused (0 = off). */
+    readonly targetQueueCap: number;
+    /**
+     * How long the state route serves the cold-row id set from cache before
+     * re-enumerating the persistence layer. The panel polls every 2s; the
+     * default keeps one full enumeration per 5s instead of one per poll.
+     */
+    readonly stateColdRowsTtlMs: number;
+    /**
+     * Serve window for a verified peer card from the shared cache. Cards are
+     * signed for days and re-signed at TTL/4, so 60s is semantically safe; a
+     * peer that restarts with a fresh card is picked up on the next window.
+     */
+    readonly cardCacheTtlMs: number;
+    /** Shorter window for unreachable/invalid cards, so a revived peer reappears quickly. */
+    readonly cardCacheNegativeTtlMs: number;
+    /**
+     * Serve window for the panel\x27s remote rows. The refresh itself rides the
+     * shared card cache, so this is pure sweep cadence: how often real
+     * network activity happens while the panel polls every 2s.
+     */
+    readonly remoteRowsTtlMs: number;
+    /**
+     * `final` reply budget: how long an inbound direct route waits for the
+     * session's next assistant message before answering with a timeout
+     * notice. Without it a session that never idles (or never produces text)
+     * leaves the caller hanging until `routeTimeoutMs` expires.
+     */
+    readonly flushTimeoutMs: number;
+    /**
+     * `a2a_route` execution budget: how long a call may plausibly wait for a
+     * remote session's reply (default 30 minutes).
+     */
+    readonly routeTimeoutMs: number;
+    /**
+     * Age at which an unsettled async task auto-dead-letters (exits the owed
+     * view, disarms the nudge, still settles on a late receipt). Default
+     * 24h; the mesh anomaly suite injects sub-second windows to exercise the
+     * dead-letter → revival lifecycle without wall-clock waits.
+     */
+    readonly taskStaleTtlMs: number;
+    /**
+     * Opt-in native-teams inbound bridge: when composed with
+     * `@nelsonlongxiang/dsh-native-teams`, a routed team name that its
+     * registry classifies as an unambiguous local claim dispatches through
+     * its authoritative routing seam (`/a2a/direct`, the outbound A2A tools,
+     * and the directory listing). Off by default — exposing every registered
+     * team to the network is an operator decision (exposure-grants
+     * governance: grants are deliberate, never ambient). Dispatcher-level
+     * only: inbound callers address the team, never its individual members
+     * (members stay visible-not-addressable).
+     */
+    readonly nativeTeamsInbound?: boolean;
+    /**
+     * Reply-wait budget for one native-teams round (the bridge's answer
+     * deadline, mirroring the steer path's 180s deadline). A round still
+     * running past it answers the honest delivered-unsettled shape instead
+     * of parking the caller; the round itself keeps going.
+     */
+    readonly nativeRoundWaitMs?: number;
+}
+/** Schemastery configuration for the A2A client plugin row. */
+export declare const Config: s<Config>;

package/lib/types/direct-forward.d.ts

@@ -1,5 +1,5 @@
-import { type TaskLedger } from './task-ledger.ts';
-import type { TaskAuthorization } from './task-auth.ts';
+import { type TaskLedger, type TaskRecord } from './task-ledger.ts';
+import { type TaskAuthorization } from './task-auth.ts';
 import type { A2aPeerCard, A2aRouteResult } from './types.ts';
 export interface ForwardRequest {
     team: string;
@@ -12,9 +12,17 @@ export interface ForwardRequest {
     guarded: boolean;
     auth?: TaskAuthorization;
 }
+/** An early receipt waits at most this long for its forward row to be born (#298). */
+export declare const BIRTH_WAIT_CAP_MS = 60000;
 /** Birth barrier exists only for eligible, actively dispatched tasks; receipts never reserve a slot. */
 export declare class ForwardBirths {
+    private readonly waitCapMs;
     private readonly pending;
+    constructor(waitCapMs?: number);
+    /**
+     * Resolves when the birth is released or after the cap, whichever is first. After the cap the receipt
+     * is judged by the normal rules against whatever row exists then — never accepted in advance (#298).
+     */
     wait(taskId: string): Promise<void> | undefined;
     begin(taskId: string): (() => void) | undefined;
 }
@@ -23,7 +31,6 @@ export interface DirectForwardDeps {
     enabled(): boolean;
     isolated(): boolean;
     deposited(handle: string): boolean;
-    memberLinked(handle: string): boolean;
     scope(handle: string, team: string): Promise<{
         ok: true;
     } | {
@@ -39,3 +46,18 @@ export interface DirectForwardDeps {
     activity(team: string, peer: string, ok: boolean): void;
 }
 export declare function createDirectForward(d: DirectForwardDeps): (request: ForwardRequest) => Promise<A2aRouteResult>;
+/**
+ * #282 S3 (same team authorizes): the admission basis for a receipt delivered to a local CLI mailbox
+ * from a member the home never linked — only for that CLI's own pending forward, only from a receiver
+ * frozen at birth, only when the body-bound (Sig3) claim's card key is the frozen peer key. Anything else:
+ * undefined. Trust assumption (design D2): the selected owner host is honest about its own canvas — it may
+ * list any label as a receiver, including one of this host's session labels in the same zone.
+ */
+export declare function forwardReceiptBasis(row: TaskRecord | undefined, caller: string, cliHandle: string, claim: {
+    readonly caller: string;
+    readonly bound: boolean;
+    readonly bodyBound?: true;
+    readonly card: {
+        readonly publicKey: string;
+    };
+}): string | undefined;

package/lib/types/faces/admin.d.ts

@@ -151,6 +151,8 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
         lastAt: number;
     }>;
     readonly ownCardUrl: string;
+    /** #282 S2: this host's canvas owner fingerprint. */
+    readonly ownCanvasFingerprint: string;
     ownerSeatNames: Record<string, string>;
     ownerAllowlist: string[];
     ownerTeamScopeInfo: boolean;

package/lib/types/faces/wire.d.ts

@@ -111,6 +111,7 @@ export type OriginClaimResult = {
     card: A2aPeerCard;
     bound: boolean;
     cli?: true;
+    bodyBound?: true;
 } | {
     ok: false;
     reason: string;
@@ -131,10 +132,16 @@ export interface WireDeps {
         readonly rawBody?: Uint8Array;
     }) => Promise<OriginClaimResult>;
     readonly forwardDirect: (request: ForwardRequest) => Promise<A2aRouteResult>;
+    /** #282 S2: this host's canvas owner fingerprint. */
+    readonly ownCanvasFingerprint: string;
     readonly diagnoseCanvas: (team: string, reason: string, caller?: string) => Promise<string>;
     readonly remoteCliProof: (handle: string, claim: Extract<OriginClaimResult, {
         ok: true;
     }>) => Promise<RemoteCliProof | undefined>;
+    /** #282 S3: the basis for a receipt to a local CLI from a member frozen on this host's own forward, else undefined. */
+    readonly forwardReceiptBasis: (taskId: string, caller: string, cliHandle: string, claim: Extract<OriginClaimResult, {
+        ok: true;
+    }>) => string | undefined;
     readonly callerLinkedToThisHost: (caller: string, callerUrl: string, callerCard: A2aPeerCard | undefined) => boolean;
     /** This host's own card URL (read when a request lands; set once the web server settles). */
     readonly ownCardUrl: string;