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

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

@@ -0,0 +1,218 @@
+/**
+ * `/handoff` (HANDOFF-001, issue #1864) — the consent, and the sentence the operator needs.
+ *
+ * Two properties are asserted on nearly every path, because they are what the command is for:
+ *
+ *   the prompt names what will be LOST before it asks, and
+ *   every outcome says where the session is now.
+ *
+ * A hand-off is irreversible from the source's side. A confirmation that did not mention the
+ * uncommitted work is not consent to lose it, and an outcome that did not say where the session
+ * went leaves the operator not knowing which computer to walk to.
+ */
+
+import type {
+  ICommandHostAdapters,
+  IHandoffProgress,
+  IHandoffStaysBehind,
+} from '@robota-sdk/agent-framework';
+import type { IActionRequest, TActionResponse } from '@robota-sdk/agent-core';
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeHandoffCommand } from '../handoff-command.js';
+
+const HERE: IHandoffProgress = { state: 'offered', stillMine: true };
+
+interface IHarness {
+  readonly destinations?: readonly { readonly deviceId: string; readonly name?: string }[];
+  readonly staysBehind?: IHandoffStaysBehind;
+  readonly transfer?: (
+    deviceId: string,
+    onProgress?: (progress: IHandoffProgress) => void,
+  ) => Promise<IHandoffProgress>;
+  readonly answer?: TActionResponse;
+  /** Omitted entirely when the host has no interactive renderer — that is a case, not a default. */
+  readonly interactive?: boolean;
+  readonly adapter?: boolean;
+}
+
+function host(harness: IHarness = {}) {
+  const asked: IActionRequest[] = [];
+  const adapters: ICommandHostAdapters =
+    harness.adapter === false
+      ? {}
+      : {
+          handoff: {
+            destinations: async () => harness.destinations ?? [{ deviceId: 'laptop' }],
+            staysBehind: async () =>
+              harness.staysBehind ?? { uncommittedChanges: false, subprocesses: 0 },
+            transfer:
+              harness.transfer ??
+              (async (_id, onProgress) => {
+                onProgress?.({ state: 'sending', stillMine: true });
+                return { state: 'done', stillMine: false };
+              }),
+            status: () => HERE,
+          },
+        };
+  return {
+    asked,
+    context: {
+      getCommandHostAdapters: () => adapters,
+      getUserInteraction:
+        harness.interactive === false
+          ? () => undefined
+          : () => ({
+              ask: async (request: IActionRequest): Promise<TActionResponse> => {
+                asked.push(request);
+                return harness.answer ?? { type: 'answer', values: ['move'] };
+              },
+            }),
+    },
+  };
+}
+
+describe('the consent names what will be lost, before it asks', () => {
+  it('says the uncommitted work and the running processes stay behind', async () => {
+    const { asked, context } = host({
+      staysBehind: { uncommittedChanges: true, subprocesses: 3 },
+    });
+    await executeHandoffCommand(context, 'laptop');
+
+    expect(asked).toHaveLength(1);
+    const description = asked[0]?.description ?? '';
+    expect(description).toContain('uncommitted changes');
+    expect(description).toContain('3 running process');
+    // The credential line is unconditional: it is true on every hand-off, and it is the one that
+    // explains why the other machine may refuse at the last step.
+    expect(description).toContain('credentials are never transferred');
+  });
+
+  it('omits what does not apply, so the prompt is not a standing warning nobody reads', async () => {
+    const { asked, context } = host({
+      staysBehind: { uncommittedChanges: false, subprocesses: 0 },
+    });
+    await executeHandoffCommand(context, 'laptop');
+
+    const description = asked[0]?.description ?? '';
+    expect(description).not.toContain('uncommitted changes');
+    expect(description).not.toContain('running process');
+    expect(description).toContain('credentials are never transferred');
+  });
+
+  it('does not transfer when the operator declines', async () => {
+    const transfer = vi.fn();
+    const { context } = host({ answer: { type: 'answer', values: ['stay'] }, transfer });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(transfer).not.toHaveBeenCalled();
+    expect(result.message).toContain('still on this machine');
+  });
+
+  it('treats a dismissed prompt as a decline, never as a yes', async () => {
+    const transfer = vi.fn();
+    const { context } = host({ answer: { type: 'cancelled' }, transfer });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(transfer).not.toHaveBeenCalled();
+    expect(result.message).toContain('still on this machine');
+  });
+
+  it('refuses when no human is attached, rather than proceeding unasked', async () => {
+    const transfer = vi.fn();
+    const { context } = host({ interactive: false, transfer });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.success).toBe(false);
+    expect(transfer).not.toHaveBeenCalled();
+    expect(result.message).toContain('needs a person to confirm');
+    expect(result.message).toContain('still on this machine');
+  });
+});
+
+describe('every outcome says where the session is now', () => {
+  it('says the destination owns it when the transfer completes', async () => {
+    const { context } = host({
+      transfer: async () => ({ state: 'done', stillMine: false }),
+    });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('laptop saved this session and has not started it');
+    expect(result.message).toContain('this one ends');
+  });
+
+  it('says the session is still here when the transfer stops, and why', async () => {
+    const { context } = host({
+      transfer: async () => ({
+        state: 'stopped',
+        reason: 'the destination resolved no provider credential',
+        stillMine: true,
+      }),
+    });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('no provider credential');
+    expect(result.message).toContain('still on this machine');
+    expect(result.message).not.toContain('this one ends');
+  });
+
+  it('names the waiting phase as safe to leave, since that is when it looks stuck', async () => {
+    const { context } = host({
+      transfer: async (_id, onProgress) => {
+        onProgress?.({ state: 'awaiting-confirmation', stillMine: true });
+        return { state: 'done', stillMine: false };
+      },
+    });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.message).toContain('this machine keeps it');
+  });
+});
+
+describe('what it refuses before asking anything', () => {
+  it('says a host with no carrier cannot move a session', async () => {
+    const { asked, context } = host({ adapter: false });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.success).toBe(false);
+    expect(asked).toHaveLength(0);
+    expect(result.message).toContain('no hand-off carrier');
+    expect(result.message).toContain('still here');
+  });
+
+  it('refuses a destination that is not reachable, and lists the ones that are', async () => {
+    const { asked, context } = host({
+      destinations: [{ deviceId: 'laptop', name: 'Work laptop' }],
+    });
+    const result = await executeHandoffCommand(context, 'tablet');
+
+    expect(result.success).toBe(false);
+    expect(asked).toHaveLength(0);
+    expect(result.message).toContain("No reachable machine is called 'tablet'");
+    expect(result.message).toContain('Work laptop');
+    expect(result.message).toContain('still on this machine');
+  });
+
+  it('lists the destinations when called with no argument', async () => {
+    const { asked, context } = host({
+      destinations: [{ deviceId: 'laptop' }, { deviceId: 'tablet' }],
+    });
+    const result = await executeHandoffCommand(context, '');
+
+    expect(asked).toHaveLength(0);
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('laptop');
+    expect(result.message).toContain('tablet');
+  });
+
+  it('says so plainly when nothing is reachable', async () => {
+    const { context } = host({ destinations: [] });
+    const result = await executeHandoffCommand(context, '');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('No other machine is reachable');
+    expect(result.message).toContain('still on this machine');
+  });
+});

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

@@ -0,0 +1,49 @@
+import { executeHandoffCommand } from './handoff-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createHandoffCommandEntry(): ICommand {
+  return {
+    name: 'handoff',
+    displayName: 'Hand off',
+    description:
+      "Push this conversation to another running session for the same user on this machine, or to another linked device, after the operator confirms what stays behind (uncommitted changes, running processes; credentials never travel). The receiving operator must also accept; the session arrives saved, not started, and this one ends once it is saved there. With no argument it lists the sessions and devices it could go to. User-only: the model cannot run it; when the user wants to continue this work in another session or on another device, suggest they run `/handoff <session-or-device-id>`.",
+    source: 'handoff',
+    // User-only: a hand-off moves authority over the operator's work to another place, a decision
+    // about where the person is, not about the task.
+    modelInvocable: false,
+    userInvocable: true,
+    argumentHint: '[session-id]',
+  };
+}
+
+function createHandoffSystemCommand(): ISystemCommand {
+  const entry = createHandoffCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: (context, args) => executeHandoffCommand(context, args),
+  };
+}
+
+export class HandoffCommandSource implements ICommandSource {
+  readonly name = 'handoff';
+
+  getCommands(): ICommand[] {
+    return [createHandoffCommandEntry()];
+  }
+}
+
+export function createHandoffCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-handoff',
+    commandSources: [new HandoffCommandSource()],
+    systemCommands: [createHandoffSystemCommand()],
+  };
+}

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, and this one ends.';
+}
+
+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 where this session could move to',
+      '  /handoff <session-or-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} saved this session and has not started it; resume it there.`
+        : `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

@@ -0,0 +1,134 @@
+import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
+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() {
+  return createTestSessionRuntime({
+    clearHistory: () => undefined,
+    compact: async () => undefined,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getPermissionMode: () => 'default',
+    setPermissionMode: () => undefined,
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 0,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
+    getHistory: () => [],
+  });
+}
+
+function createCommandHostContext() {
+  const checkpoint = {
+    id: 'checkpoint_1',
+    sessionId: 'session_1',
+    sequence: 1,
+    prompt: 'prompt',
+    createdAt: '2026-05-03T00:00:00.000Z',
+    fileCount: 0,
+  };
+  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,
+          runner: 'runtime',
+        },
+        {
+          name: 'provider',
+          displayName: 'Provider Setup',
+          description: 'Manage provider profiles',
+          modelInvocable: true,
+          runner: 'runtime',
+        },
+        // 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,
+          runner: 'runtime',
+        },
+      ],
+      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', () => {
+  it('contributes help command metadata and executable command', () => {
+    const module = createHelpCommandModule();
+
+    expect(module.name).toBe('agent-command-help');
+    expect(module.commandSources?.[0]?.getCommands()).toEqual([
+      {
+        name: 'help',
+        displayName: 'Help',
+        description: 'Show available commands',
+        source: 'help',
+        modelInvocable: false,
+      },
+    ]);
+    expect(module.systemCommands?.map((command) => command.name)).toEqual(['help']);
+    expect(module.systemCommands?.[0]?.lifecycle).toBe('inline');
+    expect(module.systemCommands?.[0]?.modelInvocable).toBe(false);
+  });
+});
+
+describe('executeHelpCommand', () => {
+  it('renders the composed command list from the host context', () => {
+    const result = executeHelpCommand(createCommandHostContext(), '');
+
+    expect(result).toEqual({
+      success: true,
+      message: [
+        'Available commands:',
+        '  Help (/help)                     — Show available commands',
+        '  Provider Setup (/provider)       — Manage provider profiles',
+        '  Plugins (/plugin)                — Manage plugins',
+      ].join('\n'),
+    });
+  });
+});