@nelsonlongxiang/dsh-open-a2a-net 0.5.13

package/lib/invariant.js

@@ -0,0 +1,16 @@
+/** Package-owned invariant companion. @module @nelsonlongxiang/dsh-open-a2a-net/invariant */
+const PACKAGE_NAME = '@nelsonlongxiang/dsh-open-a2a-net';
+/** Cordis companion plugin name. */
+export const name = 'a2a-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the plugin owns no session-event types. Inbound relay
+ * messages land as ordinary `user/message` events (source `plugin/a2a`,
+ * form `relay`) whose shape the core already validates, and tool results ride
+ * the generic tool pipeline.
+ */
+const install = () => { };
+/** Register this package's invariant companion. */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/lib/joined-store.js

@@ -0,0 +1,98 @@
+/**
+ * Persisted session-node join intent (`<dsh-home>/a2a/joined.json`). A join
+ * is a user gesture over a durable session, but the node it mounts lives and
+ * dies with the session's Agent instance — page reloads and host restarts
+ * dispose Agents, which silently dropped every join. The store keeps the
+ * intent across those lifecycles: the plugin remounts the node whenever the
+ * session's Agent comes back, until the user leaves (the only intent
+ * remover; disposal alone never unpersists).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/joined-store
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Hard cap on remembered join intents. Ids of deleted sessions linger
+ * harmlessly (no Agent ever comes back for them); the cap bounds the file,
+ * keeping the most recent intents (peer-store's bound rationale).
+ */
+export const JOIN_CAP = 64;
+/**
+ * Bounded set of session ids whose user joined them to the A2A network,
+ * with whole-file persistence. Pure of any registry knowledge: callers ask
+ * {@link has} when an Agent appears and record {@link add} / {@link remove}
+ * on the join and leave operations.
+ */
+export class JoinedSessions {
+    path;
+    /** Session ids, most recently joined first. */
+    ids = [];
+    /**
+     * @param path - persistence file (`<dsh-home>/a2a/joined.json`); empty = no persistence.
+     */
+    constructor(path) {
+        this.path = path;
+        this.restore();
+    }
+    /**
+     * Whether the session's join intent is remembered.
+     * @param id - the session id to check.
+     * @returns whether the intent is present.
+     */
+    has(id) {
+        return this.ids.includes(id);
+    }
+    /**
+     * Every remembered join intent, most recently joined first.
+     * @returns the remembered session ids.
+     */
+    list() {
+        return [...this.ids];
+    }
+    /**
+     * Remember one join intent, most-recent first, bounded by {@link JOIN_CAP}
+     * (the oldest intent beyond the cap is forgotten).
+     * @param id - the joined session id.
+     */
+    add(id) {
+        this.ids = [id, ...this.ids.filter(entry => entry !== id)].slice(0, JOIN_CAP);
+        this.persist();
+    }
+    /**
+     * Forget one join intent (the leave operation; a no-op when absent).
+     * @param id - the session id whose intent is removed.
+     */
+    remove(id) {
+        if (!this.has(id))
+            return;
+        this.ids = this.ids.filter(entry => entry !== id);
+        this.persist();
+    }
+    /** Load a persisted snapshot on construction, if present. */
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            const sessions = snapshot?.sessions;
+            if (!Array.isArray(sessions))
+                return;
+            this.ids = sessions.filter((entry) => typeof entry === 'string' && entry !== '').slice(0, JOIN_CAP);
+        }
+        catch {
+            // A corrupt store is not fatal: the user re-joins; nothing else is lost.
+        }
+    }
+    /** Persist the intent set (no-op when no path was configured). */
+    persist() {
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            const snapshot = { sessions: [...this.ids] };
+            writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
+        }
+        catch {
+            // An unwritable home must not break joining; the intent degrades to memory-only.
+        }
+    }
+}

package/lib/peer-store.js

@@ -0,0 +1,169 @@
+/**
+ * Bounded, quality-scored peer store (GNUnet hostlist semantics, slice 2).
+ * The configured peer list is a seed set, not the network: referral URLs
+ * learned from fetched cards join the store, are bounded and quality-scored,
+ * and persist across restarts. Failed fetches degrade a peer; a bad peer that
+ * keeps failing is evicted, while seeds stay for the lifetime of the config
+ * that named them. Design basis:
+ * .agents/notes/proposed/feature/2026-08-16-gnunet-prior-art-for-a2a-topology.md.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/peer-store
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Hard cap on tracked peers, seeds included (hostlist bound: 30). */
+export const PEER_CAP = 30;
+/** Initial quality score of a seed or newly offered peer. */
+export const INITIAL_SCORE = 10_000;
+/** Quality penalty on a failed fetch. */
+export const FAILURE_PENALTY = 100;
+/** Quality reward on a successful fetch. */
+export const SUCCESS_REWARD = 100;
+/** Score floor: at or below this a non-seed peer is evicted. */
+export const EVICTION_FLOOR = 0;
+/**
+ * Bounded, quality-scored peer collection with whole-file persistence.
+ * Pure of any network: the caller drives fetch outcomes through
+ * {@link noteFailure} / {@link noteSuccess} and feeds referral URLs through
+ * {@link offer}.
+ */
+export class PeerStore {
+    path;
+    cap;
+    peers = new Map();
+    /**
+     * @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, path, cap = PEER_CAP) {
+        this.path = path;
+        this.cap = cap;
+        this.restore();
+        for (const seed of seeds) {
+            if (seed === '')
+                continue;
+            // The config is authoritative for a seed: it is (re)marked as one —
+            // immune to eviction — and restarts from the initial score regardless
+            // of the persisted one. Replacing the record wholesale keeps PeerRecord
+            // fields readonly.
+            this.peers.set(seed, { url: seed, score: INITIAL_SCORE, seed: true });
+        }
+    }
+    /**
+     * 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() {
+        return [...this.peers.values()]
+            .sort((a, b) => (a.seed === b.seed ? b.score - a.score : a.seed ? -1 : 1))
+            .map(peer => peer.url);
+    }
+    /** Whether the store has room for one more peer. */
+    hasRoom() {
+        return this.peers.size < this.cap;
+    }
+    /**
+     * Offer a referral URL learned from a fetched card. Bounded: an unknown
+     * URL only joins when under the cap; a known URL changes nothing.
+     * @param url - the referred card URL.
+     * @returns whether the peer is tracked (freshly joined or already known).
+     */
+    offer(url) {
+        if (url === '')
+            return false;
+        if (this.peers.has(url))
+            return true;
+        if (!this.hasRoom())
+            return false;
+        this.peers.set(url, { url, score: INITIAL_SCORE, seed: false });
+        this.persist();
+        return true;
+    }
+    /**
+     * Drop one tracked peer outright — a self-referral (a peer listing this
+     * node's own URL back at it) must not linger as a tracked peer. Seeds are
+     * config-owned and stay.
+     * @param url - the peer to forget.
+     */
+    drop(url) {
+        const peer = this.peers.get(url);
+        if (peer === undefined || peer.seed)
+            return;
+        this.peers.delete(url);
+        this.persist();
+    }
+    /**
+     * Note a failed fetch of one peer. A non-seed's score drops; an
+     * at-or-below-floor peer is evicted, so a bad referral disappears rather
+     * than degrading forever. Seeds are config-owned and never penalized.
+     * @param url - the peer that failed.
+     */
+    noteFailure(url) {
+        const peer = this.peers.get(url);
+        if (peer === undefined || peer.seed)
+            return;
+        peer.score -= FAILURE_PENALTY;
+        if (peer.score <= EVICTION_FLOOR)
+            this.peers.delete(url);
+        this.persist();
+    }
+    /**
+     * Note a successful fetch of one peer.
+     * @param url - the peer that answered with a verified card.
+     */
+    noteSuccess(url) {
+        const peer = this.peers.get(url);
+        if (peer === undefined)
+            return;
+        peer.score += SUCCESS_REWARD;
+        this.persist();
+    }
+    /**
+     * The current quality score of one tracked peer, for state reporting.
+     * @param url - the peer URL.
+     * @returns the score, or undefined when the peer is not tracked.
+     */
+    score(url) {
+        return this.peers.get(url)?.score;
+    }
+    /** Load a persisted snapshot on construction, if present. */
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            const peers = snapshot?.peers;
+            if (!Array.isArray(peers))
+                return;
+            for (const entry of peers) {
+                const peer = entry;
+                if (typeof peer?.url !== 'string' || peer.url === '')
+                    continue;
+                this.peers.set(peer.url, {
+                    url: peer.url,
+                    score: typeof peer.score === 'number' && Number.isFinite(peer.score) ? peer.score : INITIAL_SCORE,
+                    seed: peer.seed === true,
+                });
+            }
+        }
+        catch {
+            // A corrupt store is not fatal: fall back to seeds only.
+        }
+    }
+    /** Persist the current peer set (no-op when no path was configured). */
+    persist() {
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            const snapshot = {
+                peers: [...this.peers.values()].map(peer => ({ ...peer })),
+            };
+            writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
+        }
+        catch {
+            // An unwritable home must not break routing; the store degrades to memory-only.
+        }
+    }
+}

package/lib/types/a2a-client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * In-process decentralized A2A client: the outbound peer surface — verified
+ * agent-card fetches (discovery) and direct routes to a peer's
+ * `/a2a/direct` endpoint. Timing and fetch seams are constructor-injected so
+ * tests drive them without a network.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/a2a-client
+ */
+import type { A2aPeerCard, A2aRouteResult } from './types.ts';
+/** One-shot delayed callback returning its disposer. */
+export type A2aSchedule = (callback: () => void, delayMs: number) => () => void;
+/** Minimal fetch face; the first HTTP-level failure rejects. */
+export type A2aFetch = (url: string, init: {
+    readonly method: 'GET' | 'POST';
+    readonly headers: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    readonly text: () => Promise<string>;
+}>;
+/** Constructor facts; every seam is explicit so tests inject doubles. */
+export interface A2aClientOptions {
+    /** `X-API-Key` value sent on peer requests; empty omits the header. */
+    readonly apiKey: string;
+    /** This node's caller label stamped on outbound routes. */
+    readonly sessionId: string;
+    /** Delayed-callback seam (HTTP timeouts). */
+    readonly schedule: A2aSchedule;
+    /** HTTP seam. */
+    readonly fetch: A2aFetch;
+}
+/**
+ * The A2A peer client. One instance serves the whole fiber's outbound
+ * card fetches and direct routes; it owns no connection state.
+ */
+export declare class A2aClient {
+    private readonly options;
+    /** @param options - resolved caller facts and injected seams. */
+    constructor(options: A2aClientOptions);
+    private headers;
+    private http;
+    /**
+     * Fetch one peer's agent card (discovery): team, session, capabilities.
+     * The card is verified at parse — unsigned, badly signed, or expired cards
+     * are rejected here, so a stale peer disappears from discovery without any
+     * background cleanup.
+     * @param baseUrl - the peer's base URL.
+     * @returns the verified card, or `undefined` when unreachable, malformed, or rejected.
+     */
+    fetchCard(baseUrl: string): Promise<A2aPeerCard | undefined>;
+    /**
+     * Extract the reply text from a route result member: the wire carries a
+     * plain string, a `{text}` object, or anything else JSON-encoded.
+     * @param inner - the raw `result` member of a route response.
+     * @param fallback - what a nullish member encodes as.
+     * @returns the reply text.
+     */
+    private replyText;
+    /**
+     * Route directly to a peer node's `/a2a/direct` endpoint. The peer steers
+     * the message into its live agent (or the named session team's agent) and
+     * answers within its own final-reply budget.
+     * @param baseUrl - the peer's base URL.
+     * @param team - target team name (the peer's own or a session team).
+     * @param message - request text.
+     * @param contextId - context id from a prior reply, for multi-turn.
+     * @param signal - caller cancellation.
+     * @param callerSession - caller label overriding the node's label (the calling session's node label).
+     * @returns the canonical route result (success or explicit failure).
+     */
+    routeDirect(baseUrl: string, team: string, message: string, contextId?: string, signal?: AbortSignal, callerSession?: string, asyncMode?: boolean, taskIdFromCaller?: string): Promise<A2aRouteResult>;
+}

package/lib/types/card.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Expiring signed agent cards (GNUnet HELLO semantics): the card carries its
+ * own expiry and an Ed25519 signature over identity, team, capabilities, and
+ * expiry, so only the key holder can extend a card's life. Expiry and the
+ * signature are enforced wherever a card is parsed — no background cleanup.
+ * Design basis: .agents/notes/proposed/feature/2026-08-16-gnunet-prior-art-for-a2a-topology.md (slice 1).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/card
+ */
+import { type KeyObject } from 'node:crypto';
+import type { A2aPeerCard } from './types.ts';
+/** Card validity budget. GNUnet HELLO default (2 days). */
+export declare const CARD_TTL_MS = 172800000;
+/** Announce re-sign cadence: four publication opportunities per TTL. */
+export declare const CARD_REFRESH_MS: number;
+/**
+ * The card fields the signature commits to; every field is lifecycle-relevant.
+ * `peers` is deliberately not a core field: a referral is verified as its own
+ * card at fetch time (hostlist semantics), so a tampered referral list only
+ * produces fetch failures, which the caller's peer store penalizes. `records`
+ * is a core field: a delegation is an authority claim over a name, and only
+ * the zone key holder may publish one. Cards without records sign exactly the
+ * field set above, so their signatures stay byte-identical.
+ */
+export type CardCore = Pick<A2aPeerCard, 'name' | 'session' | 'team' | 'capabilities' | 'expiresAt' | 'records'>;
+/** Why a parsed card was rejected at verification. */
+export type CardRejection = 'malformed' | 'unsigned' | 'expired' | 'bad-signature';
+/** The verification outcome: the card, or the rejection reason. */
+export type CardVerification = {
+    readonly ok: true;
+    readonly card: A2aPeerCard;
+} | {
+    readonly ok: false;
+    readonly reason: CardRejection;
+};
+/**
+ * Encode a public key as the base64 SPKI DER the card carries.
+ * @param publicKey - the signing node's Ed25519 public key.
+ * @returns the base64 SPKI DER string.
+ */
+export declare function encodePublicKey(publicKey: KeyObject): string;
+/**
+ * Sign one card core with the node's Ed25519 private key.
+ * @param core - the card's lifecycle-relevant fields, expiry included.
+ * @param privateKey - the signing node's Ed25519 private key.
+ * @returns the wire card: the core plus the public key and signature.
+ */
+export declare function signCard(core: CardCore, privateKey: KeyObject): A2aPeerCard;
+/**
+ * Verify a parsed card: shape, signature, and expiry, in that order.
+ * @param candidate - the JSON value fetched from a peer's agent-card URL.
+ * @param now - evaluation time (epoch ms); injected for tests.
+ * @returns the verified card, or the first rejection reason.
+ */
+export declare function verifyCard(candidate: unknown, now: number): CardVerification;

package/lib/types/client/A2aControl.d.ts

@@ -0,0 +1,64 @@
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** One session as the host's state route reports it. */
+export interface A2aSessionRow {
+    readonly id: string;
+    readonly label: string;
+    readonly team: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly workspace?: string;
+    readonly joined: boolean;
+    /** `false` on cold rows: the join intent is persisted but the session's agent is not loaded. */
+    readonly live?: boolean;
+    /** The user-named group this session is assigned to, if any. */
+    readonly group?: string;
+}
+/** One peer-side team row as the state route reports it (origin is its natural group). */
+export interface A2aRemoteRow {
+    readonly team: string;
+    readonly name: string;
+    readonly origin?: string;
+    readonly workspace?: string;
+}
+/** One tracked peer as the state route reports it. */
+export interface A2aPeerRow {
+    readonly url: string;
+    readonly score?: number;
+}
+/** One routing outcome as the state route reports it. */
+export interface A2aActivityRow {
+    readonly ts: number;
+    readonly dir: 'in' | 'out';
+    readonly team: string;
+    readonly peer: string;
+    readonly ok: boolean;
+}
+/** One in-flight outbound route as the state route reports it. */
+export interface A2aInFlightRow {
+    readonly team: string;
+    readonly peer: string;
+    readonly startedAt: number;
+}
+/** The state route's full body. */
+export interface A2aState {
+    readonly sessions: readonly A2aSessionRow[];
+    readonly groups: readonly string[];
+    readonly remote: readonly A2aRemoteRow[];
+    readonly peers: readonly A2aPeerRow[];
+    readonly activity: readonly A2aActivityRow[];
+    readonly inFlight: readonly A2aInFlightRow[];
+    /** The host plugin package version, when the state route reports it. */
+    readonly version?: string;
+}
+/** Wake face the registration injects: opens one session through the standard sessions flow. */
+export interface A2aControlInjected {
+    readonly openSession: (id: string) => void;
+}
+/** Full component props: the footer-action owner share, the locale seat, and the wake face. */
+export type A2aControlProps = PropsRuntime<'sidebar.footer.action'> & PropsLocale<'a2aNet'> & A2aControlInjected;
+/**
+ * Render the network toggle and its network panel.
+ * @param props - composed slot props.
+ * @returns the control element tree.
+ */
+export declare function A2aControl({ wide, t, useSessions, openSession }: A2aControlProps): import("react").JSX.Element;

package/lib/types/client/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Open A2A network plugin, browser half: a sidebar footer action listing
+ * this host's sessions as joinable network nodes. The entry probes the
+ * host's session-node state route at registration time — the seat renders
+ * only on a host that serves it (the a2a host half composed with session
+ * nodes, which is its default) — and each row joins/leaves through the
+ * guarded control routes. Opening a cold row (persisted join intent, agent
+ * not back after a restart) goes through the standard sessions flow; the
+ * host remounts the node when the session loads.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type A2aNetKey } from './locales.ts';
+export type { A2aControlInjected, A2aControlProps, A2aSessionRow } from './A2aControl.tsx';
+export type { A2aNetKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** A2A network sidebar control copy. */
+        a2aNet: A2aNetKey;
+    }
+}
+/** Services required by the browser half: the slot system, the sessions
+ * flow used to wake cold rows, and the locale dictionaries. */
+export declare const inject: string[];
+/** Registers the network control's dictionaries and its sidebar seat.
+ * @param ctx - Client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,7 @@
+/** Locale dictionaries for the A2A network sidebar control (namespace `a2aNet`). */
+/** Dictionary keys owned by the `a2aNet` namespace. */
+export type A2aNetKey = 'a2a.label' | 'a2a.title' | 'a2a.empty' | 'a2a.join' | 'a2a.leave' | 'a2a.cold' | 'a2a.wake' | 'a2a.note' | 'a2a.remote' | 'a2a.remoteUnknownOrigin' | 'a2a.peers' | 'a2a.peersEmpty' | 'a2a.activity' | 'a2a.activityEmpty' | 'a2a.inFlight' | 'a2a.inFlightStale' | 'a2a.jump' | 'a2a.search' | 'a2a.searchEmpty' | 'a2a.group' | 'a2a.groupDefault' | 'a2a.groupClear' | 'a2a.groupNew' | 'a2a.groupNewGo';
+/** Simplified Chinese dictionary. */
+export declare const zh: Record<A2aNetKey, string>;
+/** English dictionary. */
+export declare const en: Record<A2aNetKey, string>;

package/lib/types/client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * In-process decentralized A2A client: the outbound peer surface — verified
+ * agent-card fetches (discovery) and direct routes to a peer's
+ * `/a2a/direct` endpoint. Timing and fetch seams are constructor-injected so
+ * tests drive them without a network.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/client
+ */
+import type { A2aPeerCard, A2aRouteResult } from './types.ts';
+/** One-shot delayed callback returning its disposer. */
+export type A2aSchedule = (callback: () => void, delayMs: number) => () => void;
+/** Minimal fetch face; the first HTTP-level failure rejects. */
+export type A2aFetch = (url: string, init: {
+    readonly method: 'GET' | 'POST';
+    readonly headers: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    readonly text: () => Promise<string>;
+}>;
+/** Constructor facts; every seam is explicit so tests inject doubles. */
+export interface A2aClientOptions {
+    /** `X-API-Key` value sent on peer requests; empty omits the header. */
+    readonly apiKey: string;
+    /** This node's caller label stamped on outbound routes. */
+    readonly sessionId: string;
+    /** Delayed-callback seam (HTTP timeouts). */
+    readonly schedule: A2aSchedule;
+    /** HTTP seam. */
+    readonly fetch: A2aFetch;
+}
+/**
+ * The A2A peer client. One instance serves the whole fiber's outbound
+ * card fetches and direct routes; it owns no connection state.
+ */
+export declare class A2aClient {
+    private readonly options;
+    /** @param options - resolved caller facts and injected seams. */
+    constructor(options: A2aClientOptions);
+    private headers;
+    private http;
+    /**
+     * Fetch one peer's agent card (discovery): team, session, capabilities.
+     * The card is verified at parse — unsigned, badly signed, or expired cards
+     * are rejected here, so a stale peer disappears from discovery without any
+     * background cleanup.
+     * @param baseUrl - the peer's base URL.
+     * @returns the verified card, or `undefined` when unreachable, malformed, or rejected.
+     */
+    fetchCard(baseUrl: string): Promise<A2aPeerCard | undefined>;
+    /**
+     * Extract the reply text from a route result member: the wire carries a
+     * plain string, a `{text}` object, or anything else JSON-encoded.
+     * @param inner - the raw `result` member of a route response.
+     * @param fallback - what a nullish member encodes as.
+     * @returns the reply text.
+     */
+    private replyText;
+    /**
+     * Route directly to a peer node's `/a2a/direct` endpoint. The peer steers
+     * the message into its live agent (or the named session team's agent) and
+     * answers within its own final-reply budget.
+     * @param baseUrl - the peer's base URL.
+     * @param team - target team name (the peer's own or a session team).
+     * @param message - request text.
+     * @param contextId - context id from a prior reply, for multi-turn.
+     * @param signal - caller cancellation.
+     * @param callerSession - caller label overriding the node's label (the calling session's node label).
+     * @returns the canonical route result (success or explicit failure).
+     */
+    routeDirect(baseUrl: string, team: string, message: string, contextId?: string, signal?: AbortSignal, callerSession?: string): Promise<A2aRouteResult>;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Persisted session groups: user-named buckets for the network panel's
+ * session listing, stored under the a2a home so they survive restarts and
+ * follow the node (not the browser). Plain JSON, one writer (the control
+ * routes), read fresh by the state route.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/group-store
+ */
+/** On-disk shape; assignments map a session id to its group name. */
+export interface GroupSnapshot {
+    readonly groups: readonly string[];
+    readonly assignments: Readonly<Record<string, string>>;
+}
+/** Upper bound on named groups (a panel taxonomy, not a database). */
+export declare const GROUP_CAP = 20;
+/**
+ * Bounded group store with last-write-wins persistence.
+ */
+export declare class GroupStore {
+    private groups;
+    private assignments;
+    private readonly path;
+    /**
+     * @param path - the snapshot file; an empty path keeps the store in memory.
+     */
+    constructor(path: string);
+    /** Load a persisted snapshot, if present and well-formed. */
+    private restore;
+    /** Persist the current snapshot (no-op without a path). */
+    private persist;
+    /** Every named group, in creation order. */
+    list(): readonly string[];
+    /**
+     * The group a session belongs to, if any.
+     * @param id - the session id.
+     */
+    groupOf(id: string): string | undefined;
+    /** Every assignment, for the state route's session rows. */
+    all(): Readonly<Record<string, string>>;
+    /**
+     * Create a named group; whitespace trims, duplicates are idempotent, and
+     * the cap rejects a group beyond {@link GROUP_CAP}.
+     * @param name - the raw user-supplied name.
+     * @returns the stored name, or undefined when rejected.
+     */
+    create(name: string): string | undefined;
+    /**
+     * Assign one session to an existing group (creating it when new and
+     * under the cap); an empty group name unassigns.
+     * @param id - the session id.
+     * @param name - the group name, or '' to clear.
+     */
+    assign(id: string, name: string): boolean;
+    /**
+     * Delete an empty-or-not group; its assignments clear with it.
+     * @param name - the group name.
+     */
+    remove(name: string): boolean;
+}