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

package/src/session-resume-bridge.ts

@@ -0,0 +1,275 @@
+/**
+ * Persistent session-resume bridge for the reconnectable WebRTC path (REMOTE-013 Stage E4).
+ *
+ * Created ONCE per remote session and OUTLIVES individual data channels. It subscribes to the session's
+ * events exactly once, stamps every outbound `TServerMessage` with a **monotonic `seq` that is continuous
+ * across channel drops**, and retains the un-acked tail in a {@link ResumeBuffer}. The data channel is a
+ * SWAPPABLE sink:
+ *
+ * - `attach(sink)` — set the current sink (a new channel after a reconnect). Does NOT auto-replay; replay is
+ *   driven by the client's `resume`.
+ * - `detach()` — clear the sink but KEEP buffering, so output produced while no channel is attached (the gap)
+ *   is captured and replayable.
+ * - `onClientMessage(data)` — `resume{lastSeq}` replays the buffered tail (or `resume_gap` on overrun); `ack{seq}`
+ *   frees the buffer; everything else routes to the session (reusing the shared `handleClientMessage`).
+ * - `dispose()` — unsubscribe (host reconnect-window ceiling / teardown).
+ *
+ * This is the fix for the placement defect: because the seq counter + buffer live here (not in the per-channel
+ * `createSessionMessageHandler`), `seq` does not reset when a reconnect builds a new channel, and gap output is not lost.
+ * The WS localhost path does NOT use this bridge — it keeps `createSessionMessageHandler` unchanged.
+ */
+
+import { createOutboundDelivery } from './outbound-delivery.js';
+import { ResumeBuffer, type IResumeBufferOptions } from './resume-buffer.js';
+import { subscribeSessionEvents } from './session-events.js';
+import { handleClientMessage, parseClientMessage } from './session-message-handler.js';
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { IUsageQueryReporters } from './usage-messages.js';
+import type { TSeqServerMessage, TServerMessage } from './wire-messages.js';
+import type { TCommandSurfaceLocality } from '@robota-sdk/agent-interface-command';
+import type { TUsageSurface } from '@robota-sdk/agent-interface-analytics';
+import type { TDriverId } from '@robota-sdk/agent-interface-session';
+
+/** The current channel sink — receives a serialized JSON frame to put on the wire. */
+export type TResumeSink = (data: string) => void;
+
+/** Options for {@link SessionResumeBridge.attach}. */
+export interface IAttachOptions {
+  /**
+   * REMOTE-013 E4: on a RECONNECT, HOLD live sink-forwarding until the client's `resume` has replayed the
+   * buffered tail — otherwise a live frame emitted between attach and the inbound `resume` would leapfrog the
+   * gap frames on the wire, and the client's seq-dedup would then discard the (older, lower-seq) gap. Every
+   * live event is already appended to the buffer, so holding loses nothing; `replay()` flushes in order and
+   * un-holds. First-pair attach does NOT hold (the client starts at seq 0, frames arrive in order).
+   */
+  readonly awaitResume?: boolean;
+  /** Sink/carrier-owned failure lifecycle for this attachment only. */
+  readonly onDeliveryError: (error: Error, event: string) => void;
+  /**
+   * ARCH-030: this attachment's carrier backpressure reading, if it has one.
+   *
+   * Threaded through because the replay path is the burst this budget exists for — a reconnecting
+   * peer is handed the whole retained tail at once, and without a reading the boundary here would
+   * have no budget at all while the per-channel boundary did.
+   */
+  readonly pendingBytes?: () => number | undefined;
+}
+
+export interface ISessionResumeBridgeOptions {
+  readonly session: IProtocolSession;
+  readonly buffer?: IResumeBufferOptions;
+  /** REMOTE-014 E5: the SERVER-ASSIGNED driver id for this surface, injected into inbound submit/command/prompt-response. */
+  readonly driverId?: TDriverId;
+  readonly surface?: TUsageSurface;
+  readonly personalUsageReporter?: IUsageQueryReporters['personalUsageReporter'];
+  readonly usageReporter?: IUsageQueryReporters['usageReporter'];
+  readonly storedSessionUsageReporter?: IUsageQueryReporters['storedSessionUsageReporter'];
+  /** #3282 §4 part b-2: this bridge is the reconnectable WebRTC path, so it is always `'remote'`. */
+  readonly commandSurfaceLocality?: TCommandSurfaceLocality;
+  /** See {@link ISessionMessageHandlerOptions.maxFrameBytes}: the channel's limit, not the inbound one. */
+  readonly maxFrameBytes?: number;
+}
+
+export class SessionResumeBridge {
+  private readonly session: IProtocolSession;
+  private readonly buffer: ResumeBuffer;
+  private driverId?: TDriverId;
+  private readonly reporters: IUsageQueryReporters;
+  private readonly surface?: TUsageSurface;
+  private readonly commandSurfaceLocality?: TCommandSurfaceLocality;
+  private readonly maxFrameBytes?: number;
+  /**
+   * Ends with the bridge, not with a channel: a channel drop keeps the session reconnectable, so work
+   * started for a hosted app view (a call waiting on its prompt) survives it and is cancelled only when
+   * the host gives up on the session.
+   */
+  private readonly lifetime = new AbortController();
+  private readonly unsubscribe: () => void;
+  private onDeliveryError?: IAttachOptions['onDeliveryError'];
+  /**
+   * ARCH-030: the attachment's outbound boundary — and the only reference this class keeps to the current
+   * channel, which is why `dispose()` goes through `detach()` rather than clearing a separate field.
+   * Built per `attach` because a boundary LATCHES on its first failure, so a fresh one is exactly what
+   * un-latches the session for the next channel. It holds the only try/catch on the frame path.
+   */
+  private outbound?: TOutboundDeliver;
+  /**
+   * The session-lifetime entry every frame takes — event fan-out AND every reply to an inbound frame —
+   * before it is seq-stamped and buffered by {@link emit}. Distinct from {@link outbound}, which is the
+   * per-attachment exit to the current channel; this one outlives channels because the subscription does.
+   *
+   * It guards the BUFFERING step, not a carrier, and it latches for the life of the session on purpose:
+   * the failure it is placed against is the buffer refusing a frame on capacity, and a resume buffer that
+   * cannot accept frames cannot honour a later `resume` either, so there is nothing a reconnect recovers.
+   * That is the opposite of {@link outbound}, where the next channel IS the recovery — the two scopes
+   * differ because the failures do. (A per-frame serialization failure would leave the buffer intact, but
+   * such a frame is undeliverable on every carrier, since each one stringifies it too; it is reported and
+   * the carrier torn down, never silently dropped.)
+   */
+  private readonly emitBoundary: TOutboundDeliver;
+  private disposed = false;
+  /** REMOTE-013 E4: while true, live emits are buffered but NOT forwarded — released by `replay()` on reconnect. */
+  private holding = false;
+
+  public constructor(options: ISessionResumeBridgeOptions) {
+    this.session = options.session;
+    this.buffer = new ResumeBuffer(options.buffer);
+    this.driverId = options.driverId;
+    this.surface = options.surface;
+    this.commandSurfaceLocality = options.commandSurfaceLocality;
+    this.maxFrameBytes = options.maxFrameBytes;
+    this.reporters = {
+      personalUsageReporter: options.personalUsageReporter,
+      usageReporter: options.usageReporter,
+      storedSessionUsageReporter: options.storedSessionUsageReporter,
+    };
+    // ONE subscription for the whole session — outlives every channel. Every event → seq-stamped + buffered.
+    // CMD-004 Stage D: `ui_intent` is requester-routed against the LATE-BOUND driver id (bound by
+    // `setDriverId` after pairing) — routing happens BEFORE buffering, so a foreign surface's intent
+    // consumes no seq and can never leak through a later `resume` replay.
+    //
+    // ARCH-030: built through the factory, never cast — the brand is only worth having if this class
+    // does not spell its way around it. `emit` buffers and then hands the stamped frame to whatever
+    // boundary is currently ATTACHED, so it does not itself throw on a carrier failure; this boundary
+    // exists so that if it ever did, the failure would be reported rather than escaping the session's
+    // event listener.
+    this.emitBoundary = createOutboundDelivery(
+      (message) => this.emit(message),
+      (error, event) => this.reportDeliveryError(error, event),
+    );
+    this.unsubscribe = subscribeSessionEvents(this.session, this.emitBoundary, {
+      getSurfaceDriverId: () => this.driverId,
+    });
+  }
+
+  /** Set the current channel sink (on connect / reconnect). Live messages reach the client; replay is `resume`-driven. */
+  public attach(sink: TResumeSink, options: IAttachOptions): void {
+    if (this.disposed) return;
+    this.onDeliveryError = options.onDeliveryError;
+    this.outbound = createOutboundDelivery(
+      (message) => sink(JSON.stringify(message)),
+      (error, event) => this.reportDeliveryError(error, event),
+      options.pendingBytes,
+    );
+    // On a reconnect, hold live forwarding until `resume` flushes the buffered tail (avoids the live-vs-replay race).
+    this.holding = options.awaitResume === true;
+  }
+
+  /** Clear the sink (channel drop). Buffering continues so gap output is retained for the next `resume`. */
+  public detach(): void {
+    this.outbound = undefined;
+    this.onDeliveryError = undefined;
+  }
+
+  /**
+   * REMOTE-014 E5: bind the SERVER-ASSIGNED driver id (the E3 `deviceId`) once the peer pairs — the bridge
+   * injects it into every subsequent inbound submit/command/prompt-response for co-drive attribution.
+   */
+  public setDriverId(driverId: TDriverId): void {
+    this.driverId = driverId;
+  }
+
+  /** Route one inbound channel frame: `resume`/`ack` handled here; everything else → the session. */
+  public onClientMessage(data: string): void {
+    if (this.disposed) return;
+    const msg = parseClientMessage(data, this.emitBoundary);
+    if (!msg) return;
+    if (msg.type === 'resume') {
+      this.replay(msg.lastSeq);
+      return;
+    }
+    if (msg.type === 'ack') {
+      this.buffer.ackThrough(msg.seq);
+      return;
+    }
+    // Session control/query/background/prompt-response — responses funnel back through `emit` (seq'd + buffered).
+    // REMOTE-014 E5: inject the server-assigned driver id (submit/prompt-response attribution).
+    handleClientMessage(
+      this.session,
+      this.emitBoundary,
+      msg,
+      this.driverId,
+      this.reporters,
+      this.surface,
+      undefined,
+      undefined,
+      this.commandSurfaceLocality,
+      {
+        signal: this.lifetime.signal,
+        ...(this.maxFrameBytes !== undefined ? { maxFrameBytes: this.maxFrameBytes } : {}),
+      },
+    );
+  }
+
+  /** Unsubscribe from the session (host reconnect-window ceiling / teardown). Idempotent. */
+  public dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.lifetime.abort();
+    // Through `detach`, not a field assignment: the boundary's closure is what holds the channel, so
+    // clearing anything else released nothing and left teardown documented but not performed.
+    this.detach();
+    this.unsubscribe();
+  }
+
+  /** Diagnostics/tests: the last seq assigned. */
+  public get lastSeq(): number {
+    return this.buffer.lastSeq;
+  }
+
+  /**
+   * Stamp a seq, retain in the buffer, and forward to the current sink — UNLESS holding for a reconnect replay.
+   *
+   * ARCH-030: the `buffer.append` happens BEFORE the boundary, deliberately. The boundary latches on its
+   * first failure and drops everything after it, so a frame appended afterwards would be lost — appending
+   * first means a dropped frame is still in the un-acked tail and still replays on the next `resume`.
+   */
+  private emit(message: TServerMessage): void {
+    if (this.disposed) return;
+    const seq = this.buffer.append(message);
+    if (this.holding) return; // buffered only; `replay()` will flush it in order and release the hold
+    this.deliverFrame({ ...message, seq } as TSeqServerMessage);
+  }
+
+  /**
+   * Replay the buffered tail after `lastSeq` (or `resume_gap` on overrun), then RELEASE the reconnect hold so
+   * subsequent live frames flow in order behind the flushed gap.
+   *
+   * A failing sink reports ONCE across the whole tail: the boundary latches on the first failure and every
+   * remaining frame is dropped silently. Those frames stay un-acked in the buffer and replay on the next
+   * attachment. Before ARCH-030 the single report was a side effect of `detach()` running mid-loop; now it
+   * is the boundary's stated contract.
+   */
+  private replay(lastSeq: number): void {
+    const tail = this.buffer.tailAfter(lastSeq);
+    if (tail.kind === 'overrun') {
+      // `resume_gap` is neither stamped nor buffered: the client answers it with a full `get-messages`
+      // refresh, so there is nothing for it to resume from.
+      this.deliverFrame({ type: 'resume_gap' });
+      this.holding = false; // client will full-refresh via get-messages; let live frames flow
+      return;
+    }
+    for (const frame of tail.frames) {
+      this.deliverFrame({ ...frame.message, seq: frame.seq } as TSeqServerMessage);
+    }
+    this.holding = false; // gap flushed in order — resume live forwarding
+  }
+
+  /** The ONE outbound exit from this class. No frame reaches the sink except through the attachment's boundary. */
+  private deliverFrame(message: TServerMessage): void {
+    this.outbound?.(message);
+  }
+
+  /** Detach the failed sink but retain the frame, then notify its attachment owner. */
+  private reportDeliveryError(error: Error, event: string): void {
+    const onDeliveryError = this.onDeliveryError;
+    this.detach();
+    try {
+      onDeliveryError?.(error, event);
+    } catch {
+      // Carrier diagnostics cannot corrupt the retained buffer or the committed operation.
+    }
+  }
+}

package/src/settings-messages.ts

@@ -0,0 +1,103 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+import type { TCommandSurfaceLocality } from '@robota-sdk/agent-interface-command';
+import type { ISettingsSnapshot, TSettingsPatch } from '@robota-sdk/agent-interface-session';
+
+type TSettingsMessage = Extract<TClientMessage, { type: 'get-settings' | 'update-settings' }>;
+
+export function isSettingsMessage(msg: TClientMessage): msg is TSettingsMessage {
+  return msg.type === 'get-settings' || msg.type === 'update-settings';
+}
+
+/** What applying a patch did: the fresh snapshot, or why nothing was written. */
+export type TSettingsUpdateOutcome =
+  | { readonly ok: true; readonly settings: ISettingsSnapshot }
+  | {
+      readonly ok: false;
+      readonly code: 'not_available' | 'invalid' | 'refused' | 'update_failed';
+      readonly message: string;
+    };
+
+/**
+ * #3282 §4a: host-owned read/write for the Settings screen, supplied by the composition root the
+ * same way `IUsageQueryReporters` supplies usage reads — this package only correlates the request
+ * and carries the result. `updateSettings` applies through the SAME function the matching slash
+ * command uses (issue #3282 §4: "one code path, so the behavior matches the TUI"), so whatever a
+ * command would refuse on this surface is refused here too.
+ */
+export interface ISettingsReporter {
+  getSettings(
+    session: IProtocolSession,
+    locality?: TCommandSurfaceLocality,
+  ): ISettingsSnapshot | Promise<ISettingsSnapshot>;
+  /**
+   * Applies through the SAME function the matching slash command uses. `locality` (#3282 §4 part
+   * b-2) is forwarded to that command exactly as the transport received it, so a command that
+   * refuses a remote surface (installing a plugin) refuses identically here.
+   */
+  updateSettings(
+    session: IProtocolSession,
+    patch: TSettingsPatch,
+    locality?: TCommandSurfaceLocality,
+  ): TSettingsUpdateOutcome | Promise<TSettingsUpdateOutcome>;
+}
+
+export function handleSettingsMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TSettingsMessage,
+  reporter: ISettingsReporter | undefined,
+  locality?: TCommandSurfaceLocality,
+): void {
+  if (!reporter) {
+    deliverSettingsError(
+      deliver,
+      msg.requestId,
+      'not_available',
+      'Settings are not available on this host.',
+    );
+    return;
+  }
+  try {
+    if (msg.type === 'get-settings') {
+      void Promise.resolve(reporter.getSettings(session, locality)).then(
+        (settings) => deliver({ type: 'settings', requestId: msg.requestId, settings }),
+        (error) =>
+          deliverSettingsError(deliver, msg.requestId, 'update_failed', failureMessage(error)),
+      );
+      return;
+    }
+    void Promise.resolve(reporter.updateSettings(session, msg.patch, locality)).then(
+      (outcome) => {
+        if (outcome.ok) {
+          deliver({ type: 'settings', requestId: msg.requestId, settings: outcome.settings });
+        } else {
+          deliverSettingsError(deliver, msg.requestId, outcome.code, outcome.message);
+        }
+      },
+      (error) =>
+        deliverSettingsError(deliver, msg.requestId, 'update_failed', failureMessage(error)),
+    );
+  } catch (error) {
+    deliverSettingsError(
+      deliver,
+      msg.requestId,
+      'update_failed',
+      failureMessage(error instanceof Error ? error : String(error)),
+    );
+  }
+}
+
+function deliverSettingsError(
+  deliver: TOutboundDeliver,
+  requestId: string,
+  code: 'not_available' | 'invalid' | 'refused' | 'update_failed',
+  message: string,
+): void {
+  deliver({ type: 'settings_error', requestId, code, message });
+}
+
+function failureMessage(error: Error | string): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/usage-messages.ts

@@ -0,0 +1,195 @@
+import { MAX_INBOUND_FRAME_BYTES } from './message-decoders.js';
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+import type {
+  IPersonalUsageReport,
+  IPersonalUsageRequest,
+  IUsageBySourceReport,
+} from '@robota-sdk/agent-interface-analytics';
+
+type TJsonValue =
+  string | number | boolean | null | readonly TJsonValue[] | { readonly [key: string]: TJsonValue };
+
+export interface IUsageQueryReporters {
+  readonly personalUsageReporter:
+    | ((request: IPersonalUsageRequest) => IPersonalUsageReport | Promise<IPersonalUsageReport>)
+    | undefined;
+  readonly usageReporter:
+    | ((session: IProtocolSession) => IUsageBySourceReport | Promise<IUsageBySourceReport>)
+    | undefined;
+  readonly storedSessionUsageReporter:
+    ((sessionId: string) => IUsageBySourceReport | Promise<IUsageBySourceReport>) | undefined;
+}
+
+export type TMalformedUsageRequest =
+  | { type: 'personal'; requestId: string }
+  | { type: 'stored-session'; requestId: string; sessionId: string };
+
+function isJsonObject(value: TJsonValue): value is { readonly [key: string]: TJsonValue } {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function optionalNonEmptyString(value: TJsonValue | undefined): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export function malformedUsageRequest(data: string): TMalformedUsageRequest | undefined {
+  if (new TextEncoder().encode(data).byteLength > MAX_INBOUND_FRAME_BYTES) return undefined;
+  try {
+    const value = JSON.parse(data) as TJsonValue;
+    if (!isJsonObject(value)) return undefined;
+    const requestId = optionalNonEmptyString(value['requestId']);
+    if (!requestId) return undefined;
+    if (value['type'] === 'get-personal-usage-report') return { type: 'personal', requestId };
+    const sessionId = optionalNonEmptyString(value['sessionId']);
+    return value['type'] === 'get-stored-session-usage-report' && sessionId
+      ? { type: 'stored-session', requestId, sessionId }
+      : undefined;
+  } catch {
+    // allow-fallback: malformed JSON has no trustworthy request id to correlate, so the caller emits
+    // the protocol's uncorrelated decode error without echoing attacker-controlled content.
+    return undefined;
+  }
+}
+
+export function handleUsageQueryMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TClientMessage,
+  reporters: IUsageQueryReporters,
+): boolean {
+  if (msg.type === 'get-personal-usage-report') {
+    handlePersonalUsageQuery(deliver, msg, reporters.personalUsageReporter);
+    return true;
+  }
+  if (msg.type === 'get-stored-session-usage-report') {
+    handleStoredSessionUsageQuery(deliver, msg, reporters.storedSessionUsageReporter);
+    return true;
+  }
+  if (msg.type === 'get-usage-report') {
+    handleCurrentUsageQuery(session, deliver, reporters.usageReporter);
+    return true;
+  }
+  return false;
+}
+
+function handleCurrentUsageQuery(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  reporter: IUsageQueryReporters['usageReporter'],
+): void {
+  if (!reporter) {
+    deliver({
+      type: 'protocol_error',
+      message: 'Per-session usage reporting is not available on this host.',
+    });
+    return;
+  }
+  try {
+    void Promise.resolve(reporter(session)).then(
+      (report) => deliver({ type: 'usage_report', report }),
+      (error) => deliver({ type: 'protocol_error', message: failureMessage(error) }),
+    );
+  } catch (error) {
+    deliver({
+      type: 'protocol_error',
+      message: failureMessage(error instanceof Error ? error : String(error)),
+    });
+  }
+}
+
+function handleStoredSessionUsageQuery(
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'get-stored-session-usage-report' }>,
+  reporter: IUsageQueryReporters['storedSessionUsageReporter'],
+): void {
+  if (!reporter) {
+    deliverStoredSessionUsageError(
+      deliver,
+      msg,
+      'not_available',
+      'Stored-session usage reporting is not available on this host.',
+    );
+    return;
+  }
+  try {
+    void Promise.resolve(reporter(msg.sessionId)).then(
+      (report) =>
+        deliver({
+          type: 'stored_session_usage_report',
+          requestId: msg.requestId,
+          sessionId: msg.sessionId,
+          report,
+        }),
+      (error) =>
+        deliverStoredSessionUsageError(deliver, msg, 'report_failed', failureMessage(error)),
+    );
+  } catch (error) {
+    deliverStoredSessionUsageError(
+      deliver,
+      msg,
+      'report_failed',
+      failureMessage(error instanceof Error ? error : String(error)),
+    );
+  }
+}
+
+function deliverStoredSessionUsageError(
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'get-stored-session-usage-report' }>,
+  code: 'not_available' | 'report_failed',
+  message: string,
+): void {
+  deliver({
+    type: 'stored_session_usage_report_error',
+    requestId: msg.requestId,
+    sessionId: msg.sessionId,
+    code,
+    message,
+  });
+}
+
+function handlePersonalUsageQuery(
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'get-personal-usage-report' }>,
+  reporter: IUsageQueryReporters['personalUsageReporter'],
+): void {
+  if (!reporter) {
+    deliverPersonalUsageError(
+      deliver,
+      msg.requestId,
+      'not_available',
+      'Personal usage reporting is not available on this host.',
+    );
+    return;
+  }
+  try {
+    void Promise.resolve(reporter({ period: msg.period, timezone: msg.timezone })).then(
+      (report) => deliver({ type: 'personal_usage_report', requestId: msg.requestId, report }),
+      (error) =>
+        deliverPersonalUsageError(deliver, msg.requestId, 'report_failed', failureMessage(error)),
+    );
+  } catch (error) {
+    deliverPersonalUsageError(
+      deliver,
+      msg.requestId,
+      'report_failed',
+      failureMessage(error instanceof Error ? error : String(error)),
+    );
+  }
+}
+
+function deliverPersonalUsageError(
+  deliver: TOutboundDeliver,
+  requestId: string,
+  code: 'not_available' | 'report_failed',
+  message: string,
+): void {
+  deliver({ type: 'personal_usage_report_error', requestId, code, message });
+}
+
+function failureMessage(error: Error | TJsonValue | undefined): string {
+  return error instanceof Error ? error.message : String(error);
+}