@robota-sdk/agent-command 3.0.0-beta.82 → 3.0.0-beta.83

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

@@ -55,12 +55,14 @@ function createCommandHostContext() {
           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.
@@ -69,6 +71,7 @@ function createCommandHostContext() {
           displayName: 'Plugins',
           description: 'Manage plugins',
           modelInvocable: false,
+          runner: 'runtime',
         },
       ],
       listEditCheckpoints: () => [],

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

@@ -86,6 +86,7 @@ describe('formatCommandHelpMessage — example field', () => {
         description: 'Compress context window',
         example: '/compact Summarize the current context',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 
@@ -102,6 +103,7 @@ describe('formatCommandHelpMessage — example field', () => {
         description: 'Manage provider profiles',
         example: '/provider switch production',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 
@@ -117,6 +119,7 @@ describe('formatCommandHelpMessage — example field', () => {
         displayName: 'Help',
         description: 'Show available commands',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 

package/src/index.ts

@@ -79,8 +79,11 @@ export {
   type IDeviceListEntry,
   type IDevicesCommandPort,
   type IDevicesInitResult,
+  type IDevicesAddResult,
+  type IDevicesJoinResult,
   type IDevicesRecoverResult,
   type IDevicesRevokeResult,
+  type IDevicesMeshStatus,
   type IDevicesView,
   type TDevicesOutcome,
   type TDevicesRefusal,
@@ -146,4 +149,9 @@ export * from './session/index.js';
 export * from './settings/index.js';
 export * from './skills/index.js';
 export * from './statusline/index.js';
+export {
+  createTerminalClientCommands,
+  type ITerminalClientCommand,
+  type ITerminalClientCommandOptions,
+} from './terminal-client/index.js';
 export * from './user-local/index.js';

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

@@ -21,13 +21,23 @@ export function createKeybindingsCommandEntry(): ICommand {
     source: 'keybindings',
     // User-only: UI preference.
     modelInvocable: false,
+    // Key bindings belong to the terminal the user sits at, so that terminal runs it, even when
+    // attached.
+    runner: 'client',
+    surfaces: ['terminal'],
   };
 }
 
-async function executeKeybindingsCommand(
-  file: IKeybindingsFilePort,
+// A host without a terminal (the desktop app's sidecar) still answers, so the command is never
+// "unknown" there — it says where key bindings live instead.
+const KEYBINDINGS_UNAVAILABLE =
+  'Key bindings belong to the robota terminal, and this surface has none. Run /keybindings in the robota terminal.';
+
+export async function executeKeybindingsCommand(
+  file: IKeybindingsFilePort | undefined,
   context: ICommandHostTerminalHandoff & ICommandHostWorkspace,
 ): Promise<ICommandResult> {
+  if (!file) return { success: false, message: KEYBINDINGS_UNAVAILABLE };
   if (!context.canHandoffTerminal()) {
     return { success: false, message: 'Keybindings editor is unavailable here.' };
   }
@@ -54,7 +64,9 @@ export class KeybindingsCommandSource implements ICommandSource {
   }
 }
 
-export function createKeybindingsCommandModule(file: IKeybindingsFilePort): ICommandModule {
+export function createKeybindingsCommandModule(
+  file: IKeybindingsFilePort | undefined,
+): ICommandModule {
   const entry = createKeybindingsCommandEntry();
   const command: ISystemCommand = {
     name: entry.name,
@@ -63,6 +75,8 @@ export function createKeybindingsCommandModule(file: IKeybindingsFilePort): ICom
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: false,
+    runner: entry.runner,
+    surfaces: entry.surfaces,
     lifecycle: 'inline',
     execute: (context) => executeKeybindingsCommand(file, context),
   };

package/src/mcp-activation/__tests__/mcp-activation-command.test.ts

@@ -484,6 +484,47 @@ describe('/mcp login', () => {
     expect(h.added).toEqual([]);
   });
 
+  it('asks nothing for a sign-in that has already ended', async () => {
+    const ended = new AbortController();
+    ended.abort();
+    let choice: string | undefined;
+    const h = harness(
+      async (request) => {
+        choice = await request.confirmBrowser!(PROMPT, ended.signal);
+        await expect(request.readRedirect!(PROMPT, ended.signal)).rejects.toThrow();
+        return {
+          serverId: request.serverId,
+          failure: 'cancelled',
+          preRegisteredClient: false,
+          tools: [],
+        };
+      },
+      { type: 'answer', values: ['open'], text: 'http://127.0.0.1:1/callback?code=c&state=s' },
+    );
+    await h.run('login files');
+    expect(choice).toBe('cancel');
+    expect(h.asked).toEqual([]);
+  });
+
+  it('never opens the browser for a sign-in that ended while the user was choosing', async () => {
+    const signIn = new AbortController();
+    let choice: string | undefined;
+    const h = harness(
+      async (request) => {
+        choice = await request.confirmBrowser!(PROMPT, signIn.signal);
+        return signedIn(request.serverId);
+      },
+      () => {
+        // The sign-in times out while the question is still open; the user then picks `open`.
+        signIn.abort();
+        return { type: 'answer', values: ['open'] };
+      },
+    );
+    await h.run('login files');
+    expect(h.asked).toHaveLength(1);
+    expect(choice).toBe('cancel');
+  });
+
   it('never asks for a client secret, and names the terminal command instead', async () => {
     const h = harness(async (request) => signedIn(request.serverId));
     const result = await h.run('login files --client-secret');

package/src/mcp-activation/mcp-activation-command.ts

@@ -259,7 +259,10 @@ function browserConfirmer(
 ): ICommandMCPOAuthLoginRequest['confirmBrowser'] {
   const ui = context.getUserInteraction();
   if (ui === undefined) return undefined;
-  return async (prompt) => {
+  return async (prompt, signal) => {
+    // The ask port cannot withdraw a question, so a sign-in that has already ended is not asked
+    // about, and an answer that arrives after it ended never opens a browser for it.
+    if (signal.aborted) return 'cancel';
     loginPrompts += 1;
     const answer = await ui.ask({
       id: `mcp-login-browser-${loginPrompts}`,
@@ -275,7 +278,7 @@ function browserConfirmer(
       maxSelect: 1,
       default: { values: ['open'] },
     });
-    if (answer.type !== 'answer') return 'cancel';
+    if (answer.type !== 'answer' || signal.aborted) return 'cancel';
     const choice = answer.values[0];
     return choice === 'open' || choice === 'paste' ? choice : 'cancel';
   };
@@ -288,7 +291,9 @@ function redirectReader(
 ): ICommandMCPOAuthLoginRequest['readRedirect'] {
   const ui = context.getUserInteraction();
   if (ui === undefined) return undefined;
-  return async (prompt) => {
+  return async (prompt, signal) => {
+    // A sign-in that has already ended (cancelled or timed out) does not ask for a paste.
+    signal.throwIfAborted();
     loginPrompts += 1;
     const answer = await ui.ask({
       id: `mcp-login-redirect-${loginPrompts}`,

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

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { createPeersCommandModule } from '../peers-command-module.js';
+
+describe('/peers command module', () => {
+  it('is user-only: never model-invocable, and palette metadata matches the executable', () => {
+    const module = createPeersCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+    expect(executable?.modelInvocable).toBe(false);
+    expect(palette?.modelInvocable).toBe(false);
+    expect(executable?.userInvocable).toBe(true);
+    expect(executable?.description).toBe(palette?.description);
+  });
+
+  it('tells the model it covers linked devices, what it returns, and what to suggest', () => {
+    const description =
+      createPeersCommandModule().commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toMatch(/linked over the device mesh/);
+    expect(description).toMatch(/returns/i);
+    expect(description).toMatch(/user-only/i);
+    expect(description).toContain('`/peers`');
+  });
+});

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

@@ -142,6 +142,84 @@ describe('what the operator is told', () => {
   });
 });
 
+describe('linked devices of the device mesh', () => {
+  const DEVICE = 'D'.repeat(43);
+
+  function hostWithDevices(
+    peers: readonly TPeerSummary[],
+    devices: readonly { deviceId: string; name?: string; locality: 'same-host' | 'another-host' }[],
+  ): ICommandHostAdapterAccess {
+    return {
+      getCommandHostAdapters: () => ({
+        localPeers: { list: () => peers, ownSessionId: () => OWN, listDevices: () => devices },
+      }),
+    } as ICommandHostAdapterAccess;
+  }
+
+  it('lists a linked device beside the sessions on this host, addressable by its id', async () => {
+    const result = await executePeersCommand(
+      hostWithDevices(
+        [
+          { sessionId: OWN, liveness: 'alive' },
+          { sessionId: 'session-other', liveness: 'alive' },
+        ],
+        [{ deviceId: DEVICE, name: 'desktop', locality: 'another-host' }],
+      ),
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('session-other');
+    expect(result.message).toMatch(new RegExp(`${DEVICE}\\s+desktop\\s+on another machine`));
+    expect(result.message).toContain('/peers send <session-or-device-id>');
+  });
+
+  it('lists a linked device even when this is the only session on this host', async () => {
+    const result = await executePeersCommand(
+      hostWithDevices(
+        [{ sessionId: OWN, liveness: 'alive' }],
+        [{ deviceId: DEVICE, locality: 'same-host' }],
+      ),
+    );
+    expect(result.message).not.toContain('No other live session');
+    expect(result.message).toMatch(new RegExp(`${DEVICE}\\s+on this machine`));
+  });
+});
+
+describe('when local discovery is off but the device mesh is not', () => {
+  const DEVICE = 'D'.repeat(43);
+
+  function hostWithoutDiscovery(
+    devices: readonly { deviceId: string; name?: string; locality: 'same-host' | 'another-host' }[],
+  ): ICommandHostAdapterAccess {
+    return {
+      getCommandHostAdapters: () => ({
+        localPeers: {
+          list: () => [],
+          ownSessionId: () => OWN,
+          listDevices: () => devices,
+          localDiscoveryOff: 'the rendezvous directory was not admitted',
+        },
+      }),
+    } as ICommandHostAdapterAccess;
+  }
+
+  it('lists the linked devices and says why sessions on this host are not listed', async () => {
+    const result = await executePeersCommand(
+      hostWithoutDiscovery([{ deviceId: DEVICE, name: 'desktop', locality: 'another-host' }]),
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toMatch(new RegExp(`${DEVICE}\\s+desktop\\s+on another machine`));
+    expect(result.message).toContain('not admitted');
+    expect(result.message).not.toContain('Live sessions');
+    expect(result.message).toContain('/peers send <device-id>');
+  });
+
+  it('with no device linked, says discovery is off rather than that nobody is there', async () => {
+    const result = await executePeersCommand(hostWithoutDiscovery([]));
+    expect(result.message).toContain('not admitted');
+    expect(result.message).not.toContain('No other live session');
+  });
+});
+
 describe('when the host wires no discovery', () => {
   it('says the feature is unavailable rather than reporting no peers', async () => {
     // The two are different facts and the difference matters: "nobody is there" invites the operator

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

@@ -8,7 +8,7 @@ export function createPeersCommandEntry(): ICommand {
     name: 'peers',
     displayName: 'Peers',
     description:
-      'List the other live sessions on this host, send one a message, or send one a copy of a file',
+      "List the other live Robota sessions on this host and the user's other devices linked over the device mesh, send one a message, or send one a copy of a file. Returns the sessions and devices with the ids to address them by (linked devices even when local discovery is off and sessions on this host cannot be listed), or how a send ended. User-only: the model cannot run it; it answers a peer's message with its reply tool, and when the user wants to reach another session or device, suggest they run `/peers`.",
     source: 'peers',
     // The model does not enumerate the operator's other sessions. Discovery is an operator-facing
     // view of who is at the machine, which is a fact about the person and not about the task.

package/src/peers/peers-command.ts

@@ -33,6 +33,16 @@ function describe(peer: TPeerSummary, ownSessionId: string): string {
   return `  ${peer.sessionId}${peer.name ? `  ${peer.name}` : ''}  status ${status}${self ? '' : workspace(peer)}${liveness}${self}`;
 }
 
+type TDeviceSummary = ReturnType<
+  NonNullable<NonNullable<ICommandHostAdapters['localPeers']>['listDevices']>
+>[number];
+
+/** A linked device: its full id, since that is what `send` takes, and where it runs. */
+function describeDevice(device: TDeviceSummary): string {
+  const where = device.locality === 'same-host' ? 'on this machine' : 'on another machine';
+  return `  ${device.deviceId}${device.name ? `  ${device.name}` : ''}  ${where}`;
+}
+
 /** The relation this session verified. A claim it could not confirm is named as such, not shown. */
 function workspace(peer: TPeerSummary): string {
   if (peer.workspaceClaim === 'mismatched') return '  workspace claim mismatched, not believed';
@@ -165,6 +175,21 @@ export async function executePeersCommand(
   const sendVerb = /^send(?=\s|$)/.exec(trimmed);
   if (sendVerb !== null) return executeSend(adapter, trimmed.slice(sendVerb[0].length));
 
+  const devices = adapter.listDevices?.() ?? [];
+  const discoveryOff = adapter.localDiscoveryOff;
+  if (discoveryOff !== undefined) {
+    const off = `Sessions on this host are not listed: local peer discovery is off for this session (${discoveryOff}).`;
+    return {
+      message:
+        devices.length === 0
+          ? `${off}\nNo device is linked right now.`
+          : `Linked devices:\n${devices.map(describeDevice).join('\n')}\n\n${off}` +
+            `\n\nSend to one: /peers send <device-id> <message>` +
+            `\nSend a file: /peers send-file <device-id> <path>`,
+      success: true,
+    };
+  }
+
   const own = adapter.ownSessionId();
   // The workspace-judged listing when the host has one; it reads git, so only this view asks for it.
   const peers = (
@@ -172,7 +197,7 @@ export async function executePeersCommand(
   ).filter(addressable);
   const others = peers.filter((peer) => peer.sessionId !== own);
 
-  if (others.length === 0) {
+  if (others.length === 0 && devices.length === 0) {
     return {
       message:
         'No other live session is announced. Start a second session on this host, as this user, ' +
@@ -181,11 +206,15 @@ export async function executePeersCommand(
     };
   }
 
-  const lines = peers.map((peer) => describe(peer, own));
+  const sections = [`Live sessions:\n${peers.map((peer) => describe(peer, own)).join('\n')}`];
+  if (devices.length > 0) {
+    sections.push(`Linked devices:\n${devices.map(describeDevice).join('\n')}`);
+  }
+  const target = devices.length > 0 ? '<session-or-device-id>' : '<session-id>';
   return {
     message:
-      `Live sessions:\n${lines.join('\n')}\n\nSend to one: /peers send <session-id> <message>` +
-      '\nSend a file: /peers send-file <session-id> <path>',
+      `${sections.join('\n\n')}\n\nSend to one: /peers send ${target} <message>` +
+      `\nSend a file: /peers send-file ${target} <path>`,
     success: true,
   };
 }

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

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import type {
   IEditCheckpointInspection,
   IEditCheckpointRestoreResult,
@@ -252,4 +252,34 @@ describe('executeRewindCommand', () => {
     expect(result?.success).toBe(false);
     expect(result?.message).toBe('Unknown edit checkpoint');
   });
+
+  describe('in a session built without a checkpoint store', () => {
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('tells a restricted workspace to trust it, for every subcommand', async () => {
+      vi.spyOn(process, 'platform', 'get').mockReturnValue('linux');
+      const session = createInteractiveSession();
+
+      for (const args of ['', 'list', 'inspect turn-0001', 'restore turn-0001', 'branches']) {
+        const result = await session.executeCommand('rewind', args);
+        expect(result?.success).toBe(false);
+        expect(result?.message).toBe(
+          'Edit checkpoints need a trusted workspace: run robota trust --yes, then restart robota.',
+        );
+      }
+    });
+
+    it('says why on a host that cannot prove a project write is safe, without naming trust', async () => {
+      vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin');
+      const session = createInteractiveSession();
+
+      const result = await session.executeCommand('rewind', 'list');
+
+      expect(result?.success).toBe(false);
+      expect(result?.message).toContain('cannot prove a write stays inside the project');
+      expect(result?.message).not.toContain('trust');
+    });
+  });
 });

package/src/rewind/rewind-command.ts

@@ -1,4 +1,5 @@
 import {
+  EditCheckpointsUnavailableError,
   inspectCommandEditCheckpoint,
   listCommandEditCheckpoints,
   restoreCommandEditCheckpoint,
@@ -121,13 +122,33 @@ function formatRollbackResult(result: IEditCheckpointRestoreResult): ICommandRes
   };
 }
 
+/** A restricted workspace is the one case the user fixes with a command; the rest say why. */
+function unavailableMessage(error: EditCheckpointsUnavailableError): string {
+  return error.reason === 'restricted-workspace'
+    ? 'Edit checkpoints need a trusted workspace: run robota trust --yes, then restart robota.'
+    : error.message;
+}
+
 function formatError(error: Error | string): ICommandResult {
   return {
-    message: error instanceof Error ? error.message : String(error),
+    message:
+      error instanceof EditCheckpointsUnavailableError
+        ? unavailableMessage(error)
+        : error instanceof Error
+          ? error.message
+          : String(error),
     success: false,
   };
 }
 
+function list(context: ICommandHostCheckpoints): ICommandResult {
+  try {
+    return formatList(listCommandEditCheckpoints(context));
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
 function inspect(
   context: ICommandHostCheckpoints,
   checkpointId: string | undefined,
@@ -222,7 +243,7 @@ export async function executeRewindCommand(
   const subcommand = args[SUBCOMMAND_INDEX] ?? 'list';
 
   if (subcommand === 'list') {
-    return formatList(listCommandEditCheckpoints(context));
+    return list(context);
   }
 
   if (subcommand === 'inspect') {

package/src/schedule/__tests__/schedule-redos.test.ts

@@ -7,10 +7,12 @@
  * The pre-fix regexes used `\s+(.+)$`; because `.` also matches a space, the split point between
  * `\s+` and `(.+)` was ambiguous and a non-matching argument was rejected in O(n^2). Measured
  * pre-fix on the inputs below: ~17s (`/schedule cron`) and ~15s (`/monitor`); post-fix, <1ms.
+ * `/loop`'s leading interval had the same `\s+([\s\S]+)$` shape and is held to the same bound.
  */
 
 import { describe, expect, it, vi } from 'vitest';
 
+import { executeLoopCommand } from '../loop-command.js';
 import { executeMonitorCommand } from '../schedule-command.js';
 import { parseScheduleSpec } from '../schedule-spec-parser.js';
 
@@ -78,4 +80,35 @@ describe('schedule argument parsing is not polynomial-ReDoS-able', () => {
       }),
     );
   });
+
+  it('parses a pumped leading-interval `/loop` in linear time', async () => {
+    // The shape CodeQL named for `\s+([\s\S]+)$`: an interval, then a long run of whitespace.
+    const spawnScheduledWake = vi.fn();
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+    const hostile = `0s\t${'\t\t'.repeat(PUMP_LENGTH)}x`;
+
+    const started = performance.now();
+    const result = await executeLoopCommand(host, vi.fn(), hostile);
+    const took = performance.now() - started;
+
+    expect(result.success).toBe(false);
+    expect(spawnScheduledWake).not.toHaveBeenCalled();
+    expect(took).toBeLessThan(BUDGET_MS);
+  });
+
+  it.each([
+    ['5m check the build', 'check the build'],
+    ['5m \t\n  check   the build  ', 'check   the build'],
+    ['5M\ncheck', 'check'],
+  ])('still reads a leading-interval `/loop` identically: %j', async (args, instruction) => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_1' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+
+    const result = await executeLoopCommand(host, vi.fn(), args);
+
+    expect(result.success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenCalledWith(
+      expect.objectContaining({ agentInstruction: instruction }),
+    );
+  });
 });

package/src/schedule/loop-command.ts

@@ -115,7 +115,9 @@ function parseCreate(
     const requestedMs = parseDuration(intervalOnly[1]!, intervalOnly[2]!.toLowerCase());
     return requestedMs === undefined ? undefined : { instruction: boundedDefault, requestedMs };
   }
-  const leading = /^(\d+)(s|m|h|d)\s+([\s\S]+)$/i.exec(args);
+  // One required space, then the rest verbatim (trimmed below): `\s+` before `[\s\S]+` split the
+  // same spaces two ways, which CodeQL reads as polynomial backtracking.
+  const leading = /^(\d+)(s|m|h|d)\s([\s\S]+)$/i.exec(args);
   if (leading) {
     const instruction = leading[3]!.trim();
     const requestedMs = parseDuration(leading[1]!, leading[2]!.toLowerCase());

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

@@ -14,6 +14,9 @@ export function createShellCommandEntry(): ICommand {
     source: 'shell',
     // User-only: the user's own shell passthrough; the model has its permission-gated shell tool.
     modelInvocable: false,
+    // It takes over the terminal the user sits at, so that terminal runs it, even when attached.
+    runner: 'client',
+    surfaces: ['terminal'],
   };
 }
 
@@ -26,6 +29,8 @@ function createShellSystemCommand(executable?: string): ISystemCommand {
     requiresPermission: true,
     userInvocable: true,
     modelInvocable: false,
+    runner: entry.runner,
+    surfaces: entry.surfaces,
     lifecycle: 'inline',
     execute: (context, args) => executeShellCommand(context, args, executable),
   };