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

package/lib/types/faces/wire.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The /a2a/* wire faces (gh#77 batch B2; slice 2 adds log + query).
+ *
+ * Moved verbatim out of apply() in src/index.ts: the routes register when
+ * the web server settles, exactly as before. What used to be closure
+ * captures arrives through WireDeps and is destructured once below, so the
+ * route bodies read as they did in index.ts (the B1 admin.ts pattern). The
+ * one accessor deviation: the log face's `legacyInboundCount += 1` (a let in
+ * index.ts) goes through `d.bumpLegacyInbound()`, the same mutable-binding
+ * treatment admin.ts gives its six lets. direct stays inline for slice 3.
+ * @module src/faces/wire
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type WebServer from '@deepseek-ai/dsh-host-webserver';
+import type { A2aPeerCard } from '../types.ts';
+import { CanvasStore } from '../canvas-store.ts';
+import type { CliDepositStore } from '../cli-deposit.ts';
+import type { IdempotencyStore } from '../idempotency-store.ts';
+import type { JoinedSessions } from '../joined-store.ts';
+import { type TaskLedger } from '../task-ledger.ts';
+import type { Config } from '../index.ts';
+/** The cold-wake answer (mirrors index.ts's local ColdWake). */
+export type ColdWake = {
+    readonly kind: 'flight';
+    readonly flight: Promise<Agent>;
+} | {
+    readonly kind: 'no-face';
+} | {
+    readonly kind: 'archived';
+} | {
+    readonly kind: 'no-match';
+};
+/** routeIntoAgent's settled answer (mirrors index.ts's local union). */
+export type RouteOutcome = {
+    ok: true;
+    reply: string;
+    status?: string;
+    bridge?: 'native-teams';
+    placeholder?: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+interface BridgeTeamsRegistryMirror {
+    listTeams(): Array<{
+        name: string;
+        description: string;
+    }>;
+    describeTarget(handle: string): Promise<{
+        plane: 'local' | 'a2a';
+        ambiguous?: boolean;
+        localLabel?: string;
+    }>;
+    startRound(args: {
+        team?: string;
+        message: string;
+    }, parent: {
+        id: string;
+        session: {
+            events?: readonly unknown[];
+        };
+    }, signal: AbortSignal): Promise<string>;
+}
+/** nativeTeamsPrepare's answer (mirrors index.ts's local union). */
+export type NativePrepared = {
+    readonly ok: true;
+    readonly teams: BridgeTeamsRegistryMirror;
+    readonly parent: {
+        id: string;
+        session: {
+            events?: readonly unknown[];
+        };
+    };
+} | {
+    readonly ok: false;
+    readonly reason: 'not-claimed';
+} | {
+    readonly ok: false;
+    readonly reason: 'error';
+    readonly error: string;
+};
+/** nativeTeamsRound's settled answer (mirrors index.ts's local union). */
+export type NativeRoundOutcome = {
+    readonly ok: true;
+    readonly reply: string;
+    readonly settled: boolean;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly phase?: 'pre-dispatch';
+    readonly aborted?: boolean;
+};
+/** What verifyOriginClaim answers (see index.ts; reason widens to string here — the faces only interpolate it). */
+export type OriginClaimResult = {
+    ok: true;
+    caller: string;
+    callerUrl: string;
+    card: A2aPeerCard;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The closure captures the wire faces read (grows with each extracted face). */
+export interface WireDeps {
+    readonly ctx: Context;
+    readonly logger: ReturnType<Context['logger']>;
+    readonly config: Config;
+    readonly cliDeposits: CliDepositStore;
+    readonly canvasStore: CanvasStore;
+    readonly sessionNodes: Map<string, Agent>;
+    readonly joinedSessions: JoinedSessions;
+    readonly idempotencyStore: IdempotencyStore;
+    readonly verifyOriginClaim: (req: IncomingMessage) => Promise<OriginClaimResult>;
+    readonly callerLinkedToThisHost: (caller: string, callerUrl: string, callerCard: A2aPeerCard | undefined) => boolean;
+    readonly recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void;
+    readonly bumpLegacyInbound: () => void;
+    readonly secretEqual: (a: string, b: string) => boolean;
+    readonly a2aCallerRefusal: (caller: string, targetTeam?: string) => string | undefined;
+    readonly scanSessionLogList: () => Array<{
+        id: string;
+        mtimeMs: number;
+        sizeBytes: number;
+    }>;
+    readonly readSessionLogTail: (id: string, limit: number) => {
+        ok: true;
+        id: string;
+        messages: Array<{
+            role: string;
+            text: string;
+            time?: number;
+        }>;
+    } | {
+        ok: false;
+        error: string;
+    };
+    readonly taskLedger: TaskLedger;
+    readonly refuseIfFlooded: (caller: string, message: string, team: string, taskId: string, res: ServerResponse) => boolean;
+    readonly settleAndAnnounce: (message: string) => void;
+    readonly touchWakeDemand: () => void;
+    readonly session: string;
+    readonly resolveAgentForTeam: (team: string) => Agent | undefined;
+    readonly parseCanvasTeamName: (team: string) => string | undefined;
+    readonly canvasLiveAgent: (name: string | undefined, skipId?: string) => Agent | undefined;
+    readonly wakeColdTeam: (team: string, skipId?: string) => ColdWake;
+    readonly probeConsumption: (agent: Agent, taskId: string) => boolean;
+    readonly steerRelay: (agent: Agent, text: string, sender?: string) => void;
+    readonly fromClause: (from: string) => string;
+    readonly armReceiptAutosend: (target: Agent, taskId: string, callerTeam: string | undefined, deliveredText: string) => void;
+    readonly receiptExpectationOf: (receiptTarget: string) => 'receivable' | 'process-label';
+    readonly armAsyncNudge: (agent: Agent, team: string, taskId: string, delayMs: number) => void;
+    readonly liveAgent: () => Agent | undefined;
+    readonly callerIsAgent: (agent: Agent, caller: string) => boolean;
+    readonly selfRouteText: (team: string) => string;
+    readonly noWakeFaceText: (team: string) => string;
+    readonly archivedColdMatchText: (team: string) => string;
+    readonly noColdMatchText: (team: string) => string;
+    readonly nativeTeamsPrepare: (team: string) => Promise<NativePrepared>;
+    readonly nativeTeamsRound: (prepared: Extract<NativePrepared, {
+        ok: true;
+    }>, team: string, caller: string, message: string, taskId: string | undefined) => Promise<NativeRoundOutcome>;
+    readonly routeIntoAgent: (team: string, message: string, caller: string, taskId?: string) => Promise<RouteOutcome>;
+}
+/**
+ * Register the small wire faces on a settled web server.
+ * @param webServer - the settled host web server.
+ * @param d - the captures listed on {@link WireDeps}.
+ */
+export declare function registerWireFaces(webServer: WebServer, d: WireDeps): void;
+export {};

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

@@ -0,0 +1,29 @@
+/** gh#91 transitional ingress brakes. One guard per apply(), never process-global.
+ * Run AFTER admission, OriginClaim and the fresh idempotency claim, BEFORE
+ * settlement/mailbox/steer. Replays keep 409 and spend no delivery quota.
+ * All refusals carry a stable reason, task id, failed query outcome and an
+ * activity event. This is not the independent file channel or deployment.
+ */
+import type { ServerResponse } from 'node:http';
+import type { IdempotencyStore } from './idempotency-store.ts';
+export declare const WIRE_ERROR_RATE_LIMITED = -32008;
+export declare const MAX_PARTS_PER_TRANSFER = 16;
+export declare const DEFAULT_RATE_PER_MINUTE = 16;
+type Reason = 'sender-rate-limited' | 'file-parts-exceeded' | 'file-part-invalid' | 'file-part-duplicate' | 'flood-state-full';
+export declare class FloodGuard {
+    private readonly now;
+    private readonly senders;
+    private readonly transfers;
+    constructor(now?: () => number);
+    /** Check/admit one fresh task. No timer; maps and per-key sets are bounded.
+     * Active transfer entries NEVER evict to make space (which would reset a
+     * transfer's allowance); capacity exhaustion refuses visibly instead.
+     * Counts are boot-local: restart resets them, disclosed in the guide.
+     */
+    check(caller: string, message: string): Reason | undefined;
+}
+/** Host-scoped adapter; rejected fresh keys are FAILED, not stranded pending.
+ * HTTP 200 retains the existing client's structured peer-error path.
+ */
+export declare function createFloodGuard(outcomes: Pick<IdempotencyStore, 'recordOutcome'>, recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void): (caller: string, message: string, team: string, taskId: string, res: ServerResponse) => boolean;
+export {};

package/lib/types/index.d.ts

@@ -191,11 +191,19 @@ export interface Config {
     /** 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).
+     * 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[];
-    /** S3 (queued): team-scoped routing admission. Enforcement off by default. */
+    /**
+     * 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

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,35 @@
+/**
+ * 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;
+    missAt?: number;
+}

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

@@ -53,7 +53,7 @@ export type TaskStatus = 'pending' | 'dead';
 /** F5 layer-3: why a dead row aged out (stamped by the sweep at flip time). */
 export type DeadReason = 'fire-forget' | 'unconsumed';
 /** gh#31: which archive path ended a row — a receipt, a content echo, or the caller. */
-export type ArchiveEnd = 'receipt' | 'echo' | 'abandoned' | 'cancelled';
+export type ArchiveEnd = 'receipt' | 'echo' | 'abandoned' | 'cancelled' | 'evicted';
 /** One tracked outbound task still in the owed book (unsettled). */
 export interface TaskRecord {
     readonly taskId: string;
@@ -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
@@ -317,6 +323,14 @@ export declare class TaskLedger {
     resolveEcho(message: string): string[];
     /** Move one settled record to the archive head, trimming at the cap. */
     private archiveSettled;
+    /**
+     * gh#86 (chief order direct-4f596524): when the owed book exceeds
+     * TASK_CAP, the overflow rows go to the ARCHIVE as evicted - visible
+     * for audit, never silently dropped. The review seat's recommendation,
+     * chief-endorsed: the silent cap slice lost the oldest pending rows
+     * with no trace. L8 criterion: zero silently-dropped.
+     */
+    private trimOwed;
     /** Lazy dead-letter sweep: overdue pending rows flip status, at most once. */
     private sweep;
     /** Load a persisted snapshot on construction, if present. */