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

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

@@ -0,0 +1,241 @@
+/**
+ * What of the built-in command set the MODEL is offered, and what it is told.
+ *
+ * Pins, per command: offered or not, the exact model-facing descriptor, and that a user-only
+ * subcommand is neither offered nor runnable. The invariant behind it: trust, credential and
+ * permission-widening actions are never model-invocable. The reasons for each decision sit beside
+ * each command's entry.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createDoctorCommandModule } from '../../doctor/index.js';
+import { createKeybindingsCommandModule } from '../../keybindings/index.js';
+import { createThemeCommandModule } from '../../theme/index.js';
+import { createDoctorFixture } from '../../doctor/__tests__/doctor-fixture.js';
+import { createDefaultCommandModules } from '../default-command-modules.js';
+
+import type { IDoctorFixture } from '../../doctor/__tests__/doctor-fixture.js';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  IProviderCommandSettingsAdapter,
+  ISystemCommand,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+import type { IThemeCataloguePort } from '@robota-sdk/agent-interface-command';
+
+const providerDefinitions: readonly IProviderDefinition[] = [];
+const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => ({}) as TProviderSettingsDocument,
+  readTargetSettings: () => ({}) as TProviderSettingsDocument,
+  writeTargetSettings: () => undefined,
+};
+const themeCataloguePort: IThemeCataloguePort = {
+  listThemes: () => [],
+  getTheme: () => undefined,
+  getAppearance: () => ({
+    settings: { theme: 'dark', syntaxHighlighting: true, reducedMotion: false },
+  }),
+};
+
+const fixtures: IDoctorFixture[] = [];
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) fixture.cleanup();
+});
+
+/** Every built-in command, including the ones only registered when their host port exists. */
+function allBuiltInCommands(): ISystemCommand[] {
+  const fixture = createDoctorFixture({ env: {} });
+  fixtures.push(fixture);
+  const { modules } = createDefaultCommandModules({
+    cwd: '/tmp',
+    userLocalStorageRoot: '/tmp/robota-test',
+    providerDefinitions,
+    providerSettingsAdapter,
+  });
+  return [
+    ...modules,
+    createKeybindingsCommandModule({ ensureFile: async () => '/tmp/keybindings.json' }),
+    createThemeCommandModule(themeCataloguePort),
+    createDoctorCommandModule(fixture.inputs, fixture.deps),
+  ].flatMap((module) => [...(module.systemCommands ?? [])]);
+}
+
+/** Each command with its `execute` replaced, so a test can see whether it ran at all. */
+function spiedExecutor(): {
+  executor: SystemCommandExecutor;
+  executed: ReturnType<typeof vi.fn>;
+} {
+  const executed = vi.fn(() => ({ success: true, message: 'ran' }));
+  const commands = allBuiltInCommands().map((command) => ({ ...command, execute: executed }));
+  return { executor: new SystemCommandExecutor(commands), executed };
+}
+
+/** Offered to the model, each for a reason given beside its entry. */
+const MODEL_INVOCABLE = [
+  'agent',
+  'compact',
+  'context',
+  'cost',
+  'loop',
+  'mcp',
+  'memory',
+  'monitor',
+  'schedule',
+  'skills',
+];
+
+/** Whole commands the model is never offered. */
+const USER_ONLY_COMMANDS = [
+  // Trust decisions.
+  'plugin',
+  'reload-plugins',
+  'remote-control',
+  // Account and credential actions.
+  'provider',
+  // Permission widening or permission-mode changes.
+  'mode',
+  'permissions',
+  'sandbox',
+  'preset',
+  'plan',
+  'goal',
+  'cd',
+  // Crossing into another session, machine or process the user owns.
+  'peers',
+  'handoff',
+  'fork',
+  'shell',
+  'git',
+  // Exits and destructive session changes.
+  'exit',
+  'clear',
+  'reset',
+  'rewind',
+  'resume',
+  // UI-only preferences, and views the user reads.
+  'advisor',
+  'effort',
+  'language',
+  'output-style',
+  'statusline',
+  'theme',
+  'keybindings',
+  'settings',
+  'editor',
+  'rename',
+  'help',
+  'background',
+  'doctor',
+  'user-local',
+  'validate-session',
+];
+
+/** User-only subcommands of commands the model IS offered; `list` is an alias `/mcp` accepts for the user. */
+const USER_ONLY_SUBCOMMANDS: Record<string, readonly string[]> = {
+  mcp: ['approve', 'reject', 'revoke', 'logout', 'login', 'list'],
+  memory: ['approve', 'reject'],
+  context: ['add', 'remove', 'clear', 'auto'],
+  cost: ['budget'],
+};
+
+describe('built-in commands offered to the model', () => {
+  it('offers exactly the model-invocable set', () => {
+    const { executor } = spiedExecutor();
+    const offered = executor
+      .listModelInvocableCommands()
+      .map((descriptor) => descriptor.name)
+      .sort();
+    expect(offered).toEqual([...MODEL_INVOCABLE].sort());
+  });
+
+  it('covers every built-in command with a decision', () => {
+    const names = allBuiltInCommands()
+      .map((command) => command.name)
+      .sort();
+    expect(names).toEqual([...MODEL_INVOCABLE, ...USER_ONLY_COMMANDS].sort());
+  });
+
+  it('describes every offered command for the model: what, when, and what it returns', () => {
+    for (const command of allBuiltInCommands().filter((c) => c.modelInvocable === true)) {
+      expect(command.modelDescription, command.name).toBeDefined();
+      expect(command.modelDescription, command.name).toMatch(/\bUse\b|\bBefore\b|\bWhen\b/);
+      expect(command.modelDescription, command.name).toMatch(/\b[Rr]eturns\b/);
+    }
+  });
+
+  it('pins the descriptor each offered command gets', () => {
+    const { executor } = spiedExecutor();
+    const descriptors = Object.fromEntries(
+      executor
+        .listModelInvocableCommands()
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((descriptor) => [descriptor.name, descriptor]),
+    );
+    expect(descriptors).toMatchSnapshot();
+  });
+
+  it('never offers or runs a user-only command', async () => {
+    const { executor, executed } = spiedExecutor();
+    const host = createTestCommandHost();
+    for (const name of USER_ONLY_COMMANDS) {
+      expect(executor.isModelInvocable(name), name).toBe(false);
+      expect(await executor.executeModelInvocable(name, host, ''), name).toBeNull();
+    }
+    expect(executed).not.toHaveBeenCalled();
+  });
+
+  it('never offers a user-only subcommand, and refuses it before the command runs', async () => {
+    const { executor, executed } = spiedExecutor();
+    const host = createTestCommandHost();
+    const descriptors = executor.listModelInvocableCommands();
+    for (const [name, subcommands] of Object.entries(USER_ONLY_SUBCOMMANDS)) {
+      const descriptor = descriptors.find((candidate) => candidate.name === name);
+      const offeredBlock = descriptor?.description.split('Subcommands you may run')[1] ?? '';
+      for (const sub of subcommands) {
+        expect(descriptor?.argumentHint ?? '', `${name} ${sub}`).not.toMatch(
+          new RegExp(`\\b${sub}\\b`),
+        );
+        expect(offeredBlock, `${name} ${sub}`).not.toContain(`- ${sub}:`);
+        const result = await executor.executeModelInvocable(name, host, `${sub} some-arg`);
+        expect(result?.success, `${name} ${sub}`).toBe(false);
+      }
+    }
+    expect(executed).not.toHaveBeenCalled();
+  });
+
+  it('runs the read-only subset for the model', async () => {
+    const { executor, executed } = spiedExecutor();
+    const host = createTestCommandHost();
+    for (const [name, args] of [
+      ['mcp', ''],
+      ['mcp', 'status'],
+      ['memory', 'list'],
+      ['context', ''],
+      ['context', 'list'],
+      ['cost', ''],
+    ] as const) {
+      expect((await executor.executeModelInvocable(name, host, args))?.message).toBe('ran');
+    }
+    expect(executed).toHaveBeenCalledTimes(6);
+  });
+
+  it('skips the by-name prompt only where the model reaches nothing that needs it', () => {
+    const { executor } = spiedExecutor();
+    const byName = Object.fromEntries(
+      executor.listModelInvocableCommands().map((d) => [d.name, d.requiresPermission]),
+    );
+    // `/mcp`: the model reaches only `status`. `/monitor`: its command is decided by the shell
+    // gate instead (monitor-model-permission-functional.test.ts).
+    expect(byName.mcp).toBe(false);
+    expect(byName.monitor).toBe(false);
+    // Neither becomes read-only for the user or a remote read-only policy.
+    for (const name of ['mcp', 'monitor']) {
+      const command = executor.getCommand(name)!;
+      expect(executor.resolveRequiresPermission(command), name).toBe(true);
+    }
+  });
+});

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

@@ -0,0 +1,98 @@
+/**
+ * CLI-083 (issue #2287) — the default command modules forward the org policy.
+ *
+ * `createDefaultCommandModules` used to accept `orgPolicy` and hand it to the provider command
+ * module; `92596bc6f` removed the parameter along with its only caller. The consumer never changed:
+ * `provider-command-profile-operations.ts` still destructures `orgPolicy` and enforces
+ * `allowedProviders` on it.
+ *
+ * `org-policy.test.ts` already covers that enforcement — by constructing the provider module
+ * DIRECTLY with a policy. That test is green whether or not anything upstream forwards one, which
+ * is why the cut survived three months. This drives the same enforcement through the factory that
+ * lost the parameter, so it fails exactly when the forwarding is missing.
+ *
+ * There is deliberately no "the factory accepts an orgPolicy" case. At runtime JavaScript accepts an
+ * undeclared extra property silently, so that assertion passes whether or not the parameter exists —
+ * it was written, it passed against the broken tree, and it proved nothing. The signature is the
+ * type checker's job.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createDefaultCommandModules } from '../default-command-modules.js';
+
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  IOrgPolicy,
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+
+const providerDefinitions: readonly IProviderDefinition[] = ['anthropic', 'openai'].map((type) => ({
+  type,
+  displayName: type,
+  defaults: { model: 'm', apiKey: `$ENV:${type.toUpperCase()}_API_KEY` },
+  setupSteps: [],
+  requiresApiKey: true,
+  createProvider: () => {
+    throw new Error('not used');
+  },
+}));
+
+const SETTINGS: TProviderSettingsDocument = {
+  currentProvider: 'anthropic',
+  providers: {
+    anthropic: { type: 'anthropic', model: 'm' },
+    openai: { type: 'openai', model: 'm' },
+  },
+};
+
+const adapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => SETTINGS,
+  readTargetSettings: () => ({}),
+  writeTargetSettings: () => undefined,
+};
+
+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',
+    providerDefinitions,
+    providerSettingsAdapter: adapter,
+    ...(orgPolicy === undefined ? {} : { orgPolicy }),
+  });
+  const provider = modules.find((module) => module.name === 'agent-command-provider');
+  if (provider === undefined) throw new Error('the provider command module was not built');
+  return new SystemCommandExecutor([...(provider.systemCommands ?? [])]);
+}
+
+describe('CLI-083: the default command modules forward the org policy', () => {
+  it('blocks a disallowed provider switch when a policy is supplied to the FACTORY', async () => {
+    const result = await executorThroughFactory(POLICY).execute(
+      'provider',
+      createTestCommandHost(),
+      'switch openai',
+    );
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('"openai" is not allowed');
+    expect(result?.message).toContain('ops@example.com');
+  });
+
+  it('does not block when no policy is supplied — absence stays distinguishable', async () => {
+    // The control. A factory that attached a policy of its own would satisfy the case above and
+    // change behaviour for every user who has no org policy at all.
+    const result = await executorThroughFactory().execute(
+      'provider',
+      createTestCommandHost(),
+      'switch openai',
+    );
+
+    expect(result?.message ?? '').not.toContain('is not allowed');
+  });
+});

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

@@ -1,18 +1,34 @@
+import { findUnknownModuleNames, selectCommandModules } from '@robota-sdk/agent-framework';
+
 import { createAgentCommandModule } from '../agent/index.js';
 import { createBackgroundCommandModule } from '../background/index.js';
 import { createCompactCommandModule } from '../compact/index.js';
 import { createContextCommandModule } from '../context/index.js';
+import { createDevicesCommandModule } from '../devices/index.js';
+import { createDoctorCommandModule } from '../doctor/index.js';
 import { createEditorCommandModule } from '../editor/index.js';
+import { createAdvisorCommandModule } from '../advisor/index.js';
+import { createEffortCommandModule } from '../effort/index.js';
 import { createExitCommandModule } from '../exit/index.js';
+import { createForkCommandModule } from '../fork/index.js';
+import { createGitCommandModule } from '../git/index.js';
 import { createGoalCommandModule } from '../goal/index.js';
+import { createHandoffCommandModule } from '../handoff/index.js';
 import { createHelpCommandModule } from '../help/index.js';
+import { createKeybindingsCommandModule } from '../keybindings/index.js';
 import { createLanguageCommandModule } from '../language/index.js';
+import { createMCPActivationCommandModule } from '../mcp-activation/index.js';
 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 { createPeersCommandModule } from '../peers/index.js';
 import { createPermissionsCommandModule } from '../permissions/index.js';
+import { createPlanCommandModule } from '../plan/index.js';
 import { createPluginCommandModule } from '../plugin/index.js';
 import { createPresetCommandModule } from '../preset/index.js';
 import { createProviderCommandModule } from '../provider/index.js';
+import { createRemoteControlCommandModule } from '../remote-control/index.js';
 import { createResetCommandModule } from '../reset/index.js';
 import { createRewindCommandModule } from '../rewind/index.js';
 import { createScheduleCommandModule } from '../schedule/index.js';
@@ -21,15 +37,62 @@ import { createSettingsCommandModule } from '../settings/index.js';
 import { createShellCommandModule } from '../shell/index.js';
 import { createSkillsCommandModule } from '../skills/index.js';
 import { createStatusLineCommandModule } from '../statusline/index.js';
+import { createThemeCommandModule } from '../theme/index.js';
 import { createUserLocalCommandModule } from '../user-local/index.js';
 
+import type { IDevicesCommandPort } from '../devices/index.js';
+import type { IDoctorDisplayVocabulary, IDoctorInputs } from '../doctor/index.js';
+import type { IKeybindingsFilePort } from '../keybindings/index.js';
 import type { IProviderDefinition } from '@robota-sdk/agent-core';
-import type { ICommandModule, IProviderCommandSettingsAdapter } from '@robota-sdk/agent-framework';
+import type {
+  IOrgPolicy,
+  IContributionSource,
+  ISkillRootDescriptor,
+  ICommandModule,
+  IProviderCommandSettingsAdapter,
+  IUnknownCommandModuleName,
+} from '@robota-sdk/agent-framework';
+import type { IThemeCataloguePort } from '@robota-sdk/agent-interface-command';
 
 export interface IDefaultCommandModulesOptions {
   cwd: string;
+  userLocalStorageRoot: string;
+  /** Product-owned prefix for the interactive editor's temporary directory. */
+  editorTemporaryDirectoryPrefix?: string;
+  contributionSources?: readonly IContributionSource[];
+  skillRoots?: readonly ISkillRootDescriptor[];
   providerDefinitions: readonly IProviderDefinition[];
   providerSettingsAdapter: IProviderCommandSettingsAdapter;
+  /**
+   * CLI-083 (issue #2287) — the org policy, so `allowedProviders` and `requireApiKeyFromEnv` are
+   * reachable. This parameter existed, was removed by `92596bc6f` along with its only caller, and
+   * the consumer never stopped reading it: `provider-command-profile-operations.ts` still
+   * destructures `orgPolicy` from its options and enforces on it. Optional, so its absence stays
+   * distinguishable from a policy that allows everything — and that optionality is why nothing went
+   * red when the producer dropped it.
+   */
+  orgPolicy?: IOrgPolicy;
+  /** Optional TUI-owned file capability; absence means `/keybindings` is not registered. */
+  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.
+   */
+  themeCataloguePort?: IThemeCataloguePort;
+  /**
+   * The host that keeps this device's identity (its terminal, credential store and state files).
+   * Absence means `/devices` is not registered: without it the command could do nothing.
+   */
+  devicesPort?: IDevicesCommandPort;
+  /** OBSERVABILITY-1991: host-composed doctor inputs; absence means `/doctor` is not registered. */
+  doctorInputs?: IDoctorInputs;
+  /** Product-owned diagnostic wording; absent keeps `/doctor` product-neutral. */
+  doctorDisplay?: IDoctorDisplayVocabulary;
+  /** Product-owned command to resume a saved fork; absent yields neutral host guidance. */
+  formatForkResumeCommand?: (sessionId: string) => string;
+  /** Host-owned fallback text and kill switch for session-local repeat. */
+  loopOptions?: { defaultPrompt?: string; resolveDefaultPrompt?: () => string; disabled?: boolean };
   /**
    * Whitelist of module `name`s to keep. When provided, only modules whose `name`
    * appears here survive. Omitted → all modules kept (no-regression).
@@ -48,59 +111,108 @@ export interface IDefaultCommandModulesOptions {
  * Rules: if `enabled` is provided, keep only modules whose `name` is in it; then
  * remove any module whose `name` is in `disabled` (deny > allow). Neither given →
  * the full default set is returned unchanged (no-regression).
+ *
+ * INFRA-032: delegates to agent-framework's `selectCommandModules` (the allowed command→framework
+ * edge) so the filter body exists once — the previously byte-identical copy here is collapsed.
  */
 function applyModuleSelection(
   modules: readonly ICommandModule[],
   enabled: readonly string[] | undefined,
   disabled: readonly string[] | undefined,
 ): readonly ICommandModule[] {
-  let selected = modules;
-  if (enabled !== undefined) {
-    const allow = new Set(enabled);
-    selected = selected.filter((module) => allow.has(module.name));
-  }
-  if (disabled !== undefined) {
-    const deny = new Set(disabled);
-    selected = selected.filter((module) => !deny.has(module.name));
-  }
-  return selected;
+  return selectCommandModules(modules, enabled, disabled);
+}
+
+/**
+ * Result of {@link createDefaultCommandModules} (INFRA-032): the selected `modules` plus any preset
+ * `enabledCommandModules`/`disabledCommandModules` names that matched no built module. Unknown names
+ * are returned as data (not dropped silently) so the CLI startup path can surface a non-fatal notice.
+ */
+export interface IDefaultCommandModulesResult {
+  readonly modules: readonly ICommandModule[];
+  readonly unknownModuleNames: readonly IUnknownCommandModuleName[];
 }
 
 export function createDefaultCommandModules({
-  cwd,
+  cwd: _cwd,
+  userLocalStorageRoot,
+  editorTemporaryDirectoryPrefix,
+  contributionSources,
+  skillRoots,
   providerDefinitions,
   providerSettingsAdapter,
+  orgPolicy,
+  keybindingsFilePort,
+  themeCataloguePort,
+  devicesPort,
+  doctorInputs,
+  doctorDisplay,
+  formatForkResumeCommand,
+  loopOptions,
   enabledCommandModules,
   disabledCommandModules,
-}: IDefaultCommandModulesOptions): readonly ICommandModule[] {
+}: IDefaultCommandModulesOptions): IDefaultCommandModulesResult {
   const modules: readonly ICommandModule[] = [
-    createSkillsCommandModule({ cwd }),
+    createSkillsCommandModule({ contributionSources: contributionSources ?? [], skillRoots }),
     createHelpCommandModule(),
     createAgentCommandModule(),
+    createEffortCommandModule(),
+    createAdvisorCommandModule(),
     createPermissionsCommandModule(),
     createModeCommandModule(),
+    createSandboxCommandModule(),
     createPresetCommandModule(),
+    createOutputStyleCommandModule(),
     createLanguageCommandModule(),
     createBackgroundCommandModule(),
+    // CLI-1994: beside `/background`, because a fork IS a background job — the one it starts is
+    // listed, peeked at, stopped and attached to through that command and its panel.
+    createForkCommandModule(formatForkResumeCommand),
     createGoalCommandModule(),
+    createPlanCommandModule(),
     createShellCommandModule(),
-    createEditorCommandModule(),
+    createEditorCommandModule(editorTemporaryDirectoryPrefix),
+    createGitCommandModule(),
+    ...(keybindingsFilePort === undefined
+      ? []
+      : [createKeybindingsCommandModule(keybindingsFilePort)]),
+    ...(themeCataloguePort === undefined ? [] : [createThemeCommandModule(themeCataloguePort)]),
+    ...(doctorInputs === undefined
+      ? []
+      : [createDoctorCommandModule(doctorInputs, undefined, doctorDisplay)]),
     createMemoryCommandModule(),
-    createUserLocalCommandModule(),
+    createMCPActivationCommandModule(),
+    createUserLocalCommandModule(userLocalStorageRoot),
     createCompactCommandModule(),
     createContextCommandModule(),
     createExitCommandModule(),
     createSessionCommandModule(),
     createResetCommandModule(),
     createRewindCommandModule(),
-    createScheduleCommandModule(),
+    createScheduleCommandModule(loopOptions),
     createStatusLineCommandModule(),
     createPluginCommandModule(),
     createSettingsCommandModule(),
+    createPeersCommandModule(),
+    // 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.
+    createHandoffCommandModule(),
+    createRemoteControlCommandModule(),
+    ...(devicesPort === undefined ? [] : [createDevicesCommandModule(devicesPort)]),
     createProviderCommandModule({
       providerDefinitions,
       settings: providerSettingsAdapter,
+      ...(orgPolicy === undefined ? {} : { orgPolicy }),
     }),
   ];
-  return applyModuleSelection(modules, enabledCommandModules, disabledCommandModules);
+  const builtModuleNames = modules.map((module) => module.name);
+  return {
+    modules: applyModuleSelection(modules, enabledCommandModules, disabledCommandModules),
+    unknownModuleNames: findUnknownModuleNames(
+      builtModuleNames,
+      enabledCommandModules,
+      disabledCommandModules,
+    ),
+  };
 }

package/src/default/index.ts

@@ -1,2 +1,5 @@
-export type { IDefaultCommandModulesOptions } from './default-command-modules.js';
+export type {
+  IDefaultCommandModulesOptions,
+  IDefaultCommandModulesResult,
+} from './default-command-modules.js';
 export { createDefaultCommandModules } from './default-command-modules.js';