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

package/lib/transport-caps.js

@@ -0,0 +1,31 @@
+/**
+ * Transport-level wire caps shared by both directions of the direct-route
+ * surface. B5 enforcement (network ruling, 2026-08-27): an oversized payload
+ * is REJECTED, never truncated — rejection is structured on the inbound half
+ * (HTTP 413 + a JSON wire error code) and fail-fast on the outbound half
+ * (no bytes leave the process, no doomed upload burns the 15s HTTP budget).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/transport-caps
+ */
+/** Hard ceiling on one `/a2a/direct` request body, in UTF-8 bytes (512 KiB). */
+export const MAX_ROUTE_BODY_BYTES = 512 * 1024;
+/**
+ * Hard ceiling on one control-route layout save (`POST
+ * /__dsh_a2a/canvas-layout`), in UTF-8 bytes (64 KiB). Sized from the
+ * legitimate document envelope: LayoutStore clamps to 256 nodes (keys
+ * ≤ 128 chars) + 96 frames (names ≤ 40 chars), whose worst case is
+ * ≈50 KiB — the historical shared 10 KiB control cap rejected real
+ * full-fleet documents (256 nodes ≈ 23 KiB) outright, so the layout
+ * route overrides with this cap while every other control route keeps
+ * the 10 KiB default.
+ */
+export const MAX_LAYOUT_BODY_BYTES = 64 * 1024;
+/**
+ * Wire error code for a body above {@link MAX_ROUTE_BODY_BYTES}. First member
+ * of the transport rejection family (the enum registry lives in
+ * docs/protocol/delivery-origin-auth.md until it earns its own module).
+ */
+export const WIRE_ERROR_PAYLOAD_TOO_LARGE = -32001;
+/** Whether a body of this byte length may cross the wire. */
+export function withinRouteBodyCap(byteLength) {
+    return byteLength <= MAX_ROUTE_BODY_BYTES;
+}

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

@@ -5,6 +5,7 @@
  * tests drive them without a network.
  * @module @nelsonlongxiang/dsh-open-a2a-net/a2a-client
  */
+import { type CardRejection } from './card.ts';
 import type { A2aPeerCard, A2aRouteResult } from './types.ts';
 /** One-shot delayed callback returning its disposer. */
 export type A2aSchedule = (callback: () => void, delayMs: number) => () => void;
@@ -25,11 +26,43 @@ export interface A2aClientOptions {
     readonly apiKey: string;
     /** This node's caller label stamped on outbound routes. */
     readonly sessionId: string;
+    /**
+     * Zone handle stamped as `X-A2A-Caller` on card GETs (gh#7 G1): peers
+     * serve the FULL card only to named callers — anonymous fetchers get the
+     * minimal discovery card without sessionTeams/teamMemberships/lanIp.
+     * Empty omits the header (anonymous posture).
+     */
+    readonly cardCaller: string;
+    /**
+     * gh#9+gh#10 OriginClaim signer (docs/protocol/delivery-origin-auth.md):
+     * produces the four envelope headers with the NODE'S CARD KEY. Present ⇒
+     * every card GET and direct POST carries a verifiable origin claim;
+     * absent ⇒ the caller stays at the named-only posture (transition).
+     */
+    readonly originClaim?: () => Record<string, string>;
     /** Delayed-callback seam (HTTP timeouts). */
     readonly schedule: A2aSchedule;
     /** HTTP seam. */
     readonly fetch: A2aFetch;
 }
+/**
+ * One card fetch with its failure stage kept: a peer that cannot be reached
+ * (transport or HTTP error) is a different diagnosis from one that answers
+ * with a card verification rejects — probes report the difference, plain
+ * discovery collapses both to `undefined`.
+ */
+export type CardFetchOutcome = {
+    readonly ok: true;
+    readonly card: A2aPeerCard;
+} | {
+    readonly ok: false;
+    readonly stage: 'unreachable';
+    readonly detail: string;
+} | {
+    readonly ok: false;
+    readonly stage: 'rejected';
+    readonly reason: CardRejection;
+};
 /**
  * The A2A peer client. One instance serves the whole fiber's outbound
  * card fetches and direct routes; it owns no connection state.
@@ -49,6 +82,14 @@ export declare class A2aClient {
      * @returns the verified card, or `undefined` when unreachable, malformed, or rejected.
      */
     fetchCard(baseUrl: string): Promise<A2aPeerCard | undefined>;
+    /**
+     * The diagnosing half of {@link fetchCard}: the same fetch and verification
+     * with the failure stage preserved, so a probe can tell a down node from a
+     * distrusted card.
+     * @param baseUrl - the peer's base URL.
+     * @returns the verified card, or the failure's stage and detail.
+     */
+    fetchCardDetail(baseUrl: string): Promise<CardFetchOutcome>;
     /**
      * Extract the reply text from a route result member: the wire carries a
      * plain string, a `{text}` object, or anything else JSON-encoded.
@@ -69,5 +110,35 @@ export declare class A2aClient {
      * @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>;
+    routeDirect(baseUrl: string, team: string, message: string, contextId?: string, signal?: AbortSignal, callerSession?: string, asyncMode?: boolean, taskIdFromCaller?: string, callbackAddress?: string): Promise<A2aRouteResult>;
+    /**
+     * Query a peer's `/a2a/query` outcome surface (W7 slice 2): read-only
+     * lookup of one claimed task's settled outcome. The fingerprint is the
+     * authorization — the caller recomputes it from the exact submit fields
+     * with the shared `peerPayloadFingerprint`. Every transport-level failure
+     * (network miss, HTTP error, unparseable or malformed body, empty fields)
+     * answers `undefined`: a query that cannot complete carries no increment
+     * of information, never a verdict.
+     */
+    queryOutcome(baseUrl: string, taskId: string, fingerprint: string, signal?: AbortSignal): Promise<A2aQueryAnswer | undefined>;
 }
+/** The typed `/a2a/query` answer, 1:1 with the wire body's four states. */
+export type A2aQueryAnswer = {
+    readonly found: false;
+    readonly reason: 'unknown-task' | 'payload-mismatch';
+} | {
+    readonly found: true;
+    readonly status: 'pending';
+} | {
+    readonly found: true;
+    readonly status: 'completed';
+    readonly reply: string;
+    readonly settledAt: string;
+    readonly truncated?: boolean;
+} | {
+    readonly found: true;
+    readonly status: 'failed';
+    readonly error: string;
+    readonly settledAt: string;
+    readonly truncated?: boolean;
+};

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

@@ -0,0 +1,102 @@
+/**
+ * Persisted canvas teams: user-composed multi-member routing groups under
+ * the a2a home (`a2a/canvas.json`). A canvas team is a named set of member
+ * references in one of two shapes: a local session id (a joined session
+ * node on this host) or a remote team handle (`<zone>/<id8>`, a session
+ * node published by a peer — one member may sit in many teams). Routing to
+ * `<team>/canvas/<name>` resolves the first live local member, wakes the
+ * first cold local one, then falls through to the remote members in order
+ * (the directory resolves their handles; remote nodes never wake from
+ * here). Membership order is the routing priority (member list order),
+ * preserved verbatim on disk. Plain JSON, one writer (the control routes),
+ * read fresh by the state route.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/canvas-store
+ */
+/** On-disk shape: ordered team entries, each an ordered member id list. */
+export interface CanvasSnapshot {
+    readonly teams: ReadonlyArray<{
+        readonly name: string;
+        readonly members: readonly string[];
+    }>;
+}
+/** Upper bounds: a canvas taxonomy, not a database. */
+export declare const CANVAS_TEAM_CAP = 64;
+export declare const CANVAS_MEMBER_CAP = 32;
+/** Longest accepted team name (same budget as group names). */
+export declare const CANVAS_NAME_MAX = 40;
+/**
+ * Whether one member entry references a remote node rather than a local
+ * session id. Remote refs are zone-qualified team handles (`<zone>/<id8>`),
+ * so the '/'-test is deterministic: local session ids (`session-<uuid>`,
+ * `import-<uuid>`) never contain one, and canvas team names — the only other
+ * strings in a member slot — are barred from '/' at creation.
+ */
+export declare function isRemoteMemberRef(id: string): boolean;
+/**
+ * Shape-gate for a remote member reference at the control-route seam: at
+ * least one '/'-delimited segment on each side, no whitespace. The registry
+ * cross-check lives in the UI (the picker offers discovered rows only);
+ * this gate keeps malformed strings out of the persisted file.
+ */
+export declare function validRemoteMemberRef(id: string): boolean;
+/**
+ * Bounded canvas-team store with last-write-wins persistence. Pure of any
+ * registry knowledge: callers validate join state and resolve members.
+ */
+export declare class CanvasStore {
+    /** Team entries in creation order; members in add order (routing priority). */
+    private teams;
+    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 team name, in creation order. */
+    list(): readonly string[];
+    /** Whether the named team exists. */
+    hasTeam(name: string): boolean;
+    /** The named team's member ids in routing-priority order (a copy). */
+    membersOf(name: string): readonly string[];
+    /**
+     * The named team's remote member refs (zone-qualified team handles) in
+     * routing-priority order — the failover tier after the local live/cold
+     * tiers miss. Shape test only: whether the handle currently resolves is
+     * the directory's question at route time, not the store's.
+     */
+    remoteMembersOf(name: string): readonly string[];
+    /** Every team name the id is a member of, in team creation order. */
+    teamsOf(id: string): readonly string[];
+    /**
+     * Create a named team; whitespace trims, duplicates are idempotent, and
+     * the cap rejects a team beyond {@link CANVAS_TEAM_CAP}.
+     * @param name - the raw user-supplied name.
+     * @returns the stored name, or undefined when rejected.
+     */
+    create(name: string): string | undefined;
+    /**
+     * Delete a team (with its memberships).
+     * @param name - the team name.
+     */
+    remove(name: string): boolean;
+    /**
+     * Add one member (idempotent; duplicates keep the original priority slot).
+     * The team must exist — callers create it first so the cap applies once.
+     * @param name - the existing team name.
+     * @param id - the member session id.
+     */
+    addMember(name: string, id: string): boolean;
+    /**
+     * Remove one member from one team (a no-op when absent).
+     */
+    removeMember(name: string, id: string): boolean;
+    /**
+     * Drop one id from every team — the leave and archive paths: a session
+     * leaving the network keeps no canvas membership anywhere.
+     * @param id - the departing session id.
+     */
+    dropMember(id: string): void;
+}

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

@@ -1,29 +1,8 @@
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
-/** One session as the host's state route reports it. */
+/** One session as the host's state route reports it (jump-target lookup only). */
 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 {
@@ -39,16 +18,27 @@ export interface A2aInFlightRow {
     readonly peer: string;
     readonly startedAt: number;
 }
-/** The state route's full body. */
+/** One outbound task owed a receipt, as the state route reports it. */
+export interface A2aTaskRow {
+    readonly taskId: string;
+    readonly team: string;
+    readonly peer: string;
+    readonly startedAt: number;
+    readonly status: string;
+    /** C-ruling: false rows are conversational noise (delivered, no formal receipt, past the stale hour). */
+    readonly settleable?: boolean;
+}
+/** The state the feed renders. */
 export interface A2aState {
+    /** Session rows exist only to resolve an activity row's jump target. */
     readonly sessions: readonly A2aSessionRow[];
-    readonly groups: readonly string[];
-    readonly remote: readonly A2aRemoteRow[];
-    readonly peers: readonly A2aPeerRow[];
     readonly activity: readonly A2aActivityRow[];
     readonly inFlight: readonly A2aInFlightRow[];
+    readonly tasks: readonly A2aTaskRow[];
     /** The host plugin package version, when the state route reports it. */
     readonly version?: string;
+    /** C face: stale conversational tail count (delivered without formal receipt, past the stale hour). */
+    readonly tasksStaleCount?: number;
 }
 /** Wake face the registration injects: opens one session through the standard sessions flow. */
 export interface A2aControlInjected {
@@ -57,8 +47,8 @@ export interface A2aControlInjected {
 /** 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.
+ * Render the network toggle and its activity feed.
  * @param props - composed slot props.
  * @returns the control element tree.
  */
-export declare function A2aControl({ wide, t, useSessions, openSession }: A2aControlProps): import("react").JSX.Element;
+export declare function A2aControl({ wide, t, openSession }: A2aControlProps): import("react").JSX.Element;

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

@@ -1,6 +1,6 @@
 /** 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';
+export type A2aNetKey = 'a2a.label' | 'a2a.title' | 'a2a.activity' | 'a2a.activityEmpty' | 'a2a.inFlight' | 'a2a.inFlightStale' | 'a2a.tasks' | 'a2a.tasksNote' | 'a2a.tasksStale' | 'a2a.jump' | 'a2a.stageTitle' | 'a2a.stageWorkbench';
 /** Simplified Chinese dictionary. */
 export declare const zh: Record<A2aNetKey, string>;
 /** English dictionary. */

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

@@ -3,6 +3,12 @@
  * 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.
+ *
+ * @deprecated 0.6.6 — the unified team model supersedes manual grouping:
+ * canvas teams are the human-assigned grouping face and remote rows already
+ * cluster by publishing host (`origin`). The store stays readable so old
+ * panels keep working, but it is not developed further; use canvas teams
+ * for anything new.
  * @module @nelsonlongxiang/dsh-open-a2a-net/group-store
  */
 /** On-disk shape; assignments map a session id to its group name. */

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

@@ -0,0 +1,164 @@
+/**
+ * Server-side idempotency key uniqueness (work-order P3 / B3 ruling).
+ *
+ * Caller-born task ids are single-use by contract; until now the server only
+ * deduped its own ledger rows. This store closes the execution-side gap: the
+ * FIRST claim of a key inside the TTL window executes, a same-key replay of
+ * the identical payload answers `replay` (the prior attempt owns whatever
+ * outcome it produced — never re-steer, never double-bill), and a same-key
+ * DIFFERENT payload is a hard `conflict`. All three verdicts are plain data;
+ * the endpoint maps them to 200/409(-32003)/409(-32002).
+ *
+ * W7 slice 2: the claim row now also RETAINS the prior attempt's settled
+ * outcome (when a settlement hook recorded one), and {@link query} answers
+ * the read-only `/a2a/query` surface — the retrieval half of the S1
+ * recovery row. The fingerprint that guards a claim is the same value that
+ * authorizes a query: presenting {@link peerPayloadFingerprint} of the
+ * original submit means holding the original payload.
+ *
+ * Persistence at `<dsh-home>/a2a/idempotency.json`; TTL prunes lazily on
+ * every entry point (no timers — this host restarts too often), capacity
+ * evicts oldest-inserted first, and every failure degrades to memory-only.
+ * Never throws: orchestrator settlement paths fire here repeatedly under
+ * conditions nobody can predict.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/idempotency-store
+ */
+/** How long one claimed key blocks re-execution. */
+export declare const IDEMPOTENCY_TTL_MS: number;
+/** Capacity before oldest-inserted eviction (a window, not an archive). */
+export declare const IDEMPOTENCY_CAP = 256;
+/** Wire code: same key came back with a DIFFERENT payload inside the window. */
+export declare const WIRE_ERROR_IDEMPOTENCY_CONFLICT = -32002;
+/** Wire code: exact replay — refused so the prior run stays authoritative. */
+export declare const WIRE_ERROR_REPLAY_REJECTED = -32003;
+/** Cap on one stored outcome text; truncation is flagged, never silent. */
+export declare const OUTCOME_TEXT_CAP = 65536;
+/** The three claim verdicts; stable vocabulary per the consumer contract. */
+export type ClaimVerdict = 'fresh' | 'replay' | 'conflict';
+/**
+ * The payload fingerprint of one A2A submit — the shared implementation the
+ * gate claims with, the query endpoint re-verifies with, and the caller-side
+ * bridge face recomputes from the exact submit fields. ONE implementation by
+ * contract (W7 slice 2): any drift across those three roles would turn
+ * honest outcome queries into phantom payload-mismatch verdicts. The field
+ * order below IS the wire format; do not reorder.
+ */
+export declare function peerPayloadFingerprint(input: {
+    readonly caller: string;
+    readonly message: string;
+    readonly noWait: boolean;
+    readonly team: string;
+}): string;
+/** The settled outcome of the execution that earned a claim (W7 slice 2). */
+export interface TaskOutcome {
+    readonly status: 'completed' | 'failed';
+    /** The settled round text (completed rows). */
+    readonly reply?: string;
+    /** The failure prose (failed rows). */
+    readonly error?: string;
+    /** True when the stored text was cut to {@link OUTCOME_TEXT_CAP}. */
+    readonly truncated?: boolean;
+}
+/**
+ * The read-only answer for one outcome lookup. `pending` honestly means
+ * "in flight OR the outcome was never registered" — the two are
+ * indistinguishable from outside, and the answer pretends otherwise for
+ * neither (old snapshots restored without outcomes, hooks that never fire
+ * for a delivery mode, all land here).
+ */
+export type StoredQueryVerdict = {
+    readonly found: false;
+    readonly reason: 'unknown-task' | 'payload-mismatch';
+} | {
+    readonly found: true;
+    readonly status: 'pending';
+} | {
+    readonly found: true;
+    readonly status: 'completed';
+    readonly reply: string;
+    /** Settle time (epoch ms); the endpoint maps it to wire ISO. */
+    readonly settledAt: number;
+    readonly truncated?: boolean;
+} | {
+    readonly found: true;
+    readonly status: 'failed';
+    readonly error: string;
+    /** Settle time (epoch ms); the endpoint maps it to wire ISO. */
+    readonly settledAt: number;
+    readonly truncated?: boolean;
+};
+export interface IdempotencyOptions {
+    /** TTL override (tests inject short windows); defaults to {@link IDEMPOTENCY_TTL_MS}. */
+    ttlMs?: number;
+    /** Capacity override; defaults to {@link IDEMPOTENCY_CAP}. */
+    cap?: number;
+    /** Clock injection for deterministic expiry tests. */
+    now?: () => number;
+}
+/** The read-only idempotency-window aggregate (state route / a2a_status;
+ * 0.5.36 observability slice). Counters are cumulative since genesis. */
+export interface IdempotencyStats {
+    readonly window: number;
+    readonly cap: number;
+    readonly pending: number;
+    readonly settled: number;
+    readonly claimsFresh: number;
+    readonly replays: number;
+    readonly conflicts: number;
+}
+export declare class IdempotencyStore {
+    private readonly path;
+    private readonly rows;
+    private readonly ttlMs;
+    private readonly cap;
+    private readonly now;
+    private claimsFresh;
+    private replays;
+    private conflicts;
+    /**
+     * @param path - persistence file; empty string keeps the store memory-only.
+     * @param options - TTL/capacity/clock overrides for tests.
+     */
+    constructor(path: string, options?: IdempotencyOptions);
+    /**
+     * Claim or inspect one key against a payload fingerprint.
+     * @returns `'fresh'` when the key may execute now (and is recorded),
+     * `'replay'` when the identical fingerprint was already claimed inside the
+     * window, `'conflict'` when the key exists with a different fingerprint.
+     */
+    claim(taskId: string, fingerprint: string): ClaimVerdict;
+    /**
+     * Read-only aggregate for the observability surfaces (state route /
+     * a2a_status, 0.5.36): window occupancy, outcome split, and the
+     * cumulative claim-verdict counters. Never throws; the only write it may
+     * perform is the shared lazy TTL prune.
+     */
+    stats(): IdempotencyStats;
+    /**
+     * Attach the settled outcome to an existing claim (W7 slice 2). First
+     * write wins: the sync / detached-bridge / receipt hooks are mutually
+     * exclusive by wait semantics today, so a second write would only ever
+     * mean a future hook bug — ignore it instead of flip-flopping the record.
+     * Unknown or already-settled ids answer `false`. Never throws.
+     * @returns whether the outcome was recorded.
+     */
+    recordOutcome(taskId: string, outcome: TaskOutcome, settledAt?: number): boolean;
+    /**
+     * Read-only outcome lookup for the `/a2a/query` surface (W7 slice 2).
+     * The caller must present the task id AND the original payload's
+     * fingerprint — the fingerprint match is the authorization, and a
+     * mismatch is a plain negative answer, never the frozen -32002 conflict
+     * vocabulary (queries do not produce conflicts). Empty or unknown ids
+     * answer unknown-task. Never claims, never throws; the only write it may
+     * perform is the shared lazy TTL prune.
+     */
+    query(taskId: string, fingerprint: string): StoredQueryVerdict;
+    /** Whether one key currently sits inside the window (diagnostics). */
+    has(taskId: string): boolean;
+    /** Drop expired keys; runs on every entry point, never timer-driven. */
+    private prune;
+    /** Capacity guard: Map iteration order = insertion order, so first key dies. */
+    private evictOldest;
+    private restore;
+    private persist;
+}