@nelsonlongxiang/dsh-open-a2a-net 0.6.31 → 0.6.32

package/lib/types/node-self.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Node self-update (docs/design/node-identity.md §6; slice N4): the
+ * `node_update_self` tool a session carrying a node may call to write ONE
+ * section of its node's mutable layer, and the human review queue.
+ *
+ * - Only bound sessions get the tool (it is registered with the node's
+ *   sections at mount). Its parameters cannot name, role, team or touch the
+ *   core layer: one of the four mutable sections, text, reason, CAS sha.
+ * - Session-level taint (§6, H2; owner ruling 2026-11-03 「会话级污染」, which
+ *   reads §9's `via != host-face` as "this session has received input from
+ *   outside this host"): once a session has, every self-update it makes is
+ *   parked in the review queue, where a human approves or rejects it through
+ *   the apiKey-gated nodes face. Either of two signals taints:
+ *   1. the host marks the session when it DELIVERS remote content into it
+ *      (every relay steer and the queue-mode nudge — {@link SessionTaint});
+ *      the mark is persisted and never cleared;
+ *   2. a scan of the session's whole event log (fail-closed backstop): an
+ *      `a2a-relay` message that is not a host-built node reminder, a `user`
+ *      message whose controller rpcId starts with `a2a-` (this plugin's
+ *      nudge), or any source kind not known here. Context the agent loop
+ *      injects (runtime/time/skill/tool-job notices…) is neutral.
+ *   3. this plugin's own A2A tools that hand the model peer-originated text
+ *      (any route answer — a reply or an error —, inbound task briefs, peer
+ *      card rows — {@link toolTaint}) mark the calling session when they return.
+ *   Messages that carry ANOTHER session's text (a subagent's closing message,
+ *   a peer agent's message, a referenced transcript) take that session's
+ *   taint, so a subagent that talked to a peer cannot launder its reply.
+ *   Only remote EVIDENCE is persisted (a relay, a nudge, a tainted other
+ *   session, an A2A tool read); an unknown source, an unknown sender or a log
+ *   with no person's input refuses this one call (fail-closed) without
+ *   marking, so a host feature this module does not know yet never taints a
+ *   session forever.
+ *   The boundary, stated honestly: remote text the model reads through
+ *   general tools (a fetched page, an issue body) is not a delivery and does
+ *   not taint; nor can a `kind:'user'` prompt another plugin submits through
+ *   the session controller be told apart from a person (only this plugin's
+ *   nudge, rpcId `a2a-*`, is recognised).
+ * - Daily cap: at most {@link SELF_UPDATE_DAILY_MAX} node writes per node
+ *   per UTC day; beyond that the call is refused (not queued).
+ * - Each write freezes a full mutable version through the store (quota,
+ *   CAS, max+1), attributed `by: node:<session>`, `via: node-tool`; the
+ *   session's frozen prompt does not change — the write is echoed in a live
+ *   runtime context instead (§5).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/node-self
+ */
+import { type NodeResult, type NodeStore, type PromptVersion } from './node-store.ts';
+export declare const SELF_UPDATE_DAILY_MAX = 8;
+/** Queued writes awaiting a human, across all nodes. */
+export declare const REVIEW_QUEUE_MAX = 64;
+/** Queued writes per node: a tainted session cannot crowd out every other node's items. */
+export declare const REVIEW_PER_NODE_MAX = 8;
+/** What the log scan may ask about OTHER sessions. */
+export interface SessionLookups {
+    /** Whether that session is marked tainted. */
+    readonly tainted: (session: string) => boolean;
+    /** Whether that id is a session of this host the plugin knows (a live or joined root). */
+    readonly local: (session: string) => boolean;
+}
+/** Host-only marker routeTrunk puts on a route result it built from this host alone (a symbol: no peer JSON can carry it). */
+export declare const LOCAL_ROUTE: unique symbol;
+/** Mark a route result as built on this host alone (host refusals, host-built delivery notes, a clean local session's reply). */
+export declare function localRoute<T extends object>(value: T): T;
+/**
+ * gh#198 (owner ruling 2026-11-03 「按建议判据做」): whether one of this plugin's A2A tools just handed the
+ * model content that came from outside this host — a route that reached (or tried) a peer, inbound task
+ * rows, a directory row that is not this host's, a status/probe that names peers. A result built from
+ * this host's own facts alone is not remote. `a2a_route` reads the host-written `peer_content` flag the
+ * tool sets last (so a peer reply cannot set it); anything else defaults to remote.
+ */
+export declare function peerContentOf(name: string, value: unknown): boolean;
+/**
+ * The via to mark the calling session with after one of the A2A tools returned, or '' when its result
+ * carries nothing from outside this host ({@link peerContentOf}).
+ */
+export declare function toolTaint(name: string, value: unknown): string;
+/** The `tool/result` meta the A2A tools persist, so the log backstop reads the same verdict ({@link sessionSource}). */
+export declare const peerContentMeta: (name: string) => (_args: unknown, value: unknown) => {
+    a2aPeerContent: boolean;
+};
+/**
+ * The event-log backstop of the session taint: whether ANY input in the session's log came from
+ * outside this host. A node reminder is local only when the HOST built it (`nodeReminder: true` on an
+ * `a2a-relay` source — remote deliveries are relayed by this host with a fixed source shape, so a
+ * remote caller cannot set that field). A session with no person's input at all is not local either.
+ */
+export declare function sessionSource(events: readonly unknown[], others?: SessionLookups): {
+    local: true;
+} | {
+    local: false;
+    via: string;
+    evidence: boolean;
+};
+/** Sessions remembered as tainted; the oldest beyond this are forgotten (a forgotten one re-taints from its log or next delivery). */
+export declare const TAINT_CAP = 4096;
+/**
+ * The persisted half of the session taint (`node-taint.json`): the host marks a session the moment it
+ * delivers remote content into it, and the mark is never cleared. A file that does not parse is kept
+ * in place and read-only, and then EVERY session reads as tainted (fail-closed).
+ */
+export declare class SessionTaint {
+    private readonly root;
+    private readonly now;
+    private rows;
+    private readOnlyReason;
+    constructor(root: string, now?: () => string);
+    private get file();
+    private restore;
+    get readOnly(): string;
+    /** Why a session is tainted ('' = it is not). Fail-closed while the file is unreadable. */
+    of(session: string): string;
+    /** Mark a session (idempotent). Never throws; a mark that cannot be written still holds in memory. */
+    mark(session: string, via: string): void;
+}
+export interface ReviewItem {
+    readonly id: string;
+    readonly node: string;
+    readonly section: string;
+    readonly text: string;
+    readonly reason: string;
+    readonly expected_sha256: string;
+    readonly session: string;
+    /** Why it was parked: the remote source kind of the turn. */
+    readonly via: string;
+    readonly at: string;
+}
+/** The human review queue for remote-turn self-updates (`node-review.json`; corrupt = kept in place, read-only). */
+export declare class NodeReviewQueue {
+    private readonly root;
+    private readonly now;
+    private items;
+    private readOnlyReason;
+    constructor(root: string, now?: () => string);
+    private get file();
+    private restore;
+    private commit;
+    get readOnly(): string;
+    list(node?: string): readonly ReviewItem[];
+    get(id: string): ReviewItem | undefined;
+    /**
+     * Queue one write. A newer proposal for the same node, section and session REPLACES the older one
+     * (the human reviews the latest wish, not a backlog of drafts); the text must fit the section quota;
+     * each node holds at most {@link REVIEW_PER_NODE_MAX} items and the queue {@link REVIEW_QUEUE_MAX}.
+     */
+    add(input: Omit<ReviewItem, 'id' | 'at'>): NodeResult<ReviewItem>;
+    remove(id: string): NodeResult<true>;
+    /** A node archived: its pending items go with it. */
+    dropNode(node: string): void;
+}
+/** Node writes (`by: node:…`) frozen for `node` on the UTC day of `now`. */
+export declare function nodeWritesToday(store: NodeStore, node: string, now: string): number;
+export interface SelfUpdateDeps {
+    readonly store: NodeStore;
+    readonly queue: NodeReviewQueue;
+    /** The persisted session taint (marked at remote deliveries). */
+    readonly taint: SessionTaint;
+    /** The calling session's event log (the taint's fail-closed backstop). */
+    readonly events: (agent: unknown) => readonly unknown[];
+    /** Whether an id is a session of this host the plugin knows (for messages naming another session). */
+    readonly localSession?: (session: string) => boolean;
+    readonly now?: () => string;
+    /** A write went through (the binder echoes it in the session's live context). */
+    readonly onWritten: (session: string, version: PromptVersion, section: string) => void;
+}
+export type SelfUpdateResult = {
+    ok: true;
+    version: number;
+    sha256: string;
+} | {
+    ok: false;
+    error: string;
+    queued?: string;
+    code?: string;
+    current_sha256?: string;
+};
+/** One self-update call, decided. Pure over its deps (the tool below only adapts it). */
+export declare function selfUpdate(d: SelfUpdateDeps, node: string, session: string, agent: unknown, args: Record<string, unknown>): SelfUpdateResult;
+/** The tool registered on a bound session's own scope. */
+export declare function selfUpdateTool(d: SelfUpdateDeps, node: string, session: string): import("@deepseek-ai/dsh-tools").ToolDefinition;

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

@@ -0,0 +1,180 @@
+/**
+ * Node identity store (docs/design/node-identity.md, slice N1): long-lived,
+ * human-named nodes that a session can carry, with layered prompt versions.
+ *
+ * - `nodes.json` under the a2a home holds the node records and the retired
+ *   names (a name is never reused, and never renamed — §8-1).
+ * - Prompt layers live in two namespaces, append-only:
+ *   `nodes/<name>/core-v<n>.json` (the immutable layer, humans only) and
+ *   `nodes/<name>/mutable-v<n>.json` (the four-section mutable layer).
+ *   Every version is a FULL snapshot; the next number is max+1 over the
+ *   files on disk, so a write after a rollback never collides; a write must
+ *   name the sha it expects to replace (CAS — parallel sessions of one node).
+ * - Identity writes (create / update / archive / core / rollback) are
+ *   gated by the caller (the nodes face requires apiKey even on loopback,
+ *   §8-2); this module only validates shapes and keeps the chain closed.
+ * - Never-reuse survives a lost roster: create makes the node's version
+ *   directory at once, and a name with a directory counts as used. A roster
+ *   that does not parse, or parses into the wrong shape, is copied to
+ *   `nodes.json.corrupt-<ts>` and LEFT IN PLACE; the store is READ-ONLY for
+ *   as long as it stays unreadable (every restart), so it is never silently
+ *   overwritten. Entries dropped as malformed are backed up first
+ *   (`nodes.json.dropped-<ts>`). Writes go to disk first (tmp + rename) and
+ *   only then into memory.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/node-store
+ */
+/** §8-1: node names. */
+export declare const NODE_NAME: RegExp;
+/** Upper bound on live nodes per host (a roster, not a database). */
+export declare const NODE_CAP = 64;
+/** The four mutable sections, in prompt order (§5). */
+export declare const MUTABLE_SECTIONS: readonly ["当前状态", "执行要点", "已知陷阱", "当前重点"];
+export type MutableSection = typeof MUTABLE_SECTIONS[number];
+/** §8-9 quotas, in characters (code points, not UTF-16 units). */
+export declare const QUOTA: {
+    readonly core: 2000;
+    readonly mutable: 3000;
+    readonly mutableSection: 1000;
+};
+export type Layer = 'core' | 'mutable';
+export interface NodeCarrier {
+    /** Checkout the node's sessions run in (session controller create). */
+    readonly cwd: string;
+    /** Agent preset id; '' = the host default. */
+    readonly agentPreset: string;
+    /** Model selection; '' = the preset's default. */
+    readonly model: string;
+}
+export interface NodeRecord {
+    readonly name: string;
+    readonly label: string;
+    readonly role: readonly string[];
+    readonly teams: readonly string[];
+    readonly carrier: NodeCarrier;
+    readonly prompt: {
+        readonly core_version: number;
+        readonly core_sha256: string;
+        readonly mutable_version: number;
+        readonly mutable_sha256: string;
+    };
+    readonly created_by: string;
+    readonly created_at: string;
+}
+/** One frozen prompt version (either namespace). */
+export interface PromptVersion {
+    readonly layer: Layer;
+    readonly version: number;
+    /** sha256 over the canonical JSON of {version, sections}. */
+    readonly sha256: string;
+    readonly parent_version: number;
+    /** core: {'core': text}; mutable: the four sections. Always the full layer. */
+    readonly sections: Readonly<Record<string, string>>;
+    readonly changed: readonly string[];
+    readonly reason: string;
+    readonly by: string;
+    readonly via: string;
+    readonly at: string;
+    readonly rollback_of?: number;
+}
+export type NodeErrorCode = 'bad-request' | 'not-found' | 'conflict' | 'quota' | 'cap' | 'unavailable';
+export type NodeResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+    code: NodeErrorCode;
+};
+/** The sha a version is pinned by: canonical JSON of {version, sections} (keys sorted). */
+export declare function promptSha(version: number, sections: Readonly<Record<string, string>>): string;
+/**
+ * Node store. One writer (the nodes face); read fresh by the state face.
+ */
+export declare class NodeStore {
+    private readonly now;
+    private nodes;
+    private retired;
+    private readonly root;
+    /** Set when the roster on disk could not be read: identity writes are refused until a human repairs it. */
+    private readOnlyReason;
+    /** Roster entries dropped on load (malformed), for the face to report. */
+    readonly dropped: string[];
+    /**
+     * @param root - the `<home>/a2a` directory; '' keeps everything in memory (tests).
+     * @param now - clock seam (ISO timestamps).
+     */
+    constructor(root: string, now?: () => string);
+    private get file();
+    private versionDir;
+    private restore;
+    /** Disk first (tmp + rename), memory after — a failed write leaves both as they were. */
+    private commit;
+    /** Identity writes are refused while the roster is read-only. */
+    private writable;
+    /** Why the store refuses writes ('' when it does not). */
+    get readOnly(): string;
+    /** Names reserved in memory mode (root ''), standing in for the version directory. */
+    private readonly memReserved;
+    /** A name is used when it is live, retired, or has a version directory (created with the node, so it survives a lost roster). */
+    private nameUsed;
+    private readonly memVersions;
+    private versionNumbers;
+    private writeVersion;
+    /** One frozen version, or undefined. */
+    version(name: string, layer: Layer, version: number): PromptVersion | undefined;
+    /**
+     * The version a node's record pins for `layer`, only when it is well-formed AND its sha is the one
+     * the record pins — a hand-edited or swapped version file reads as absent, never as prompt text.
+     * undefined for an unknown node, a layer never written (version 0), or a file that fails either check.
+     */
+    current(name: string, layer: Layer): PromptVersion | undefined;
+    /**
+     * A specific version a live session froze at mount (#174: a plugin reload re-mounts at it). The pinned
+     * current version goes through {@link current} (the roster's sha); an older one must be well-formed,
+     * carry its own number, AND match the sha the mount recorded — the outside anchor a hand-edited file
+     * that recomputed its own sha cannot also fake. undefined when any check fails (the caller falls back).
+     */
+    frozen(name: string, layer: Layer, version: number, sha: string): PromptVersion | undefined;
+    /** Version numbers present for one layer, ascending. */
+    versions(name: string, layer: Layer): number[];
+    list(): readonly NodeRecord[];
+    get(name: string): NodeRecord | undefined;
+    /** Create a node (identity write). The name is final and never reused. */
+    create(input: {
+        name?: unknown;
+        label?: unknown;
+        role?: unknown;
+        teams?: unknown;
+        carrier?: unknown;
+    }, by: string): NodeResult<NodeRecord>;
+    /** Update label / role / teams / carrier (identity write). There is no rename. */
+    update(name: string, input: {
+        name?: unknown;
+        label?: unknown;
+        role?: unknown;
+        teams?: unknown;
+        carrier?: unknown;
+    }): NodeResult<NodeRecord>;
+    /** Archive a node (identity write): it leaves the roster, its name is retired, its versions stay on disk. */
+    archive(name: string): NodeResult<string>;
+    private fields;
+    /**
+     * Freeze a new version of one layer. `sections` is the FULL layer for
+     * core (`{core: text}`) and a PATCH for mutable (the named sections
+     * replace their text; the rest carry over). `expectedSha` must equal the
+     * layer's current sha ('' while the layer has no version yet).
+     */
+    writeLayer(name: string, layer: Layer, sections: unknown, meta: {
+        expectedSha?: unknown;
+        reason?: unknown;
+        by: string;
+        via: string;
+    }): NodeResult<PromptVersion>;
+    /** Roll a layer back (identity write): freezes a NEW version whose content is the target's. */
+    rollback(name: string, layer: Layer, to: unknown, meta: {
+        expectedSha?: unknown;
+        reason?: unknown;
+        by: string;
+    }): NodeResult<PromptVersion>;
+    private freeze;
+}

package/lib/types/node-tasks.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Node task pointers (docs/design/node-identity.md §2 "任务指针", §5 task context, §6; slice N6).
+ *
+ * - A pointer is `owner/repo#n` plus a CACHED state — GitHub is the truth
+ *   (`open` / `merged` / `closed` / `declined`; `unknown` until a check
+ *   answers). Each records the node's `core_version` and `mutable_version`
+ *   when it was tracked (§6 归因).
+ * - Kept in `node-tasks.json` under the a2a home, beside the roster rather
+ *   than inside it: a cache that changes on every check must not rewrite
+ *   the identity roster. The newest 64 per node stay — finished pointers are
+ *   evicted before open ones — and evicted ones are appended to
+ *   `node-tasks-archive.jsonl`.
+ * - Checks: once when a pointer is tracked, a full pass right after the
+ *   plugin loads, and a full pass every 12 hours. Finished pointers are not
+ *   re-checked (a re-opened issue keeps reading finished — the cost of not
+ *   polling finished work). One check per ref at a time; a finished state
+ *   is never walked back to open by a late answer. A probe that cannot
+ *   answer marks the check `unknown` and keeps the last known state.
+ * - Reminder (§6 主触发): a pointer that finished AFTER it was tracked —
+ *   it was `open` here, or GitHub's merged_at / closed_at is later than
+ *   `since` — calls `onSettled` once. A pointer that finished before it
+ *   was tracked, or whose finish time cannot be told, does not remind; an
+ *   unknown state never does. A reminder that reached no session (a cold
+ *   host boot: the load-time pass runs before any session is live) is kept
+ *   as `remind_pending` and handed out the next time the node mounts on a
+ *   session (`takePending`), so a merge during downtime is not swallowed.
+ *   The finish-time comparison trusts the host clock; skew of a few minutes
+ *   can add or drop a reminder for a pointer whose first check failed.
+ * - After the plugin unloads (`dispose`), a check still in flight neither
+ *   writes nor reminds: a newer instance owns the file by then.
+ * - A file that does not parse is left in place and the table is read-only;
+ *   malformed rows are backed up before the next write drops them (as the
+ *   roster and the bindings table do).
+ * @module @nelsonlongxiang/dsh-open-a2a-net/node-tasks
+ */
+import { type GithubProbe, type TaskState } from './node-github.ts';
+import type { NodeResult } from './node-store.ts';
+export declare const TASK_KEEP = 64;
+/** §5: the task context is generated, so it is truncated (not refused) at this many characters. */
+export declare const TASKS_CONTEXT_MAX = 1500;
+/** §6 / §8-8: the full check runs twice a day. */
+export declare const TASKS_CHECK_MS: number;
+export interface TaskPointer {
+    readonly ref: string;
+    readonly state: TaskState | 'unknown';
+    /** Whether the last check answered ('ok') or could not ('unknown': no credential, offline, …). */
+    readonly check: 'ok' | 'unknown' | 'pending';
+    readonly since: string;
+    readonly checked_at: string;
+    readonly core_version: number;
+    readonly mutable_version: number;
+    readonly by: string;
+    /** A reminder is owed: it finished, but no live session carried the node at the time. */
+    readonly remind_pending?: true;
+}
+/** The §6 reminder for a pointer that finished. */
+export declare function settledReminder(p: TaskPointer): string;
+/** The part of a Cordis context the table schedules on. */
+export interface TaskSchedule {
+    readonly timer: {
+        interval(cb: () => void, ms: number): unknown;
+        timeout(cb: () => void, ms: number): unknown;
+    };
+    effect(execute: () => () => void, label?: string): unknown;
+}
+export interface NodeTasksDeps {
+    readonly probe: GithubProbe;
+    readonly logger: {
+        warn: (format: string, ...args: unknown[]) => void;
+    };
+    /** A pointer finished after it was tracked (§6 主触发); returns how many sessions got the reminder. */
+    readonly onSettled: (node: string, pointer: TaskPointer) => number;
+    readonly now?: () => string;
+}
+export declare class NodeTasks {
+    private readonly root;
+    private readonly d;
+    private table;
+    private readOnlyReason;
+    private running;
+    private readonly inflight;
+    /** Owed reminders already handed out by this process: a clear that could not be written must not repeat at every mount. */
+    private readonly handedOut;
+    private disposed;
+    private readonly now;
+    /** @param root - the `<home>/a2a` directory; '' keeps the table in memory (tests). */
+    constructor(root: string, d: NodeTasksDeps);
+    private get file();
+    private stamp;
+    private restore;
+    private commit;
+    get readOnly(): string;
+    list(node: string): readonly TaskPointer[];
+    /**
+     * Run the checks on the plugin's context: one full pass right after load (a restart within 12 hours
+     * would otherwise never check), one every 12 hours, and stop writing once the plugin unloads.
+     */
+    schedule(ctx: TaskSchedule): void;
+    /** Track a pointer at the node's current versions; checks it once in the background. Re-tracking is a no-op. */
+    track(node: string, ref: unknown, versions: {
+        core: number;
+        mutable: number;
+    }, by: string): NodeResult<TaskPointer>;
+    untrack(node: string, ref: unknown): NodeResult<true>;
+    /** An archived node's pointers move to the archive file. */
+    dropNode(node: string): void;
+    /** Check one pointer now; joins a check of the same pointer already in flight. Never throws. */
+    check(node: string, ref: string): Promise<void>;
+    private checkOnce;
+    private setPending;
+    /**
+     * The reminders owed to `node`, cleared as they are handed out (one session gets each). A clear that
+     * cannot be written still hands them out, once per process — a reminder may then repeat after a restart,
+     * never vanish.
+     */
+    takePending(node: string): TaskPointer[];
+    /** The full pass: every pointer not yet finished, one at a time. A pass already running is joined. */
+    checkAll(): Promise<void>;
+    /** §5 task context: open first, then newest; truncated (never refused) at {@link TASKS_CONTEXT_MAX}. '' when none. */
+    render(node: string): string;
+}

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

@@ -0,0 +1,119 @@
+/**
+ * OriginClaim envelope (gh#9+gh#10, docs/protocol/delivery-origin-auth.md):
+ * the signer every outbound peer request stamps and the verifier every peer
+ * face (card, /a2a/direct, /a2a/log, /a2a/canvas-op, /a2a/canvas-changed)
+ * runs.
+ *
+ * Two canonical forms ride the same four base headers
+ * (X-A2A-Caller / -Url / -Ts):
+ *   · bound (v2, §2.1): JSON.stringify([tag, caller, callerUrl, ts,
+ *     audience, METHOD, path]) in X-A2A-Caller-Sig2, the audience origin in
+ *     X-A2A-Caller-Aud. The verifier requires the audience to be one of its
+ *     own origins and signs-over its own method and path, so an envelope is
+ *     good at exactly the host and route it was made for.
+ *   · unbound (v1, legacy): JSON.stringify([caller, callerUrl, ts]) in
+ *     X-A2A-Caller-Sig. Emitted and accepted only while the unbound window
+ *     is open (originClaimUnboundWindow); accepted ones are counted.
+ * Once the window closes a present Sig2 is the only thing verified. While
+ * it is open, a Sig2 that misses (audience or signature) falls back to the
+ * Sig the envelope also carries — no more than stripping Sig2 would give —
+ * and the miss is counted, so a peer dialled by an unlisted name keeps
+ * working through the rollout and shows on the gauge.
+ */
+import { type KeyObject } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+import type { A2aFetch } from './a2a-client.ts';
+import type { CardCacheEntry } from './runtime.ts';
+import type { A2aPeerCard } from './types.ts';
+/** ts skew tolerance (protocol constant, §7). */
+export declare const ORIGIN_CLAIM_SKEW_MS: number;
+/** Domain tag of the bound form: a v1 signature can never verify as v2. */
+export declare const ORIGIN_CLAIM_BOUND_TAG = "a2a-origin-claim/2";
+/** Where an outbound request goes: the bound form signs both. */
+export interface OriginClaimTarget {
+    readonly url: string;
+    readonly method: string;
+}
+export type OriginClaimRefusal = 'absent' | 'bad-caller-shape' | 'bad-ts' | 'no-card' | 'bad-sig' | 'not-derivable' | 'wrong-audience' | 'unbound-closed';
+/** Only the canonical origin root can claim that origin's identity. */
+export declare function isRootOriginUrl(value: string): boolean;
+/**
+ * #189 follow-up: whether a path-prefixed claim URL is EXACTLY a peer URL the operator seeded (a
+ * mounted card endpoint, delivery-origin-auth §"挂载卡片端点"): same origin and same path (trailing
+ * slashes ignored), neither carrying userinfo, query or fragment. A different path under the same
+ * origin is a different publisher and never matches.
+ */
+export declare function sameMountedUrl(seeded: string, claimUrl: string): boolean;
+export type OriginClaimVerdict = {
+    ok: true;
+    caller: string;
+    callerUrl: string;
+    card: A2aPeerCard;
+    bound: boolean;
+    cli?: true;
+} | {
+    ok: false;
+    reason: OriginClaimRefusal;
+};
+/** The unbound (v1) canonical form. */
+export declare function unboundCanonical(caller: string, callerUrl: string, ts: number): string;
+/** The bound (v2) canonical form; method upper-cased, path without query. */
+export declare function boundCanonical(caller: string, callerUrl: string, ts: number, audience: string, method: string, path: string): string;
+/** An origin in URL's normal form, or '' when the text is not an http(s) URL. */
+export declare function originOf(url: string): string;
+/** The path a request names, without its query (the bound form signs this). */
+export declare function pathOf(url: string): string;
+/**
+ * Sign one envelope for `target`. The bound form is always present; the
+ * unbound one only while `unbound` (the window) is open, so an upgraded
+ * host stops signing the unbound form the moment it closes.
+ */
+export declare function signOriginClaim(target: OriginClaimTarget, signer: {
+    readonly caller: string;
+    readonly callerUrl: string;
+    readonly privateKey: KeyObject;
+    readonly unbound: boolean;
+    readonly now: number;
+}): Record<string, string>;
+/**
+ * The origins this host answers to for one request: the configured ones
+ * (own card URL, operator aliases) plus the address the request actually
+ * arrived on — the socket's LOCAL end, which a sender cannot choose (unlike
+ * the Host header). A loopback arrival answers to all its loopback
+ * spellings — unless `loopbackArrival` is off (originClaimUrl declares a
+ * tunnel or proxy, whose requests all arrive on loopback), and then only
+ * when a configured origin is loopback at that port.
+ */
+export declare function requestAudiences(req: IncomingMessage, configured: readonly string[], loopbackArrival?: boolean): Set<string>;
+/**
+ * gh#133: a CLI identity deposited on the verifying host — the full handle,
+ * the bare name it signs as, and its deposited card (undefined when the
+ * deposit no longer verifies).
+ */
+export interface CliDepositCard {
+    readonly handle: string;
+    readonly name: string;
+    readonly card: A2aPeerCard | undefined;
+}
+/**
+ * Verify one request's envelope. Cheap refusals (shape, ts, audience,
+ * closed window) answer before any card fetch; the card is then read from
+ * the shared cache or fetched PLAIN from the caller's well-known URL.
+ */
+export declare function verifyOriginClaim(req: IncomingMessage, d: {
+    readonly cardCache: Map<string, CardCacheEntry>;
+    readonly fetch: A2aFetch;
+    /** This host's configured origins (own card URL, operator aliases). */
+    readonly audiences: readonly string[];
+    /** The unbound window: accept a Sig-only (v1) envelope. */
+    readonly unboundOpen: boolean;
+    /** Count one accepted unbound envelope (the drain gauge). */
+    readonly onUnbound: () => void;
+    /** Count one bound form that missed and fell back to the unbound one. */
+    readonly onBoundMiss?: () => void;
+    /** A loopback arrival is an audience of its own (default); off when originClaimUrl declares a tunnel or proxy. */
+    readonly loopbackArrival?: boolean;
+    readonly now: number;
+    /** On the faces that admit CLI identities: the deposit a claim URL names. */
+    readonly cliDeposit?: (callerUrl: string) => CliDepositCard | undefined;
+}): Promise<OriginClaimVerdict>;

package/lib/types/peer-directory.d.ts

@@ -0,0 +1,39 @@
+import type { A2aPeerCard } from './types.ts';
+import type { DirectoryTeamRow } from './tools/info.ts';
+type CanvasEntry = NonNullable<A2aPeerCard['canvasOrg']>[number];
+/** Only this card's own valid canvas namespace may name its teams. */
+export declare function advertisedCanvasTeams(card: A2aPeerCard): CanvasEntry[];
+/** Match a session claim without treating another zone's canvas as a session. */
+export declare function sessionCandidateMatches(card: A2aPeerCard, team: string): boolean;
+/** Match a scoped caller to this peer's canvas before sending the payload. */
+export declare function canvasCandidateMatches(card: A2aPeerCard, team: string, caller?: {
+    id: string;
+    handle: string;
+}, resolveLocal?: (ref: string) => string | undefined): boolean;
+/** A naked team string is unsafe when both a canvas and another face claim it. */
+export declare function canvasTargetAmbiguous(cards: readonly (A2aPeerCard | undefined)[], team: string, caller: {
+    id: string;
+    handle: string;
+} | undefined, resolveLocal: ((ref: string) => string | undefined) | undefined, hasDelegation: boolean): boolean;
+/**
+ * Existing peer rows plus optional canvas rows for the model-tool directory.
+ * The GUI's remote-node rows call with includeCanvas=false, so a group is
+ * never rendered as an extra session node. Membership is carried only as an
+ * internal scope hint and stripped before the tool's public result.
+ */
+export declare function peerDirectoryRows(card: A2aPeerCard, peer: string, includeCanvas: boolean): DirectoryTeamRow[];
+/**
+ * Whether one caller label can receive network traffic back. Composite
+ * `<zone>/<id>` shapes route anywhere (N1); bare zone names resolve to a
+ * live initiator per host, so cross-host they would steer whichever node
+ * shares the name — treated as unroutable everywhere.
+ */
+export declare function routableCallerLabel(callerSession: string | undefined): boolean;
+/**
+ * Why an async route from such a caller cannot expect its receipt: the
+ * autosend arm skips it and the steered hint is omitted, so the debt has
+ * no paying path — say so at dispatch time instead of silently stranding
+ * a pending row.
+ */
+export declare function unroutableCallerNote(label: string): string;
+export {};

package/lib/types/receipt.d.ts

@@ -11,6 +11,11 @@
  * open with a brace can never be mistaken for machine payloads.
  * @module @nelsonlongxiang/dsh-open-a2a-net/receipt
  */
+/**
+ * Refusal text for an unusable task id, or undefined when the id is fine.
+ * Both delivery paths (wire face, local candidate) refuse at intake.
+ */
+export declare function taskIdRefusal(taskId: string): string | undefined;
 /** The network's fixed, case-sensitive correlation template. */
 export declare const RECEIPT_PATTERN: RegExp;
 /** Controlled outcome vocabulary — the ONLY branchable field of an envelope. */
@@ -22,6 +27,13 @@ export interface ReceiptEnvelopeV2Fields {
     idempotencyKey?: string;
     sessionKey?: string;
     elapsedMs?: number;
+    /**
+     * #114 S5: the session a host-synthesized receipt speaks for (the host is
+     * only its courier). Additive: parsers that predate it ignore it.
+     */
+    onBehalfOf?: string;
+    /** #114 S5: 16-hex ref of the inbound authorization record (task-auth.ts authorizationRef); audit only. */
+    authRef?: string;
 }
 export interface ParsedReceipt {
     /** Correlation key from the immutable header. */