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

package/src/preset/index.ts

@@ -0,0 +1,6 @@
+export {
+  createPresetCommandEntry,
+  createPresetCommandModule,
+  PresetCommandSource,
+} from './preset-command-module.js';
+export { executePresetCommand } from './preset-command.js';

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

@@ -0,0 +1,80 @@
+import { createPresetRegistry } from '@robota-sdk/agent-preset';
+
+import { executePresetCommand } from './preset-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+const PRESET_COMMAND_DESCRIPTION = 'List presets or switch the active preset';
+const PRESET_ARGUMENT_HINT = 'list | <preset-id>';
+
+/**
+ * Build one subcommand per registered preset id (mirrors the permission-mode subcommands).
+ *
+ * ARCH-009 LIMIT, stated rather than left implicit: this lists the BUILT-INS, because it builds a
+ * STATIC catalog entry at module-construction time and has no `ICommandHostContext` to reach a
+ * host-supplied registry. `/preset`'s own execution — listing, lookup, resolution — goes through the
+ * host's registry, so an embedded host with its own presets resolves and applies correctly; only the
+ * pre-computed subcommand hints for tab-completion omit that host's external presets.
+ *
+ * What ARCH-009 changed here is what the limit COSTS. This used to read a process-wide mutable
+ * registry, so the hints a host saw depended on which other host had loaded presets first. They are
+ * now the built-ins and nothing else — wrong the same way for everyone, and never someone else's.
+ *
+ * Closing it needs the catalog to be built per host rather than per module, which is a change to how
+ * command modules are constructed and not to this file. Filed separately.
+ */
+function buildPresetSubcommands(source = 'preset'): ICommand[] {
+  return createPresetRegistry()
+    .listPresets()
+    .map((preset) => ({
+      name: preset.id,
+      description: preset.description,
+      source,
+    }));
+}
+
+export function createPresetCommandEntry(): ICommand {
+  return {
+    name: 'preset',
+    displayName: 'Agent Preset',
+    description: PRESET_COMMAND_DESCRIPTION,
+    source: 'preset',
+    argumentHint: PRESET_ARGUMENT_HINT,
+    subcommands: buildPresetSubcommands('preset'),
+    // User-only: a preset swaps tools, commands and permission posture; the user chooses it.
+    modelInvocable: false,
+  };
+}
+
+function createPresetSystemCommand(): ISystemCommand {
+  const entry = createPresetCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    argumentHint: entry.argumentHint,
+    subcommands: entry.subcommands,
+    lifecycle: 'inline',
+    execute: executePresetCommand,
+  };
+}
+
+export class PresetCommandSource implements ICommandSource {
+  readonly name = 'preset';
+
+  getCommands(): ICommand[] {
+    return [createPresetCommandEntry()];
+  }
+}
+
+export function createPresetCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-preset',
+    commandSources: [new PresetCommandSource()],
+    systemCommands: [createPresetSystemCommand()],
+  };
+}

package/src/preset/preset-command.ts

@@ -0,0 +1,148 @@
+import { selectAction } from '@robota-sdk/agent-core';
+import { applyPresetToSession } from '@robota-sdk/agent-framework';
+import { createPresetRegistry } from '@robota-sdk/agent-preset';
+
+import type {
+  ICommandHostAdapterAccess,
+  ICommandHostPresetApplication,
+  IPresetApplicationOptions,
+  ICommandHostSessionAccess,
+  ICommandHostUserInteraction,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IPresetSummary } from '@robota-sdk/agent-preset';
+
+/**
+ * ARCH-009 — the registry `/preset` discovers through.
+ *
+ * The host supplies the instance it resolved with through the ADAPTER bag — the same path
+ * `/permission-mode` and `/plugin` already take to their host capabilities. A host that supplies none
+ * gets a fresh built-ins registry. That order is the point: while discovery read a module-global
+ * registry directly, two products in one process shared one mutable list, so ARCH-008's per-instance
+ * resolution was only half-true for an embedded host. A command runs with an `ICommandHostContext`
+ * and nothing else, so the context is the only path from here to the instance the shell built.
+ *
+ * The fallback is deliberate rather than transitional, and it is no longer process state: a host that
+ * never loads external presets has nothing to hand over, and `/preset` should still list the
+ * built-ins. `createPresetRegistry()` with no argument is exactly that, constructed per call.
+ */
+/**
+ * What `/preset` actually needs from a registry — three members, no assertion.
+ *
+ * Narrower than `agent-preset`'s `IPresetRegistry` on purpose. Review of ARCH-009 reported the first
+ * version reaching that contract with three casts, one of which (`listPresets()`) widened optional
+ * `title`/`description` into required ones and would have printed `id — undefined: undefined` for a
+ * host that typechecked. The fix is not a better cast: it is asking for the shape the command uses,
+ * so both the built-in registry and a host adapter satisfy it STRUCTURALLY and nothing is asserted.
+ *
+ * `getPreset` returns `unknown` because presence is the whole question here.
+ */
+interface IPresetDiscovery {
+  listPresets(): readonly IPresetSummary[];
+  getPreset(id: string): unknown;
+  resolvePreset(id: string, context?: unknown): IPresetApplicationOptions;
+}
+
+function presetRegistry(context: ICommandHostAdapterAccess): IPresetDiscovery {
+  return context.getCommandHostAdapters?.().presetRegistry ?? createPresetRegistry();
+}
+
+/** Read the active preset id from the session, defaulting when the optional seam is absent. */
+function readActivePresetId(context: ICommandHostSessionAccess): string {
+  return context.getSession().getActivePresetId();
+}
+
+/** Build the `/preset` listing: one line per preset, marking the active one with a `*` prefix. */
+function formatPresetList(active: string, registry: IPresetDiscovery): string {
+  const lines = registry.listPresets().map((preset) => {
+    const marker = preset.id === active ? '* ' : '  ';
+    return `${marker}${preset.id} — ${preset.title}: ${preset.description}`;
+  });
+  return ['Available presets:', ...lines].join('\n');
+}
+
+/** Build the rejection message for an unknown preset id, listing the valid ids. */
+function formatUnknownPresetMessage(id: string, registry: IPresetDiscovery): string {
+  const ids = registry
+    .listPresets()
+    .map((preset) => preset.id)
+    .join(', ');
+  return `Unknown preset: ${id}. Available: ${ids}`;
+}
+
+/** The `/preset` (or `/preset list`) listing result. */
+function presetListResult(
+  context: ICommandHostSessionAccess,
+  registry: IPresetDiscovery,
+): ICommandResult {
+  const active = readActivePresetId(context);
+  return {
+    message: formatPresetList(active, registry),
+    success: true,
+    data: { presets: registry.listPresets(), active },
+  };
+}
+
+/**
+ * Ask the user to pick a preset (CMD-004 inline ask). Returns the chosen id, or `undefined` when no
+ * interactive renderer is attached or the user cancelled — the caller then shows the preset list.
+ */
+async function resolvePresetViaAsk(
+  context: ICommandHostUserInteraction,
+  registry: IPresetDiscovery,
+): Promise<string | undefined> {
+  const ui = context.getUserInteraction();
+  if (!ui) return undefined;
+  const options = registry.listPresets().map((preset) => ({
+    value: preset.id,
+    label: preset.id,
+    description: preset.description,
+  }));
+  const response = await ui.ask(selectAction('preset', 'Select a preset', options));
+  return response.type === 'answer' ? response.values[0] : undefined;
+}
+
+export async function executePresetCommand(
+  context: ICommandHostPresetApplication &
+    ICommandHostSessionAccess &
+    ICommandHostUserInteraction &
+    ICommandHostAdapterAccess,
+  args: string,
+): Promise<ICommandResult> {
+  // ARCH-009: resolved ONCE per invocation, so listing, lookup and resolution cannot disagree — a
+  // host that swapped registries mid-command would otherwise report one set and apply another.
+  const registry = presetRegistry(context);
+  let id: string | undefined = args.trim().split(/\s+/)[0];
+
+  if (id === 'list') {
+    return presetListResult(context, registry);
+  }
+
+  if (id === undefined || id.length === 0) {
+    id = await resolvePresetViaAsk(context, registry);
+    if (id === undefined) {
+      return presetListResult(context, registry);
+    }
+  }
+
+  if (registry.getPreset(id) === undefined) {
+    return {
+      message: formatUnknownPresetMessage(id, registry),
+      success: false,
+    };
+  }
+
+  const resolved = registry.resolvePreset(id);
+  const result = await applyPresetToSession(context, id, resolved);
+  // INFRA-032: surface any preset command-module name that matched no live module as a non-fatal
+  // notice — an in-session `/preset` switch is no longer silent about a short form / typo.
+  const noticeLines = result.unknownCommandModules.map(
+    ({ name, kind }) =>
+      `Preset command-module "${name}" (${kind}) matched no module — expected the agent-command-* form; ignored.`,
+  );
+  return {
+    message: [`Switched to preset: ${id}`, ...noticeLines].join('\n'),
+    success: true,
+    data: { preset: id, unknownCommandModules: result.unknownCommandModules },
+  };
+}

package/src/provider/__tests__/optional-provider-credentials.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import type { TProviderSettingsDocument } from '@robota-sdk/agent-framework';
+import { createProviderCommandModule } from '../provider-command-module.js';
+import { scriptedContext } from './scripted-interaction.js';
+
+const localDefinition: IProviderDefinition = {
+  type: 'local',
+  defaults: { model: 'installed-model', baseURL: 'http://localhost:1234/v1' },
+  setupSteps: [
+    { key: 'baseURL', title: 'Server URL', defaultValue: 'http://localhost:1234/v1' },
+    { key: 'model', title: 'Installed model', defaultValue: 'installed-model' },
+    { key: 'apiKey', title: 'Server API key (optional)', masked: true, editOnly: true },
+  ],
+  requiresApiKey: false,
+  createProvider: () => {
+    throw new Error('not used');
+  },
+};
+
+function commands(initial: TProviderSettingsDocument = {}) {
+  let settings = initial;
+  const module = createProviderCommandModule({
+    providerDefinitions: [localDefinition],
+    env: { LOCAL_TOKEN: 'synthetic-selected-token' },
+    settings: {
+      readMergedSettings: () => settings,
+      readTargetSettings: () => settings,
+      writeTargetSettings: (next) => {
+        settings = next;
+      },
+    },
+  });
+  return {
+    executor: new SystemCommandExecutor([...(module.systemCommands ?? [])]),
+    read: () => settings,
+    module,
+  };
+}
+
+describe('optional provider credentials', () => {
+  it('adds a keyless profile after only endpoint and model answers', async () => {
+    const { executor, read } = commands();
+    const { context, requests } = scriptedContext([
+      { type: 'answer', values: [], text: '' },
+      { type: 'answer', values: [], text: '' },
+    ]);
+
+    const result = await executor.execute('provider', context, 'add local');
+
+    expect(result?.success).toBe(true);
+    expect(requests.map((request) => request.id)).toEqual([
+      'provider-setup-baseURL',
+      'provider-setup-model',
+    ]);
+    expect(read().providers?.local).toEqual({
+      type: 'local',
+      model: 'installed-model',
+      baseURL: 'http://localhost:1234/v1',
+    });
+  });
+
+  it.each([undefined, '$ENV:LOCAL_TOKEN', 'synthetic-existing-token'])(
+    'allows blank optional key editing and preserves the previous credential %s',
+    async (apiKey) => {
+      const profile = {
+        type: 'local',
+        model: 'installed-model',
+        baseURL: 'http://localhost:1234/v1',
+        ...(apiKey === undefined ? {} : { apiKey }),
+      };
+      const { executor, read } = commands({ providers: { local: profile } });
+      const { context, requests } = scriptedContext([
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: 'another-installed-model' },
+        { type: 'answer', values: [], text: '' },
+      ]);
+
+      const result = await executor.execute('provider', context, 'edit local');
+
+      expect(result?.success).toBe(true);
+      expect(requests[2]).toMatchObject({
+        id: 'provider-setup-apiKey',
+        masked: true,
+        allowEmpty: true,
+      });
+      expect(JSON.stringify(requests)).not.toContain('synthetic-existing-token');
+      expect(read().providers?.local).toEqual({ ...profile, model: 'another-installed-model' });
+    },
+  );
+
+  it('keeps credential management user-only and advertises the edit recovery action', () => {
+    const { module } = commands();
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+    expect(entry).toMatchObject({ modelInvocable: false });
+    expect(module.systemCommands?.[0]).toMatchObject({
+      modelInvocable: false,
+      userInvocable: true,
+    });
+    expect(entry?.argumentHint).toContain('edit <profile>');
+    expect(entry?.description).toContain('credentials');
+  });
+
+  it.each(['$ENV:MISSING_SERVER_TOKEN', '$ENV:'])(
+    'leaves the working profile untouched when an edit supplies %s',
+    async (apiKey) => {
+      const initial = {
+        providers: {
+          local: {
+            type: 'local',
+            model: 'installed-model',
+            baseURL: 'http://localhost:1234/v1',
+            apiKey: 'synthetic-working-token',
+          },
+        },
+      };
+      const { executor, read } = commands(initial);
+      const { context } = scriptedContext([
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: '' },
+        { type: 'answer', values: [], text: apiKey },
+      ]);
+      await expect(executor.execute('provider', context, 'edit local')).rejects.toThrow(
+        'missing apiKey',
+      );
+      expect(read()).toEqual(initial);
+    },
+  );
+});

package/src/provider/__tests__/org-policy.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import type {
+  ICommandHostContext,
+  IOrgPolicy,
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+import { createProviderCommandModule } from '../provider-command-module.js';
+import { scriptedContext } from './scripted-interaction.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+const providerDefinitions: readonly IProviderDefinition[] = [
+  {
+    type: 'anthropic',
+    displayName: 'Anthropic',
+    defaults: { model: 'claude-sonnet-4-6', apiKey: '$ENV:ANTHROPIC_API_KEY' },
+    setupSteps: [
+      { key: 'apiKey', title: 'Anthropic API key', masked: true },
+      { key: 'model', title: 'Anthropic model', defaultValue: 'claude-sonnet-4-6' },
+    ],
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+  {
+    type: 'openai',
+    displayName: 'OpenAI',
+    defaults: { model: 'gpt-4o', apiKey: '$ENV:OPENAI_API_KEY' },
+    setupSteps: [
+      { key: 'apiKey', title: 'OpenAI API key', masked: true },
+      { key: 'model', title: 'OpenAI model', defaultValue: 'gpt-4o' },
+    ],
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+
+function createSettingsAdapter(
+  merged: TProviderSettingsDocument,
+  target: TProviderSettingsDocument = {},
+): { adapter: IProviderCommandSettingsAdapter } {
+  let writable = target;
+  return {
+    adapter: {
+      readMergedSettings: () => merged,
+      readTargetSettings: () => writable,
+      writeTargetSettings: (next) => {
+        writable = next;
+      },
+    },
+  };
+}
+
+function createExecutor(
+  adapter: IProviderCommandSettingsAdapter,
+  orgPolicy?: IOrgPolicy,
+): SystemCommandExecutor {
+  const module = createProviderCommandModule({ providerDefinitions, settings: adapter, orgPolicy });
+  return new SystemCommandExecutor([...(module.systemCommands ?? [])]);
+}
+
+/** Context with no interactive renderer attached (headless/automation). */
+const headlessContext = createTestCommandHost();
+
+describe('org policy enforcement in provider commands', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+  it('blocks /provider switch when target is not in allowedProviders', async () => {
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+        openai: { type: 'openai', model: 'gpt-4o' },
+      },
+    });
+    const orgPolicy: IOrgPolicy = {
+      allowedProviders: ['anthropic'],
+      adminContact: 'admin@example.com',
+    };
+
+    const result = await createExecutor(adapter, orgPolicy).execute(
+      'provider',
+      headlessContext,
+      'switch openai',
+    );
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('"openai" is not allowed');
+    expect(result?.message).toContain('admin@example.com');
+    expect(result?.hostActions).toBeUndefined();
+  });
+
+  it('allows /provider switch when target is in allowedProviders', async () => {
+    // #3282: the switch now validates the target profile against `providerDefinitions` before
+    // writing anything, the same way the hot-swap it triggers would build the provider — so the
+    // profile needs a resolvable credential, same as a real one would.
+    vi.stubEnv('OPENAI_API_KEY', 'sk-test');
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+        openai: { type: 'openai', model: 'gpt-4o' },
+      },
+    });
+    const orgPolicy: IOrgPolicy = { allowedProviders: ['anthropic', 'openai'] };
+
+    const result = await createExecutor(adapter, orgPolicy).execute(
+      'provider',
+      headlessContext,
+      'switch openai',
+    );
+
+    expect(result?.success).toBe(true);
+    expect(result?.hostActions).toEqual([{ type: 'provider-hot-swap', profileName: 'openai' }]);
+  });
+
+  it('rejects plaintext API key during edit when requireApiKeyFromEnv is true', async () => {
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: {
+          type: 'anthropic',
+          model: 'claude-sonnet-4-6',
+          apiKey: 'sk-existing-key',
+        },
+      },
+    });
+    const orgPolicy: IOrgPolicy = { requireApiKeyFromEnv: true, adminContact: 'sec@example.com' };
+
+    // Anthropic has 2 setup steps: apiKey then model
+    const { context } = scriptedContext([
+      { type: 'answer', values: ['anthropic'] },
+      { type: 'answer', values: ['edit'] },
+      { type: 'answer', values: [], text: 'sk-plaintext-key' },
+      { type: 'answer', values: [], text: 'claude-sonnet-4-6' },
+    ]);
+    const completed = await createExecutor(adapter, orgPolicy).execute('provider', context, 'list');
+
+    expect(completed?.success).toBe(false);
+    expect(completed?.message).toContain('environment variable references');
+    expect(completed?.message).toContain('sec@example.com');
+  });
+
+  it('allows env-ref API key during edit when requireApiKeyFromEnv is true', async () => {
+    vi.stubEnv('ORG_TEST_KEY', 'sk-test-resolved-value');
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: {
+          type: 'anthropic',
+          model: 'claude-sonnet-4-6',
+          apiKey: 'sk-existing-key',
+        },
+      },
+    });
+    const orgPolicy: IOrgPolicy = { requireApiKeyFromEnv: true };
+
+    const { context } = scriptedContext([
+      { type: 'answer', values: ['anthropic'] },
+      { type: 'answer', values: ['edit'] },
+      { type: 'answer', values: [], text: '$ENV:ORG_TEST_KEY' },
+      { type: 'answer', values: [], text: 'claude-opus-4-5' },
+    ]);
+    const completed = await createExecutor(adapter, orgPolicy).execute('provider', context, 'list');
+
+    expect(completed?.success).toBe(true);
+  });
+});