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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-command",
-  "version": "3.0.0-beta.81",
+  "version": "3.0.0-beta.83",
   "description": "Consolidated command module implementations for Robota SDK CLI",
   "type": "module",
   "main": "dist/node/index.js",
@@ -28,19 +28,24 @@
           "default": "./dist/node/index.cjs"
         }
       }
-    }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "CHANGELOG.md"
   ],
   "dependencies": {
-    "@robota-sdk/agent-core": "3.0.0-beta.81",
-    "@robota-sdk/agent-framework": "3.0.0-beta.81",
-    "@robota-sdk/agent-interface-execution": "3.0.0-beta.81",
-    "@robota-sdk/agent-interface-command": "3.0.0-beta.81",
-    "@robota-sdk/agent-preset": "3.0.0-beta.81",
-    "@robota-sdk/agent-interface-session": "3.0.0-beta.81"
+    "@robota-sdk/agent-core": "3.0.0-beta.83",
+    "@robota-sdk/agent-framework": "3.0.0-beta.83",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.83",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.83",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.83",
+    "@robota-sdk/agent-preset": "3.0.0-beta.83"
   },
   "devDependencies": {
     "@types/node": "^22.19.21",
@@ -50,6 +55,11 @@
     "vitest": "^3.2.6"
   },
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota.git",
+    "directory": "packages/agent-command"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/command-module-utils.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSystemCommandFromEntry } from './command-module-utils.js';
+
+const behavior = {
+  lifecycle: 'inline',
+  requiresPermission: false,
+  execute: () => ({ success: true, message: 'ran' }),
+} as const;
+
+describe('createSystemCommandFromEntry', () => {
+  it('#3189: carries where the entry says it runs, so the catalog and the palette agree', () => {
+    const command = createSystemCommandFromEntry(
+      {
+        name: 'local',
+        description: 'Runs on the terminal',
+        source: 'test',
+        runner: 'client',
+        surfaces: ['terminal'],
+      },
+      behavior,
+    );
+
+    expect(command.runner).toBe('client');
+    expect(command.surfaces).toEqual(['terminal']);
+  });
+
+  it('leaves an unstated placement unstated rather than guessing one', () => {
+    const command = createSystemCommandFromEntry(
+      { name: 'plain', description: 'Runs on the runtime', source: 'test' },
+      behavior,
+    );
+
+    expect('runner' in command).toBe(false);
+    expect('surfaces' in command).toBe(false);
+  });
+});

package/src/command-module-utils.ts

@@ -25,6 +25,8 @@ export function createSystemCommandFromEntry(
     ...(entry.argumentHint !== undefined ? { argumentHint: entry.argumentHint } : {}),
     ...(entry.safety !== undefined ? { safety: entry.safety } : {}),
     ...(entry.subcommands !== undefined ? { subcommands: entry.subcommands } : {}),
+    ...(entry.runner !== undefined ? { runner: entry.runner } : {}),
+    ...(entry.surfaces !== undefined ? { surfaces: entry.surfaces } : {}),
     ...(behavior.semanticRole !== undefined ? { semanticRole: behavior.semanticRole } : {}),
     lifecycle: behavior.lifecycle,
     requiresPermission: behavior.requiresPermission,

package/src/default/__tests__/default-command-modules.test.ts

@@ -1,4 +1,8 @@
-import { describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it } from 'vitest';
 
 import type { IProviderDefinition } from '@robota-sdk/agent-core';
 import type {
@@ -8,6 +12,10 @@ import type {
 
 import { createDefaultCommandModules } from '../default-command-modules.js';
 
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'robota-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
 const providerDefinitions: readonly IProviderDefinition[] = [
   {
     type: 'anthropic',
@@ -26,7 +34,7 @@ const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
   writeTargetSettings: () => undefined,
 };
 
-const baseOptions = { cwd: '/tmp', userLocalStorageRoot: '/tmp/robota-test', providerDefinitions, providerSettingsAdapter } as const;
+const baseOptions = { cwd: '/tmp', userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT, providerDefinitions, providerSettingsAdapter } as const;
 
 function moduleNames(opts: Parameters<typeof createDefaultCommandModules>[0]): string[] {
   return createDefaultCommandModules(opts).modules.map((module) => module.name);
@@ -45,7 +53,7 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
     // `/output-style`; FLOW-008 added `/effort`; `/advisor` joined beside it). The list below is the
     // assertion that matters — a length on its own can be restored by any substitution, and the count
     // exists only to catch an addition that also removed something.
-    expect(names).toHaveLength(35);
+    expect(names).toHaveLength(38);
     expect(names).toEqual([
       'agent-command-skills',
       'agent-command-help',
@@ -66,6 +74,8 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
       'agent-command-shell',
       'agent-command-editor',
       'agent-command-git',
+      'agent-command-keybindings',
+      'agent-command-theme',
       'agent-command-memory',
       'agent-command-mcp-activation',
       'agent-command-user-local',
@@ -80,6 +90,7 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
       'agent-command-plugin',
       'agent-command-settings',
       'agent-command-peers',
+      'agent-command-events',
       'agent-command-handoff',
       'agent-command-remote-control',
       'agent-command-provider',
@@ -92,14 +103,42 @@ describe('createDefaultCommandModules — PRESET-004 module-selection delta', ()
     expect(names).toHaveLength(2);
   });
 
-  it('BEHAVIOR-2003: registers /keybindings only when the file capability is injected', () => {
-    expect(moduleNames(baseOptions)).not.toContain('agent-command-keybindings');
-    expect(
-      moduleNames({
-        ...baseOptions,
-        keybindingsFilePort: { ensureFile: async () => '/tmp/keybindings.json' },
-      }),
-    ).toContain('agent-command-keybindings');
+  it('#3186: /keybindings and /theme exist on a host without a terminal, and say where they work', async () => {
+    const { modules } = createDefaultCommandModules(baseOptions);
+    const commands = modules.flatMap((module) => module.systemCommands ?? []);
+    for (const name of ['keybindings', 'theme']) {
+      const command = commands.find((candidate) => candidate.name === name);
+      expect(command, name).toBeDefined();
+      const result = await command!.execute({} as never, '');
+      expect(result).toMatchObject({ success: false });
+      expect(result.message).toMatch(/robota terminal/);
+    }
+  });
+
+  it('#3189: exactly /editor, /keybindings, /shell and /theme run on the terminal client', () => {
+    const { modules } = createDefaultCommandModules(baseOptions);
+    const TERMINAL_CLIENT = ['editor', 'keybindings', 'shell', 'theme'];
+
+    // The executable commands: what the runtime keeps in its catalog and what the listing reads.
+    const clientSystemCommands = modules
+      .flatMap((module) => module.systemCommands ?? [])
+      .filter((command) => command.runner === 'client');
+    expect(clientSystemCommands.map((command) => command.name).sort()).toEqual(TERMINAL_CLIENT);
+    for (const command of clientSystemCommands) {
+      expect(command.surfaces, command.name).toEqual(['terminal']);
+    }
+
+    // The palette entries, which must say the same — the two views cannot disagree.
+    const clientEntries = modules
+      .flatMap((module) => module.commandSources ?? [])
+      .flatMap((source) => source.getCommands())
+      .filter((entry) => entry.runner === 'client');
+    expect(clientEntries.map((entry) => entry.name).sort()).toEqual(TERMINAL_CLIENT);
+    for (const entry of clientEntries) {
+      expect(entry.surfaces, entry.name).toEqual(['terminal']);
+      // Running on the client does not change who may run it: all four stay user-only.
+      expect(entry.modelInvocable, entry.name).toBe(false);
+    }
   });
 
   it('TC-02: disabledCommandModules blacklist removes the named module', () => {

package/src/default/__tests__/model-exposure.test.ts

@@ -7,7 +7,11 @@
  * each command's entry.
  */
 
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, afterEach, describe, expect, it, vi } from 'vitest';
 
 import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
 import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
@@ -41,6 +45,10 @@ const themeCataloguePort: IThemeCataloguePort = {
   }),
 };
 
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'robota-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
 const fixtures: IDoctorFixture[] = [];
 afterEach(() => {
   for (const fixture of fixtures.splice(0)) fixture.cleanup();
@@ -52,12 +60,16 @@ function allBuiltInCommands(): ISystemCommand[] {
   fixtures.push(fixture);
   const { modules } = createDefaultCommandModules({
     cwd: '/tmp',
-    userLocalStorageRoot: '/tmp/robota-test',
+    userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
     providerDefinitions,
     providerSettingsAdapter,
   });
+  // /keybindings and /theme are in the default set; built here with their capabilities instead.
+  const withoutPortless = modules.filter(
+    (module) => module.name !== 'agent-command-keybindings' && module.name !== 'agent-command-theme',
+  );
   return [
-    ...modules,
+    ...withoutPortless,
     createKeybindingsCommandModule({ ensureFile: async () => '/tmp/keybindings.json' }),
     createThemeCommandModule(themeCataloguePort),
     createDoctorCommandModule(fixture.inputs, fixture.deps),
@@ -94,6 +106,7 @@ const USER_ONLY_COMMANDS = [
   'plugin',
   'reload-plugins',
   'remote-control',
+  'events',
   // Account and credential actions.
   'provider',
   // Permission widening or permission-mode changes.

package/src/default/__tests__/org-policy-forwarding.test.ts

@@ -17,7 +17,11 @@
  * type checker's job.
  */
 
-import { describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it } from 'vitest';
 import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
 import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 
@@ -55,13 +59,17 @@ const adapter: IProviderCommandSettingsAdapter = {
   writeTargetSettings: () => undefined,
 };
 
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'robota-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
 const POLICY: IOrgPolicy = { allowedProviders: ['anthropic'], adminContact: 'ops@example.com' };
 
 /** Build the provider executor the way the PRODUCT does — through the default-modules factory. */
 function executorThroughFactory(orgPolicy?: IOrgPolicy): SystemCommandExecutor {
   const { modules } = createDefaultCommandModules({
     cwd: '/work',
-    userLocalStorageRoot: '/tmp/robota-test',
+    userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
     providerDefinitions,
     providerSettingsAdapter: adapter,
     ...(orgPolicy === undefined ? {} : { orgPolicy }),

package/src/default/default-command-modules.ts

@@ -22,6 +22,7 @@ import { createMemoryCommandModule } from '../memory/index.js';
 import { createModeCommandModule } from '../mode/index.js';
 import { createSandboxCommandModule } from '../sandbox/index.js';
 import { createOutputStyleCommandModule } from '../output-style/index.js';
+import { createEventsCommandModule } from '../events/index.js';
 import { createPeersCommandModule } from '../peers/index.js';
 import { createPermissionsCommandModule } from '../permissions/index.js';
 import { createPlanCommandModule } from '../plan/index.js';
@@ -72,12 +73,11 @@ export interface IDefaultCommandModulesOptions {
    * red when the producer dropped it.
    */
   orgPolicy?: IOrgPolicy;
-  /** Optional TUI-owned file capability; absence means `/keybindings` is not registered. */
+  /** Optional TUI-owned file capability; absent, `/keybindings` says it belongs to the robota terminal. */
   keybindingsFilePort?: IKeybindingsFilePort;
   /**
-   * SCREEN-2002: the surface's theme catalogue. Absence means `/theme` is not registered at all —
-   * print mode and `--serve` render no themes, and a command that cannot do anything is better
-   * missing than present-and-failing.
+   * SCREEN-2002: the surface's theme catalogue. Absent (print mode, `--serve`), `/theme` is still
+   * listed and says it belongs to the robota terminal, which runs it itself when attached.
    */
   themeCataloguePort?: IThemeCataloguePort;
   /**
@@ -173,10 +173,8 @@ export function createDefaultCommandModules({
     createShellCommandModule(),
     createEditorCommandModule(editorTemporaryDirectoryPrefix),
     createGitCommandModule(),
-    ...(keybindingsFilePort === undefined
-      ? []
-      : [createKeybindingsCommandModule(keybindingsFilePort)]),
-    ...(themeCataloguePort === undefined ? [] : [createThemeCommandModule(themeCataloguePort)]),
+    createKeybindingsCommandModule(keybindingsFilePort),
+    createThemeCommandModule(themeCataloguePort),
     ...(doctorInputs === undefined
       ? []
       : [createDoctorCommandModule(doctorInputs, undefined, doctorDisplay)]),
@@ -194,6 +192,7 @@ export function createDefaultCommandModules({
     createPluginCommandModule(),
     createSettingsCommandModule(),
     createPeersCommandModule(),
+    createEventsCommandModule(),
     // HANDOFF-001 (issue #1864). Registered even though no product wires the carrier adapter yet:
     // the command's own answer to a host without one is to say so, which is a better state than a
     // capability nobody can see. It is also what makes the carrier's arrival observable.

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

@@ -44,7 +44,12 @@ function fakePort(): IDevicesCommandPort & { calls: string[] } {
       calls.push(`init:${options.name ?? ''}`);
       return {
         ok: true as const,
-        value: { userId: USER, deviceId: DEVICE_A, signingKeyId: SIGNING, keyStorage: 'OS keychain' },
+        value: {
+          userId: USER,
+          deviceId: DEVICE_A,
+          signingKeyId: SIGNING,
+          keyStorage: 'OS keychain',
+        },
       };
     }),
     recover: vi.fn(async () => {
@@ -63,6 +68,20 @@ function fakePort(): IDevicesCommandPort & { calls: string[] } {
       calls.push(`revoke:${target}`);
       return { ok: true as const, value: { deviceId: DEVICE_B, name: 'desktop' } };
     }),
+    add: vi.fn(async () => {
+      calls.push('add');
+      return {
+        ok: true as const,
+        value: { deviceId: DEVICE_B, name: 'desktop', confirmed: true },
+      };
+    }),
+    join: vi.fn(async (options) => {
+      calls.push(`join:${options.name ?? ''}`);
+      return {
+        ok: true as const,
+        value: { userId: USER, deviceId: DEVICE_B, name: 'desktop', keyStorage: 'OS keychain' },
+      };
+    }),
   };
 }
 
@@ -105,7 +124,19 @@ describe('/devices command', () => {
       'init',
       'revoke',
       'recover',
+      'add',
+      'join',
     ]);
+    // What the model reads names the one-time code as terminal-only, so it never asks for it.
+    expect(palette?.description).toMatch(/enrol/i);
+    expect(palette?.description).toMatch(/terminal/i);
+  });
+
+  it('tells the model it also shows the device mesh status', () => {
+    const description =
+      createDevicesCommandModule(fakePort()).commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toMatch(/device mesh/);
+    expect(description).toMatch(/Operator-only/);
   });
 
   it('lists the roster with short ids, this device, the signing-key holder and expiry', async () => {
@@ -125,6 +156,17 @@ describe('/devices command', () => {
     vi.mocked(port.list).mockResolvedValueOnce(undefined);
     const result = await start(port).command('devices', 'list');
     expect(result?.message).toMatch(/\/devices init/);
+    // A device of a user who already has others joins them; `init` would never link to them.
+    expect(result?.message).toMatch(/\/devices join/);
+    expect(result?.message).toMatch(/separate identity/);
+  });
+
+  it('describes init as for the first device, and join as the way to the devices a user has', () => {
+    const entry = createDevicesCommandModule(fakePort()).commandSources?.[0]?.getCommands()[0];
+    const init = entry?.subcommands?.find((sub) => sub.name === 'init');
+    expect(init?.description).toMatch(/first device/);
+    expect(init?.description).toMatch(/separate identity/);
+    expect(entry?.description).toMatch(/separate identity/);
   });
 
   it('runs init, recover and revoke on the operator terminal', async () => {
@@ -156,7 +198,7 @@ describe('/devices command', () => {
   it('refuses without an interactive terminal and never reaches the port (fail closed)', async () => {
     const port = fakePort();
     const harness = start(port, handoff(false));
-    for (const args of ['init', 'recover', 'revoke abcdef']) {
+    for (const args of ['init', 'recover', 'revoke abcdef', 'add', 'join', 'join desktop']) {
       const result = await harness.command('devices', args);
       expect(result?.success).toBe(false);
       expect(result?.message).toMatch(/interactive terminal/i);
@@ -167,15 +209,17 @@ describe('/devices command', () => {
   it('refuses a model invocation', async () => {
     const port = fakePort();
     const harness = start(port);
-    const result = await harness.session.executeModelCommand('devices', 'init');
-    expect(result?.success ?? false).toBe(false);
+    for (const args of ['init', 'add', 'join']) {
+      const result = await harness.session.executeModelCommand('devices', args);
+      expect(result?.success ?? false).toBe(false);
+    }
     expect(port.calls).toEqual([]);
   });
 
   it('refuses every verb from a remote surface', async () => {
     const port = fakePort();
     const harness = start(port);
-    for (const args of ['', 'init', 'recover', 'revoke abcdef']) {
+    for (const args of ['', 'init', 'recover', 'revoke abcdef', 'add', 'join']) {
       const result = await harness.session.executeCommand('devices', args, 'remote');
       expect(result?.success).toBe(false);
       expect(result?.message).toMatch(/operator/i);
@@ -183,15 +227,58 @@ describe('/devices command', () => {
     expect(port.calls).toEqual([]);
   });
 
-  it('names add and join as not yet available rather than guessing', async () => {
+  it('shows the device mesh: whether it is on, how it finds devices, and what is linked', async () => {
+    const port = {
+      ...fakePort(),
+      meshStatus: () => ({
+        state: 'on' as const,
+        sources: ['local network (mDNS)', 'Mainline DHT'],
+        linked: [{ deviceId: DEVICE_B, name: 'desktop', locality: 'another-host' as const }],
+      }),
+    };
+    const result = await start(port).command('devices', '');
+    expect(result?.message).toMatch(/Device mesh: on/);
+    expect(result?.message).toContain('local network (mDNS), Mainline DHT');
+    expect(result?.message).toMatch(
+      new RegExp(`${DEVICE_B.slice(0, 10)}\\s+desktop\\s+on another machine`),
+    );
+  });
+
+  it('says how to turn the device mesh on when it is off', async () => {
+    const port = {
+      ...fakePort(),
+      meshStatus: () => ({ state: 'off' as const, sources: [], linked: [] }),
+    };
+    const result = await start(port).command('devices', 'list');
+    expect(result?.message).toMatch(/Device mesh: off/);
+    expect(result?.message).toContain('transports.mesh.enabled');
+  });
+
+  it('runs add and join on the operator terminal and reports ids and names only', async () => {
+    const port = fakePort();
+    const runs = vi.fn();
+    const harness = start(port, handoff(true, runs));
+    const add = await harness.command('devices', 'add');
+    expect(add?.success).toBe(true);
+    expect(add?.message).toContain('desktop');
+    expect(add?.message).toContain(DEVICE_B.slice(0, 10));
+    const join = await harness.command('devices', 'join my desktop');
+    expect(join?.success).toBe(true);
+    expect(join?.message).toContain(DEVICE_B.slice(0, 10));
+    expect(join?.message).toContain('OS keychain');
+    expect(port.calls).toEqual(['add', 'join:my desktop']);
+    expect(runs).toHaveBeenCalledTimes(2);
+  });
+
+  it('says what to do when an enrollment is refused', async () => {
     const port = fakePort();
     const harness = start(port);
-    for (const args of ['add', 'join abc']) {
-      const result = await harness.command('devices', args);
-      expect(result?.success).toBe(false);
-      expect(result?.message).toMatch(/not available yet/i);
-    }
-    expect(port.calls).toEqual([]);
+    vi.mocked(port.join).mockResolvedValueOnce({ ok: false, reason: 'code-not-accepted' });
+    expect((await harness.command('devices', 'join'))?.message).toMatch(/devices add/);
+    vi.mocked(port.add).mockResolvedValueOnce({ ok: false, reason: 'no-relay' });
+    expect((await harness.command('devices', 'add'))?.message).toMatch(/relayUrl/);
+    vi.mocked(port.join).mockResolvedValueOnce({ ok: false, reason: 'code-on-command-line' });
+    expect((await harness.command('devices', 'join ABCDE'))?.message).toMatch(/devices add/);
   });
 
   it('requires a device id for revoke', async () => {