@nelsonlongxiang/dsh-open-a2a-net 0.5.14 → 0.6.24

package/lib/types/index.d.ts

@@ -5,11 +5,45 @@
  * inbound direct routes into live agent sessions.
  * @module @nelsonlongxiang/dsh-open-a2a-net
  */
+/**
+ * Fix 1 (能发即能收): resolve the caller's routable label for one routed
+ * dispatch. Priority: the joined session's node team > the exempt initiator
+ * face (the NODE team — bare, team-name routable) > the session label (not
+ * routable; the dispatch registers receiptless per fix 2).
+ */
+export declare function resolveCallerLabel(input: {
+    joined: boolean;
+    initiatorFace: boolean;
+    nodeTeam: string;
+    joinedTeam?: string;
+    sessionLabel?: string;
+}): string | undefined;
+import { type ReceiptResolvedInfo } from './task-ledger.ts';
 import type { Context } from '@deepseek-ai/cordis';
 import s from '@deepseek-ai/schemastery';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'a2a-relay': {
+            kind: 'a2a-relay';
+        } & import('@deepseek-ai/dsh-llm').ContextFormed & {
+            /** The sending peer's routable label (team or session), when known.
+             * ui-chat's relay context body renders "来自 X" + the full text from
+             * this field; without it the row falls back to an opaque body. */
+            senderSessionId?: string;
+        };
+    }
+}
 export type * from './types.ts';
 export { A2aClient } from './a2a-client.ts';
 export type { A2aClientOptions, A2aFetch, A2aSchedule } from './a2a-client.ts';
+export { NATIVE_TEAMS_A2A_FACE_KEY } from './teams-bridge.ts';
+export type { NativeTeamsBridgeFace, TeamsBridgeResolveInfo, TeamsBridgeSubmitOutcome, TeamsBridgeSubmitRequest } from './teams-bridge.ts';
+export type { ReceiptResolvedInfo } from './task-ledger.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'a2a/receipt-resolved'(payload: ReceiptResolvedInfo): void;
+    }
+}
 export declare const name = "a2a";
 export declare const inject: string[];
 /** One signed zone delegation published on this node's agent card. */
@@ -34,6 +68,8 @@ export interface Config {
     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';
     /**
      * Publish this node's `/.well-known/agent-card.json` on the shared web
      * server (peer discovery). Requires the web server in the composition;
@@ -58,6 +94,30 @@ export interface Config {
      * 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;
+    /**
+     * 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
@@ -81,14 +141,103 @@ export interface Config {
      */
     readonly sessionNodes: boolean;
     /**
-     * Wake every cold joined session's agent when 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 — log replay plus composed preset world — so the default stays
-     * off for deployments that would rather pay on demand (wake-on-route and
-     * the sidebar's wake button remain available).
+     * 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: joinable-team patterns for a2a_team_join — exact names or
+     * trailing-`*` prefixes. Empty list denies every join (default).
+     */
+    readonly teamJoinAllowlist: string[];
+    /** S3 (queued): team-scoped routing admission. Enforcement off by default. */
+    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;
+    /**
+     * 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
@@ -101,6 +250,32 @@ export interface Config {
      * 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>;
@@ -110,4 +285,33 @@ export declare const Config: s<Config>;
  * @param ctx - registrant context carrying the tool registry and timer.
  * @param config - deployment's A2A node facts.
  */
+/**
+ * gh#9 control-face leniency audit (docs/protocol/delivery-origin-auth.md
+ * §10): a keyless host that runs session nodes rides loopback leniency for
+ * every control write — on a host that grants sessions a shell that is a
+ * speed bump, not authentication. Pure logic so the boot warning is
+ * testable without a mount.
+ * @param apiKey - the configured API key ('' disables header auth).
+ * @param sessionNodes - whether session nodes are enabled.
+ * @returns the warning to log, or undefined.
+ */
+export declare function controlFaceLeniencyWarning(apiKey: string, sessionNodes: boolean): string | undefined;
+/**
+ * Exposure audit for unauthenticated direct deliveries (defect card F4, the
+ * zero-risk slice). `/a2a/direct` carries no per-call caller identity yet
+ * (docs/protocol/delivery-origin-auth.md stays best-effort until the
+ * OriginClaim envelope lands), so with an empty `apiKey` every process that
+ * can reach this host's ports can steer every joined session. A node that
+ * only talks to loopback peers (same-host collaboration) is not exposed;
+ * one seeded with non-loopback peers is, and the operator should either set
+ * `apiKey` or accept the exposure deliberately.
+ * @param peers - the configured seed peer URLs.
+ * @param apiKey - the configured API key ('' disables header auth).
+ * @returns the non-loopback seed peers and, when they coincide with an
+ *   empty key, the boot warning to log.
+ */
+export declare function directDeliveryExposure(peers: readonly string[], apiKey: string): {
+    nonLoopbackPeers: string[];
+    warning: string | undefined;
+};
 export declare function apply(ctx: Context, config: Config): void;

package/lib/types/joined-store.d.ts

@@ -54,6 +54,15 @@ export declare class JoinedSessions {
      * @param id - the session id whose intent is removed.
      */
     remove(id: string): void;
+    /**
+     * F7 (wake-intent self-heal): re-read the persisted snapshot into memory.
+     * A boot-time transient (e.g. the workspace registry briefly reporting a
+     * session archived) can prune the in-memory intent while the file still
+     * holds it — the file is the durable source of the user's gesture, so the
+     * reload restores memory to match it. Callers use this as a one-shot
+     * fallback when a wake finds no in-memory match.
+     */
+    reload(): void;
     /** Load a persisted snapshot on construction, if present. */
     private restore;
     /** Persist the intent set (no-op when no path was configured). */

package/lib/types/layout-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Persisted spatial layout for the infinite-canvas page ('a2a/canvas-layout.json').
+ * Pure presentation state: node coordinates, team-frame rectangles, and the
+ * viewport transform. Membership truth stays in canvas.json - this store may
+ * be reset freely without touching who sits in which team.
+ *
+ * Unit semantics (contract note 6, 2026-08-28 ruling): {x,y} are 2D
+ * planning-canvas card centers in pixels. Other consumers (the 3D
+ * observation lens) must reproject into their own envelope, never consume
+ * the values as absolute scene coordinates.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/layout-store
+ */
+/** One draggable point in world space. */
+export interface LayoutPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** One team-frame rectangle in world space. */
+export interface LayoutRect extends LayoutPoint {
+    readonly w: number;
+    readonly h: number;
+}
+/** The viewport transform (world point at the top-left corner, plus zoom). */
+export interface LayoutViewport extends LayoutPoint {
+    readonly scale: number;
+}
+/** The whole persisted document. */
+export interface LayoutSnapshot {
+    readonly version: 1;
+    readonly viewport: LayoutViewport;
+    readonly nodes: Readonly<Record<string, LayoutPoint>>;
+    readonly frames: Readonly<Record<string, LayoutRect>>;
+}
+/** World-coordinate magnitude bound: values beyond are clamped, never trusted. */
+export declare const COORD_LIMIT = 1000000;
+/** Zoom bounds, matching the page's wheel clamps. */
+export declare const SCALE_MIN = 0.25;
+export declare const SCALE_MAX = 3;
+/** Document shape caps: a layout taxonomy, not a database. */
+export declare const LAYOUT_NODE_CAP = 256;
+export declare const LAYOUT_FRAME_CAP = 96;
+/**
+ * Whole-document layout store with last-write-wins persistence. Accepts
+ * anything the client sends and answers with the normalized truth: clients
+ * round-trip GET after save when they need canonical numbers.
+ */
+export declare class LayoutStore {
+    private doc;
+    private readonly path;
+    /** @param path - the snapshot file; an empty path keeps memory-only. */
+    constructor(path: string);
+    private restore;
+    private persist;
+    /** The current snapshot, or null before the first save. */
+    get(): LayoutSnapshot | null;
+    /**
+     * Replace the document wholesale after normalization.
+     * @returns false when the payload is not a version-1 layout document.
+     */
+    save(raw: unknown): boolean;
+    /** Drop all persisted presentation state. */
+    reset(): void;
+}

package/lib/types/peer-store.d.ts

@@ -23,6 +23,8 @@ export interface PeerRecord {
     readonly url: string;
     score: number;
     readonly seed: boolean;
+    /** The signed-card session the peer served last, when a fetch revealed it. */
+    readonly session?: string;
 }
 /** The persisted store document (whole-file read/write, small by design). */
 export interface PeerStoreSnapshot {
@@ -37,19 +39,27 @@ export interface PeerStoreSnapshot {
 export declare class PeerStore {
     private readonly path;
     private readonly cap;
+    private readonly persistDebounceMs;
     private readonly peers;
     /**
      * @param seeds - the configured seed URLs; always retained (never evicted).
      * @param path - persistence file (`<dsh-home>/a2a/peers.json`); empty = no persistence.
      * @param cap - peer bound, seeds included (default {@link PEER_CAP}).
      */
-    constructor(seeds: readonly string[], path: string, cap?: number);
+    constructor(seeds: readonly string[], path: string, cap?: number, persistDebounceMs?: number);
     /**
      * Every tracked peer URL: seeds first (in first-tracked order), then
      * offered peers by score descending (equal scores keep first-tracked order).
      * @returns the ordered peer URLs.
      */
     list(): readonly string[];
+    /**
+     * The operator-established subset (gh#8 N9): URLs that came from the
+     * config seed set — never the referral-learned tail. Team-name resolution
+     * rides this basis so a self-naming host nobody linked cannot capture
+     * routes; probing and visibility keep the full list.
+     */
+    listSeeded(): readonly string[];
     /** Whether the store has room for one more peer. */
     private hasRoom;
     /**
@@ -84,8 +94,41 @@ export declare class PeerStore {
      * @returns the score, or undefined when the peer is not tracked.
      */
     score(url: string): number | undefined;
+    /**
+     * Record the signed-card session a tracked peer served. The session is the
+     * node identity (the same fact the self-referral guard judges), so learning
+     * it per URL is what lets the caller collapse alias spellings of one node
+     * (loopback vs LAN IP) into a single tracked peer.
+     * @param url - the tracked peer the card came from.
+     * @param session - the verified card's session label; empty is ignored.
+     */
+    learnSession(url: string, session: string): void;
+    /**
+     * The strongest tracked URL known to serve one node identity — seeds beat
+     * referrals, then the higher score wins (ties keep first-tracked order).
+     * @param session - the signed-card session to look up.
+     * @returns the winning peer URL, or undefined when none is tracked.
+     */
+    bySession(session: string): string | undefined;
     /** Load a persisted snapshot on construction, if present. */
     private restore;
-    /** Persist the current peer set (no-op when no path was configured). */
+    /**
+     * Persist the current peer set (no-op when no path was configured).
+     * Writes are debounced and asynchronous: a sweep that settles dozens of
+     * fetch outcomes must not fire one synchronous writeFileSync per change
+     * (each blocks the event loop for milliseconds on Windows). The dirty
+     * flag coalesces the whole window into one async write; `flush()` lets
+     * tests and teardown await the final state on disk. A crash inside the
+     * window loses at most `persistDebounceMs` of score deltas — seeds are
+     * re-seeded from config on every boot, and scores rebuild on contact.
+     */
+    private dirty;
+    private writeChain;
+    private pendingTimer;
     private persist;
+    /**
+     * Await the last scheduled write (tests and teardown). Resolves when the
+     * debounced write chain has settled with the current in-memory state.
+     */
+    flush(): Promise<void>;
 }

package/lib/types/receipt-ladder.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Receipt delivery three-tier hard order (work-order P2 / B1 residual):
+ * caller lane first; if it fails, escalate ONCE to the owner mailbox so the
+ * outcome still lands somewhere answerable on this host; total failure stays
+ * a breadcrumb (correlation & archive remain the authoritative truth).
+ *
+ * Extracted pure so the ladder is unit-drivable without live agents.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/receipt-ladder
+ */
+/** Everything the ladder needs from its host — all seams, zero globals. */
+export interface ReceiptLadderDeps {
+    /** Try delivering the receipt text to one routable team. */
+    deliver: (team: string) => Promise<unknown>;
+    /** This host's process/team mailbox (tier two). */
+    ownerTeam: string;
+    /** Observability hook: `stage` distinguishes `to <team>` / `to owner <team>` / `both lanes`. */
+    log: (stage: string, error: unknown) => void;
+}
+/**
+ * Attempt delivery through the ladder.
+ * @param callerTeam - tier-one target (`callbackTarget`). When it already IS
+ * the owner team, a failure terminates after tier one — escalating to
+ * yourself would just double the noise.
+ */
+export declare function runReceiptLadder(deps: ReceiptLadderDeps, callerTeam: string): Promise<void>;

package/lib/types/receipt.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Receipt text codec — single home for the correlation pattern and the v2
+ * structured envelope (receipt-envelope-v2.md). The header line
+ * `[A2A receipt] task <id> …` stays byte-identical to the network's original
+ * contract; the machine payload rides EXACTLY ONE following line that must be
+ * a complete JSON object containing at least one known key. Everything after
+ * it is human continuation and every consumer ignores unknown keys.
+ *
+ * Discriminator over a bare `{`: an object qualifies as an envelope only when
+ * one of the known keys is present, so legacy prose summaries that happen to
+ * open with a brace can never be mistaken for machine payloads.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/receipt
+ */
+/** The network's fixed, case-sensitive correlation template. */
+export declare const RECEIPT_PATTERN: RegExp;
+/** Controlled outcome vocabulary — the ONLY branchable field of an envelope. */
+export declare const RECEIPT_OUTCOMES: readonly ["completed", "failed", "abandoned", "expired", "rejected", "sync_completed", "unknown"];
+export type ReceiptOutcomeV2 = (typeof RECEIPT_OUTCOMES)[number];
+/** Envelope fields this codec extracts; anything else rides through ignored (append-only). */
+export interface ReceiptEnvelopeV2Fields {
+    outcome?: ReceiptOutcomeV2;
+    idempotencyKey?: string;
+    sessionKey?: string;
+    elapsedMs?: number;
+}
+export interface ParsedReceipt {
+    /** Correlation key from the immutable header. */
+    taskId: string;
+    /**
+     * Raw post-id text. When a machine line was recognized this is ONLY the
+     * human summary line (continuation prose excluded); without one it is the
+     * legacy multi-line remainder, byte-for-byte.
+     */
+    summary: string;
+    /** Present when the second line carried a recognized envelope. */
+    envelope?: ReceiptEnvelopeV2Fields;
+}
+/**
+ * Parse one inbound message against the receipt contract.
+ * @returns `null` when the message is not a receipt at all; otherwise the
+ * correlation key with its summary and, when present, the v2 envelope.
+ */
+export declare function parseReceipt(message: string): ParsedReceipt | null;
+/**
+ * Compose a receipt text: the immutable header (+ human summary) followed,
+ * when any envelope field is supplied, by exactly one complete JSON line.
+ * @param taskId - correlation key echoed in the header.
+ * @param summary - human-readable outcome tail on the header line.
+ * @param fields - structured projection; omit entirely for a pure v1 receipt.
+ */
+export declare function formatReceipt(taskId: string, summary: string, fields?: ReceiptEnvelopeV2Fields): string;

package/lib/types/self-suppress.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Unmasked-identity suppression: decentralized gossip mirrors peer lists back
+ * and forth, so every alias of this node's own address comes home as an
+ * inbound referral within minutes of being dropped. Fetching one is the
+ * identity check that drops it (the fetched card carries our session id),
+ * but the next inbound referral re-offers the same URL seconds later, and
+ * the peer store flickers between present and dropped forever.
+ *
+ * The same flicker plagues alias spellings of OTHER tracked nodes: a peer
+ * reached as both loopback and LAN IP drops one spelling on the alias
+ * collapse, and the next mirrored referral re-offers it. This filter
+ * therefore remembers each URL whose fetch revealed a settled identity —
+ * self or an already-tracked peer — for a window far beyond any realistic
+ * offer cadence: offers inside the window are refused without a network
+ * round-trip. Shape-agnostic on purpose — alias spellings never seen before
+ * (localhost vs 127.0.0.1 vs a hostname) suppress naturally once their first
+ * fetch unmasks them.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/self-suppress
+ */
+/** How long an identity-revealing URL stays suppressed after its unmasking fetch. */
+export declare const SELF_REFERRAL_SUPPRESS_MS: number;
+/** Bounded memory of URLs whose recent fetch proved they serve a known identity. */
+export declare class SelfReferralFilter {
+    private readonly remembered;
+    private readonly now;
+    /** @param now - injectable clock for deterministic tests. */
+    constructor(now?: () => number);
+    /**
+     * Record that fetching `url` served this node's own card. Expired entries
+     * prune first, so the map stays bounded by the live offer cadence.
+     */
+    remember(url: string): void;
+    /**
+     * Whether one inbound referral is still worth offering to the store.
+     * A URL unmasked as self inside the suppression window refuses without a
+     * fetch; every other URL passes through unchanged.
+     */
+    shouldOffer(url: string): boolean;
+    /** Drop entries past the window (called from the mutating entry points). */
+    private prune;
+}

package/lib/types/session-transcript.d.ts

@@ -0,0 +1,37 @@
+/** One human-readable transcript entry. */
+export interface TranscriptEntry {
+    role: 'user' | 'assistant';
+    text: string;
+    time?: number;
+}
+/** Hard caps so a pathological log cannot balloon memory or the response. */
+export declare const TRANSCRIPT_MAX_FILE_BYTES: number;
+export declare const TRANSCRIPT_MAX_DECOMPRESSED_BYTES: number;
+export declare const TRANSCRIPT_ENTRY_TEXT_CAP = 500;
+export declare const TRANSCRIPT_DEFAULT_LIMIT = 20;
+export declare const TRANSCRIPT_MAX_LIMIT = 100;
+/** Byte range of one structurally complete zstd frame. */
+interface FrameRange {
+    start: number;
+    end: number;
+}
+/**
+ * Walk concatenated zstd frames structurally (no block decoding) and return
+ * their byte ranges. Malformed structure rejects; EOF inside a final frame is
+ * dropped from the result (a torn tail frame decodes to nothing usable).
+ */
+export declare function scanZstdFrames(buffer: Buffer): FrameRange[];
+/**
+ * Decode a session log artifact to text. Plain .jsonl passes through; .zstd
+ * artifacts are split into frames and decoded frame by frame (node's public
+ * decoder is single-frame).
+ */
+export declare function decodeSessionLog(buffer: Buffer): string;
+/**
+ * Extract the last `limit` human-visible turns from a decoded session log.
+ * User lines come from user/message data.content[].text; assistant lines from
+ * assistant/message data.message.content[] segments of type "text" (reasoning
+ * and tool calls are working detail, not transcript).
+ */
+export declare function extractTranscript(logText: string, limit?: number): TranscriptEntry[];
+export {};

package/lib/types/skill-registration.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Register the a2a-network skill (runtime contribution). */
+export declare function registerA2aNetworkSkill(ctx: Context): void;

package/lib/types/stage-mount.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stage-mount pathname resolution: both static stages (canvas office floor,
+ * Three.js nexus viewer) serve one built Vite tree behind a mount prefix,
+ * and both used to answer the bare `/mount` form directly with index.html.
+ * That shell then resolved its `./assets/…` script reference against `/`,
+ * fetched `/assets/index-*.js` from the web root — a 404 — and rendered a
+ * silent black shell (`main.ts` returns early when state fetches fail). The
+ * fix is the directory-classic one: a bare mount request redirects to
+ * `mount/`, every other relative resolution then lands inside the tree.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/stage-mount
+ */
+/** Outcome of resolving one request pathname against a stage mount. */
+export interface StageResolution {
+    /** `301` target — present exactly when the client addressed the bare mount. */
+    readonly redirectTo?: string;
+    /**
+     * Mount-stripped file path, still percent-encoded and un-decoded, ready
+     * for the handler's traversal guard and decode. `'/index.html'` when the
+     * client addressed the mount itself.
+     */
+    readonly rel: string;
+}
+/**
+ * Resolve one request pathname against a stage mount prefix.
+ * @param pathname - `req.url` verbatim (query string allowed, split here).
+ * @param mount - the registered mount prefix, e.g. `/__dsh_a2a_nexus`.
+ * @returns the redirect target plus the within-tree relative path.
+ */
+export declare function resolveStageMount(pathname: string, mount: string): StageResolution;