@robota-sdk/agent-cli 3.0.0-beta.82 → 3.0.0-beta.84

package/dist/node/index.d.ts

@@ -3,7 +3,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import "@modelcontextprotocol/sdk/shared/auth.js";
 import "@modelcontextprotocol/sdk/types.js";
 import "@modelcontextprotocol/sdk/shared/transport.js";
-//#region ../agent-core/dist/node/types-gNrckgFE.d.ts
+//#region ../agent-core/dist/node/types-BQ-sKCQS.d.ts
 //#region src/interfaces/universal-value.d.ts
 /**
  * Universal value type axis (recursive, JSON-like + Date).
@@ -91,7 +91,7 @@ interface IOutboundTraceContext {
 /** Claude Code compatible session end reasons. */
 type TSessionEndReason = 'clear' | 'resume' | 'logout' | 'prompt_input_exit' | 'bypass_permissions_disabled' | 'other';
 //#endregion
-//#region ../agent-core/dist/node/index-D2rky0wZ.d.ts
+//#region ../agent-core/dist/node/index-DXZ-pyEr.d.ts
 /**
  * Context data type - for execution contexts
  */
@@ -105,81 +105,37 @@ type TLoggerData = Record<string, TUniversalValue | Date | Error>;
  */
 type TToolParameters = Record<string, TUniversalValue>;
 //#endregion
-//#region src/interfaces/interaction.d.ts
-/**
- * UI-agnostic "ask the user" contract (CMD-004).
- *
- * The SSOT for the interaction action lives in agent-core so every interaction *source* can reach it:
- * command execution (`ICommandHostContext`, agent-framework) AND tool execution
- * (`IToolExecutionContext`, agent-core, for model-issued questions — CMD-005). These are pure types
- * with no runtime dependency, so the contract crosses a serialization/transport boundary unchanged
- * (no function-valued fields).
- *
- * A single shape covers every interaction kind, parameterised by fields rather than split into
- * variants:
- * - confirm    → two options, `maxSelect` 1
- * - single     → options, `maxSelect` 1
- * - multi      → options, `maxSelect` > 1
- * - free text  → no options, `allowFreeText` true
- * - secret     → free text with `masked` true
- */
-/** One predefined option the user can choose. */
-interface IActionOption {
-  value: string;
-  label: string;
-  description?: string;
+//#region src/interfaces/tool-continuation.d.ts
+/** Core-owned identity, independent of a provider's reusable tool-call identifier. */
+interface IToolActionIdentity {
+  executionId: string;
+  actionId: string;
+  parentCallId: string;
+  toolCallId: string;
+  toolName: string;
 }
-/** Pre-selected option values and/or prefilled free text for an action request. */
-interface IActionDefault {
-  values?: readonly string[];
-  text?: string;
+interface IToolContinuationPrompt {
+  kind: string;
+  data: TToolParameters;
 }
-/** One request for the user to answer. See the module doc for how the fields encode each kind. */
-interface IActionRequest {
-  /** Correlation key; the ask port resolves a given id exactly once (idempotent, first-answer wins). */
-  id: string;
-  title: string;
-  description?: string;
-  /** Predefined options. Empty/omitted ⇒ pure free-text entry. */
-  options?: readonly IActionOption[];
-  /** Minimum selections required (default 1). */
-  minSelect?: number;
-  /** Maximum selections allowed (default 1 ⇒ single; > 1 ⇒ multi). */
-  maxSelect?: number;
-  /** Allow a typed custom answer in addition to / instead of the options. */
-  allowFreeText?: boolean;
-  /** Free-text entry is masked (secret entry such as an API key); the renderer hides input. */
-  masked?: boolean;
-  /** Allow submitting empty free text. */
-  allowEmpty?: boolean;
-  /** Placeholder shown in the free-text field. */
-  placeholder?: string;
-  /** Maximum options shown before scrolling (renderer hint). */
-  maxVisible?: number;
-  /** Pre-selected option values and/or prefilled free text. */
-  default?: IActionDefault;
+interface IToolWaitRequest extends IToolActionIdentity, IToolContinuationPrompt {
+  requestId: string;
 }
-/**
- * The user's answer to an {@link IActionRequest}. `answer` carries the selected option values and/or
- * the typed text; `cancelled` means the user dismissed the request, or no interactive renderer was
- * available to answer it.
- */
-type TActionResponse = {
-  type: 'answer';
-  values: readonly string[];
-  text?: string;
-} | {
-  type: 'cancelled';
-};
-/**
- * The injected "ask the user" port — a single seam reachable by every interaction source (command
- * execution now; tool execution for model-issued questions later) and rendered per-environment by each
- * transport. The concurrency model (broadcast to attached interactive channels, first answer wins,
- * later answers for an already-resolved `id` ignored) is owned by the port implementation, not the
- * contract.
- */
-interface IUserInteraction {
-  ask(request: IActionRequest): Promise<TActionResponse>;
+interface IToolWaitResponse {
+  requestId: string;
+  responseId: string;
+  response: TToolParameters;
+}
+interface IToolWaitState {
+  request: IToolWaitRequest;
+  response?: IToolWaitResponse;
+}
+/** Available before effect admission. The runtime owns interpretation and authorization. */
+interface IToolContinuation {
+  readonly action: IToolActionIdentity;
+  readonly waits: readonly IToolWaitState[];
+  /** Return a saved response or persist a request and suspend this execution. */
+  request(prompt: IToolContinuationPrompt): Promise<TToolParameters>;
 }
 /**
  * Message metadata used across conversation history and provider adapters.
@@ -361,8 +317,6 @@ interface IModelRef {
   provider: string;
   model: string;
 }
-//#endregion
-//#region src/utils/provider-failure.d.ts
 /** Why a provider call failed, as far as switching models is concerned. */
 type TProviderFailureReason = 'overloaded' | 'service-unavailable' | 'server-error' | 'model-unavailable' | 'authentication' | 'billing' | 'rate-limit' | 'invalid-request' | 'network' | 'aborted' | 'unknown';
 //#endregion
@@ -804,24 +758,6 @@ interface IAIProvider {
    */
   close?(): Promise<void>;
 }
-/**
- * The catalog a search tool loads through — the port `IToolExecutionContext.deferredTools` carries.
- *
- * Narrow on purpose: a tool that can list and load must not be able to register, remove or execute.
- */
-interface IDeferredToolCatalog {
-  /**
-   * Deferred tools not yet loaded — the population a search can still discover. Empty while
-   * deferral is not engaged, because nothing is withheld then.
-   */
-  listDeferredTools(): IToolSchema[];
-  /**
-   * Mark the named deferred tools loaded for the rest of the session and return their schemas. A
-   * resident name is returned as it is (it was never withheld); an unknown name throws, naming the
-   * entry, and then nothing is loaded — the check runs over every name before the first load.
-   */
-  loadDeferredTools(names: readonly string[]): IToolSchema[];
-}
 //#endregion
 //#region src/event-service/interfaces.d.ts
 /**
@@ -896,7 +832,104 @@ interface IEventService {
   unsubscribe(listener: TEventListener): void;
 }
 //#endregion
+//#region src/interfaces/interaction.d.ts
+/**
+ * UI-agnostic "ask the user" contract (CMD-004).
+ *
+ * The SSOT for the interaction action lives in agent-core so every interaction *source* can reach it:
+ * command execution (`ICommandHostContext`, agent-framework) AND tool execution
+ * (`IToolExecutionContext`, agent-core, for model-issued questions — CMD-005). These are pure types
+ * with no runtime dependency, so the contract crosses a serialization/transport boundary unchanged
+ * (no function-valued fields).
+ *
+ * A single shape covers every interaction kind, parameterised by fields rather than split into
+ * variants:
+ * - confirm    → two options, `maxSelect` 1
+ * - single     → options, `maxSelect` 1
+ * - multi      → options, `maxSelect` > 1
+ * - free text  → no options, `allowFreeText` true
+ * - secret     → free text with `masked` true
+ */
+/** One predefined option the user can choose. */
+interface IActionOption {
+  value: string;
+  label: string;
+  description?: string;
+}
+/** Pre-selected option values and/or prefilled free text for an action request. */
+interface IActionDefault {
+  values?: readonly string[];
+  text?: string;
+}
+/** One request for the user to answer. See the module doc for how the fields encode each kind. */
+interface IActionRequest {
+  /** Correlation key; the ask port resolves a given id exactly once (idempotent, first-answer wins). */
+  id: string;
+  title: string;
+  description?: string;
+  /** Predefined options. Empty/omitted ⇒ pure free-text entry. */
+  options?: readonly IActionOption[];
+  /** Minimum selections required (default 1). */
+  minSelect?: number;
+  /** Maximum selections allowed (default 1 ⇒ single; > 1 ⇒ multi). */
+  maxSelect?: number;
+  /** Allow a typed custom answer in addition to / instead of the options. */
+  allowFreeText?: boolean;
+  /** Free-text entry is masked (secret entry such as an API key); the renderer hides input. */
+  masked?: boolean;
+  /** Allow submitting empty free text. */
+  allowEmpty?: boolean;
+  /** Placeholder shown in the free-text field. */
+  placeholder?: string;
+  /** Maximum options shown before scrolling (renderer hint). */
+  maxVisible?: number;
+  /** Pre-selected option values and/or prefilled free text. */
+  default?: IActionDefault;
+}
+/**
+ * The user's answer to an {@link IActionRequest}. `answer` carries the selected option values and/or
+ * the typed text; `cancelled` means the user dismissed the request, or no interactive renderer was
+ * available to answer it.
+ */
+type TActionResponse = {
+  type: 'answer';
+  values: readonly string[];
+  text?: string;
+} | {
+  type: 'cancelled';
+};
+/**
+ * The injected "ask the user" port — a single seam reachable by every interaction source (command
+ * execution now; tool execution for model-issued questions later) and rendered per-environment by each
+ * transport. The concurrency model (broadcast to attached interactive channels, first answer wins,
+ * later answers for an already-resolved `id` ignored) is owned by the port implementation, not the
+ * contract.
+ */
+interface IUserInteraction {
+  ask(request: IActionRequest): Promise<TActionResponse>;
+}
+/**
+ * The catalog a search tool loads through — the port `IToolExecutionContext.deferredTools` carries.
+ *
+ * Narrow on purpose: a tool that can list and load must not be able to register, remove or execute.
+ */
+interface IDeferredToolCatalog {
+  /**
+   * Deferred tools not yet loaded — the population a search can still discover. Empty while
+   * deferral is not engaged, because nothing is withheld then.
+   */
+  listDeferredTools(): IToolSchema[];
+  /**
+   * Mark the named deferred tools loaded for the rest of the session and return their schemas. A
+   * resident name is returned as it is (it was never withheld); an unknown name throws, naming the
+   * entry, and then nothing is loaded — the check runs over every name before the first load.
+   */
+  loadDeferredTools(names: readonly string[]): IToolSchema[];
+}
+//#endregion
 //#region src/interfaces/tool.d.ts
+/** Awaited host admission for effective parameters, immediately before a tool body. */
+type TToolEffectAdmission<TParameters = TToolParameters> = (parameters: TParameters) => Promise<void>;
 type TToolContextExtensionValue = TUniversalValue | Date | Error | TLoggerData | TContextData | TToolParameters | TToolMetadata;
 /**
  * Tool metadata structure - specific type definition
@@ -926,6 +959,10 @@ interface IToolResult {
 interface IToolExecutionContext {
   toolName: string;
   parameters: TToolParameters;
+  /** Runtime-owned barrier, consumed after permission and before entering the tool. */
+  beforeToolEffect?: TToolEffectAdmission;
+  /** Journaled pre-effect request/response port for admission-aware runtime wrappers. */
+  continuation?: IToolContinuation;
   /**
    * Run-scoped cancellation signal (CORE-018). Long-running tools MUST honor it: terminate
    * the underlying work (kill the child process, abort the network request) and return an
@@ -984,6 +1021,14 @@ interface IToolExecutionContext {
    * Owner-bound instances must not be layered across different owners.
    */
   baseEventService?: IEventService;
+  /**
+   * The service this call's caller would give the tool with `setEventService`, carried with the
+   * call instead. One tool instance can serve several agents, and the service set on it is
+   * whichever agent set one last; a tool that emits events of its own (the `FunctionTool` span)
+   * emits them here when present, so they reach the agent that made the call. The no-op default
+   * service means that caller wants none.
+   */
+  instanceEventService?: IEventService;
   /**
    * Injected "ask the user" port (CMD-004). Present when an interactive renderer is attached, letting
    * a tool solicit a structured answer from the user (the model-issued question seam consumed by
@@ -1038,6 +1083,11 @@ interface IParameterValidationResult {
 interface IToolContract<TParameters = TToolParameters, TResult = IToolResult> {
   readonly schema: IToolSchema;
   execute(parameters: TParameters, context: IToolExecutionContext): Promise<TResult>;
+  /**
+   * Wrappers await admission exactly once with final canonical arguments after preconditions and before
+   * the body. Denial returns without admission. Admission failures propagate unchanged.
+   */
+  executeWithAdmission?(parameters: TParameters, context: IToolExecutionContext, admit: TToolEffectAdmission<TParameters>): Promise<TResult>;
   validate(parameters: TParameters): boolean;
   validateParameters(parameters: TParameters): IParameterValidationResult;
   getDescription(): string;
@@ -1309,6 +1359,27 @@ interface ICapabilityDescriptor {
  * re-exports it. A transport-origin command runs as a local one by default; an optional policy may restrict (REMOTE-006).
  */
 type TCommandInvocationSource = 'user' | 'model' | 'remote';
+/**
+ * Whether a `'remote'`-sourced invocation is provably on this machine. The loopback-bound WS carrier
+ * (the desktop app and a locally served browser page) is `'local'`; the device-mesh/WebRTC carrier
+ * proves no locality ("a browser device proves no locality, so it is treated as another machine" —
+ * the same rule `ConnectionAuthority` already applies to pairing), so it is always `'remote'`. Absent
+ * (an in-process caller, an older host, or a test double) defaults to `'local'` — the allow-by-default
+ * posture the rest of the command layer already uses. A command that runs code from outside the
+ * session (installing a plugin) reads this to refuse a remote device even though `'remote'`-sourced
+ * commands otherwise run like a local one (REMOTE-006).
+ */
+type TCommandSurfaceLocality = 'local' | 'remote';
+/**
+ * Who runs a command. `'runtime'`: the process that owns the session runs it, whichever surface
+ * sent it. `'client'`: the surface the user is typing into runs it itself, because what it does
+ * belongs to that surface (its terminal, its appearance), not to the session. A client that is
+ * attached to a runtime in another process runs such a command locally instead of sending it; the
+ * runtime keeps it in its catalog so help stays complete and a surface that cannot run it refuses it.
+ */
+type TCommandRunner = 'runtime' | 'client';
+/** A kind of client surface. Names the surfaces a `'client'` command can run on. */
+type TCommandSurface = 'terminal' | 'gui';
 /** A command entry */
 interface ICommand {
   /** Command name without slash (e.g., "mode") — used for invocation */
@@ -1368,6 +1439,15 @@ interface ICommand {
   agent?: string;
   /** Plugin installation directory (plugin skills/commands only) */
   pluginDir?: string;
+  /**
+   * Who runs this command. Absent → `'runtime'`; the listing resolves it, see
+   * `ICommandListEntry.runner`.
+   */
+  runner?: TCommandRunner;
+  /**
+   * The surfaces a `'client'` command can run on. Absent → the command does not restrict them.
+   */
+  surfaces?: readonly TCommandSurface[];
 }
 /** A source that provides commands */
 interface ICommandSource {
@@ -1494,6 +1574,40 @@ interface ICommandListEntry {
    * list does not say". Those need different handling and the first must not be reached by accident.
    */
   modelInvocable: boolean;
+  /**
+   * Who runs this command — what a surface reads to mark a command another surface owns. A client
+   * does not route by it: it runs locally only the commands it implements itself, so an older
+   * runtime or a catalog that arrives late cannot misroute a command.
+   *
+   * REQUIRED for the same reason as `modelInvocable`: the producer resolves a command that declares
+   * no runner to `'runtime'` in one place, so "runs on the runtime" is never confused with "the
+   * producer of this list does not say".
+   */
+  runner: TCommandRunner;
+  /** The surfaces a `'client'` command can run on. Absent when the command does not restrict them. */
+  surfaces?: readonly TCommandSurface[];
+  /** The argument grammar a client shows after the name while the user types (e.g. `<name> [args]`). */
+  argumentHint?: string;
+  /** The subcommands a client completes after `/<name> `. Absent when the command declares none. */
+  subcommands?: readonly ICommandSubcommandEntry[];
+}
+/** A subcommand as a client offers it after its command's name. */
+interface ICommandSubcommandEntry {
+  readonly name: string;
+  readonly description: string;
+  readonly displayName?: string;
+  readonly argumentHint?: string;
+}
+/** A skill as a client offers it beside the commands; `/<name>` activates it. */
+interface ICommandSkillListEntry {
+  readonly name: string;
+  readonly description: string;
+  readonly source: string;
+  readonly modelInvocable: boolean;
+  readonly userInvocable: boolean;
+  readonly argumentHint?: string;
+  readonly context?: string;
+  readonly agent?: string;
 }
 type TPluginInstallScope = 'user' | 'project';
 interface ICommandInstalledPlugin {
@@ -1546,6 +1660,26 @@ interface IBackgroundTaskError {
  * TYPE-003: alias of the `agent-core` usage-triple SSOT (`ITokenUsage`) — derived, not re-declared.
  */
 type IBackgroundTaskUsage = ITokenUsage;
+/**
+ * Issue #3288 §1: why a tool call inside a task was refused — the same distinction the session-layer
+ * enforcer already records for its own denials (`hasApprover ? 'user' : 'no-approver'`), named here for
+ * a task's result rather than a live session's denial log: `'no-approver'` when no approver was
+ * attached at all (print mode, a truly headless run); `'denied-by-person'` when one was attached and
+ * answered no; `'approver-error'` when it threw or rejected instead of answering — a broken approver
+ * still fails the call closed rather than hanging it; `'cancelled'` when the task ended (finished,
+ * failed, or was stopped) before an attached approver's answer arrived — a `false` produced by that
+ * cutoff is not the same fact as a person's own denial, so it is never counted as one.
+ */
+type TBackgroundTaskPermissionDenialReason = 'denied-by-person' | 'no-approver' | 'approver-error' | 'cancelled';
+/**
+ * How many of a task's tool calls were refused, and why. Additive: a caller only reads this when at
+ * least one call was refused, so a task with none carries no new field — the result of a task that
+ * finished exactly as it always did is unchanged.
+ */
+interface IBackgroundTaskDeniedToolCalls {
+  readonly total: number;
+  readonly byReason: Readonly<Record<TBackgroundTaskPermissionDenialReason, number>>;
+}
 interface IBaseBackgroundTaskResult {
   taskId: string;
   output: string;
@@ -1555,6 +1689,8 @@ interface IAgentBackgroundTaskResult extends IBaseBackgroundTaskResult {
   kind: 'agent';
   /** ANALYTICS-001 (Phase 2): total token usage of an agent task, attributed to it in the parent log. */
   usage?: IBackgroundTaskUsage;
+  /** Issue #3288 §1: present only when the task had at least one tool call refused. */
+  deniedToolCalls?: IBackgroundTaskDeniedToolCalls;
 }
 interface IProcessBackgroundTaskResult extends IBaseBackgroundTaskResult {
   kind: 'process';
@@ -1800,7 +1936,7 @@ interface ISubagentJobState extends Pick<IBackgroundTaskState<'agent'>, 'id' | '
   error?: string;
 }
 //#endregion
-//#region ../agent-interface-session/dist/node/session-contracts-BVCzd3uY.d.ts
+//#region ../agent-interface-session/dist/node/session-contracts-C4R5bYiU.d.ts
 //#endregion
 //#region src/session-loop-contracts.d.ts
 /** A self-paced loop's durable lifecycle, independent of its disposable wake timer. */
@@ -2044,7 +2180,7 @@ interface ISessionReplayValidationResult {
  */
 type TWorkspaceRelation = 'same-worktree' | 'same-repo' | 'different-repo' | 'unknown';
 //#endregion
-//#region ../agent-framework/dist/node/createInteractiveRuntime-Bmh2KYP6.d.ts
+//#region ../agent-framework/dist/node/createInteractiveRuntime-3MZpPTdw.d.ts
 //#region src/effort/effort-resolution.d.ts
 type TEffortSelection = TModelEffort | 'auto';
 type TEffortSource = 'command' | 'flag' | 'environment' | 'settings' | 'preset' | 'model-default';
@@ -2092,16 +2228,6 @@ interface IEditCheckpointRestoreResult {
 }
 //#endregion
 //#region src/command-api/host-context-types.d.ts
-interface ICommandSkillListEntry {
-  readonly name: string;
-  readonly description: string;
-  readonly source: string;
-  readonly modelInvocable: boolean;
-  readonly userInvocable: boolean;
-  readonly argumentHint?: string;
-  readonly context?: string;
-  readonly agent?: string;
-}
 interface ICommandSkillActivationRequest {
   readonly invocationSource: TCommandInvocationSource;
   readonly displayInput?: string;
@@ -2249,10 +2375,25 @@ interface ISessionUsageRecord {
 //#region src/command-api/agent-job-roles.d.ts
 /** Starting, steering and ending subagent jobs. */
 interface IAgentJobDispatch {
+  /**
+   * #3282 §4: the agent switcher's roster — `definedIn` is a plain-words location (a discovered
+   * file's path, or "Built-in") a person picking an agent can read.
+   */
   listAgentDefinitions(): Array<{
     name: string;
     description: string;
+    definedIn: string;
   }>;
+  /**
+   * #3282 §4: the agent type `/agent <name>` (no prompt) currently selects — the agent switcher
+   * shows it checked. Never throws; a host without the agent runtime just has the fallback default.
+   */
+  getDefaultAgentType(): string;
+  /**
+   * #3282 §4: `/agent <name>` (bare, no prompt) sets this — the agent type used as the default
+   * `agentType` whenever one is not otherwise named. Throws if the agent runtime is unavailable.
+   */
+  setDefaultAgentType(agentType: string): void;
   listAgentJobs(): ISubagentJobState[];
   spawnAgentJob(input: {
     agentType: string;
@@ -2328,7 +2469,7 @@ interface IAgentJobMonitors {
 interface IAgentJobLogs {
   readBackgroundTaskLog(taskId: string, cursor?: IBackgroundTaskLogCursor): Promise<IBackgroundTaskLogPage>;
 }
-/** Aggregate: all 15 members remain source-compatible. Declare a role port instead of this. */
+/** Aggregate of the five role interfaces above, kept source-compatible. Declare a role port instead of this. */
 interface IAgentJobHostContext extends IAgentJobDispatch, IAgentJobGroups, IAgentJobSchedules, IAgentJobMonitors, IAgentJobLogs {}
 //#endregion
 //#region src/command-api/preset/preset-application-types.d.ts
@@ -2512,9 +2653,22 @@ interface IPermissionRuleLayer {
   readonly deny: readonly string[];
   readonly ask: readonly string[];
 }
+/** One rule to remove from the settings layer it was declared in (#3282 §4a). */
+interface IPermissionRuleRemoval {
+  /** The `scope` of the {@link IPermissionRuleLayer} the rule was read from. */
+  readonly scope: string;
+  readonly kind: 'allow' | 'deny' | 'ask';
+  readonly pattern: string;
+}
 /** Where each configured permission rule comes from, read fresh on every call. */
 interface ICommandPermissionRulesAdapter {
   readLayers(): readonly IPermissionRuleLayer[];
+  /**
+   * #3282 §4a: remove one declared rule from its settings layer. Optional — a host with no write
+   * target for any layer (read-only rule discovery) makes rule removal fail EXPLICITLY wherever it
+   * is offered, never a silent no-op. Returns `false` when no writable layer matched the removal.
+   */
+  removeRule?(removal: IPermissionRuleRemoval): boolean;
 }
 /** How shell commands are confined: not at all, confined without prompts, or confined and asked. */
 type TSandboxCommandMode = 'off' | 'auto-allow' | 'regular';
@@ -2527,6 +2681,22 @@ interface ICommandSandboxStatus {
   readonly network: boolean;
   readonly excludedCommands: readonly string[];
 }
+/** One external-event grant as the owner sees it: never the principal, a token or any content. */
+interface ICommandExternalEventGrant {
+  readonly grantId: string;
+  readonly principal: 'subject' | 'client';
+  readonly state: 'open' | 'revoked';
+  readonly counters: {
+    readonly accepted: number;
+    readonly refused: Readonly<Partial<Record<string, number>>>;
+    readonly settled: Readonly<Partial<Record<string, number>>>;
+  };
+}
+/** The session's external-event grants: `/events` lists them and withdraws one. */
+interface ICommandExternalEventsAdapter {
+  list(): readonly ICommandExternalEventGrant[];
+  revoke(grantId: string): 'revoked' | 'unknown-grant';
+}
 /** The OS sandbox, live: `/sandbox` reads it and changes the mode for the next command. */
 interface ICommandSandboxAdapter {
   status(): ICommandSandboxStatus;
@@ -2594,6 +2764,15 @@ interface ICommandMCPActivationSummary {
   readonly provenanceId: string;
   readonly definitionFingerprint: string;
   readonly securityIdentity: string;
+  /**
+   * #3282 §4 part b-2: this process's live connection outcome for an `allowed` server — absent for
+   * one that is not `allowed`, or has not been attempted yet. `'failed'`'s reason is
+   * {@link connectionFailureReason}; a connected server's tool names are {@link toolNames}.
+   */
+  readonly connection?: 'connected' | 'failed';
+  readonly connectionFailureReason?: string;
+  /** The names of the tools this server currently contributes; empty when not connected. */
+  readonly toolNames?: readonly string[];
 }
 /**
  * A definition-source-level problem — issue #2794: a configuration root that is not an object, no
@@ -2714,6 +2893,33 @@ interface ICommandMCPActivationAdapter {
    * a name it already had. Called once per sign-in that returned tools.
    */
   oauthToolsAdded?(serverId: string, added: readonly string[]): void;
+  /**
+   * #3282 §4 part b-2: `/mcp reload` and the Settings screen's "Reload servers" button. Retries
+   * every allowed server that is not currently connected; a server already connected is left
+   * running. Never rejects: a server that still cannot connect keeps its `list()` failure reason.
+   * Absent: the host offers no reload (the button/command then say so).
+   */
+  reload?(): Promise<{
+    readonly tools: readonly IToolWithEventService[];
+    readonly connectedServerIds: readonly string[];
+    readonly failedServerIds: readonly string[];
+    /**
+     * Identifies this call's staged tool provenance for `reloadToolsAdded`; absent when there is
+     * nothing to acknowledge (no server newly connected). Two `reload()` calls outstanding at once
+     * — `/mcp reload` runs inline, unblocked by the mid-turn gate, and an `update-settings` write
+     * is fire-and-forget, so this is reachable, not hypothetical — join the same connection pass
+     * and get the same token back; a fresh call started only after the last one's token was
+     * acknowledged gets a new one.
+     */
+    readonly reloadToken?: string;
+  }>;
+  /**
+   * Which of `reload`'s tools the session actually took, keyed to the `reloadToken` it returned;
+   * any other was left out for a name it already had. `token` not matching the currently staged
+   * reload — already committed, or superseded by a later call — makes this a no-op, so a late or
+   * duplicate acknowledgement can never clear or corrupt a different reload's provenance.
+   */
+  reloadToolsAdded?(token: string, added: readonly string[]): void;
 }
 /**
  * PEER-004 (#1863): a live session this one can address, as the operator sees it.
@@ -2734,6 +2940,16 @@ interface ILocalPeerSummary {
   /** `mismatched` when the peer's claim disagreed with what this session read; it is not believed. */
   readonly workspaceClaim?: 'verified' | 'mismatched' | 'absent';
 }
+/**
+ * Another of the user's devices with an admitted device-mesh link to this session, as the operator
+ * sees it. `deviceId` names it for a later `send`; `locality` is where the carrier established it
+ * runs, shown and never an authority input.
+ */
+interface ILinkedDeviceSummary {
+  readonly deviceId: string;
+  readonly name?: string;
+  readonly locality: 'same-host' | 'another-host';
+}
 /**
  * PEER-004: what `/peers` reads. The registry, the guarded directory and the liveness rule all live
  * in the composition root — a command never touches the filesystem, for the same reason it never
@@ -2749,6 +2965,16 @@ interface ICommandLocalPeersAdapter {
   listWithWorkspace?(): Promise<readonly ILocalPeerSummary[]>;
   /** This session's own id, so the command can mark which row is the reader. */
   ownSessionId(): string;
+  /**
+   * The user's other devices linked to this session over the device mesh, addressed by device id
+   * wherever a session id is taken. Absent on a host with no device mesh.
+   */
+  listDevices?(): readonly ILinkedDeviceSummary[];
+  /**
+   * Why sessions on this host cannot be listed, when local discovery is off for this session; the
+   * linked devices still are. Absent when discovery is on.
+   */
+  readonly localDiscoveryOff?: string;
   /**
    * PEER-006: hand `text` to another announced session, and report what came back.
    *
@@ -2970,6 +3196,8 @@ interface ICommandHostAdapters {
   workspace?: ICommandWorkspaceAdapter;
   /** Absent on a host with no OS sandbox — `/sandbox` then says so. */
   sandbox?: ICommandSandboxAdapter;
+  /** Absent when the session holds no external-event grant — `/events` then says so. */
+  externalEvents?: ICommandExternalEventsAdapter;
 }
 interface IContextReferenceAddResult {
   reference?: IContextReferenceItem;
@@ -3130,6 +3358,17 @@ interface ICommandHostUserInteraction {
    */
   getUserInteraction(): IUserInteraction | undefined;
 }
+/**
+ * Whether THIS session is running with no provider configured yet (issue #3282 §3 setup mode).
+ *
+ * Exists for exactly one command (`/provider add`, deciding hot-swap vs. restart) — never inferred
+ * from settings, because an ordinary session started from an env-default provider also has none
+ * persisted. The member is optional so a host with no concept of setup mode costs nothing and is
+ * correctly read as "not in it" (`?.() === true`), never mistaken for a required capability.
+ */
+interface ICommandHostSetupState {
+  isSetupRequired?(): boolean;
+}
 /** Re-applying preset-owned configuration to the live session. */
 interface ICommandHostPresetApplication {
   /** Apply an additive response style to the live system prompt. */
@@ -3168,6 +3407,12 @@ interface ICommandHostContextReferences {
 interface ICommandHostWorkspace {
   getCwd(): string;
   getCommandInvocationSource(): TCommandInvocationSource;
+  /**
+   * #3282 §4 part b-2: whether THIS invocation is provably on this machine. Optional so an older or
+   * narrower host still satisfies this interface; a caller that needs it treats a missing method the
+   * same as `'local'` (allow-by-default, matching the rest of the command layer).
+   */
+  getCommandSurfaceLocality?(): TCommandSurfaceLocality;
 }
 /** What commands and skills this host can dispatch. */
 interface ICommandHostCatalog {
@@ -3249,8 +3494,8 @@ interface ICommandHostTerminalHandoff {
 interface ICommandHostAdapterAccess {
   getCommandHostAdapters?(): ICommandHostAdapters;
 }
-/** Aggregate: all 47 members remain source-compatible. Declare a role port instead of this. */
-interface ICommandHostContext extends ICommandHostSessionAccess, ICommandHostAgentJobs, ICommandHostUserInteraction, ICommandHostPresetApplication, ICommandHostContextWindow, ICommandHostContextReferences, ICommandHostWorkspace, ICommandHostCatalog, ICommandHostCheckpoints, ICommandHostMemory, ICommandHostBackgroundTasks, ICommandHostGoal, ICommandHostPlan, ICommandHostTerminalHandoff, ICommandHostAdapterAccess {}
+/** Aggregate: all 48 members remain source-compatible. Declare a role port instead of this. */
+interface ICommandHostContext extends ICommandHostSessionAccess, ICommandHostAgentJobs, ICommandHostUserInteraction, ICommandHostSetupState, ICommandHostPresetApplication, ICommandHostContextWindow, ICommandHostContextReferences, ICommandHostWorkspace, ICommandHostCatalog, ICommandHostCheckpoints, ICommandHostMemory, ICommandHostBackgroundTasks, ICommandHostGoal, ICommandHostPlan, ICommandHostTerminalHandoff, ICommandHostAdapterAccess {}
 //#endregion
 //#region src/command-api/contracts.d.ts
 type TSystemCommandLifecycle = 'inline' | 'blocking' | 'background';
@@ -3272,6 +3517,10 @@ interface ISystemCommand {
   argumentHint?: string;
   safety?: TCapabilitySafety;
   subcommands?: readonly ICommand[];
+  /** Who runs this command; absent → `'runtime'`. See `ICommand.runner`. */
+  runner?: TCommandRunner;
+  /** The surfaces a `'client'` command can run on. See `ICommand.surfaces`. */
+  surfaces?: readonly TCommandSurface[];
   lifecycle?: TSystemCommandLifecycle;
   /**
    * Whether executing this command requires explicit user permission/confirmation.