super-dsh 0.1.6 → 0.1.9

package/superd-hub/dist/a2a-log.js

@@ -0,0 +1,42 @@
+// Operational journal for the A2A/mesh surface (0.1.7-b headliner; the
+// 2026-09-29 first-person field pass found the hub emits ZERO journal lines
+// — every field question forced registry forensics). One line per machine
+// event, greppable `a2a.<event>` vocabulary, no secrets (messageIds and
+// session/conversation ids only — never envelope bodies, never cookies).
+//
+// The pure modules (a2a-service/a2a-ingest) stay runtime-agnostic: they take
+// an optional A2aLogFn and only FORMAT lines; the cordis host (a2a-row.ts)
+// wires it onto ctx.logger so lines land in the unit journal (4999 rig /
+// dev3 dsh.service). Tests inject a collector.
+/**
+ * Render one journal-friendly line: `superd-hub: a2a.<event> k=v k=v`.
+ * Values are quoted (JSON) only when they contain whitespace, so the common
+ * case stays grep-friendly: `a2a.completion.transcript conversation=abc123 bytes=42`.
+ */
+export function formatA2aLogLine(event, fields = {}) {
+    const parts = [`superd-hub: a2a.${event}`];
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined)
+            continue;
+        const text = String(value);
+        parts.push(`${key}=${/\s/.test(text) ? JSON.stringify(text) : text}`);
+    }
+    return parts.join(' ');
+}
+/**
+ * The host wiring both rows share: level → process console. NOT ctx.logger —
+ * the pack composes no cordis logger-console exporter, so LoggerService
+ * records go nowhere (verified live 2026-09-29); console matches the
+ * world-join / world-provision precedent and lands in every unit log.
+ */
+export function consoleA2aLog() {
+    return (level, event, fields) => {
+        const line = formatA2aLogLine(event, fields);
+        if (level === 'warn')
+            console.warn(line);
+        else if (level === 'error')
+            console.error(line);
+        else
+            console.log(line);
+    };
+}

package/superd-hub/dist/a2a-row.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `super-dsh/a2a` — the SuperD Hub TOOL row (mesh P3 Task 4, spec §9):
+ * composes the single model-facing `superd-hub` tool onto ctx0's `tools`
+ * service and closes T3's `nativeGateway` seam with the hub process's OWN
+ * in-process session-plane gateway.
+ *
+ * WHY A SUBPATH ROW (documented ruling, not riding the bare `superd-hub`
+ * row): world trees compose the `superd-hub` row too (world-mount.ts
+ * `WORLD_HUB_ROW`) and they DO provide a `tools` service (the base web-app
+ * composition's `tools` row is not in the wave-1/wave-2 disable lists) — so
+ * riding gateway.ts's apply would register a mis-wired A2A tool inside every
+ * world (its `nativeGateway` would be THAT WORLD's typertGateway, while the
+ * 'native' a6 belongs to ctx0's agent). The pack's precedent for an
+ * explicitly-composed capability is the subpath row (web-trust,
+ * fusion-transport — "composing this row IS the switch"): this row lives
+ * only in the pack's own cordis.patch.yml, which world profiles never
+ * compose (world-provision.ts `WORLD_BASE_BUNDLES`), so it mounts in ctx0
+ * only — exactly the P3 initiator surface (native DSH sessions; foreign
+ * runtimes get their own injection in P5, spec §10). Individually
+ * toggleable per the pack's row discipline.
+ *
+ * Dormancy (better-dash plugin.ts discipline): zero static injects; the
+ * dynamic `ctx.inject(['tools', 'typertGateway'])` keeps the row dormant —
+ * and side-effect-free — until BOTH the tool registry and ctx0's session
+ * plane exist. `tools.register` scopes the registration to the calling
+ * fiber, so the tool unregisters with the row.
+ *
+ * The stream-face bridge: T2's `A2aGateway` declares a 3-arg
+ * `openWireStream(endpoint, payload, signal)`, but a RAW typertGateway
+ * instance speaks the upstream canonical 6-arg order
+ * `openWireStream(endpoint, payload, uplink, peer, signal, control)`
+ * (dsh-api-gateway/src/index.ts:434; the 0.1.3-j lesson — positional
+ * misbinding strands streams forever). This row hands the RAW ctx0
+ * instance to `createA2aHost`. NOTE: T3's resolver hands LOCAL world rows
+ * from the shared target registry RAW (world-join.ts registers the instance
+ * verbatim) — fixed in round 1 (2026-09-28 review): the resolver now bridges
+ * ALL local rows + the native seam through the shared `bridgeTypertGateway`
+ * (a2a-host.ts), and FEDERATED wire adapters pass through unwrapped.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin (row) name. */
+export declare const name = "superd-a2a";
+/** Zero static injects — the tools/typertGateway legs are dynamic (dormancy). */
+export declare const inject: string[];
+/** Injection seam for tests: a tmpdir home instead of the ambient/prod DSH_HOME (rpc.ts discipline). */
+export interface HubToolRowOptions {
+    /** Hub home backing the registries; defaults to `resolveDshHome()` at wiring time. */
+    home?: string;
+}
+/**
+ * Wire the tool row: build T2+T3's service with ctx0's own gateway injected
+ * at the native seam, then register the `superd-hub` tool once the `tools`
+ * service and the session plane are both live.
+ * @param ctx - the hub host root context (ctx0).
+ * @param opts - optional home override (tests inject a tmpdir).
+ */
+export declare function wireHubToolRow(ctx: Context, opts?: HubToolRowOptions): void;
+/** MUST stay an arrow (RM0/better-dash note: function declarations get `new`-called, disposers lost). */
+export declare const apply: (ctx: Context) => void;
+declare const _default: {
+    name: string;
+    inject: string[];
+    apply: (ctx: Context) => void;
+};
+export default _default;

package/superd-hub/dist/a2a-row.js

@@ -0,0 +1,162 @@
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { createSuperdHubTool } from './hub-tool.js';
+import { createA2aIngest } from './a2a-ingest.js';
+import { statusSweepLegs, loadAgentStatus } from './agent-status.js';
+import { setSweepCollectors } from './mesh-link.js';
+import { consoleA2aLog } from './a2a-log.js';
+import { createA2aService } from './a2a-service.js';
+import { resolveA2aGatewayFor, localA2aInitiator } from './a2a-host.js';
+import { registerA2aRpc, registerExecRpc } from './mesh-rpc.js';
+import { runOneShotExec, postOneShotExec } from './exec.js';
+import { ensureSelf, listRemotes } from './machines.js';
+import { cookieOf } from './mesh-link.js';
+import { PtyPool } from './exec-pty-session.js';
+import { LocalScriptChannel, WsPtyChannel } from './exec-pty-channel.js';
+import { PTY_EXEC_PATH } from './exec-pty-rpc.js';
+import { agentLinks } from './agent-roster.js';
+/** Stable Cordis plugin (row) name. */
+export const name = 'superd-a2a';
+/** Zero static injects — the tools/typertGateway legs are dynamic (dormancy). */
+export const inject = [];
+/**
+ * Resolve one initiator's live agent handle. Read LAZILY at delivery time
+ * (`ctx.get`, no declaration): the registry's availability must not gate the
+ * row, and the runtime Agent object carries followup/steer/inject even though
+ * its public type surface says `{id}` (dsh-agent runtime-types.ts interface
+ * merge — compile-time only, one object at runtime; T3's A2aAgentHandle is
+ * its structural subset).
+ */
+function liveAgentHandle(ctx, sessionId) {
+    const registry = ctx.get('agents');
+    const agent = registry?.get(sessionId);
+    return agent === undefined || agent === null ? undefined : agent;
+}
+/** The default roster view over the hub home (the /api/agent-runtime facts). */
+function rosterViewOf(home) {
+    return {
+        self: ensureSelf(home, 'local'),
+        remotes: listRemotes(home).map((row) => ({ id: row.id, label: row.label !== '' ? row.label : row.name })),
+        agents: agentLinks(home),
+    };
+}
+/**
+ * Wire the tool row: build T2+T3's service with ctx0's own gateway injected
+ * at the native seam, then register the `superd-hub` tool once the `tools`
+ * service and the session plane are both live.
+ * @param ctx - the hub host root context (ctx0).
+ * @param opts - optional home override (tests inject a tmpdir).
+ */
+export function wireHubToolRow(ctx, opts = {}) {
+    const home = opts.home ?? resolveDshHome();
+    ctx.inject(['tools', 'typertGateway'], (t) => {
+        // RAW instance in, bridged at the resolver (fix round 1: one shared
+        // bridge in a2a-host.ts covers the native seam AND all local world rows).
+        const raw = t.get('typertGateway');
+        // postoffice R4: ONE resolver, ONE ingest, TWO consumers — the initiator
+        // service's self-routing leg calls the very same ingest handler the HTTP
+        // endpoint calls (protocol-identical by construction). The service takes
+        // a LAZY provider: the ingest's delivery face buffers through the
+        // service's own buffer leg, so it can only be built after the service.
+        const gatewayFor = resolveA2aGatewayFor({ home, nativeGateway: raw });
+        // Operational journal: the pure modules only format lines; this is
+        // where they meet the process console and land in the unit log (4999 rig
+        // / dev3 dsh.service journal). NOT ctx.logger: the pack composes no
+        // cordis logger-console exporter, so ctx.logger records go nowhere
+        // (verified live 2026-09-29 — zero a2a lines through a full envelope
+        // flow). Console matches the world-join/world-provision precedent for
+        // operational lines. One line per machine event, no secrets.
+        const alog = consoleA2aLog();
+        let ingestRef;
+        const service = createA2aService({ home, gatewayFor, ingest: () => ingestRef, log: alog });
+        const delivery = {
+            agents: { get: (sessionId) => liveAgentHandle(ctx, sessionId) },
+            buffer: (initiatorSessionId, message) => { service.buffer(initiatorSessionId, message); },
+        };
+        ingestRef = createA2aIngest({ home, gatewayFor, delivery, log: alog });
+        // postoffice R5: the sweep's dual-responsibility legs (outbox pull +
+        // session-list collection) over THIS assembly — registered process-level;
+        // gateway.ts's existing sweep timer picks them up (no second timer).
+        setSweepCollectors(statusSweepLegs({ home, gatewayFor, ingest: ingestRef }));
+        // the a2a endpoints (POST /api/superd/a2a + GET outbox) ride the shared
+        // /api fence like the machines route; registered on the same inject scope
+        // (they live and die with the typertGateway seam).
+        registerA2aRpc(t, ingestRef);
+        // P4: the exec endpoint rides the same shared /api fence (spec §8.1).
+        registerExecRpc(t, alog);
+        // P4 exec face: the local executing side + the wire leg over the pairing
+        // cookie. The initiator-side per-machine knob (execEnabled) is honored
+        // here, before any bytes leave (spec §5).
+        const execFace = {
+            selfM4: () => ensureSelf(home, 'local').id,
+            run: (input) => runOneShotExec(input, alog),
+            post: async (machineId, input) => {
+                const row = listRemotes(home).find((r) => r.id === machineId);
+                if (row === undefined)
+                    throw new Error(`unknown machine "${machineId}" — call agents for the roster`);
+                if (row.execEnabled === false)
+                    throw new Error(`exec is disabled for machine "${machineId}" on this registry row (execEnabled=false)`);
+                alog?.('info', 'exec.remote', { machine: machineId, cmd: input.cmd, timeoutSec: input.timeoutSec ?? 120 });
+                const result = await postOneShotExec(row.origin, input, { cookie: cookieOf(row.id, home) });
+                // F6 (first-person 0.1.7-d finding): the initiator side needs its own
+                // completion line — without it a remote result lives only in the tool
+                // response and the initiator's journal stays blind to the outcome.
+                alog?.('info', 'exec.remote.done', {
+                    machine: machineId,
+                    exit: result.exit ?? 'none',
+                    durationMs: result.durationMs,
+                    ...(result.outcome === 'exited' ? {} : { outcome: result.outcome }),
+                    ...(result.truncated ? { truncated: true } : {}),
+                });
+                return result;
+            },
+        };
+        // P4 §8.2 initiator half: the PTY pool. Session key = (calling DSH
+        // session, machine) — per-agent direct, no central allocation (D12).
+        const ptyPool = new PtyPool({ idleTtlSec: 600 });
+        ctx.effect(() => () => { void ptyPool.disposeAll(); }, 'superd-a2a: pty pool teardown');
+        const execPty = async (sessionKey, machine, cmd, opts = {}) => {
+            const channelOf = () => {
+                if (machine === ensureSelf(home, 'local').id)
+                    return new LocalScriptChannel();
+                const row = listRemotes(home).find((r) => r.id === machine);
+                if (row === undefined)
+                    throw new Error(`unknown machine "${machine}" — call agents for the roster`);
+                if (row.execEnabled === false)
+                    throw new Error(`exec is disabled for machine "${machine}" on this registry row (execEnabled=false)`);
+                alog?.('info', 'exec.pty.dial', { machine, session: sessionKey });
+                return new WsPtyChannel(`${row.origin.replace(/^http/, 'ws')}${PTY_EXEC_PATH}`, { cookie: cookieOf(row.id, home) });
+            };
+            const session = ptyPool.getOrCreate(`${sessionKey}|m:${machine}`, channelOf);
+            const result = await session.dispatch(cmd, { ...(opts.timeoutSec === undefined ? {} : { timeoutSec: opts.timeoutSec }) });
+            alog?.('info', 'exec.pty.run', {
+                machine,
+                cmd: cmd.length > 120 ? `${cmd.slice(0, 117)}...` : cmd,
+                exit: result.exit ?? 'none',
+                ...(result.cwd !== null ? { cwd: result.cwd } : {}),
+                durationMs: result.durationMs,
+                ...(result.reconnected ? { reconnected: true } : {}),
+                ...(result.timedOut ? { timedOut: true } : {}),
+            });
+            return result;
+        };
+        const execFaceFull = { ...execFace, pty: execPty };
+        // the a2a endpoints (POST /api/superd/a2a + GET /api/superd/a2a/outbox) ride the shared
+        t.tools.register(createSuperdHubTool({
+            service,
+            delivery,
+            exec: execFaceFull,
+            // R6: the agent_status leg reads the R5 cache (the sweep's legs fill it)
+            status: () => loadAgentStatus(home),
+            roster: () => rosterViewOf(home),
+            // This row mounts in ctx0 only (header ruling): every caller is a
+            // native DSH session, so the initiator's a6 is the 'native' row's.
+            initiatorOf: (sessionId) => localA2aInitiator(home, 'native', sessionId),
+            onWatch: (dispose) => { ctx.effect(() => dispose, 'superd-a2a: a2a completion watch'); },
+        }));
+    });
+}
+/** MUST stay an arrow (RM0/better-dash note: function declarations get `new`-called, disposers lost). */
+export const apply = (ctx) => {
+    wireHubToolRow(ctx);
+};
+export default { name, inject, apply };

package/superd-hub/dist/a2a-service.d.ts

@@ -0,0 +1,357 @@
+import { A2aAddressError } from './a2a-wire.js';
+import type { A2aIngest } from './a2a-ingest.js';
+import type { A2aLogFn } from './a2a-log.js';
+export { A2aAddressError };
+/** One tracked conversation = one target-side DSH session (spec §2). */
+export interface ConversationRow {
+    /** Display/tool alias — first 6 chars of the session id's uuid part (the constant `session-` prefix stripped), collision-lengthened 6→8→10; legacy rows keep older spellings verbatim. */
+    shortId: string;
+    /** Machine id (m4) the conversation lives on. */
+    machine: string;
+    /** Agent id (a6) the conversation belongs to. */
+    agent: string;
+    /** Full DSH session id (the wire identity). */
+    sessionId: string;
+    /** Operator-facing title (optional; never an identity). */
+    title?: string;
+    /**
+     * R4 amendment (2026-09-28 review): present ONLY on MIRROR rows (the peer
+     * hosted the conversation here) = the LOCAL a6 hosting the session.
+     * Presence identifies the row as locally-hosted and routes continuations
+     * to our own ingest. Absent = initiator-row semantics (the session lives
+     * at {machine, agent}). Additive optional; no migration.
+     */
+    hostAgent?: string;
+    /**
+     * The initiator identity's full session id — the peer→initiator asynchronous
+     * delivery address. R4: persisted at create/first-send on INITIATOR rows.
+     * 0.1.7-i: MIRROR rows persist it at adoption too (the opener's session
+     * from the envelope) — the send-failed notice must address the original
+     * initiator even when the write-back dies before the initiator-side ingest
+     * ever learned the conversation. Additive; absent = pre-R4 rows / not yet
+     * sent.
+     */
+    initiatorSession?: string;
+    /**
+     * D20 (2026-09-29): present ONLY on MIRROR rows = the hosted peer has sent
+     * through the channel at least once in this conversation. Monotonic per
+     * conversation — once set, the completion watch NEVER transcribes again
+     * (the channel reply IS the reply; unsent turn-end output is the peer's
+     * own business). Additive optional; no migration.
+     */
+    channelUsed?: true;
+    /** D20: epoch ms of the peer's LAST channel send on this row — the watermark the completion watch compares against its arm time to detect "sent during this turn's window" (suppresses the artifact when the send already was it). */
+    lastSentAt?: number;
+    /**
+     * 0.1.7-h R2: epoch ms when a stop envelope cancelled a LIVE turn here.
+     * The completion watch compares it against its arm watermark — a turn that
+     * ends because the INITIATOR stopped it must surface as
+     * reason=stopped-by-initiator, not as the peer going silent. Additive
+     * optional; no migration.
+     */
+    stoppedAt?: number;
+    /** Epoch ms when the row was created. */
+    createdAt: number;
+    /** Epoch ms of the last successful send. */
+    lastActivityAt: number;
+    /**
+     * D30 (2026-09-30): the peer's last output delivered into this conversation
+     * (a channel reply or a turn-end transcript), recorded when this hub
+     * RECEIVES it. Queryable through agent_status by the conversation's
+     * INITIATOR only (the ownership gate). Additive optional; no migration.
+     */
+    lastOutput?: string;
+    /** Epoch ms of lastOutput. */
+    lastOutputAt?: number;
+}
+/** The whole registry file. */
+export interface ConversationsFile {
+    conversations: ConversationRow[];
+}
+/** Read the registry; a missing or unreadable/corrupt file degrades to empty (never throws). */
+export declare function loadConversations(home: string): ConversationsFile;
+/** Persist the registry: recursive mkdir, tmp write, chmod 0600, atomic rename (machines.ts discipline). */
+export declare function saveConversations(home: string, file: ConversationsFile): void;
+/**
+ * shortId mint (D2 fix): DSH session ids are `session-<uuid>`, so slicing the
+ * raw id only ever captures the constant prefix (the live registry degenerated
+ * to "session-", "session-3", …). Strip the prefix, mint the first 6 chars of
+ * the uuid part, collision-lengthen 6→8→10… (step 2, spec §11). Ids without the
+ * prefix (older/foreign spellings) mint from the whole id the same way. A
+ * re-seen sessionId keeps its row's shortId (stable across restarts); stored
+ * shortIds are reserved as taken — DEGENERATE ones are re-minted once by
+ * {@link migrateConversations}, all others stay verbatim forever.
+ */
+export declare function shortIdFor(sessionId: string, rows: readonly ConversationRow[]): string;
+/**
+ * Degenerate-pattern predicate (D2 migration): a stored shortId that still
+ * carries the `session-` prefix AND whose remainder is shorter than the new
+ * mint length — exactly the ids the old prefix-slicing bug produced. Such ids
+ * carry (almost) no information and teach peers to echo garbage.
+ */
+export declare function isDegenerateShortId(shortId: string): boolean;
+/**
+ * One-time registry migration (D2 amended, review 2026-09-28): rows matching
+ * the degenerate pattern are re-minted with the current algorithm and written
+ * back; non-degenerate rows are never touched. Peers still holding an old
+ * degenerate id in their context is accepted collateral — the registry holds
+ * test data today, which is the cheapest migration window there will ever be.
+ * @returns the re-minted rows (empty when nothing needed migrating).
+ */
+export declare function migrateConversations(home: string): ConversationRow[];
+/**
+ * THE teaching envelope — one template constant (D20 v3, 2026-09-29: the
+ * SINGLE merged text, no variants). Filled with the INITIATOR's identity
+ * (machine-agent address = the write-back target), the conversation title,
+ * the body, and the shortId a superd-hub tool addresses. Tail = the user's
+ * 2026-09-29 redline, four short paragraphs, each carrying one load:
+ * provenance + channel-only principle / heterogeneity disclosure (tool
+ * availability genuinely differs per runtime — this is what stops a
+ * tool-less model from hunting for one) / how+when to send (sending does
+ * not end the turn) / the fallback, phrased from the RECEIVER's operational
+ * truth ("the hub receive no hub message" — intentionally or prevented;
+ * wording per user ruling 0.1.7-h: the receiver is the hub, the message
+ * class is a hub message). The "if available" conditional is evaluated by
+ * the MODEL against its own tool
+ * list; never pre-select variants on unknowable runtime state. Never a
+ * separate user prompt (the OMP 20-tool-call incident).
+ */
+export declare const A2A_MESSAGE_TEMPLATE = "A2A message from {machine}-{agent} (conversation \"{title}\"):\n\n{message}\n\nThis conversation is initiated through superd-hub by the sender. The sender sees only what arrives through this conversation.\n\nAs superd-hub hosts various kinds of agent runtimes, integration into each runtime and superd-hub tool availability in each runtime session might differ.\n\nTo reply, send a message back: with a superd-hub tool, if available, {action:\"send\", agent:\"{machine}-{agent}\", conversationId:\"{shortId}\", message:\"\u2026\"}. You can send at any point, more than once \u2014 sending does not end your turn.\n\nIf the hub receive no hub message from you (intentionally or whatever situation prevents so), your last output at this turn's end is delivered to the sender as your reply.";
+/** Title shown when the conversation has none. */
+export declare const A2A_UNTITLED = "(untitled)";
+/**
+ * Render the teaching envelope for one send — a SINGLE pass over the template
+ * (injection fix, 2026-09-28): each placeholder is expanded exactly once from
+ * the fields, and user-supplied values (title, message) are never re-scanned,
+ * so a title containing the literal `{shortId}` or `{message}` lands verbatim
+ * instead of being expanded by a later replaceAll round.
+ */
+export declare function renderA2aEnvelope(fields: {
+    machine: string;
+    agent: string;
+    title?: string;
+    shortId: string;
+    message: string;
+}): string;
+/** Bounded unread buffer size per initiator session. */
+export declare const A2A_BUFFER_MAX = 32;
+/** D28: the sender's synchronous receipt window. If the end-to-end wire has not settled by then the hub answers `accepted` and lets the SAME in-flight request finish in the background. */
+export declare const A2A_SYNC_RECEIPT_MS = 10000;
+/** D28: the TOTAL wire budget for one send (120s). The POST timeout is set from the request start, so after the 10s synchronous window the SAME in-flight request still has ~110s left to settle; the peer may spend it bringing the runtime up (spawn OR resume — indistinguishable at the process level). */
+export declare const A2A_WIRE_TOTAL_BUDGET_MS = 120000;
+/** stop('session') degradation notice — the session plane has no close RPC upstream. */
+export declare const A2A_NO_SESSION_CLOSE_REASON = "no session-close endpoint upstream";
+/** Target address: machine id (m4) + agent id (a6) — the `gatewayFor` key. */
+export interface A2aAddress {
+    machine: string;
+    id: string;
+}
+/**
+ * Initiator identity envelope (spec §7.3), opaque in T2 — Task 3 gives it its
+ * real shape. T2 uses `machine`/`agent` for the teaching template and
+ * `sessionId` as the unread-buffer key.
+ */
+export interface A2aInitiator {
+    machine: string;
+    agent: string;
+    sessionId: string;
+}
+/** Prompt delivery mode (upstream `SessionPromptRequest.mode`); default 'queue' — peer semantics, never interrupting. */
+export type A2aDelivery = 'queue' | 'steer';
+/**
+ * Receipt taxonomy (D28): 'delivered' on every successful prompt submission
+ * (end-to-end delivery complete); 'failed' carries an executable error body.
+ * ('accepted' / 'spawn-failed' land with the 0.1.8 poll mechanism, T5.)
+ */
+export type A2aReceiptOutcome = 'delivered' | 'accepted' | 'failed';
+/** One failed-send error body, verbatim from the gateway (wire error shape). */
+export interface A2aReceiptError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/** send()'s immediate return (spec §2: inbox-acceptance receipt). */
+export interface A2aReceipt {
+    outcome: A2aReceiptOutcome;
+    /** The client-minted requestId — the durable identity of the injected user message. */
+    messageId: string;
+    /** Conversation shortId (absent when no conversation resolved). */
+    conversationId?: string;
+    /** Target session ('' when the failure predates session resolution). */
+    sessionId: string;
+    /** Present iff outcome === 'failed'. */
+    error?: A2aReceiptError;
+    /** Model-facing guidance riding a non-terminal receipt (D28: an `accepted` receipt explains that the same in-flight request keeps running). */
+    note?: string;
+}
+/** One send request (spec §7.2): no conversationId ≡ new conversation. */
+export interface A2aSendRequest {
+    /**
+     * Target agent. REQUIRED to open a new conversation (no conversationId);
+     * on a continuation it may be omitted — the hub derives the route from the
+     * registry row + the caller's session (D24/T3). When supplied on a
+     * continuation it is a checked assertion: a mismatch is refused.
+     */
+    to?: A2aAddress;
+    conversationId?: string;
+    title?: string;
+    message: string;
+    delivery?: A2aDelivery;
+}
+/** Conversation reference: address + shortId. */
+export interface A2aConversationRef {
+    to: A2aAddress;
+    conversationId: string;
+}
+/** One stop request (D24/T3): `to` is optional — the hub derives the session owner from the row. */
+export interface A2aStopRequest {
+    conversationId: string;
+    /** The session owner's address; optional (derived from the row), checked when supplied. */
+    to?: A2aAddress;
+}
+/** One captured turn completion. */
+export interface A2aCompletion {
+    conversationId: string;
+    sessionId: string;
+    turn: number;
+    /** `turn/end.data.reason.kind` (TurnEndReason). */
+    reason: string;
+    /** Text blocks of the turn's LAST non-interrupted assistant/message, joined with '\n\n'. */
+    text: string;
+}
+export type A2aCompletionCb = (completion: A2aCompletion) => void;
+export type A2aErrorCb = (error: {
+    code: string;
+    message: string;
+}) => void;
+export interface A2aSubscribeOptions {
+    /**
+     * Correlate one send: the requestId used on `session/prompt`. The cb fires
+     * exactly once — for the turn that admitted this request's user message
+     * (matched by `data.source.rpcId`) — then the subscription auto-disposes.
+     * Omit to observe every turn completion while subscribed (one cb per turn).
+     */
+    requestId?: string;
+    /** Death/failure notice path (missing conversation/gateway, second stream death). */
+    onError?: A2aErrorCb;
+}
+export type A2aStopScope = 'turn' | 'session';
+/** stop() idle note — the honest answer when the pre-cancel liveness snapshot showed no live turn (D5). */
+export declare const A2A_NO_TURN_ACTIVE_NOTE = "no turn was active";
+/** stop() result: 'turn' answers a turn-scope stop; 'turn-only' reports the session-scope degradation.
+ * `cancelled:false` is the honest idle answer (D5): the cancel RPC still fired (today's wire behavior
+ * is unchanged), but the pre-cancel liveness read showed no turn to stop — the note says so. */
+export type A2aStopResult = {
+    scope: 'turn';
+    cancelled: true;
+} | {
+    scope: 'turn';
+    cancelled: false;
+    note: typeof A2A_NO_TURN_ACTIVE_NOTE;
+} | {
+    scope: 'turn-only';
+    cancelled: true;
+    reason: typeof A2A_NO_SESSION_CLOSE_REASON;
+} | {
+    scope: 'turn-only';
+    cancelled: false;
+    note: typeof A2A_NO_TURN_ACTIVE_NOTE;
+    reason: typeof A2A_NO_SESSION_CLOSE_REASON;
+};
+/** One buffered (undelivered) inbound message for an initiator session. */
+export interface A2aBufferedMessage {
+    messageId: string;
+    initiatorSessionId: string;
+    from: A2aAddress;
+    conversationId: string;
+    text: string;
+    bufferedAt: number;
+}
+/** Input half of a buffer push (Task 3's delivery layer calls this on reply-delivery failure). */
+export type A2aBufferInput = Omit<A2aBufferedMessage, 'initiatorSessionId' | 'bufferedAt'>;
+/** The gateway face this service consumes — structural subset of `GatewayFace` (targets.ts). */
+export interface A2aGateway {
+    dispatchRpc(endpoint: string, payload: unknown, signal: AbortSignal): Promise<unknown>;
+    openWireStream(endpoint: string, payload: unknown, signal: AbortSignal): AsyncIterable<unknown> | Promise<AsyncIterable<unknown>>;
+}
+/**
+ * Typed address-resolution failure (D7) — the class lives in a2a-wire.ts
+ * since postoffice R1 (the wire helpers classify transport failures with
+ * it); re-exported above for this module's existing consumers.
+ */
+export interface A2aServiceDeps {
+    home: string;
+    /** Still the LOCAL leg's resolver (subscribeCompletion + the ingest assembly source); the send/stop paths never resolve a REMOTE gateway since R4 — remote routing is envelope-wire only. */
+    gatewayFor(addr: A2aAddress): A2aGateway;
+    /**
+     * R4: the ingest handler shared with the HTTP endpoint — the self-routing
+     * leg. LAZY (resolved at send time, never construction time: the ingest's
+     * delivery face buffers through THIS service's buffer leg, so the instance
+     * can only exist after the service does).
+     */
+    ingest?(): A2aIngest | undefined;
+    /** R4: fetch override for the remote wire leg (tests inject fixtures). */
+    fetchImpl?: typeof fetch;
+    /** Operational journal (0.1.7-b): one greppable line per machine event; the cordis host wires it onto ctx.logger, tests inject a collector. */
+    log?: A2aLogFn;
+    now?(): number;
+    /** D28: override the synchronous receipt window (tests run it small; production uses A2A_SYNC_RECEIPT_MS). */
+    syncReceiptMs?: number;
+}
+export interface A2aService {
+    /** Create-or-resume + inject one user turn; receipt semantics (never throws — failures are 'failed' receipts). */
+    send(req: A2aSendRequest, initiator: A2aInitiator): Promise<A2aReceipt>;
+    /** Subscribe turn completions of one conversation over session/follow; returns the dispose fn. */
+    subscribeCompletion(conv: A2aConversationRef, cb: A2aCompletionCb, opts?: A2aSubscribeOptions): () => void;
+    /** Cancel the active turn; 'session' scope degrades to turn-only with the typed reason. cancelled:false + note is the honest idle answer (D5 — the cancel still fires; a pre-cancel snapshot read proved no turn was live). */
+    stop(req: A2aStopRequest, scope: A2aStopScope): Promise<A2aStopResult>;
+    /** Buffer one undelivered message for an initiator (bounded A2A_BUFFER_MAX, oldest dropped). */
+    buffer(initiatorSessionId: string, message: A2aBufferInput): void;
+    /** Sweep the unread buffer — one initiator, or all; swept entries are returned and cleared. */
+    read(initiatorSessionId?: string): A2aBufferedMessage[];
+    /** Snapshot of the registry rows. */
+    listConversations(): ConversationRow[];
+}
+/** Map one typed address failure to its wire error body (D7): the error's own
+ * message; the code keeps 'a2a/gateway-unavailable' for the unreachable branch
+ * (today's code) and names the kind otherwise. */
+export declare function addressErrorBody(error: A2aAddressError): {
+    code: string;
+    message: string;
+};
+/**
+ * D5 turn-liveness read: open the follow stream, replay the FIRST snapshot
+ * frame's records, and report whether a turn is still open (a turn/start not
+ * followed by its turn/end). Read manually (no for-await) and aborted BEFORE
+ * returning — closing an async generator suspended at an await must not gate
+ * the answer (the close promise can reject on abort and would eat the result).
+ * @returns true (a turn is live), false (idle), or undefined when the plane
+ * could not answer (stream death, stream end, no snapshot, read timeout) —
+ * callers treat undefined conservatively: cancel anyway, keep today's shape.
+ */
+export declare function turnLivenessOf(gateway: A2aGateway, sessionId: string): Promise<boolean | undefined>;
+/**
+ * One session-plane RPC through the gateway: payload via `wireArgsOf`,
+ * `{ok:false,error}` rethrown as a typed EnvelopeError (error body verbatim),
+ * transport throws pass through untouched (they are already gateway/* typed).
+ */
+export declare function sessionRpc<T>(gateway: A2aGateway, endpoint: string, request: unknown): Promise<T>;
+/** A directly-addressed session to watch — the ingest leg (postoffice R3)
+ * subscribes the LOCAL gateway without the initiator-side registry checks. */
+export interface A2aSessionSource {
+    /** The session-plane gateway owning the session (local leg on the ingest side). */
+    gateway: A2aGateway;
+    /** The session to follow. */
+    sessionId: string;
+    /** Conversation id reported in fired completions (the registry shortId). */
+    conversationId: string;
+}
+/**
+ * The completion watcher behind `subscribeCompletion` (extracted verbatim in
+ * postoffice R3): one follow stream over the addressed session, turn-text
+ * reduction, requestId arming, one resubscribe, snapshot-history fire.
+ * Same contract as the service method — every fired completion is one cb,
+ * armed subscriptions auto-dispose after their turn fires.
+ */
+export declare function subscribeSessionCompletion(source: A2aSessionSource, cb: A2aCompletionCb, opts?: A2aSubscribeOptions): () => void;
+export declare function createA2aService(deps: A2aServiceDeps): A2aService;