@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.81

package/src/handoff/handoff-command.ts

@@ -0,0 +1,187 @@
+import type {
+  ICommandHostAdapterAccess,
+  ICommandHostAdapters,
+  ICommandHostUserInteraction,
+  IHandoffProgress,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+/**
+ * `/handoff` (HANDOFF-001, issue #1864) — move this session to another machine.
+ *
+ * The command holds no protocol. It reads an injected adapter and touches no transport, for the same
+ * reason `/peers` does not: the carrier, the wire composition and the device identity are
+ * composition-root concerns and must have one owner.
+ *
+ * ## What it is FOR, which is the consent
+ *
+ * A hand-off loses things on purpose — uncommitted working-tree changes and running subprocesses
+ * stay on this machine, because moving them would make this a file-sync product and a process cannot
+ * migrate at all. Those are the operator's to lose, so they are named in the prompt BEFORE the
+ * question, not reported afterwards. A confirmation that did not mention them is not consent.
+ *
+ * ## The sentence it always ends on
+ *
+ * Every outcome that is not `done` says the session is still on this machine. That is not
+ * reassurance: it is the one invariant the whole design exists to preserve, and the operator is the
+ * person who has to know whether to keep typing here or walk to the other computer.
+ */
+
+type THandoffHost = ICommandHostAdapterAccess & Partial<ICommandHostUserInteraction>;
+
+/** The line that answers "where is my session?" — printed on every path, success included. */
+function whereIsIt(progress: IHandoffProgress): string {
+  return progress.stillMine
+    ? 'This session is still on this machine, and still yours to use.'
+    : 'This session now belongs to the destination. This copy is read-only.';
+}
+
+function describeDestinations(
+  destinations: readonly { readonly deviceId: string; readonly name?: string }[],
+): string {
+  return destinations.map((d) => `  ${d.deviceId}${d.name ? `  ${d.name}` : ''}`).join('\n');
+}
+
+function usage(): ICommandResult {
+  return {
+    success: true,
+    message: [
+      'Usage:',
+      '  /handoff              list the machines this session could move to',
+      '  /handoff <device-id>  move it there, after confirming what stays behind',
+    ].join('\n'),
+  };
+}
+
+export async function executeHandoffCommand(
+  context: THandoffHost,
+  args: string,
+): Promise<ICommandResult> {
+  const adapter: ICommandHostAdapters['handoff'] = context.getCommandHostAdapters?.().handoff;
+  if (adapter === undefined) {
+    // Said plainly rather than offered and then failed. A host with no carrier cannot move a
+    // session, and a command that took the request anyway would spend the operator's attention
+    // before telling them.
+    return {
+      success: false,
+      message:
+        'This session has no hand-off carrier, so it cannot be moved to another machine. ' +
+        'Nothing changed — the session is still here.',
+    };
+  }
+
+  const target = args.trim();
+  if (target === '' || target === 'help') {
+    const destinations = await adapter.destinations();
+    if (destinations.length === 0) {
+      return {
+        success: true,
+        message:
+          'No other machine is reachable for a hand-off right now.\n' + whereIsIt(adapter.status()),
+      };
+    }
+    return {
+      success: true,
+      message: [
+        'This session could move to:',
+        describeDestinations(destinations),
+        '',
+        usage().message ?? '',
+      ].join('\n'),
+    };
+  }
+
+  const destinations = await adapter.destinations();
+  if (!destinations.some((d) => d.deviceId === target)) {
+    return {
+      success: false,
+      message:
+        `No reachable machine is called '${target}'.\n` +
+        (destinations.length > 0
+          ? `Reachable now:\n${describeDestinations(destinations)}`
+          : 'None are reachable right now.') +
+        `\n${whereIsIt(adapter.status())}`,
+    };
+  }
+
+  const staying = await adapter.staysBehind();
+  const consequences = [
+    staying.uncommittedChanges
+      ? '  - uncommitted changes in the working tree stay on THIS machine'
+      : null,
+    staying.subprocesses > 0
+      ? `  - ${staying.subprocesses} running process(es) stay on THIS machine and will not be reachable there`
+      : null,
+    '  - the destination uses ITS OWN provider credential; credentials are never transferred',
+  ].filter((line): line is string => line !== null);
+
+  const ask = context.getUserInteraction?.();
+  if (ask === undefined) {
+    // No human is attached. Refused, never guessed: a hand-off is irreversible from the source's
+    // side, and "nobody was there to say no" is not a yes.
+    return {
+      success: false,
+      message:
+        'A hand-off needs a person to confirm what stays behind, and no interactive session is ' +
+        `attached.\n${whereIsIt(adapter.status())}`,
+    };
+  }
+
+  const answer = await ask.ask({
+    id: `handoff:${target}`,
+    title: `Move this session to ${target}?`,
+    description: ['What will NOT travel:', ...consequences].join('\n'),
+    options: [
+      { value: 'move', label: `Move it to ${target}` },
+      { value: 'stay', label: 'Keep it here' },
+    ],
+  });
+  if (answer.type !== 'answer' || !answer.values.includes('move')) {
+    return {
+      success: true,
+      message: `Hand-off cancelled.\n${whereIsIt(adapter.status())}`,
+    };
+  }
+
+  const progressLines: string[] = [];
+  const final = await adapter.transfer(target, (progress) => {
+    progressLines.push(renderProgress(progress, target));
+  });
+
+  return {
+    success: final.state === 'done',
+    message: [
+      ...progressLines,
+      final.state === 'done'
+        ? `Hand-off complete. ${target} is running this session now.`
+        : `Hand-off stopped: ${final.reason ?? 'no reason was reported'}.`,
+      whereIsIt(final),
+    ].join('\n'),
+  };
+}
+
+/**
+ * One progress line, in the operator's vocabulary.
+ *
+ * `awaiting-confirmation` is spelled out rather than shortened because it is the phase the operator
+ * is most likely to interrupt: the payload is on the other machine and this one has not yet heard
+ * that it is on disk there. Quitting here is safe, and the wording is what says so.
+ */
+function renderProgress(progress: IHandoffProgress, target: string): string {
+  // Exhaustive by construction: the default returns nothing rather than a plausible-looking line, so
+  // a new state added to the contract shows up as a blank line in a test instead of as a wrong one.
+  switch (progress.state) {
+    case 'offered':
+      return `Offering the session to ${target}...`;
+    case 'sending':
+      return 'Sending the session...';
+    case 'awaiting-confirmation':
+      return `Sent. Waiting for ${target} to confirm it has the session on disk — until it does, this machine keeps it.`;
+    case 'done':
+      return `${target} confirmed it has the session.`;
+    case 'stopped':
+      return `Stopped: ${progress.reason ?? 'no reason was reported'}.`;
+    default:
+      return '';
+  }
+}

package/src/handoff/index.ts

@@ -0,0 +1,6 @@
+export { executeHandoffCommand } from './handoff-command.js';
+export {
+  HandoffCommandSource,
+  createHandoffCommandEntry,
+  createHandoffCommandModule,
+} from './handoff-command-module.js';

package/src/help/__tests__/help-command-module.test.ts

@@ -2,9 +2,13 @@ import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/ag
 import { describe, expect, it } from 'vitest';
 import { createHelpCommandModule } from '../help-command-module.js';
 import { executeHelpCommand } from '../help-command.js';
+import {
+  createTestCommandHost,
+  createTestSessionRuntime,
+} from '@robota-sdk/agent-framework/testing';
 
-function createCommandSessionRuntime(): ICommandSessionRuntime {
-  return {
+function createCommandSessionRuntime() {
+  return createTestSessionRuntime({
     clearHistory: () => undefined,
     compact: async () => undefined,
     getContextState: () => ({
@@ -21,10 +25,10 @@ function createCommandSessionRuntime(): ICommandSessionRuntime {
     getAutoCompactThreshold: () => false,
     getFullHistory: () => [],
     getHistory: () => [],
-  };
+  });
 }
 
-function createCommandHostContext(): ICommandHostContext {
+function createCommandHostContext() {
   const checkpoint = {
     id: 'checkpoint_1',
     sessionId: 'session_1',
@@ -33,42 +37,61 @@ function createCommandHostContext(): ICommandHostContext {
     createdAt: '2026-05-03T00:00:00.000Z',
     fileCount: 0,
   };
-  return {
-    getSession: () => createCommandSessionRuntime(),
-    getContextState: () => ({
-      maxTokens: 100,
-      usedTokens: 10,
-      usedPercentage: 10,
-      remainingPercentage: 90,
-    }),
-    getAutoCompactThreshold: () => 0.8,
-    compactContext: async () => undefined,
-    getCwd: () => '/workspace',
-    listCommands: () => [
-      { name: 'help', displayName: 'Help', description: 'Show available commands' },
-      { name: 'provider', displayName: 'Provider Setup', description: 'Manage provider profiles' },
-      { name: 'plugin', displayName: 'Plugins', description: 'Manage plugins' },
-    ],
-    listEditCheckpoints: () => [],
-    restoreEditCheckpoint: async () => ({
-      target: checkpoint,
-      restoredCheckpointCount: 0,
-      restoredFileCount: 0,
-      removedCheckpointCount: 0,
-    }),
-    rollbackEditCheckpoint: async () => ({
-      target: checkpoint,
-      restoredCheckpointCount: 0,
-      restoredFileCount: 0,
-      removedCheckpointCount: 0,
-    }),
-    getUsedMemoryReferences: () => [],
-    recordMemoryEvent: () => undefined,
-    listBackgroundTasks: () => [],
-    readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
-    cancelBackgroundTask: async () => undefined,
-    closeBackgroundTask: async () => undefined,
-  };
+  return createTestCommandHost({
+    overrides: {
+      getSession: () => createCommandSessionRuntime(),
+      getContextState: () => ({
+        maxTokens: 100,
+        usedTokens: 10,
+        usedPercentage: 10,
+        remainingPercentage: 90,
+      }),
+      getAutoCompactThreshold: () => 0.8,
+      compactContext: async () => undefined,
+      getCwd: () => '/workspace',
+      listCommands: () => [
+        {
+          name: 'help',
+          displayName: 'Help',
+          description: 'Show available commands',
+          modelInvocable: true,
+        },
+        {
+          name: 'provider',
+          displayName: 'Provider Setup',
+          description: 'Manage provider profiles',
+          modelInvocable: true,
+        },
+        // SEC-008: `plugin` installs and enables code, so it is NOT model-invocable — the fixture says
+        // what the real command says rather than the value that happened to compile.
+        {
+          name: 'plugin',
+          displayName: 'Plugins',
+          description: 'Manage plugins',
+          modelInvocable: false,
+        },
+      ],
+      listEditCheckpoints: () => [],
+      restoreEditCheckpoint: async () => ({
+        target: checkpoint,
+        restoredCheckpointCount: 0,
+        restoredFileCount: 0,
+        removedCheckpointCount: 0,
+      }),
+      rollbackEditCheckpoint: async () => ({
+        target: checkpoint,
+        restoredCheckpointCount: 0,
+        restoredFileCount: 0,
+        removedCheckpointCount: 0,
+      }),
+      getUsedMemoryReferences: () => [],
+      recordMemoryEvent: () => undefined,
+      listBackgroundTasks: () => [],
+      readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+      cancelBackgroundTask: async () => undefined,
+      closeBackgroundTask: async () => undefined,
+    },
+  });
 }
 
 describe('createHelpCommandModule', () => {

package/src/help/__tests__/help-command.test.ts

@@ -1,10 +1,14 @@
 import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
-import type { ICommandListEntry } from '@robota-sdk/agent-interface-transport';
+import type { ICommandListEntry } from '@robota-sdk/agent-interface-command';
 import { formatCommandHelpMessage } from '@robota-sdk/agent-framework';
 import { describe, expect, it } from 'vitest';
+import {
+  createTestCommandHost,
+  createTestSessionRuntime,
+} from '@robota-sdk/agent-framework/testing';
 
-function createCommandSessionRuntime(): ICommandSessionRuntime {
-  return {
+function createCommandSessionRuntime() {
+  return createTestSessionRuntime({
     clearHistory: () => undefined,
     compact: async () => undefined,
     getContextState: () => ({
@@ -21,7 +25,7 @@ function createCommandSessionRuntime(): ICommandSessionRuntime {
     getAutoCompactThreshold: () => false,
     getFullHistory: () => [],
     getHistory: () => [],
-  };
+  });
 }
 
 function createCheckpoint() {
@@ -35,40 +39,42 @@ function createCheckpoint() {
   };
 }
 
-function buildContext(commands: ICommandListEntry[]): ICommandHostContext {
+function buildContext(commands: ICommandListEntry[]) {
   const checkpoint = createCheckpoint();
-  return {
-    getSession: () => createCommandSessionRuntime(),
-    getContextState: () => ({
-      maxTokens: 100,
-      usedTokens: 10,
-      usedPercentage: 10,
-      remainingPercentage: 90,
-    }),
-    getAutoCompactThreshold: () => 0.8,
-    compactContext: async () => undefined,
-    getCwd: () => '/workspace',
-    listCommands: () => commands,
-    listEditCheckpoints: () => [],
-    restoreEditCheckpoint: async () => ({
-      target: checkpoint,
-      restoredCheckpointCount: 0,
-      restoredFileCount: 0,
-      removedCheckpointCount: 0,
-    }),
-    rollbackEditCheckpoint: async () => ({
-      target: checkpoint,
-      restoredCheckpointCount: 0,
-      restoredFileCount: 0,
-      removedCheckpointCount: 0,
-    }),
-    getUsedMemoryReferences: () => [],
-    recordMemoryEvent: () => undefined,
-    listBackgroundTasks: () => [],
-    readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
-    cancelBackgroundTask: async () => undefined,
-    closeBackgroundTask: async () => undefined,
-  };
+  return createTestCommandHost({
+    overrides: {
+      getSession: () => createCommandSessionRuntime(),
+      getContextState: () => ({
+        maxTokens: 100,
+        usedTokens: 10,
+        usedPercentage: 10,
+        remainingPercentage: 90,
+      }),
+      getAutoCompactThreshold: () => 0.8,
+      compactContext: async () => undefined,
+      getCwd: () => '/workspace',
+      listCommands: () => commands,
+      listEditCheckpoints: () => [],
+      restoreEditCheckpoint: async () => ({
+        target: checkpoint,
+        restoredCheckpointCount: 0,
+        restoredFileCount: 0,
+        removedCheckpointCount: 0,
+      }),
+      rollbackEditCheckpoint: async () => ({
+        target: checkpoint,
+        restoredCheckpointCount: 0,
+        restoredFileCount: 0,
+        removedCheckpointCount: 0,
+      }),
+      getUsedMemoryReferences: () => [],
+      recordMemoryEvent: () => undefined,
+      listBackgroundTasks: () => [],
+      readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+      cancelBackgroundTask: async () => undefined,
+      closeBackgroundTask: async () => undefined,
+    },
+  });
 }
 
 describe('formatCommandHelpMessage — example field', () => {
@@ -79,6 +85,7 @@ describe('formatCommandHelpMessage — example field', () => {
         displayName: 'Compact Context',
         description: 'Compress context window',
         example: '/compact Summarize the current context',
+        modelInvocable: true,
       },
     ]);
 
@@ -94,6 +101,7 @@ describe('formatCommandHelpMessage — example field', () => {
         displayName: 'Provider Setup',
         description: 'Manage provider profiles',
         example: '/provider switch production',
+        modelInvocable: true,
       },
     ]);
 
@@ -108,6 +116,7 @@ describe('formatCommandHelpMessage — example field', () => {
         name: 'help',
         displayName: 'Help',
         description: 'Show available commands',
+        modelInvocable: true,
       },
     ]);
 

package/src/help/help-command-module.ts

@@ -3,7 +3,7 @@ import { HELP_COMMAND_DESCRIPTION } from '@robota-sdk/agent-framework';
 import { executeHelpCommand } from './help-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createHelpCommandEntry(): ICommand {
   return {
@@ -11,6 +11,7 @@ export function createHelpCommandEntry(): ICommand {
     displayName: 'Help',
     description: HELP_COMMAND_DESCRIPTION,
     source: 'help',
+    // User-only: a listing for the user; the model already sees the commands it may run.
     modelInvocable: false,
   };
 }

package/src/help/help-command.ts

@@ -1,9 +1,9 @@
 import { formatCommandHelpMessage } from '@robota-sdk/agent-framework';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandHostCatalog } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
-export function executeHelpCommand(context: ICommandHostContext, _args: string): ICommandResult {
+export function executeHelpCommand(context: ICommandHostCatalog, _args: string): ICommandResult {
   return {
     success: true,
     message: formatCommandHelpMessage(context),

package/src/index.ts

@@ -2,19 +2,143 @@ export * from './agent/index.js';
 export * from './default/index.js';
 export * from './background/index.js';
 export * from './goal/index.js';
+// HANDOFF-001 (issue #1864). Named rather than `export *`: the star form is frozen pre-existing
+// debt in this barrel, and `sdk-public-surface` lets it shrink but never grow.
+export {
+  HandoffCommandSource,
+  createHandoffCommandEntry,
+  createHandoffCommandModule,
+  executeHandoffCommand,
+} from './handoff/index.js';
+export * from './plan/index.js';
 export * from './compact/index.js';
 export * from './context/index.js';
 export * from './editor/index.js';
+export {
+  createGitCommandEntry,
+  createGitCommandModule,
+  createGitProcess,
+  executeGitCommand,
+  gitEnvironment,
+  GitCommandSource,
+  type ICreateGitProcessOptions,
+  type IGitCommandModuleOptions,
+  type IGitProcessPort,
+  type IGitProcessRunOptions,
+  type TGitCommandContext,
+  type TGitProcessFailureReason,
+  type TGitProcessOutcome,
+} from './git/index.js';
+// OBSERVABILITY-1991: named rather than `export *` — the star form is frozen debt in this barrel.
+export {
+  STORAGE_REPAIR_ID,
+  doctorRepairAllowlist,
+  DoctorCommandSource,
+  applyDoctorRepair,
+  buildDoctorReport,
+  collectSettingsSecrets,
+  createDoctorCommandEntry,
+  createDoctorCommandModule,
+  createNodeDoctorDeps,
+  isDoctorRepairId,
+  planDoctorRepair,
+  redactDiagnosticText,
+  renderDoctorReport,
+  type IDoctorDisplayVocabulary,
+  resolveCommandOnPath,
+  runDoctor,
+  type IDoctorCheck,
+  type IDoctorDeps,
+  type IDoctorEndpointProbeResult,
+  type IDoctorInputs,
+  type IDoctorPathFacts,
+  type IDoctorRepairPlan,
+  type IDoctorReport,
+  type TDoctorCheckStatus,
+  type TDoctorNotProbed,
+  type TDoctorRepairOutcome,
+  type TDoctorRepairPlanResult,
+} from './doctor/index.js';
+export {
+  EffortCommandSource,
+  createEffortCommandEntry,
+  createEffortCommandModule,
+  executeEffortCommand,
+} from './effort/index.js';
+export {
+  ADVISOR_SETTING_KEY,
+  AdvisorCommandSource,
+  createAdvisorCommandEntry,
+  createAdvisorCommandModule,
+  executeAdvisorCommand,
+} from './advisor/index.js';
 export * from './exit/index.js';
 export * from './help/index.js';
+export {
+  createDevicesCommandModule,
+  type IDeviceListEntry,
+  type IDevicesCommandPort,
+  type IDevicesInitResult,
+  type IDevicesRecoverResult,
+  type IDevicesRevokeResult,
+  type IDevicesView,
+  type TDevicesOutcome,
+  type TDevicesRefusal,
+} from './devices/index.js';
+export {
+  createKeybindingsCommandEntry,
+  createKeybindingsCommandModule,
+  KeybindingsCommandSource,
+  type IKeybindingsFilePort,
+} from './keybindings/index.js';
+export {
+  createThemeCommandEntry,
+  createThemeCommandModule,
+  executeThemeCommand,
+  ThemeCommandSource,
+} from './theme/index.js';
+// Re-exported from the contract package so a composition root that depends on this package — the
+// CLI — can name the port it injects without also depending on the interface package directly.
+export type {
+  IThemeAppearanceState,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+  TReducedMotionOverride,
+} from './theme/index.js';
 export * from './language/index.js';
 export * from './memory/index.js';
+export {
+  createMCPActivationCommandEntry,
+  createMCPActivationCommandModule,
+  MCPActivationCommandSource,
+} from './mcp-activation/mcp-activation-command-module.js';
+export { executeMCPActivationCommand } from './mcp-activation/mcp-activation-command.js';
+export {
+  mcpUnavailableServersNotice,
+  mcpUserActionCommand,
+  mcpUserActionNotice,
+} from './mcp-activation/mcp-model-notice.js';
+export type { TMCPUserAction, TMCPUserActionSurface } from './mcp-activation/mcp-model-notice.js';
 export * from './mode/index.js';
+export {
+  createSandboxCommandModule,
+  executeSandboxCommand,
+  formatSandboxStatus,
+  SANDBOX_MODES,
+  SandboxCommandSource,
+} from './sandbox/index.js';
+export {
+  OutputStyleCommandSource,
+  createOutputStyleCommandEntry,
+  createOutputStyleCommandModule,
+  executeOutputStyleCommand,
+} from './output-style/index.js';
 export * from './permissions/index.js';
 export * from './plugin/index.js';
 export * from './preset/index.js';
 export * from './shell/index.js';
 export * from './provider/index.js';
+export * from './remote-control/index.js';
 export * from './reset/index.js';
 export * from './rewind/index.js';
 export * from './schedule/index.js';
@@ -23,5 +147,3 @@ export * from './settings/index.js';
 export * from './skills/index.js';
 export * from './statusline/index.js';
 export * from './user-local/index.js';
-export { createDefaultPluginCommandAdapter } from './plugins/default-plugin-command-adapter.js';
-export { reloadPluginCommandSource } from './plugins/default-plugin-command-source-loader.js';