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

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

@@ -49,6 +49,7 @@ export type RouteOutcome = {
     status?: string;
     bridge?: 'native-teams';
     placeholder?: boolean;
+    ownTurn?: true;
 } | {
     ok: false;
     error: string;
@@ -111,6 +112,7 @@ export type OriginClaimResult = {
     card: A2aPeerCard;
     bound: boolean;
     cli?: true;
+    bodyBound?: true;
 } | {
     ok: false;
     reason: string;
@@ -131,10 +133,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;
@@ -224,5 +232,23 @@ export declare function settlerClaimFields(claim: {
  * @param webServer - the settled host web server.
  * @param d - the captures listed on {@link WireDeps}.
  */
+/** #298: how long, and how many, sync-answered forwards are remembered for marking their duplicate receipt. */
+export declare const SYNC_ANSWERED_TTL_MS = 3600000;
+export declare const SYNC_ANSWERED_CAP = 256;
+/**
+ * #298: forwards whose final sync answer — the member's own reply, not a delivered/mailbox placeholder — was
+ * fully written back to the CLI that sent them. That member's receipt for the same task, landing in that CLI's
+ * mailbox unrefused, is marked a duplicate — never dropped. In memory only: after a restart the receipt arrives
+ * unmarked, which is today's behaviour.
+ */
+export declare class SyncAnswered {
+    private readonly now;
+    private readonly rows;
+    constructor(now?: () => number);
+    note(taskId: string, handle: string, answeredBy: string): void;
+    /** True once for a task answered to exactly this handle by exactly this sender; the row is consumed. */
+    take(taskId: string, handle: string, sender: string): boolean;
+    private sweep;
+}
 export declare function registerWireFaces(webServer: WebServer, d: WireDeps): void;
 export {};