@robota-sdk/agent-transport 3.0.0-beta.78 → 3.0.0-beta.81

package/src/session-resume-bridge.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 { 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'];
+}
+
+export class SessionResumeBridge {
+  private readonly session: IProtocolSession;
+  private readonly buffer: ResumeBuffer;
+  private driverId?: TDriverId;
+  private readonly reporters: IUsageQueryReporters;
+  private readonly surface?: TUsageSurface;
+  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.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,
+    );
+  }
+
+  /** Unsubscribe from the session (host reconnect-window ceiling / teardown). Idempotent. */
+  public dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    // 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/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);
+}

package/src/wire-messages.ts

@@ -0,0 +1,165 @@
+import type {
+  IPersonalUsageReport,
+  IPersonalUsageRequest,
+  IUsageBySourceReport,
+} from '@robota-sdk/agent-interface-analytics';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type {
+  IBackgroundJobGroupState,
+  IExecutionWorkspaceSnapshot,
+  TBackgroundJobGroupEvent,
+} from '@robota-sdk/agent-interface-execution';
+import type {
+  IBackgroundTaskInput,
+  IBackgroundTaskListFilter,
+  IBackgroundTaskLogCursor,
+  IBackgroundTaskLogPage,
+  IBackgroundTaskState,
+  TBackgroundTaskEvent,
+} from '@robota-sdk/agent-interface-execution';
+import type {
+  IAskRequestEvent,
+  IBranchEvent,
+  IExecutionResult,
+  IContextFileRefreshedEvent,
+  IPermissionRequestEvent,
+  IPromptResolvedEvent,
+  IPlanApprovalEvent,
+  ISessionRenamedEvent,
+  IToolState,
+  IUiIntentEvent,
+  TPermissionResultValue,
+} from '@robota-sdk/agent-interface-session';
+import type { ISessionConversationRead, TDriverId } from '@robota-sdk/agent-interface-session';
+import type { TActionResponse } from '@robota-sdk/agent-interface-transport';
+
+export type TBackgroundControlAction = 'cancel' | 'close' | 'send';
+
+/** Inbound message from client to server. */
+export type TClientMessage =
+  | { type: 'submit'; prompt: string }
+  | { type: 'command'; name: string; args?: string }
+  | { type: 'abort' }
+  | { type: 'cancel-queue' }
+  | { type: 'get-messages' }
+  | { type: 'get-context' }
+  // SELFHOST-004: request the assembled trace/cost read-model (spans + cost-by-source) for the run.
+  | { type: 'get-usage-report' }
+  | {
+      type: 'get-personal-usage-report';
+      requestId: string;
+      period: IPersonalUsageRequest['period'];
+      timezone: string;
+    }
+  | { type: 'get-stored-session-usage-report'; requestId: string; sessionId: string }
+  | { type: 'get-executing' }
+  | { type: 'get-pending' }
+  | { type: 'get-execution-workspace' }
+  | { type: 'get-background-tasks'; filter?: IBackgroundTaskListFilter }
+  | { type: 'get-background-task'; taskId: string }
+  | { type: 'get-background-job-groups' }
+  | { type: 'get-background-job-group'; groupId: string }
+  | { type: 'wait-background-job-group'; groupId: string }
+  | { type: 'cancel-background-task'; taskId: string; reason?: string }
+  | { type: 'close-background-task'; taskId: string }
+  | { type: 'send-background-task'; taskId: string; input: IBackgroundTaskInput }
+  | { type: 'read-background-task-log'; taskId: string; cursor?: IBackgroundTaskLogCursor }
+  // REMOTE-007: a driving client answers a pending permission/ask prompt by id (first answer wins).
+  | { type: 'permission-response'; id: string; result: TPermissionResultValue }
+  | { type: 'ask-response'; id: string; response: TActionResponse }
+  // REMOTE-013 E4 session-resume: `resume` asks the host to replay the tail after `lastSeq` (the last seq the
+  // client applied); `ack` lets the host free its un-acked buffer up to `seq`. Only meaningful post-E3-accept.
+  | { type: 'resume'; lastSeq: number }
+  | { type: 'ack'; seq: number };
+
+/** Outbound message from server to client. */
+export type TServerMessage =
+  // REMOTE-014 E5: turn-authored events optionally carry the ACTIVE turn's `driverId` (co-drive authorship,
+  // display-only). Stamped at `subscribeSessionEvents` from `getActiveDriverId()`; background/goal/memory/
+  // execution-workspace events are NEVER stamped (they are not authored by a driver turn).
+  | { type: 'text_delta'; delta: string; driverId?: TDriverId }
+  | { type: 'user_message'; content: string; driverId?: TDriverId }
+  | { type: 'tool_start'; state: IToolState; driverId?: TDriverId }
+  | { type: 'tool_end'; state: IToolState; driverId?: TDriverId }
+  | { type: 'thinking'; isThinking: boolean; driverId?: TDriverId }
+  | { type: 'complete'; result: IExecutionResult; driverId?: TDriverId }
+  | { type: 'interrupted'; result: IExecutionResult; driverId?: TDriverId }
+  | { type: 'error'; message: string; driverId?: TDriverId }
+  | {
+      type: 'command_result';
+      name: string;
+      message: string;
+      success: boolean;
+      data?: ICommandResult['data'];
+    }
+  | { type: 'messages'; messages: ReturnType<ISessionConversationRead['getMessages']> }
+  | { type: 'context'; state: ReturnType<ISessionConversationRead['getContextState']> }
+  // SELFHOST-004 (P5, TC-08): carry the assembled trace/cost read-model (per-op span timeline +
+  // cost-by-source) across the sidecar boundary — no existing variant carries per-op `durationMs` or
+  // per-source `costUsd`. The GUI renders it renderer-side.
+  | { type: 'usage_report'; report: IUsageBySourceReport }
+  | { type: 'personal_usage_report'; requestId: string; report: IPersonalUsageReport }
+  | {
+      type: 'personal_usage_report_error';
+      requestId: string;
+      code: 'not_available' | 'report_failed';
+      message: string;
+    }
+  | {
+      type: 'stored_session_usage_report';
+      requestId: string;
+      sessionId: string;
+      report: IUsageBySourceReport;
+    }
+  | {
+      type: 'stored_session_usage_report_error';
+      requestId: string;
+      sessionId: string;
+      code: 'not_available' | 'report_failed';
+      message: string;
+    }
+  | { type: 'executing'; executing: boolean }
+  | { type: 'pending'; pending: string | null }
+  | { type: 'execution_workspace_event'; snapshot: IExecutionWorkspaceSnapshot }
+  | { type: 'background_task_event'; event: TBackgroundTaskEvent }
+  | { type: 'background_job_group_event'; event: TBackgroundJobGroupEvent }
+  | { type: 'plan_event'; event: IPlanApprovalEvent }
+  | { type: 'context_file_refreshed'; event: IContextFileRefreshedEvent }
+  | { type: 'branch_event'; event: IBranchEvent }
+  | { type: 'background_tasks'; tasks: IBackgroundTaskState[] }
+  | { type: 'background_task'; taskId: string; task: IBackgroundTaskState | null }
+  | { type: 'background_job_groups'; groups: IBackgroundJobGroupState[] }
+  | { type: 'background_job_group'; groupId: string; group: IBackgroundJobGroupState | null }
+  | { type: 'background_task_log'; taskId: string; page: IBackgroundTaskLogPage }
+  // REMOTE-007: forward the session's transport-neutral prompt events so a remote surface can render +
+  // answer the SAME prompt (permission/ask). `prompt_resolved` dismisses it when another surface won.
+  | { type: 'permission_request'; event: IPermissionRequestEvent }
+  | { type: 'ask_request'; event: IAskRequestEvent }
+  | { type: 'prompt_resolved'; event: IPromptResolvedEvent }
+  // CMD-004 Phase 2: forward command-issued UI intents (same pattern as `ask_request`). The event is
+  // requester-routed — a client renders it only when `event.requesterDriverId` is its own driver id;
+  // an unsupported intent yields an explicit "not available on this surface" notice, never a silent drop.
+  | { type: 'ui_intent'; event: IUiIntentEvent }
+  // CMD-004 Phase 2 Stage E: BROADCAST session events — every attached surface receives them
+  // (co-driving titles/transcripts follow the host-executed rename/clear; never requester-filtered).
+  | { type: 'session_renamed'; event: ISessionRenamedEvent }
+  | { type: 'history_cleared' }
+  | {
+      type: 'background_task_control_result';
+      action: TBackgroundControlAction;
+      taskId: string;
+      success: boolean;
+      message?: string;
+    }
+  | { type: 'protocol_error'; message: string }
+  // REMOTE-013 E4: sent instead of a replay when the client's `lastSeq` predates the host's retained buffer
+  // (overrun) — the client must do a full `get-messages` refresh rather than accept a silent gap.
+  | { type: 'resume_gap' };
+
+/**
+ * REMOTE-013 E4: a server message stamped with its monotonic session sequence number (added by the
+ * {@link SessionResumeBridge} on the reconnectable WebRTC path). Intersecting over the union distributes the
+ * `seq` field onto every variant. The WS localhost path never stamps it (a `type`-dispatching client ignores
+ * an absent/extra `seq`).
+ */
+export type TSeqServerMessage = TServerMessage & { seq: number };

package/dist/node/headless/index.cjs

@@ -1 +0,0 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../headless-xq77JBq0.cjs");exports.HeadlessInteractionChannel=e.t,exports.PrintTerminal=e.a,exports.createHeadlessRunner=e.r,exports.createHeadlessTransport=e.n,exports.promptInput=e.i;

package/dist/node/headless/index.d.ts

@@ -1,2 +0,0 @@
-import { a as IHeadlessRunnerOptions, c as promptInput, i as createHeadlessTransport, l as PrintTerminal, n as IHeadlessInteractionChannelOptions, o as TOutputFormat, r as IHeadlessTransportOptions, s as createHeadlessRunner, t as HeadlessInteractionChannel } from "../index-JTD_xtEQ.js";
-export { HeadlessInteractionChannel, type IHeadlessInteractionChannelOptions, type IHeadlessRunnerOptions, type IHeadlessTransportOptions, PrintTerminal, type TOutputFormat, createHeadlessRunner, createHeadlessTransport, promptInput };

package/dist/node/headless/index.js

@@ -1 +0,0 @@
-import{a as e,i as t,n,r,t as i}from"../headless-DG_MEbf0.js";export{i as HeadlessInteractionChannel,e as PrintTerminal,r as createHeadlessRunner,n as createHeadlessTransport,t as promptInput};

package/dist/node/headless-DG_MEbf0.js

@@ -1,19 +0,0 @@
-import*as e from"node:readline";import{randomUUID as t}from"node:crypto";import{execSync as n}from"node:child_process";import{InteractiveSession as r}from"@robota-sdk/agent-framework";var i=class{write(e){process.stdout.write(e)}writeLine(e){process.stdout.write(e+`
-`)}writeMarkdown(e){process.stdout.write(e)}writeError(e){process.stderr.write(e+`
-`)}prompt(t){return new Promise(n=>{let r=e.createInterface({input:process.stdin,output:process.stdout,terminal:!1,historySize:0});r.question(t,e=>{r.close(),n(e)})})}async select(e,t=0){for(let n=0;n<e.length;n++){let r=n===t?`>`:` `;process.stdout.write(`  ${r} ${n+1}) ${e[n]}\n`)}let n=(await this.prompt(`  Choose [1-${e.length}] (default: ${e[t]}): `)).trim().toLowerCase();if(n===``)return t;let r=parseInt(n,10);return!isNaN(r)&&r>=1&&r<=e.length?r-1:t}spinner(e){return{stop(){},update(){}}}};const a=(e,t=!1)=>new Promise((n,r)=>{process.stdout.write(e);let i=``,a=process.stdin,o=a.isRaw;if(!a.isTTY){r(Error(`Cannot prompt for input: stdin is not a TTY.
-Set your API key via environment variable instead:
-  ANTHROPIC_API_KEY=<key> robota
-  OPENAI_API_KEY=<key> robota`));return}a.setRawMode(!0),a.resume(),a.setEncoding(`utf8`);let s=e=>{for(let r of e)if(r===`\r`||r===`
-`){a.removeListener(`data`,s),a.setRawMode(o??!1),a.pause(),process.stdout.write(`
-`),n(i.trim());return}else r===``||r===`\b`?i.length>0&&(i=i.slice(0,-1),process.stdout.write(`\b \b`)):r===``?(a.removeListener(`data`,s),a.setRawMode(o??!1),a.pause(),process.stdout.write(`
-`),process.exit(0)):r.charCodeAt(0)>=32&&(i+=r,process.stdout.write(t?`*`:r))};a.on(`data`,s)});function o(e){let t=e.trimStart();if(!t.startsWith(`/`))return null;let[n=``,...r]=t.slice(1).split(/\s+/);return n.length===0?null:{name:n,args:r.join(` `)}}async function s(e,t){let n=o(t);if(!n)return{kind:`not-slash`};let r=await e.executeCommand(n.name,n.args);return r?r.effects?.some(e=>e.type===`session-execution-started`)?{kind:`session-execution`}:{kind:`command-result`,result:r}:{kind:`command-result`,result:{message:`Unknown command "/${n.name}".`,success:!1}}}function c(e,n,r){let i=JSON.stringify({type:`stream_event`,event:r,session_id:n(e),uuid:t()});process.stdout.write(i+`
-`)}function l(e,t,n,r){let i=n=>c(e,t,n),a=e=>i({type:`content_block_delta`,delta:{type:`text_delta`,text:e}}),o=e=>i({type:`background_task_event`,background_task_event:e}),s=e=>i({type:`background_job_group_event`,background_job_group_event:e}),l=()=>u(e,{onTextDelta:a,onBackgroundTaskEvent:o,onBackgroundJobGroupEvent:s,onComplete:d,onInterrupted:f,onError:p}),d=i=>{l(),n(t(e),i.response,`success`),r(0)},f=i=>{l(),n(t(e),i.response,`success`),r(0)},p=i=>{l(),n(t(e),``,`error`,i),r(1)};return e.on(`text_delta`,a),e.on(`background_task_event`,o),e.on(`background_job_group_event`,s),e.on(`complete`,d),e.on(`interrupted`,f),e.on(`error`,p),l}function u(e,t){e.off(`text_delta`,t.onTextDelta),e.off(`background_task_event`,t.onBackgroundTaskEvent),e.off(`background_job_group_event`,t.onBackgroundJobGroupEvent),e.off(`complete`,t.onComplete),e.off(`interrupted`,t.onInterrupted),e.off(`error`,t.onError)}function d(e){let{session:t,outputFormat:n}=e;return{run:e=>n===`text`?g(t,e):n===`json`?_(t,e):v(t,e),runGoal:(e,r={})=>f(t,e,r,n)}}function f(e,t,n,r){return new Promise(i=>{let a=()=>{e.off(`complete`,o),e.off(`error`,s),e.off(`goal_event`,c)},o=e=>{e.response&&process.stdout.write(e.response+`
-`)},s=t=>{a(),r===`text`?process.stderr.write(t.message+`
-`):m(h(e),``,`error`,t),i(1)},c=t=>{if(t.type!==`goal_stopped`)return;a();let n=t.goal,o=n.stopReason===`satisfied`,s=o?`Goal satisfied after ${n.iterations} iteration(s).`:`Goal stopped: ${n.stopReason} (after ${n.iterations} iteration(s)).`;r===`text`?(o?process.stdout:process.stderr).write(s+`
-`):m(h(e),s,o?`success`:`error`),i(o?0:2)};e.on(`complete`,o),e.on(`error`,s),e.on(`goal_event`,c),e.setGoal(t,n.maxIterations?{maxIterations:n.maxIterations}:{})})}function p(e){let t=e.message.toLowerCase();return t.includes(`api key`)||t.includes(`no provider`)||t.includes(`provider`)?`config_error`:t.includes(`tool`)||t.includes(`execution`)?`tool_error`:`api_error`}function m(e,t,n,r){let i={type:`result`,result:t,session_id:e,subtype:n};n===`error`&&r!==void 0&&(i.error_code=p(r));let a=JSON.stringify(i);process.stdout.write(a+`
-`)}function h(e){try{return e.getSession().getSessionId()}catch{return``}}function g(e,t){return new Promise(n=>{let r=()=>{e.off(`complete`,i),e.off(`interrupted`,a),e.off(`error`,o)},i=e=>{r(),process.stdout.write(e.response+`
-`),n(0)},a=e=>{r(),e.response&&process.stdout.write(e.response+`
-`),n(0)},o=e=>{r(),process.stderr.write(e.message+`
-`),n(1)};e.on(`complete`,i),e.on(`interrupted`,a),e.on(`error`,o),s(e,t).then(i=>{if(i.kind===`command-result`){r(),process.stdout.write(i.result.message+`
-`),n(+!i.result.success);return}i.kind!==`session-execution`&&e.submit(t)})})}function _(e,t){return new Promise(n=>{let r=()=>{e.off(`complete`,i),e.off(`interrupted`,a),e.off(`error`,o)},i=t=>{r(),m(h(e),t.response,`success`),n(0)},a=t=>{r(),m(h(e),t.response,`success`),n(0)},o=t=>{r(),m(h(e),``,`error`,t),n(1)};e.on(`complete`,i),e.on(`interrupted`,a),e.on(`error`,o),s(e,t).then(i=>{if(i.kind===`command-result`){r(),m(h(e),i.result.message,i.result.success?`success`:`error`),n(+!i.result.success);return}i.kind!==`session-execution`&&e.submit(t)})})}function v(e,t){return new Promise(n=>{let r=l(e,h,m,n);s(e,t).then(i=>{if(i.kind===`command-result`){r(),m(h(e),i.result.message,i.result.success?`success`:`error`),n(+!i.result.success);return}i.kind!==`session-execution`&&e.submit(t)})})}function y(e){let t=null,n=0;return{name:`headless`,attach(e){t=e},async start(){if(!t)throw Error(`No session attached. Call attach() first.`);n=await d({session:t,outputFormat:e.outputFormat}).run(e.prompt)},async stop(){},getExitCode(){return n}}}var b=class{opts;exitCode=0;constructor(e){this.opts=e}async run(e){let t=this.createSession(),n=d({session:t,outputFormat:this.opts.outputFormat});this.exitCode=await n.run(e),await t.shutdown({reason:`prompt_input_exit`,message:`Headless transport complete`})}async runGoal(e,t={}){let n=this.createSession(),r=d({session:n,outputFormat:this.opts.outputFormat});this.exitCode=await r.runGoal(e,t),await n.shutdown({reason:`prompt_input_exit`,message:`Headless goal complete`})}createSession(){let e=this.opts.shellExec??(e=>n(e,{timeout:5e3,encoding:`utf-8`,stdio:`pipe`}).trimEnd());return new r({cwd:this.opts.cwd,provider:this.opts.provider,permissionMode:this.opts.permissionMode??`bypassPermissions`,maxTurns:this.opts.maxTurns,sessionStore:this.opts.sessionStore,resumeSessionId:this.opts.resumeSessionId,forkSession:this.opts.forkSession,sessionName:this.opts.sessionName,bare:this.opts.bare||void 0,allowedTools:this.opts.allowedTools,deniedTools:this.opts.deniedTools,appendSystemPrompt:this.opts.appendSystemPrompt,...this.opts.persona===void 0?{}:{persona:this.opts.persona},...this.opts.systemPrompt?{systemPrompt:this.opts.systemPrompt}:{},backgroundTaskRunners:this.opts.backgroundTaskRunners,subagentRunnerFactory:this.opts.subagentRunnerFactory,commandModules:this.opts.commandModules,commandHostAdapters:this.opts.commandHostAdapters,shellExec:e,agentName:this.opts.agentName,...this.opts.activePresetId===void 0?{}:{activePresetId:this.opts.activePresetId},...this.opts.enableParallelSubagents===void 0?{}:{enableParallelSubagents:this.opts.enableParallelSubagents},...this.opts.selfVerification===void 0?{}:{selfVerification:this.opts.selfVerification}})}getExitCode(){return this.exitCode}};export{i as a,a as i,y as n,d as r,b as t};
-//# sourceMappingURL=headless-DG_MEbf0.js.map