@robota-sdk/agent-transport 3.0.0-beta.100

package/src/node/stdio-carrier.ts

@@ -0,0 +1,59 @@
+/**
+ * The input bridge and close observation a stdio protocol carrier shares.
+ *
+ * A protocol SDK that reads a stream owns what it reads: closing the SDK connection destroys its
+ * source. Handing it the process input directly would let one carrier's `stop()` destroy `process.stdin`
+ * for the whole process, so the carrier reads a `PassThrough` bridge fed by the input instead. Piping
+ * also makes EOF observable before the SDK starts reading and keeps early frames, with backpressure,
+ * until it does.
+ *
+ * This module only attaches and detaches. What a close or failure means — settle a promise, cancel a
+ * startup, end the process — stays with each carrier.
+ */
+
+import { PassThrough } from 'node:stream';
+
+import type { Readable, Writable } from 'node:stream';
+
+export interface IStdioCarrierHandlers {
+  /** The peer ended its side: `end` or `close` on the input. May fire more than once. */
+  readonly onInputClose: () => void;
+  /** The output closed. */
+  readonly onOutputClose: () => void;
+  /** The output failed to accept a write. */
+  readonly onOutputError: (error: Error) => void;
+}
+
+export interface IStdioCarrier {
+  /** Hand this to the protocol SDK in place of the input; destroying it never destroys the input. */
+  readonly bridge: PassThrough;
+  /** Remove the listeners, unpipe and destroy the bridge. Safe to call again; the streams stay open. */
+  release(): void;
+}
+
+export function attachStdioCarrier(
+  input: Readable,
+  output: Writable,
+  handlers: IStdioCarrierHandlers,
+): IStdioCarrier {
+  const bridge = new PassThrough();
+  let released = false;
+  input.once('end', handlers.onInputClose);
+  input.once('close', handlers.onInputClose);
+  output.once('close', handlers.onOutputClose);
+  output.on('error', handlers.onOutputError);
+  input.pipe(bridge);
+  return {
+    bridge,
+    release() {
+      if (released) return;
+      released = true;
+      input.off('end', handlers.onInputClose);
+      input.off('close', handlers.onInputClose);
+      output.off('close', handlers.onOutputClose);
+      output.off('error', handlers.onOutputError);
+      input.unpipe(bridge);
+      bridge.destroy();
+    },
+  };
+}

package/src/observer-messages.ts

@@ -0,0 +1,47 @@
+import type { TClientMessage } from './wire-messages.js';
+
+/**
+ * The only inbound messages an observer may send: reads of this session. An allowlist, so a message
+ * type added later is refused to observers until someone decides it is a read. `get-prompts` is left
+ * out: an observer never receives prompts, open ones included.
+ *
+ * The host refuses anything else from an observer, and a client in observe mode sends only these, so
+ * both sides read this one list.
+ */
+export const OBSERVER_MESSAGES: ReadonlySet<TClientMessage['type']> = new Set<
+  TClientMessage['type']
+>([
+  'get-messages',
+  'get-history',
+  'get-context',
+  'get-status',
+  'get-commands',
+  'list-models',
+  'get-executing',
+  'get-pending',
+  'get-execution-workspace',
+  'read-execution-detail',
+  'get-agent-definitions',
+  'get-usage-report',
+  'list-sessions',
+  'get-background-tasks',
+  'get-background-task',
+  'get-background-job-groups',
+  'get-background-job-group',
+  'wait-background-job-group',
+  'read-background-task-log',
+  // #3282 §4a: reading the Settings snapshot is a pure read of this session's own configuration.
+  // `update-settings` stays out — an observer never writes.
+  'get-settings',
+  // #3282 §4c: the Project panel's reads — git status, one file's diff, project memory. All three are
+  // read-only (there is no "restore"/write counterpart in this feature — see the SPEC.md design
+  // decision on why checkpoints/rewind are excluded entirely), so all three are observer-safe.
+  'project-status',
+  'project-diff',
+  'project-memory',
+]);
+
+/** Whether an observer may send a message of this type. */
+export function isObserverMessageType(type: string): boolean {
+  return (OBSERVER_MESSAGES as ReadonlySet<string>).has(type);
+}

package/src/open-prompts.ts

@@ -0,0 +1,76 @@
+/**
+ * #3189: the permission and ask prompts a session has open, as the frames that asked them.
+ *
+ * The session keeps only the promise each prompt waits on, and emits the prompt once, when it is
+ * asked. A client that attaches later would never see a prompt already open. This keeps what the
+ * transport forwarded, per session, for a `get-prompts` reply.
+ *
+ * It is held by the connections that receive prompts and learns everything through their own
+ * subscriptions, so it never listens to the session itself. That matters: a session asks only while
+ * someone listens for prompts, and a listener of its own here would keep an unattended session's
+ * prompt open instead of failing it closed. When the last such connection goes, the session settles
+ * every open prompt, so nothing is kept.
+ */
+
+import type { IProtocolSession } from './protocol-session.js';
+import type { TServerMessage } from './wire-messages.js';
+
+export type TOpenPromptFrame = Extract<
+  TServerMessage,
+  { type: 'permission_request' | 'ask_request' }
+>;
+
+interface IOpenPrompts {
+  readonly frames: Map<string, TOpenPromptFrame>;
+  holders: number;
+}
+
+const openPromptsBySession = new WeakMap<IProtocolSession, IOpenPrompts>();
+
+/** One connection's hold on its session's open prompts; every holder reports what it forwards. */
+export interface IOpenPromptsHold {
+  /** A prompt was asked. */
+  record(frame: TOpenPromptFrame): void;
+  /** A prompt was settled, by an answer or by the session. */
+  forget(id: string): void;
+  /** The host made another session current; the previous session's prompts are settled. */
+  clear(): void;
+  /** This connection no longer receives prompts. */
+  release(): void;
+}
+
+/** Called by a connection that receives prompts, before it subscribes to them. */
+export function holdOpenPrompts(session: IProtocolSession): IOpenPromptsHold {
+  let open = openPromptsBySession.get(session);
+  if (open === undefined) {
+    open = { frames: new Map(), holders: 0 };
+    openPromptsBySession.set(session, open);
+  }
+  const held = open;
+  held.holders += 1;
+  let released = false;
+  return {
+    record: (frame) => {
+      if (!released) held.frames.set(frame.event.id, frame);
+    },
+    forget: (id) => {
+      held.frames.delete(id);
+    },
+    clear: () => {
+      held.frames.clear();
+    },
+    release: () => {
+      if (released) return;
+      released = true;
+      held.holders -= 1;
+      if (held.holders === 0 && openPromptsBySession.get(session) === held) {
+        openPromptsBySession.delete(session);
+      }
+    },
+  };
+}
+
+/** The prompts open now, oldest first; none when no connection that receives prompts is attached. */
+export function listOpenPrompts(session: IProtocolSession): readonly TOpenPromptFrame[] {
+  return [...(openPromptsBySession.get(session)?.frames.values() ?? [])];
+}

package/src/outbound-delivery.ts

@@ -0,0 +1,240 @@
+/**
+ * The connection-scoped outbound delivery boundary (ARCH-030).
+ *
+ * Every outbound `TServerMessage` on one connection — session-event fan-out AND every reply to an
+ * inbound frame — goes through ONE boundary that owns carrier-failure containment. Before this
+ * existed, `subscribeSessionEvents` guarded its sends while the reply paths received the raw carrier
+ * `send`, so a reply resolving after a disconnect threw from a Promise continuation, escaped as an
+ * unhandled rejection, and left the carrier's cleanup — written, idempotent, and waiting — unnotified.
+ *
+ * WHO BUILDS IT. The **carrier**, from its own private sink and its own failure policy, and passes the
+ * result down into the protocol handler. Not the other way round: the raw sink and the "what does a
+ * failed send mean for this connection" decision both belong to the carrier, and handing the protocol
+ * layer a raw sink so it can hand a wrapper back leaves the raw sink reachable — which is the hole a
+ * twelfth reply family walks through next year.
+ *
+ * WHY IT IS BRANDED. {@link createOutboundDelivery} is the only producer of {@link TOutboundDeliver}, so
+ * a plain `(message: TServerMessage) => void` is **refused by the compiler** wherever a boundary is
+ * required. That turns "a new raw-send continuation cannot be added silently" from a scan that a rename
+ * defeats into a type error at the call site. `src/__tests__` is inside this package's `tsconfig.json`
+ * `include`, so the `@ts-expect-error` case pinning it is checked by `tsgo --noEmit`.
+ *
+ * IT LATCHES. A boundary reports AT MOST ONE delivery failure; after the first, it is closed and every
+ * subsequent frame is dropped without a further report. All three carriers already treat a delivery
+ * failure as terminal (`WsSessionDelivery.close` → `socket.close(1011)`, `WebRtcDeliveryLifecycle` →
+ * `channel.close()`, `PairingGate` → `pairingChannel.close`) and each had grown its own latch to
+ * suppress the repeats; the latch belongs upstream of all three. `SessionResumeBridge` already behaved
+ * this way, so the handler path converges onto the bridge's semantics rather than the reverse.
+ *
+ * A boundary is not reusable across carriers: a latched one stays latched. `SessionResumeBridge` builds
+ * a fresh boundary per `attach`, which is what un-latches the session after a reconnect.
+ */
+
+import type { TServerMessage } from './wire-messages.js';
+
+declare const outboundDeliveryBrand: unique symbol;
+
+/**
+ * Deliver one outbound frame on a connection. A carrier failure is REPORTED through the boundary's
+ * error handler, never thrown at the caller — so a reply resolving after a disconnect cannot escape as
+ * an unhandled rejection or out of the carrier's inbound listener.
+ *
+ * Only {@link createOutboundDelivery} produces one. The brand is the mechanism, not decoration: it is
+ * what makes a raw carrier `send` unusable where a boundary is required.
+ */
+export type TOutboundDeliver = ((message: TServerMessage) => void) & {
+  readonly [outboundDeliveryBrand]: true;
+
+  /**
+   * Bytes this carrier has ACCEPTED and not yet written to the peer — or `undefined` when it cannot
+   * say.
+   *
+   * `deliver` returning is not delivery. Both carriers hand this boundary a fire-and-forget sink, so
+   * a frame that has "been sent" may be sitting in a socket buffer the boundary cannot see. Anything
+   * this boundary counted itself would be a count of what it HANDED OVER, which is a different
+   * quantity from what the peer has not read — and a budget over the wrong quantity reports a
+   * healthy connection for a peer that stopped reading (ARCH-030 / issue #1734).
+   *
+   * `undefined` is deliberately not `0`. A carrier that cannot report backpressure and a carrier with
+   * nothing pending are different states, and collapsing them would let "unknown" satisfy any
+   * threshold placed on this number.
+   */
+  readonly pendingBytes: () => number | undefined;
+};
+
+/**
+ * Observe THIS connection's first outbound delivery failure. `event` is the `type` of the frame that
+ * could not be delivered — for the fan-out, the frame a session event was forwarded as (usually, not
+ * always, the event's own name), and the reply's type for a reply (`command_result`, `protocol_error`, …).
+ *
+ * Required, never optional: a carrier that could opt out of observing its own delivery failures is the
+ * silent-failure shape this boundary exists to remove.
+ */
+export type TDeliveryErrorHandler = (error: Error, event: TServerMessage['type']) => void;
+
+/**
+ * Build the outbound delivery boundary for ONE connection from that connection's raw sink and its
+ * failure policy.
+ *
+ * @param send - the carrier's raw sink. May throw; that is what makes it raw.
+ * @param onDeliveryError - the carrier's failure policy, invoked at most once. A handler that itself
+ *   throws is isolated: a diagnostic cannot reverse an already-committed session operation.
+ * @param pendingBytes - the carrier's own backpressure reading. Optional because not every carrier
+ *   has one; omitted, the boundary answers `undefined` rather than inventing a number.
+ */
+/**
+ * Default outbound backpressure budget, in bytes the carrier has accepted and not yet written.
+ *
+ * 8 MiB. The number is a policy, not a measurement, and it is stated here rather than inlined so a
+ * reader can find the one place that decides it. It is well above any single frame this protocol
+ * produces and well below a figure at which a non-reading peer could exhaust the host — the property
+ * that matters is that SOME finite budget exists, because the previous behaviour was unbounded.
+ *
+ * A carrier that cannot report `pendingBytes` is not subject to it: `undefined` is unknown, not zero,
+ * so no threshold applies to it. That is deliberate and it is a gap — a carrier with no backpressure
+ * reading has no budget — recorded rather than hidden behind a default of `0`, which would refuse
+ * every frame on such a carrier.
+ */
+const BYTES_PER_MIB = Number('1024') * Number('1024');
+export const DEFAULT_MAX_PENDING_BYTES = Number('8') * BYTES_PER_MIB;
+
+/**
+ * Backpressure budget for a terminal attached to a session on the same host, in either role.
+ *
+ * 1 MiB, tighter than the default: an attached terminal reads a local socket, so a backlog this large
+ * means it stopped reading rather than that a network is slow. Exceeding it closes that connection
+ * only; the session never waits for a reader, so other surfaces keep streaming.
+ */
+export const ATTACHED_SURFACE_MAX_PENDING_BYTES = BYTES_PER_MIB;
+
+/**
+ * Is this carrier holding more than the budget allows?
+ *
+ * Exported because a WebSocket carries TWO kinds of outbound frame over one socket — the text
+ * protocol and TRANS-001's payload channels — and only one of them goes through
+ * {@link createOutboundDelivery}. A budget the binary path re-implemented would be a second opinion
+ * about one socket's backpressure; a budget it skipped would leave the same non-reading peer
+ * unbounded on the other half of the connection.
+ *
+ * `undefined` is unknown, not zero: a carrier that cannot report backpressure is never over budget.
+ */
+export function isOverPendingBudget(
+  pending: number | undefined,
+  limit: number = DEFAULT_MAX_PENDING_BYTES,
+): boolean {
+  return pending !== undefined && pending > limit;
+}
+
+/**
+ * Default outbound DRAIN budget (issue #2306): how long a carrier may stay non-empty before the peer
+ * is treated as not reading.
+ *
+ * 120 seconds. The byte budget bounds HOW MUCH a peer holds; it cannot bound HOW LONG, because
+ * `bufferedAmount` is a quantity with no history — a peer draining just enough to stay under 8 MiB
+ * forever is never over it. The figure is generous on purpose: a legitimately slow link drains to
+ * zero between bursts, so the clock resets, whereas a peer that keeps SOMETHING pending for two
+ * minutes straight is holding a session, its resume buffer, and a socket it does not intend to read.
+ * A badly chosen figure here disconnects real users, which is why it is one named constant and an
+ * argument, never an inline number. `Infinity` disables the budget.
+ */
+export const DEFAULT_MAX_PENDING_MS = Number('120') * Number('1000');
+
+/**
+ * The drain clock the boundary keeps for a carrier (issue #2306). One timestamp, not per-frame
+ * bookkeeping: it starts on the first reading that finds the carrier non-empty, RESETS only when a
+ * reading finds it empty (a peer that drains to one byte and stalls again has not drained), and is
+ * consulted synchronously at each send — the boundary has no timer and gains none here.
+ */
+export interface IPendingStallClock {
+  readonly maxPendingMs: number;
+  /**
+   * Record one reading of the carrier's pending bytes. Returns how long the carrier has been
+   * continuously non-empty when that exceeds the budget; `undefined` otherwise. An `undefined`
+   * reading is unknown, not zero: it neither starts nor resets the clock.
+   */
+  observe: (pending: number | undefined) => number | undefined;
+}
+
+export function createPendingStallClock(
+  maxPendingMs: number = DEFAULT_MAX_PENDING_MS,
+  now: () => number = Date.now,
+): IPendingStallClock {
+  let nonEmptySince: number | undefined;
+  return {
+    maxPendingMs,
+    observe(pending) {
+      if (pending === undefined) return undefined;
+      if (pending === 0) {
+        nonEmptySince = undefined;
+        return undefined;
+      }
+      const at = now();
+      nonEmptySince ??= at;
+      const stalledMs = at - nonEmptySince;
+      return stalledMs > maxPendingMs ? stalledMs : undefined;
+    },
+  };
+}
+
+export function createOutboundDelivery(
+  send: (message: TServerMessage) => void,
+  onDeliveryError: TDeliveryErrorHandler,
+  pendingBytes?: () => number | undefined,
+  maxPendingBytes: number = DEFAULT_MAX_PENDING_BYTES,
+  stallClock: IPendingStallClock = createPendingStallClock(),
+): TOutboundDeliver {
+  let closed = false;
+  const deliver = (message: TServerMessage): void => {
+    if (closed) return;
+    // The budget is checked BEFORE the send, not after: a peer that has stopped reading is detected
+    // by what the carrier is still holding, and adding one more frame first would make the boundary
+    // the last contributor to the overflow it is reporting.
+    const pending = pendingBytes?.();
+    if (isOverPendingBudget(pending, maxPendingBytes)) {
+      closed = true;
+      reportFailure(
+        new Error(
+          `outbound backpressure budget exceeded: ${pending} byte(s) pending, limit ${maxPendingBytes}. ` +
+            'The peer has accepted frames it is not reading.',
+        ),
+        message.type,
+      );
+      return;
+    }
+    // Issue #2306: the same reading, judged by duration. A peer under the byte budget that has kept
+    // the carrier non-empty for longer than the drain budget is not reading either.
+    const stalledMs = stallClock.observe(pending);
+    if (stalledMs !== undefined) {
+      closed = true;
+      reportFailure(
+        new Error(
+          `outbound drain budget exceeded: ${pending} byte(s) pending for ${stalledMs} ms, limit ${stallClock.maxPendingMs} ms. ` +
+            'The peer is reading too slowly to ever drain what it accepted.',
+        ),
+        message.type,
+      );
+      return;
+    }
+    try {
+      send(message);
+    } catch (error) {
+      // allow-fallback: this IS the boundary — a carrier send failure is a CARRIER lifecycle failure,
+      // reported to the carrier's own policy (which closes the connection). It is never swallowed, and
+      // re-throwing it would fail a session operation that has already committed.
+      closed = true;
+      reportFailure(error instanceof Error ? error : new Error(String(error)), message.type);
+    }
+  };
+  function reportFailure(error: Error, event: TServerMessage['type']): void {
+    try {
+      onDeliveryError(error, event);
+    } catch {
+      // allow-fallback: the carrier-owned diagnostic is the LAST step of a failure already being
+      // reported. A throw from it has nowhere left to go, and letting it out would make a committed
+      // session operation fail for the sake of a diagnostic.
+    }
+  }
+  return Object.assign(deliver, {
+    pendingBytes: (): number | undefined => pendingBytes?.(),
+  }) as TOutboundDeliver;
+}

package/src/peer-message-ledger.ts

@@ -0,0 +1,193 @@
+/**
+ * PEER-001 (#1809): the receiver's record of what it has already taken responsibility for.
+ *
+ * ## What this decides, and why it is not the carrier's job
+ *
+ * The issue requires delivery, acknowledgement, duplicate, retry and shutdown to produce
+ * "deterministic, documented outcomes". Every one of those is a question about what the receiver has
+ * SEEN BEFORE, which no carrier can answer: a WebRTC data channel redelivers on reconnect, a retry
+ * repeats a message the sender already sent, and neither the socket nor the frame codec has any
+ * memory to consult. So the decision lives here, once, and the carriers stay dumb.
+ *
+ * ## The rules, stated rather than emergent
+ *
+ * - **A repeated `id` is a duplicate**, and the ledger returns the SAME ack it returned the first
+ *   time. That is what makes a retry safe: the sender learns the message landed, and the receiver
+ *   does not deliver it twice. An ack that merely said "duplicate" without the original state would
+ *   force the sender to guess whether the first attempt was accepted or refused.
+ * - **Sequence is per origin.** Two peers are independent senders; a shared counter would make one
+ *   peer's traffic look like the other's gap.
+ * - **A gap is REPORTED, never silently reordered.** If sequence 5 arrives while 4 has not, the
+ *   ledger says so. Buffering-and-reordering is a policy the session layer may choose; inventing it
+ *   here would hide a lost message behind an apparent success, which is the failure mode this whole
+ *   contract exists to avoid.
+ * - **Nothing is remembered across shutdown.** The ledger is per-connection state by construction —
+ *   a peer that reconnects gets a fresh sequence space, and the session layer decides what to do
+ *   with a peer that restarts mid-conversation.
+ */
+
+import type {
+  IPeerMessage,
+  IPeerMessageAck,
+  TPeerDeliveryState,
+} from '@robota-sdk/agent-interface-session-mobility';
+
+/**
+ * What the receiver has seen from one origin.
+ *
+ * `delivered` is a SET, not just a high-water mark, and that distinction is the whole of review
+ * finding #1. A high-water mark cannot tell "sequence 2 was already used" from "sequence 2 is the
+ * gap we reported and it has just arrived" — and answering the second as if it were the first
+ * refuses a message that was never delivered, permanently. `highestSequence` is kept alongside it
+ * because reporting a gap needs the frontier, not the membership.
+ *
+ * Exported because it is reachable from `IPeerMessageLedger`. A public interface whose field type is
+ * unexported is a name a consumer cannot write down (review finding #2). Measured: `tsdown` inlines
+ * it into the bundled declaration so no TS4033 is raised today — the finding's build-breakage claim
+ * does not reproduce — but a type nobody can name is still a bad public surface.
+ */
+export interface IOriginRecord {
+  /** The highest sequence delivered from this origin — the frontier a gap is measured against. */
+  highestSequence: number;
+  /** Every sequence actually delivered. Membership, not a range: gaps get filled out of order. */
+  delivered: Set<number>;
+  /** Acks already issued, by message id, so a retry gets the original answer back. */
+  issued: Map<string, IPeerMessageAck>;
+}
+
+/** Per-connection receive state. Created empty; discarded when the connection ends. */
+export interface IPeerMessageLedger {
+  readonly origins: Map<string, IOriginRecord>;
+}
+
+export function createPeerMessageLedger(): IPeerMessageLedger {
+  return { origins: new Map() };
+}
+
+/** Why a message was not accepted, when it was not. */
+export interface IPeerMessageRejection {
+  readonly state: Extract<TPeerDeliveryState, 'refused' | 'failed'>;
+  readonly reason: string;
+}
+
+export interface IPeerMessageVerdict {
+  readonly ack: IPeerMessageAck;
+  /**
+   * Should the session deliver this to the agent?
+   *
+   * False for a duplicate and for a refusal. Separate from `ack.state` because a caller that
+   * re-derived it from the state string would have to re-list which states mean "deliver", and that
+   * list is exactly what drifts.
+   */
+  readonly deliver: boolean;
+  /**
+   * Set when this message's sequence is ahead of the last one delivered from its origin.
+   *
+   * Reported, not resolved. The session layer decides whether a gap is worth waiting for; the
+   * ledger's job is to make sure it is never invisible.
+   */
+  readonly gapBefore?: number;
+}
+
+/**
+ * Record a message and say what should happen to it.
+ *
+ * Pure with respect to its inputs except for the ledger it is handed, which it updates in place —
+ * the caller owns the ledger's lifetime, so a connection ending is a reference going away rather
+ * than a cleanup step someone can forget.
+ */
+export function admitPeerMessage(
+  ledger: IPeerMessageLedger,
+  message: IPeerMessage,
+  rejection?: IPeerMessageRejection,
+): IPeerMessageVerdict {
+  const originId = message.origin.sessionId;
+  let record = ledger.origins.get(originId);
+  if (record === undefined) {
+    record = { highestSequence: 0, delivered: new Set(), issued: new Map() };
+    ledger.origins.set(originId, record);
+  }
+
+  // A repeated id is answered with the ORIGINAL verdict, before anything else is considered: a
+  // retry must not be re-judged, or a message accepted once could be refused on its second arrival
+  // and the sender would have two contradictory answers for one message.
+  const previous = record.issued.get(message.id);
+  if (previous !== undefined) {
+    return { ack: { ...previous, state: 'duplicate' }, deliver: false };
+  }
+
+  if (rejection !== undefined) {
+    const ack: IPeerMessageAck = {
+      id: message.id,
+      sequence: message.sequence,
+      state: rejection.state,
+      reason: rejection.reason,
+    };
+    record.issued.set(message.id, ack);
+    return { ack, deliver: false };
+  }
+
+  // A sequence this origin ACTUALLY delivered before, under a different id: a sender reusing a
+  // sequence, which is a protocol error rather than a duplicate.
+  //
+  // Membership, not `<= highestSequence`. The high-water form refused the late arrival of a gap it
+  // had itself reported — deliver 1, receive 3 (gap at 2 reported), then 2 arrives and is rejected
+  // as "already used" although it was never delivered. That contradicted this module's own stated
+  // rule that a gap is reported so the SESSION layer can decide, since the session never got the
+  // chance. Found in review.
+  if (record.delivered.has(message.sequence)) {
+    const ack: IPeerMessageAck = {
+      id: message.id,
+      sequence: message.sequence,
+      state: 'refused',
+      reason:
+        `sequence ${message.sequence} was already delivered by this origin under a different ` +
+        'message id. A retry must repeat its id; a new id on a delivered sequence cannot be ' +
+        'ordered against what the receiver already has.',
+    };
+    record.issued.set(message.id, ack);
+    return { ack, deliver: false };
+  }
+
+  const expected = record.highestSequence + 1;
+  const gapBefore = message.sequence > expected ? expected : undefined;
+
+  const ack: IPeerMessageAck = {
+    id: message.id,
+    sequence: message.sequence,
+    state: 'delivered',
+  };
+  record.issued.set(message.id, ack);
+  record.delivered.add(message.sequence);
+  // The frontier only moves FORWARD. A gap arriving late fills membership without rewinding what a
+  // later gap is measured against.
+  record.highestSequence = Math.max(record.highestSequence, message.sequence);
+
+  return gapBefore === undefined ? { ack, deliver: true } : { ack, deliver: true, gapBefore };
+}
+
+/**
+ * Mark a delivered message as acknowledged by the agent side.
+ *
+ * Separate from `admitPeerMessage` because delivery and acknowledgement answer different questions —
+ * "did the receiver take it" versus "did the agent act on it" — and a sender waiting for the second
+ * must not be told the first.
+ */
+export function acknowledgePeerMessage(
+  ledger: IPeerMessageLedger,
+  originSessionId: string,
+  id: string,
+): IPeerMessageAck | undefined {
+  const record = ledger.origins.get(originSessionId);
+  const issued = record?.issued.get(id);
+  if (record === undefined || issued === undefined || issued.state !== 'delivered')
+    return undefined;
+  const acknowledged: IPeerMessageAck = { ...issued, state: 'acknowledged' };
+  record.issued.set(id, acknowledged);
+  return acknowledged;
+}
+
+/** Forget one origin — used when a peer disconnects and its sequence space is no longer meaningful. */
+export function forgetPeerOrigin(ledger: IPeerMessageLedger, originSessionId: string): void {
+  ledger.origins.delete(originSessionId);
+}

package/src/permission-summary.ts

@@ -0,0 +1,18 @@
+/**
+ * The one argument a person recognises a tool call by, for every transport that puts a permission
+ * request to a person in its own wire form. Shared so the transports name the same call the same
+ * way; the built-in file tools take `filePath`, other tools `file_path` or `path`.
+ */
+import type { TToolArgs } from '@robota-sdk/agent-core';
+
+/** In the order the tools put them first. */
+const SUMMARY_ARGUMENTS = ['command', 'filePath', 'file_path', 'path', 'url', 'pattern', 'query'];
+
+/** The call's identifying argument, or `undefined` when it has none worth showing. */
+export function permissionSummaryArgument(toolArgs: TToolArgs): string | undefined {
+  for (const key of SUMMARY_ARGUMENTS) {
+    const value = toolArgs[key];
+    if (typeof value === 'string' && value !== '') return value;
+  }
+  return undefined;
+}