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

package/lib/types/index.d.ts

@@ -20,9 +20,7 @@ export declare function resolveCallerLabel(input: {
 }): string | undefined;
 import { type ReceiptResolvedInfo } from './task-ledger.ts';
 import { type AffectedEntry } from './auth-observer.ts';
-import { type SettlementMode } from './task-auth.ts';
 import type { Context } from '@deepseek-ai/cordis';
-import s from '@deepseek-ai/schemastery';
 declare module '@deepseek-ai/dsh-llm' {
     interface MessageSourceMap {
         'a2a-relay': {
@@ -50,281 +48,9 @@ declare module '@deepseek-ai/cordis' {
 }
 export declare const name = "a2a";
 export declare const inject: string[];
-/** 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>;
+import { Config } from './config.ts';
+export { Config };
+export type { DelegateConfig } from './config.ts';
 /**
  * Register the outbound peer tools, the direct-route endpoint, and (when
  * composed) the announced card and session-node control surface.

package/lib/types/live-roots.d.ts

@@ -0,0 +1,35 @@
+/**
+ * #291: live top-level agents across harness generations.
+ *
+ * Hosts up to 0.2.1 expose `AgentRegistry.roots()` — "all live top-level
+ * agents (created without an owning agent context)". 0.2.2-rc removed it:
+ * live lineage moved to the subagent tree and the registry keeps only
+ * `list()` (all live agents). Top-level is then the delegation-depth
+ * predicate of `@deepseek-ai/dsh-subagent/depth` `delegationDepthOf` —
+ * depth 0 is top-level, absence is top-level. That package is not a
+ * plugin-provided dependency, so its read is mirrored here.
+ *
+ * Nothing in this module throws. The `agent/created` listener runs at
+ * session publication and a throwing listener vetoes the publication — the
+ * 2026-11-05 session-resume incident (history sessions vanished from the
+ * list until refresh). An unreadable or throwing registry surface degrades
+ * to an empty join surface, never to a broken session list. Unlike the
+ * harness' own `delegationDepthOf`, invalid depth values read as absent
+ * instead of throwing, for the same reason.
+ */
+import type { Agent, AgentRegistry } from '@deepseek-ai/dsh-agent';
+/**
+ * Delegation depth of a live agent: 0 = top-level. Mirrors the harness'
+ * authoritative max(persisted session header, runtime options); invalid
+ * values read as absent (never throwing) — see the module comment.
+ */
+export declare function delegationDepthOf(agent: Agent): number;
+/** Whether a live agent is top-level (not inside any subagent tree). */
+export declare function isTopLevelAgent(agent: Agent): boolean;
+/**
+ * Live top-level agents on this host: `roots()` where the host still has
+ * it (exact pre-0.2.2 semantics, so old hosts change nothing), else
+ * `list()` filtered by delegation depth. A missing registry, a surface
+ * with neither method, or a throwing method all degrade to `[]`.
+ */
+export declare function liveRootAgents(registry: AgentRegistry | undefined | null): Agent[];

package/lib/types/origin-claim.d.ts

@@ -56,6 +56,7 @@ export type OriginClaimVerdict = {
     card: A2aPeerCard;
     bound: boolean;
     cli?: true;
+    bodyBound?: true;
 } | {
     ok: false;
     reason: OriginClaimRefusal;

package/lib/types/queue-guard.d.ts

@@ -29,5 +29,7 @@ export interface QueueRow {
 export declare function queuedFor(rows: readonly QueueRow[], team: string): number;
 /** The refusal text when `team`'s queue is full, else undefined. `cap <= 0` disables the guard. */
 export declare function queueFullRefusal(rows: readonly QueueRow[], team: string, message: string, cap: number, mailbox: boolean, ownTask: (taskId: string) => boolean): string | undefined;
+/** #282 S1: the one next step for a full target queue. */
+export declare const QUEUE_FULL_NEXT = "wait for a receipt from the target (a2a-net inbox / a2a_tasks), then send again with a new task id; do not resend in a loop";
 /** Wire-face adapter in the flood guard's shape: a refused fresh key is FAILED, not stranded pending. */
 export declare function createQueueGuard(rows: () => readonly QueueRow[], cap: () => number, ownTask: (taskId: string) => boolean, outcomes: Pick<IdempotencyStore, 'recordOutcome'>, recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void): (caller: string, message: string, team: string, taskId: string, mailbox: boolean, res: ServerResponse) => boolean;

package/lib/types/task-auth.d.ts

@@ -17,9 +17,12 @@ export type Admission = {
 } | {
     readonly ok: false;
     readonly refusal: string;
+    readonly next?: string;
 };
 /** The refusal text of a decision, or undefined when admitted — the shape the faces have always read. */
 export declare const refusalOf: (admission: Admission) => string | undefined;
+/** The next step of a refused decision, or undefined. */
+export declare const nextOf: (a: Admission) => string | undefined;
 /** One cached peer card's published canvas org (gh#71). */
 export interface PeerOrgEntry {
     readonly team?: unknown;

package/lib/types/types.d.ts

@@ -160,6 +160,8 @@ export interface A2aRouteError {
     /** A2A JSON-RPC-style code when the peer supplied one. */
     readonly code?: number;
     readonly task_id?: string;
+    /** One actionable next step for the caller (#282 S1); absent when nothing the caller can do helps. */
+    readonly next?: string;
 }
 /** Canonical `a2a_route` value: success or explicit failure. */
 export type A2aRouteResult = A2aRouteOk | A2aRouteError;