@nelsonlongxiang/dsh-open-a2a-net 0.6.28 → 0.6.29

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

@@ -0,0 +1,56 @@
+/**
+ * Recursion guard (#60, first step: the hop budget) per
+ * docs/protocol/recursion-guard.md. State rides the payload: the origin
+ * mints the envelope with a full budget, every forwarded leg decrements,
+ * and a zero-budget arrival is refused with a STRUCTURED budget-exhausted
+ * error — silent swallowing is forbidden. The visited set (protocol §4.3)
+ * is the SECOND step and is deliberately absent here.
+ *
+ * Wire form: the X-A2A-Guard header carries a base64 JSON payload
+ * { visitToken, hopBudget, deadlineAt? }. An ABSENT header means a
+ * non-forwarding origin: the receiver grants the default one-shot budget
+ * and records guardMode 'default' (protocol §6 — old peers are
+ * constrained, not broken). Parse cost is O(1) for the budget path.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/recursion-guard
+ */
+export declare const DEFAULT_HOP_BUDGET = 4;
+/** Wire code for a zero-budget arrival (cluster-C registry, after -32006). */
+export declare const WIRE_ERROR_BUDGET_EXHAUSTED = -32007;
+/** The guard payload as it travels on the wire. */
+export interface RecursionGuard {
+    readonly visitToken: string;
+    readonly hopBudget: number;
+    readonly deadlineAt?: number;
+}
+export type GuardVerdict = {
+    readonly kind: 'ok';
+    readonly guard: RecursionGuard;
+    readonly mode: 'explicit' | 'default';
+} | {
+    readonly kind: 'budget-exhausted';
+};
+/**
+ * Ingress check: parse the header, validate the budget, fail closed. A
+ * malformed payload falls back to the default budget (a guard that cannot
+ * be evaluated must not reject honest first-hop traffic; the budget bound
+ * still applies). hopBudget <= 0 on arrival ⇒ budget-exhausted.
+ */
+export declare function checkGuardAtIngress(header: string | undefined): GuardVerdict;
+/** Mint the outbound guard for a first-hop dispatch (full budget at origin). */
+export declare function mintGuard(): RecursionGuard;
+/** Serialize for the X-A2A-Guard header. */
+export declare function guardHeader(guard: RecursionGuard): string;
+/**
+ * The ingress refusal path (gh#60): budget-exhausted answers the structured
+ * error, records the receiptless ledger row, and reports true (the caller
+ * returns). The whole response lives here so the ingress seam stays ONE
+ * line (the index.ts ratchet pays-as-it-goes: no net line growth).
+ */
+export declare function refuseIfBudgetExhausted(req: {
+    headers: Record<string, unknown>;
+}, res: {
+    writeHead: (status: number, headers: Record<string, string | number>) => void;
+    end: (body: string) => void;
+}, team: string, caller: string, taskId: string, ledger: {
+    trackReceiptless: (taskId: string, team: string, peer: string, contextId?: string, brief?: string) => void;
+}): boolean;

package/lib/types/runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared A2A runtime types (gh#77): shapes that used to be declared inside
+ * `apply()` and are now read by the face modules as well.
+ * @module src/runtime
+ */
+import type { A2aPeerCard } from './types.ts';
+/**
+ * Recent routing activity for the network panel: a bounded ring of the
+ * latest inbound and outbound route outcomes, newest last. The state route
+ * serves a copy; the panel derives unread badges from new entries.
+ */
+export interface RouteActivityEntry {
+    readonly ts: number;
+    readonly dir: 'in' | 'out';
+    readonly team: string;
+    readonly peer: string;
+    readonly ok: boolean;
+}
+/**
+ * In-flight outbound routes: a route registers on dial and unregisters on
+ * settlement, so the panel can show collaboration in progress ("who is
+ * waiting on whom") — the state route serves a snapshot.
+ */
+export interface InFlightRoute {
+    readonly id: number;
+    readonly team: string;
+    readonly peer: string;
+    readonly startedAt: number;
+}
+/** One peer-card cache entry: when it was fetched and what came back. */
+export interface CardCacheEntry {
+    at: number;
+    card: A2aPeerCard | undefined;
+}

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

@@ -120,6 +120,12 @@ export interface ArchivedRecord {
     readonly endedBy?: ArchiveEnd;
     /** gh#31: which side of the wire the row served, copied from the owed row (absent on rows archived before the field). */
     readonly direction?: 'inbound' | 'outbound';
+    /**
+     * gh#68: copied from the owed row when it awaited no receipt, so a tidied
+     * fire-forget expiry is not read as a send we gave up on. Only `false` is
+     * ever stored; absent means a receipt was owed (or the row predates the field).
+     */
+    readonly receiptExpected?: false;
 }
 /**
  * How one archived row ended (gh#31). The recorded field wins; legacy rows