@robota-sdk/agent-transport 3.0.0-beta.83 → 3.0.0-beta.85

package/dist/node/index.d.cts

@@ -1,12 +1,21 @@
 import { IPersonalUsageReport, IPersonalUsageRequest, IUsageBySourceReport, TUsageSurface } from "@robota-sdk/agent-interface-analytics";
-import { ICommandListEntry, ICommandResult, ICommandSkillListEntry } from "@robota-sdk/agent-interface-command";
+import { ICommandListEntry, ICommandResult, ICommandSkillListEntry, TCommandSurfaceLocality } from "@robota-sdk/agent-interface-command";
 import { IBackgroundJobGroupState, IBackgroundTaskInput, IBackgroundTaskListFilter, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, IBackgroundTaskState, IExecutionDetailCursor, IExecutionDetailPage, IExecutionWorkspaceSnapshot, TBackgroundJobGroupEvent, TBackgroundTaskEvent } from "@robota-sdk/agent-interface-execution";
-import { IAskRequestEvent, IBranchEvent, IContextFileRefreshedEvent, IExecutionResult, IPermissionRequestEvent, IPlanApprovalEvent, IPromptResolvedEvent, ISessionBackgroundGroups, ISessionBackgroundTasks, ISessionCommands, ISessionConversationRead, ISessionDirectory, ISessionDriverAttribution, ISessionEvents, ISessionExecutionDetail, ISessionExecutionState, ISessionExecutionWorkspace, ISessionListing, ISessionPromptResolution, ISessionRenamedEvent, ISessionSelfPacedLoopControl, ISessionStatusRead, ISessionStatusSnapshot, ISessionSwitchedEvent, ISessionTurnControl, ISessionTurnSubmission, IToolState, IUiIntentEvent, TDriverId, TPermissionResultValue, TSessionChangeRefusalCode, TTurnSource, TWaitingLoopStopOutcome } from "@robota-sdk/agent-interface-session";
+import { IAskRequestEvent, IBranchEvent, IContextFileRefreshedEvent, IExecutionResult, IModelListGroup, IPermissionRequestEvent, IPlanApprovalEvent, IPromptResolvedEvent, ISessionAgentJobs, ISessionBackgroundGroups, ISessionBackgroundTasks, ISessionCommands, ISessionConversationRead, ISessionDirectory, ISessionDriverAttribution, ISessionEvents, ISessionExecutionDetail, ISessionExecutionState, ISessionExecutionWorkspace, ISessionListing, ISessionProjectRead, ISessionPromptResolution, ISessionRenamedEvent, ISessionSelfPacedLoopControl, ISessionStatusRead, ISessionStatusSnapshot, ISessionSwitchedEvent, ISessionTurnControl, ISessionTurnSubmission, ISettingsSnapshot, IToolState, IUiIntentEvent, TDriverId, TPermissionResultValue, TProjectDiffRead, TProjectMemoryRead, TProjectStatusRead, TSessionChangeRefusalCode, TSessionDeleteRefusalCode, TSettingsPatch, TTurnSource, TWaitingLoopStopOutcome } from "@robota-sdk/agent-interface-session";
 import { IBinaryFrame, IChannelEventFrame, TActionResponse, TChannelReceiveResult } from "@robota-sdk/agent-interface-transport";
 import { IHandoffIntegrity, IPeerMessage, IPeerMessageAck, TPeerDeliveryState } from "@robota-sdk/agent-interface-session-mobility";
 //#region src/wire-messages.d.ts
 type TBackgroundControlAction = 'cancel' | 'close' | 'send';
 type THistoryEntry = ReturnType<ISessionConversationRead['getFullHistory']>[number];
+/**
+ * #3282 §4: one agent the switcher can offer. `definedIn` is a plain-words location — a discovered
+ * file's path, or "Built-in" — never a raw internal id.
+ */
+interface IWireAgentDefinitionSummary {
+  name: string;
+  description: string;
+  definedIn: string;
+}
 /**
  * #3189: one entry of the session's full history as it crosses the wire. The same record the session
  * keeps, except that `timestamp` is an ISO 8601 string: a `Date` does not survive JSON, and a
@@ -47,6 +56,12 @@ type TClientMessage = {
   type: 'get-commands';
 } | {
   type: 'get-status';
+} | {
+  type: 'list-models';
+  requestId: string;
+} | {
+  type: 'get-agent-definitions';
+  requestId: string;
 } | {
   type: 'list-sessions';
   requestId: string;
@@ -57,6 +72,15 @@ type TClientMessage = {
   type: 'switch-session';
   sessionId: string;
   requestId?: string;
+} | {
+  type: 'rename-session';
+  sessionId: string;
+  name: string;
+  requestId: string;
+} | {
+  type: 'delete-session';
+  sessionId: string;
+  requestId: string;
 } | {
   type: 'get-usage-report';
 } | {
@@ -82,6 +106,16 @@ type TClientMessage = {
 } | {
   type: 'stop-waiting-loop';
   requestId: string;
+} | {
+  type: 'project-status';
+  requestId: string;
+} | {
+  type: 'project-diff';
+  requestId: string;
+  path: string;
+} | {
+  type: 'project-memory';
+  requestId: string;
 } | {
   type: 'get-background-tasks';
   filter?: IBackgroundTaskListFilter;
@@ -125,6 +159,13 @@ type TClientMessage = {
 } | {
   type: 'ack';
   seq: number;
+} | {
+  type: 'get-settings';
+  requestId: string;
+} | {
+  type: 'update-settings';
+  requestId: string;
+  patch: TSettingsPatch;
 };
 /** Outbound message from server to client. */
 type TServerMessage = {
@@ -157,7 +198,24 @@ type TServerMessage = {
   driverId?: TDriverId;
 } | {
   type: 'error';
+  /** The raw failure text — kept for a "Details" disclosure; never the whole story on its own. */
   message: string;
+  /**
+   * What kind of failure this was, when it's known — so a renderer can say what happened and
+   * what to do next in plain words instead of showing `message` verbatim (#3289 §3). Additive:
+   * absent for a session error this classification does not recognize (unchanged behavior).
+   */
+  code?: 'auth' | 'rate_limit' | 'model_unavailable' | 'network' | 'provider';
+  /** The provider/profile name the failure came from, when `code` names one. */
+  provider?: string;
+  /** For `code: 'rate_limit'`, how long until a retry may succeed, when the provider said so. */
+  retryAfterSeconds?: number;
+  /**
+   * For `code: 'model_unavailable'`, the model the failed request tried — captured at the moment
+   * of failure so a renderer never has to fall back to whatever model is live by the time it
+   * draws this notice (which may already be a different one the person switched to).
+   */
+  model?: string;
   driverId?: TDriverId;
 } | {
   type: 'command_result';
@@ -170,6 +228,20 @@ type TServerMessage = {
 } | {
   type: 'messages';
   messages: ReturnType<ISessionConversationRead['getMessages']>;
+  /**
+   * #3288 §2: the SAME history, projected into display segments (text runs and finished tool
+   * calls, diffs included) — so a reload/reconnect/resume replay shows tool rows instead of bare
+   * text. Optional so an older host that has not grown `getMessagesDisplay()` yet still sends a
+   * valid frame; a client without this field falls back to `messages`-only (text bubbles), the
+   * same as before this existed.
+   */
+  display?: ReturnType<ISessionConversationRead['getMessagesDisplay']>;
+  /**
+   * #3289 §3: this connection's own server-assigned driver id, carried on the first frame every
+   * connection already gets — so a client can tell its OWN turns from a co-driver's instead of
+   * treating everything but the literal `'owner'` id as someone else (REMOTE-014 E5 display-only).
+   */
+  driverId?: TDriverId;
 } | {
   type: 'history';
   startIndex: number;
@@ -190,6 +262,17 @@ type TServerMessage = {
 } | {
   type: 'session_status';
   status: ISessionStatusSnapshot;
+} | {
+  type: 'model_list';
+  requestId: string;
+  groups: readonly IModelListGroup[];
+  currentProfile?: string;
+  currentModel: string;
+} | {
+  type: 'agent_definitions';
+  requestId: string;
+  agents: readonly IWireAgentDefinitionSummary[];
+  current: string;
 } | {
   type: 'sessions';
   requestId: string;
@@ -207,6 +290,24 @@ type TServerMessage = {
   code: TSessionChangeRefusalCode;
   message: string;
   requestId?: string;
+} | {
+  type: 'session_renamed_in_list';
+  requestId: string;
+  sessionId: string;
+  name: string;
+} | {
+  type: 'session_rename_failed';
+  requestId: string;
+  message: string;
+} | {
+  type: 'session_deleted';
+  requestId: string;
+  sessionId: string;
+} | {
+  type: 'session_delete_failed';
+  requestId: string;
+  code: TSessionDeleteRefusalCode;
+  message: string;
 } | {
   type: 'usage_report';
   report: IUsageBySourceReport;
@@ -252,6 +353,18 @@ type TServerMessage = {
   type: 'waiting_loop_stop';
   requestId: string;
   outcome: TWaitingLoopStopOutcome;
+} | {
+  type: 'project_status';
+  requestId: string;
+  result: TProjectStatusRead;
+} | {
+  type: 'project_diff';
+  requestId: string;
+  result: TProjectDiffRead;
+} | {
+  type: 'project_memory';
+  requestId: string;
+  result: TProjectMemoryRead;
 } | {
   type: 'background_task_event';
   event: TBackgroundTaskEvent;
@@ -314,6 +427,15 @@ type TServerMessage = {
   requestId?: string;
 } | {
   type: 'resume_gap';
+} | {
+  type: 'settings';
+  requestId: string;
+  settings: ISettingsSnapshot;
+} | {
+  type: 'settings_error';
+  requestId: string;
+  code: 'not_available' | 'invalid' | 'refused' | 'update_failed';
+  message: string;
 };
 /**
  * REMOTE-013 E4: a server message stamped with its monotonic session sequence number (added by the
@@ -416,7 +538,48 @@ declare function createOutboundDelivery(send: (message: TServerMessage) => void,
 //#endregion
 //#region src/protocol-session.d.ts
 /** Session roles required by the shared WebSocket/WebRTC protocol. */
-interface IProtocolSession extends ISessionTurnSubmission, ISessionTurnControl, ISessionCommands, ISessionStatusRead, ISessionEvents, ISessionPromptResolution, ISessionConversationRead, ISessionExecutionState, ISessionDriverAttribution, ISessionBackgroundTasks, ISessionBackgroundGroups, ISessionExecutionWorkspace, ISessionExecutionDetail, ISessionSelfPacedLoopControl {}
+interface IProtocolSession extends ISessionTurnSubmission, ISessionTurnControl, ISessionCommands, ISessionStatusRead, ISessionEvents, ISessionPromptResolution, ISessionConversationRead, ISessionExecutionState, ISessionDriverAttribution, ISessionBackgroundTasks, ISessionBackgroundGroups, ISessionExecutionWorkspace, ISessionExecutionDetail, ISessionSelfPacedLoopControl, ISessionAgentJobs {}
+/**
+ * #3282 §4c: a protocol session that ALSO answers the Project panel's reads. `Partial` (not a fourth
+ * mandatory role on {@link IProtocolSession} itself) deliberately: every existing test double and
+ * every other host that builds an `IProtocolSession` keeps type-checking unchanged, and the panel's
+ * three methods are runtime-probed (`typeof session.readProjectStatus === 'function'`) rather than
+ * assumed — `InteractiveSession` (the one production implementation) provides all three, satisfying
+ * this type with no further wiring.
+ */
+type TProjectReadCapableSession = IProtocolSession & Partial<ISessionProjectRead>;
+//#endregion
+//#region src/settings-messages.d.ts
+type TSettingsMessage = Extract<TClientMessage, {
+  type: 'get-settings' | 'update-settings';
+}>;
+declare function isSettingsMessage(msg: TClientMessage): msg is TSettingsMessage;
+/** What applying a patch did: the fresh snapshot, or why nothing was written. */
+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.
+ */
+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>;
+}
+declare function handleSettingsMessage(session: IProtocolSession, deliver: TOutboundDeliver, msg: TSettingsMessage, reporter: ISettingsReporter | undefined, locality?: TCommandSurfaceLocality): void;
 //#endregion
 //#region src/usage-messages.d.ts
 interface IUsageQueryReporters {
@@ -467,8 +630,8 @@ declare const PROTOCOL_SESSION_EVENT_CLASSIFICATION: {
  */
 type TSessionSurfaceRole = 'drive' | 'observe';
 interface ISessionMessageHandlerOptions {
-  /** IProtocolSession to expose. */
-  session: IProtocolSession;
+  /** IProtocolSession to expose — `Partial<ISessionProjectRead>` is probed, not assumed (#3282 §4c). */
+  session: TProjectReadCapableSession;
   /**
    * ARCH-030: the CARRIER's connection-scoped outbound delivery boundary — not a raw `send`, and not a
    * `send` plus an error callback for this handler to assemble into one. The carrier owns both the sink
@@ -495,6 +658,15 @@ interface ISessionMessageHandlerOptions {
   storedSessionUsageReporter?: NonNullable<IUsageQueryReporters['storedSessionUsageReporter']>;
   /** Host-owned session directory (#3189): list, start and switch the host's sessions. */
   sessionDirectory?: ISessionDirectory;
+  /** #3282 §4a: host-owned read/write for the GUI Settings screen. */
+  settingsReporter?: ISettingsReporter;
+  /**
+   * #3282 §4 part b-2: carrier-decided, like `role` — whether THIS carrier's connections are
+   * provably on this machine. The loopback WS carrier is `'local'`; the device-mesh/WebRTC carrier
+   * sets `'remote'`. Absent → `'local'`, forwarded to `executeCommand` and the settings reporter so a
+   * command that runs code from outside the session (installing a plugin) can refuse a remote device.
+   */
+  commandSurfaceLocality?: TCommandSurfaceLocality;
 }
 /**
  * Create a carrier-neutral message handler for an IProtocolSession.
@@ -645,6 +817,8 @@ interface ISessionResumeBridgeOptions {
   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;
 }
 declare class SessionResumeBridge {
   private readonly session;
@@ -652,6 +826,7 @@ declare class SessionResumeBridge {
   private driverId?;
   private readonly reporters;
   private readonly surface?;
+  private readonly commandSurfaceLocality?;
   private readonly unsubscribe;
   private onDeliveryError?;
   /**
@@ -879,5 +1054,5 @@ declare class HandoffChunkAssembler {
  */
 declare function chunkCountFor(integrity: IHandoffIntegrity, maxChunkBytes?: number): number;
 //#endregion
-export { ATTACHED_SURFACE_MAX_PENDING_BYTES, CHANNEL_FRAME_MAGIC, CHANNEL_FRAME_VERSION, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_PENDING_BYTES, DEFAULT_MAX_PENDING_MS, HandoffChunkAssembler, type IAttachOptions, type IBufferedFrame, type IChunkResult, type IHandoffChunk, type IPeerMessageLedger, type IPeerMessageRejection, type IPeerMessageVerdict, type IPendingStallClock, type IProtocolSession, type IResumeBufferOptions, type ISessionMessageHandlerOptions, type ISessionResumeBridgeOptions, type IWireHistoryEntry, MAX_INBOUND_FRAME_BYTES, PROTOCOL_SESSION_EVENT_CLASSIFICATION, ResumeBuffer, SessionResumeBridge, type TChunkOutcome, type TChunkRejection, type TClientMessage, type TDeliveryErrorHandler, type TMessageDecodeResult, type TOutboundDeliver, type TProtocolSessionEventClassification, type TResumeSink, type TResumeTail, type TSeqServerMessage, type TServerMessage, type TSessionSurfaceRole, type TWireExecutionResult, acknowledgePeerMessage, admitPeerMessage, chunkCountFor, chunkHandoffPayload, createOutboundDelivery, createPeerMessageLedger, createPendingStallClock, createSessionMessageHandler, decodeChannelFrame, decodeClientMessage, decodeFrame, decodeServerMessage, encodeBinaryFrame, encodeChannelEventFrame, forgetPeerOrigin, isChannelFrame, isObserverMessageType, isOverPendingBudget };
+export { ATTACHED_SURFACE_MAX_PENDING_BYTES, CHANNEL_FRAME_MAGIC, CHANNEL_FRAME_VERSION, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_PENDING_BYTES, DEFAULT_MAX_PENDING_MS, HandoffChunkAssembler, type IAttachOptions, type IBufferedFrame, type IChunkResult, type IHandoffChunk, type IPeerMessageLedger, type IPeerMessageRejection, type IPeerMessageVerdict, type IPendingStallClock, type IProtocolSession, type IResumeBufferOptions, type ISessionMessageHandlerOptions, type ISessionResumeBridgeOptions, type ISettingsReporter, type IWireAgentDefinitionSummary, type IWireHistoryEntry, MAX_INBOUND_FRAME_BYTES, PROTOCOL_SESSION_EVENT_CLASSIFICATION, ResumeBuffer, SessionResumeBridge, type TChunkOutcome, type TChunkRejection, type TClientMessage, type TDeliveryErrorHandler, type TMessageDecodeResult, type TOutboundDeliver, type TProtocolSessionEventClassification, type TResumeSink, type TResumeTail, type TSeqServerMessage, type TServerMessage, type TSessionSurfaceRole, type TSettingsUpdateOutcome, type TWireExecutionResult, acknowledgePeerMessage, admitPeerMessage, chunkCountFor, chunkHandoffPayload, createOutboundDelivery, createPeerMessageLedger, createPendingStallClock, createSessionMessageHandler, decodeChannelFrame, decodeClientMessage, decodeFrame, decodeServerMessage, encodeBinaryFrame, encodeChannelEventFrame, forgetPeerOrigin, handleSettingsMessage, isChannelFrame, isObserverMessageType, isOverPendingBudget, isSettingsMessage };
 //# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/wire-messages.ts","../../src/outbound-delivery.ts","../../src/protocol-session.ts","../../src/usage-messages.ts","../../src/session-events.ts","../../src/session-message-handler.ts","../../src/observer-messages.ts","../../src/message-decoders.ts","../../src/resume-buffer.ts","../../src/channel-frames.ts","../../src/session-resume-bridge.ts","../../src/peer-message-ledger.ts","../../src/handoff-chunking.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/wire-messages.ts","../../src/outbound-delivery.ts","../../src/protocol-session.ts","../../src/settings-messages.ts","../../src/usage-messages.ts","../../src/session-events.ts","../../src/session-message-handler.ts","../../src/observer-messages.ts","../../src/message-decoders.ts","../../src/resume-buffer.ts","../../src/channel-frames.ts","../../src/session-resume-bridge.ts","../../src/peer-message-ledger.ts","../../src/handoff-chunking.ts"],"mappings":"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"}

package/dist/node/index.d.ts

@@ -1,12 +1,21 @@
-import { IAskRequestEvent, IBranchEvent, IContextFileRefreshedEvent, IExecutionResult, IPermissionRequestEvent, IPlanApprovalEvent, IPromptResolvedEvent, ISessionBackgroundGroups, ISessionBackgroundTasks, ISessionCommands, ISessionConversationRead, ISessionDirectory, ISessionDriverAttribution, ISessionEvents, ISessionExecutionDetail, ISessionExecutionState, ISessionExecutionWorkspace, ISessionListing, ISessionPromptResolution, ISessionRenamedEvent, ISessionSelfPacedLoopControl, ISessionStatusRead, ISessionStatusSnapshot, ISessionSwitchedEvent, ISessionTurnControl, ISessionTurnSubmission, IToolState, IUiIntentEvent, TDriverId, TPermissionResultValue, TSessionChangeRefusalCode, TTurnSource, TWaitingLoopStopOutcome } from "@robota-sdk/agent-interface-session";
+import { IAskRequestEvent, IBranchEvent, IContextFileRefreshedEvent, IExecutionResult, IModelListGroup, IPermissionRequestEvent, IPlanApprovalEvent, IPromptResolvedEvent, ISessionAgentJobs, ISessionBackgroundGroups, ISessionBackgroundTasks, ISessionCommands, ISessionConversationRead, ISessionDirectory, ISessionDriverAttribution, ISessionEvents, ISessionExecutionDetail, ISessionExecutionState, ISessionExecutionWorkspace, ISessionListing, ISessionProjectRead, ISessionPromptResolution, ISessionRenamedEvent, ISessionSelfPacedLoopControl, ISessionStatusRead, ISessionStatusSnapshot, ISessionSwitchedEvent, ISessionTurnControl, ISessionTurnSubmission, ISettingsSnapshot, IToolState, IUiIntentEvent, TDriverId, TPermissionResultValue, TProjectDiffRead, TProjectMemoryRead, TProjectStatusRead, TSessionChangeRefusalCode, TSessionDeleteRefusalCode, TSettingsPatch, TTurnSource, TWaitingLoopStopOutcome } from "@robota-sdk/agent-interface-session";
 import { IPersonalUsageReport, IPersonalUsageRequest, IUsageBySourceReport, TUsageSurface } from "@robota-sdk/agent-interface-analytics";
-import { ICommandListEntry, ICommandResult, ICommandSkillListEntry } from "@robota-sdk/agent-interface-command";
+import { ICommandListEntry, ICommandResult, ICommandSkillListEntry, TCommandSurfaceLocality } from "@robota-sdk/agent-interface-command";
 import { IBackgroundJobGroupState, IBackgroundTaskInput, IBackgroundTaskListFilter, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, IBackgroundTaskState, IExecutionDetailCursor, IExecutionDetailPage, IExecutionWorkspaceSnapshot, TBackgroundJobGroupEvent, TBackgroundTaskEvent } from "@robota-sdk/agent-interface-execution";
 import { IBinaryFrame, IChannelEventFrame, TActionResponse, TChannelReceiveResult } from "@robota-sdk/agent-interface-transport";
 import { IHandoffIntegrity, IPeerMessage, IPeerMessageAck, TPeerDeliveryState } from "@robota-sdk/agent-interface-session-mobility";
 //#region src/wire-messages.d.ts
 type TBackgroundControlAction = 'cancel' | 'close' | 'send';
 type THistoryEntry = ReturnType<ISessionConversationRead['getFullHistory']>[number];
+/**
+ * #3282 §4: one agent the switcher can offer. `definedIn` is a plain-words location — a discovered
+ * file's path, or "Built-in" — never a raw internal id.
+ */
+interface IWireAgentDefinitionSummary {
+  name: string;
+  description: string;
+  definedIn: string;
+}
 /**
  * #3189: one entry of the session's full history as it crosses the wire. The same record the session
  * keeps, except that `timestamp` is an ISO 8601 string: a `Date` does not survive JSON, and a
@@ -47,6 +56,12 @@ type TClientMessage = {
   type: 'get-commands';
 } | {
   type: 'get-status';
+} | {
+  type: 'list-models';
+  requestId: string;
+} | {
+  type: 'get-agent-definitions';
+  requestId: string;
 } | {
   type: 'list-sessions';
   requestId: string;
@@ -57,6 +72,15 @@ type TClientMessage = {
   type: 'switch-session';
   sessionId: string;
   requestId?: string;
+} | {
+  type: 'rename-session';
+  sessionId: string;
+  name: string;
+  requestId: string;
+} | {
+  type: 'delete-session';
+  sessionId: string;
+  requestId: string;
 } | {
   type: 'get-usage-report';
 } | {
@@ -82,6 +106,16 @@ type TClientMessage = {
 } | {
   type: 'stop-waiting-loop';
   requestId: string;
+} | {
+  type: 'project-status';
+  requestId: string;
+} | {
+  type: 'project-diff';
+  requestId: string;
+  path: string;
+} | {
+  type: 'project-memory';
+  requestId: string;
 } | {
   type: 'get-background-tasks';
   filter?: IBackgroundTaskListFilter;
@@ -125,6 +159,13 @@ type TClientMessage = {
 } | {
   type: 'ack';
   seq: number;
+} | {
+  type: 'get-settings';
+  requestId: string;
+} | {
+  type: 'update-settings';
+  requestId: string;
+  patch: TSettingsPatch;
 };
 /** Outbound message from server to client. */
 type TServerMessage = {
@@ -157,7 +198,24 @@ type TServerMessage = {
   driverId?: TDriverId;
 } | {
   type: 'error';
+  /** The raw failure text — kept for a "Details" disclosure; never the whole story on its own. */
   message: string;
+  /**
+   * What kind of failure this was, when it's known — so a renderer can say what happened and
+   * what to do next in plain words instead of showing `message` verbatim (#3289 §3). Additive:
+   * absent for a session error this classification does not recognize (unchanged behavior).
+   */
+  code?: 'auth' | 'rate_limit' | 'model_unavailable' | 'network' | 'provider';
+  /** The provider/profile name the failure came from, when `code` names one. */
+  provider?: string;
+  /** For `code: 'rate_limit'`, how long until a retry may succeed, when the provider said so. */
+  retryAfterSeconds?: number;
+  /**
+   * For `code: 'model_unavailable'`, the model the failed request tried — captured at the moment
+   * of failure so a renderer never has to fall back to whatever model is live by the time it
+   * draws this notice (which may already be a different one the person switched to).
+   */
+  model?: string;
   driverId?: TDriverId;
 } | {
   type: 'command_result';
@@ -170,6 +228,20 @@ type TServerMessage = {
 } | {
   type: 'messages';
   messages: ReturnType<ISessionConversationRead['getMessages']>;
+  /**
+   * #3288 §2: the SAME history, projected into display segments (text runs and finished tool
+   * calls, diffs included) — so a reload/reconnect/resume replay shows tool rows instead of bare
+   * text. Optional so an older host that has not grown `getMessagesDisplay()` yet still sends a
+   * valid frame; a client without this field falls back to `messages`-only (text bubbles), the
+   * same as before this existed.
+   */
+  display?: ReturnType<ISessionConversationRead['getMessagesDisplay']>;
+  /**
+   * #3289 §3: this connection's own server-assigned driver id, carried on the first frame every
+   * connection already gets — so a client can tell its OWN turns from a co-driver's instead of
+   * treating everything but the literal `'owner'` id as someone else (REMOTE-014 E5 display-only).
+   */
+  driverId?: TDriverId;
 } | {
   type: 'history';
   startIndex: number;
@@ -190,6 +262,17 @@ type TServerMessage = {
 } | {
   type: 'session_status';
   status: ISessionStatusSnapshot;
+} | {
+  type: 'model_list';
+  requestId: string;
+  groups: readonly IModelListGroup[];
+  currentProfile?: string;
+  currentModel: string;
+} | {
+  type: 'agent_definitions';
+  requestId: string;
+  agents: readonly IWireAgentDefinitionSummary[];
+  current: string;
 } | {
   type: 'sessions';
   requestId: string;
@@ -207,6 +290,24 @@ type TServerMessage = {
   code: TSessionChangeRefusalCode;
   message: string;
   requestId?: string;
+} | {
+  type: 'session_renamed_in_list';
+  requestId: string;
+  sessionId: string;
+  name: string;
+} | {
+  type: 'session_rename_failed';
+  requestId: string;
+  message: string;
+} | {
+  type: 'session_deleted';
+  requestId: string;
+  sessionId: string;
+} | {
+  type: 'session_delete_failed';
+  requestId: string;
+  code: TSessionDeleteRefusalCode;
+  message: string;
 } | {
   type: 'usage_report';
   report: IUsageBySourceReport;
@@ -252,6 +353,18 @@ type TServerMessage = {
   type: 'waiting_loop_stop';
   requestId: string;
   outcome: TWaitingLoopStopOutcome;
+} | {
+  type: 'project_status';
+  requestId: string;
+  result: TProjectStatusRead;
+} | {
+  type: 'project_diff';
+  requestId: string;
+  result: TProjectDiffRead;
+} | {
+  type: 'project_memory';
+  requestId: string;
+  result: TProjectMemoryRead;
 } | {
   type: 'background_task_event';
   event: TBackgroundTaskEvent;
@@ -314,6 +427,15 @@ type TServerMessage = {
   requestId?: string;
 } | {
   type: 'resume_gap';
+} | {
+  type: 'settings';
+  requestId: string;
+  settings: ISettingsSnapshot;
+} | {
+  type: 'settings_error';
+  requestId: string;
+  code: 'not_available' | 'invalid' | 'refused' | 'update_failed';
+  message: string;
 };
 /**
  * REMOTE-013 E4: a server message stamped with its monotonic session sequence number (added by the
@@ -416,7 +538,48 @@ declare function createOutboundDelivery(send: (message: TServerMessage) => void,
 //#endregion
 //#region src/protocol-session.d.ts
 /** Session roles required by the shared WebSocket/WebRTC protocol. */
-interface IProtocolSession extends ISessionTurnSubmission, ISessionTurnControl, ISessionCommands, ISessionStatusRead, ISessionEvents, ISessionPromptResolution, ISessionConversationRead, ISessionExecutionState, ISessionDriverAttribution, ISessionBackgroundTasks, ISessionBackgroundGroups, ISessionExecutionWorkspace, ISessionExecutionDetail, ISessionSelfPacedLoopControl {}
+interface IProtocolSession extends ISessionTurnSubmission, ISessionTurnControl, ISessionCommands, ISessionStatusRead, ISessionEvents, ISessionPromptResolution, ISessionConversationRead, ISessionExecutionState, ISessionDriverAttribution, ISessionBackgroundTasks, ISessionBackgroundGroups, ISessionExecutionWorkspace, ISessionExecutionDetail, ISessionSelfPacedLoopControl, ISessionAgentJobs {}
+/**
+ * #3282 §4c: a protocol session that ALSO answers the Project panel's reads. `Partial` (not a fourth
+ * mandatory role on {@link IProtocolSession} itself) deliberately: every existing test double and
+ * every other host that builds an `IProtocolSession` keeps type-checking unchanged, and the panel's
+ * three methods are runtime-probed (`typeof session.readProjectStatus === 'function'`) rather than
+ * assumed — `InteractiveSession` (the one production implementation) provides all three, satisfying
+ * this type with no further wiring.
+ */
+type TProjectReadCapableSession = IProtocolSession & Partial<ISessionProjectRead>;
+//#endregion
+//#region src/settings-messages.d.ts
+type TSettingsMessage = Extract<TClientMessage, {
+  type: 'get-settings' | 'update-settings';
+}>;
+declare function isSettingsMessage(msg: TClientMessage): msg is TSettingsMessage;
+/** What applying a patch did: the fresh snapshot, or why nothing was written. */
+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.
+ */
+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>;
+}
+declare function handleSettingsMessage(session: IProtocolSession, deliver: TOutboundDeliver, msg: TSettingsMessage, reporter: ISettingsReporter | undefined, locality?: TCommandSurfaceLocality): void;
 //#endregion
 //#region src/usage-messages.d.ts
 interface IUsageQueryReporters {
@@ -467,8 +630,8 @@ declare const PROTOCOL_SESSION_EVENT_CLASSIFICATION: {
  */
 type TSessionSurfaceRole = 'drive' | 'observe';
 interface ISessionMessageHandlerOptions {
-  /** IProtocolSession to expose. */
-  session: IProtocolSession;
+  /** IProtocolSession to expose — `Partial<ISessionProjectRead>` is probed, not assumed (#3282 §4c). */
+  session: TProjectReadCapableSession;
   /**
    * ARCH-030: the CARRIER's connection-scoped outbound delivery boundary — not a raw `send`, and not a
    * `send` plus an error callback for this handler to assemble into one. The carrier owns both the sink
@@ -495,6 +658,15 @@ interface ISessionMessageHandlerOptions {
   storedSessionUsageReporter?: NonNullable<IUsageQueryReporters['storedSessionUsageReporter']>;
   /** Host-owned session directory (#3189): list, start and switch the host's sessions. */
   sessionDirectory?: ISessionDirectory;
+  /** #3282 §4a: host-owned read/write for the GUI Settings screen. */
+  settingsReporter?: ISettingsReporter;
+  /**
+   * #3282 §4 part b-2: carrier-decided, like `role` — whether THIS carrier's connections are
+   * provably on this machine. The loopback WS carrier is `'local'`; the device-mesh/WebRTC carrier
+   * sets `'remote'`. Absent → `'local'`, forwarded to `executeCommand` and the settings reporter so a
+   * command that runs code from outside the session (installing a plugin) can refuse a remote device.
+   */
+  commandSurfaceLocality?: TCommandSurfaceLocality;
 }
 /**
  * Create a carrier-neutral message handler for an IProtocolSession.
@@ -645,6 +817,8 @@ interface ISessionResumeBridgeOptions {
   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;
 }
 declare class SessionResumeBridge {
   private readonly session;
@@ -652,6 +826,7 @@ declare class SessionResumeBridge {
   private driverId?;
   private readonly reporters;
   private readonly surface?;
+  private readonly commandSurfaceLocality?;
   private readonly unsubscribe;
   private onDeliveryError?;
   /**
@@ -879,5 +1054,5 @@ declare class HandoffChunkAssembler {
  */
 declare function chunkCountFor(integrity: IHandoffIntegrity, maxChunkBytes?: number): number;
 //#endregion
-export { ATTACHED_SURFACE_MAX_PENDING_BYTES, CHANNEL_FRAME_MAGIC, CHANNEL_FRAME_VERSION, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_PENDING_BYTES, DEFAULT_MAX_PENDING_MS, HandoffChunkAssembler, type IAttachOptions, type IBufferedFrame, type IChunkResult, type IHandoffChunk, type IPeerMessageLedger, type IPeerMessageRejection, type IPeerMessageVerdict, type IPendingStallClock, type IProtocolSession, type IResumeBufferOptions, type ISessionMessageHandlerOptions, type ISessionResumeBridgeOptions, type IWireHistoryEntry, MAX_INBOUND_FRAME_BYTES, PROTOCOL_SESSION_EVENT_CLASSIFICATION, ResumeBuffer, SessionResumeBridge, type TChunkOutcome, type TChunkRejection, type TClientMessage, type TDeliveryErrorHandler, type TMessageDecodeResult, type TOutboundDeliver, type TProtocolSessionEventClassification, type TResumeSink, type TResumeTail, type TSeqServerMessage, type TServerMessage, type TSessionSurfaceRole, type TWireExecutionResult, acknowledgePeerMessage, admitPeerMessage, chunkCountFor, chunkHandoffPayload, createOutboundDelivery, createPeerMessageLedger, createPendingStallClock, createSessionMessageHandler, decodeChannelFrame, decodeClientMessage, decodeFrame, decodeServerMessage, encodeBinaryFrame, encodeChannelEventFrame, forgetPeerOrigin, isChannelFrame, isObserverMessageType, isOverPendingBudget };
+export { ATTACHED_SURFACE_MAX_PENDING_BYTES, CHANNEL_FRAME_MAGIC, CHANNEL_FRAME_VERSION, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_PENDING_BYTES, DEFAULT_MAX_PENDING_MS, HandoffChunkAssembler, type IAttachOptions, type IBufferedFrame, type IChunkResult, type IHandoffChunk, type IPeerMessageLedger, type IPeerMessageRejection, type IPeerMessageVerdict, type IPendingStallClock, type IProtocolSession, type IResumeBufferOptions, type ISessionMessageHandlerOptions, type ISessionResumeBridgeOptions, type ISettingsReporter, type IWireAgentDefinitionSummary, type IWireHistoryEntry, MAX_INBOUND_FRAME_BYTES, PROTOCOL_SESSION_EVENT_CLASSIFICATION, ResumeBuffer, SessionResumeBridge, type TChunkOutcome, type TChunkRejection, type TClientMessage, type TDeliveryErrorHandler, type TMessageDecodeResult, type TOutboundDeliver, type TProtocolSessionEventClassification, type TResumeSink, type TResumeTail, type TSeqServerMessage, type TServerMessage, type TSessionSurfaceRole, type TSettingsUpdateOutcome, type TWireExecutionResult, acknowledgePeerMessage, admitPeerMessage, chunkCountFor, chunkHandoffPayload, createOutboundDelivery, createPeerMessageLedger, createPendingStallClock, createSessionMessageHandler, decodeChannelFrame, decodeClientMessage, decodeFrame, decodeServerMessage, encodeBinaryFrame, encodeChannelEventFrame, forgetPeerOrigin, handleSettingsMessage, isChannelFrame, isObserverMessageType, isOverPendingBudget, isSettingsMessage };
 //# sourceMappingURL=index.d.ts.map