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

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

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createStatusLineCommandModule } from '../statusline-command-module.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+const COMMAND_CONTEXT = createTestCommandHost();
+
+describe('createStatusLineCommandModule', () => {
+  it('provides statusline metadata and user-only executable command from one module owner', () => {
+    const module = createStatusLineCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-statusline');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'statusline',
+        description:
+          'Configure TUI status-line visibility and fields such as model, context, tokens, session, and git branch.',
+        source: 'statusline',
+        argumentHint: 'on | off | reset | git on | git off',
+        modelInvocable: false,
+      }),
+    );
+    expect(entry?.subcommands?.map((subcommand) => subcommand.name)).toEqual([
+      'on',
+      'off',
+      'reset',
+      'git',
+    ]);
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'statusline',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it.each([
+    {
+      args: 'on',
+      message: 'Status line enabled.',
+      patch: { enabled: true },
+    },
+    {
+      args: 'off',
+      message: 'Status line disabled.',
+      patch: { enabled: false },
+    },
+    {
+      args: 'reset',
+      message: 'Status line settings reset.',
+      patch: { enabled: true, gitBranch: true },
+    },
+    {
+      args: 'git on',
+      message: 'Status line git branch shown.',
+      patch: { gitBranch: true },
+    },
+    {
+      args: 'git off',
+      message: 'Status line git branch hidden.',
+      patch: { gitBranch: false },
+    },
+  ])(
+    'emits a statusline settings patch for /statusline $args',
+    async ({ args, message, patch }) => {
+      const executor = new SystemCommandExecutor([
+        ...(createStatusLineCommandModule().systemCommands ?? []),
+      ]);
+
+      const result = await executor.execute('statusline', COMMAND_CONTEXT, args);
+
+      expect(result).toEqual({
+        success: true,
+        message,
+        hostActions: [{ type: 'statusline-settings-patch', patch }],
+      });
+    },
+  );
+
+  it('reports usage for unsupported arguments without host actions', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createStatusLineCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('statusline', COMMAND_CONTEXT, 'wat');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('Usage: /statusline');
+    expect(result?.hostActions).toBeUndefined();
+  });
+});

package/src/statusline/index.ts

@@ -0,0 +1,6 @@
+export {
+  createStatusLineCommandEntry,
+  createStatusLineCommandModule,
+  StatusLineCommandSource,
+} from './statusline-command-module.js';
+export { executeStatusLineCommand, STATUSLINE_USAGE } from './statusline-command.js';

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

@@ -0,0 +1,55 @@
+import {
+  buildStatusLineCommandSubcommands,
+  STATUSLINE_COMMAND_ARGUMENT_HINT,
+  STATUSLINE_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+
+import { executeStatusLineCommand } from './statusline-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createStatusLineCommandEntry(): ICommand {
+  return {
+    name: 'statusline',
+    displayName: 'Status Line',
+    description: STATUSLINE_COMMAND_DESCRIPTION,
+    source: 'statusline',
+    argumentHint: STATUSLINE_COMMAND_ARGUMENT_HINT,
+    subcommands: buildStatusLineCommandSubcommands('statusline'),
+    // User-only: UI preference.
+    modelInvocable: false,
+  };
+}
+
+function createStatusLineSystemCommand(): ISystemCommand {
+  const entry = createStatusLineCommandEntry();
+  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: executeStatusLineCommand,
+  };
+}
+
+export class StatusLineCommandSource implements ICommandSource {
+  readonly name = 'statusline';
+
+  getCommands(): ICommand[] {
+    return [createStatusLineCommandEntry()];
+  }
+}
+
+export function createStatusLineCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-statusline',
+    commandSources: [new StatusLineCommandSource()],
+    systemCommands: [createStatusLineSystemCommand()],
+  };
+}

package/src/statusline/statusline-command.ts

@@ -0,0 +1,80 @@
+import { DEFAULT_STATUS_LINE_COMMAND_SETTINGS } from '@robota-sdk/agent-framework';
+
+import type { ICommandHostNoCapability } from '@robota-sdk/agent-framework';
+import type {
+  ICommandResult,
+  TStatusLineCommandSettingsPatch,
+} from '@robota-sdk/agent-interface-command';
+
+interface IStatusLineCommandSuccessAction {
+  success: true;
+  message: string;
+  patch: TStatusLineCommandSettingsPatch;
+}
+
+interface IStatusLineCommandFailureAction {
+  success: false;
+  message: string;
+}
+
+type TStatusLineCommandAction = IStatusLineCommandSuccessAction | IStatusLineCommandFailureAction;
+
+export const STATUSLINE_USAGE = [
+  'Usage: /statusline on | off | reset | git on | git off',
+  'Fields: model, context, permission mode, message count, session name, thinking state, git branch.',
+].join('\n');
+
+function parseStatusLineArgs(args: string): TStatusLineCommandAction {
+  const parts = args
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((part) => part.length > 0);
+  const [first, second] = parts;
+
+  if (first === 'on' && second === undefined) {
+    return { success: true, message: 'Status line enabled.', patch: { enabled: true } };
+  }
+  if (first === 'off' && second === undefined) {
+    return { success: true, message: 'Status line disabled.', patch: { enabled: false } };
+  }
+  if (first === 'reset' && second === undefined) {
+    return {
+      success: true,
+      message: 'Status line settings reset.',
+      patch: { ...DEFAULT_STATUS_LINE_COMMAND_SETTINGS },
+    };
+  }
+  if (first === 'git' && second === 'on' && parts.length === 2) {
+    return {
+      success: true,
+      message: 'Status line git branch shown.',
+      patch: { gitBranch: true },
+    };
+  }
+  if (first === 'git' && second === 'off' && parts.length === 2) {
+    return {
+      success: true,
+      message: 'Status line git branch hidden.',
+      patch: { gitBranch: false },
+    };
+  }
+
+  return { success: false, message: STATUSLINE_USAGE };
+}
+
+export function executeStatusLineCommand(
+  _context: ICommandHostNoCapability,
+  args: string,
+): ICommandResult {
+  const action = parseStatusLineArgs(args);
+  if (!action.success) {
+    return { success: false, message: action.message };
+  }
+
+  return {
+    success: true,
+    message: action.message,
+    hostActions: [{ type: 'statusline-settings-patch', patch: action.patch }],
+  };
+}

package/src/terminal-client/__tests__/terminal-client-commands.test.ts

@@ -0,0 +1,216 @@
+/**
+ * #3189 — the commands a terminal attached to a workspace daemon runs in its own process.
+ *
+ * The attached terminal routes by this set, not by the daemon's catalog, so the set must name exactly
+ * the commands the default assembly marks `runner: 'client'` — a command in one list and not the
+ * other would either run on the daemon or never run at all. And each client command must answer as
+ * the in-process command does, because it is the same command running somewhere else.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it, vi } from 'vitest';
+
+import { createDefaultCommandModules } from '../../default/index.js';
+import { createEditorCommandModule } from '../../editor/index.js';
+import { createKeybindingsCommandModule } from '../../keybindings/index.js';
+import { createShellCommandModule } from '../../shell/index.js';
+import { createThemeCommandModule } from '../../theme/index.js';
+import { createTerminalClientCommands } from '../terminal-client-commands.js';
+
+import type { ITerminalClientCommand } from '../terminal-client-commands.js';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  ICommandHostContext,
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+  ICommandModule,
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+import type {
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+} from '@robota-sdk/agent-interface-command';
+
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'agent-test-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+const providerDefinitions: readonly IProviderDefinition[] = [];
+const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => ({}) as TProviderSettingsDocument,
+  readTargetSettings: () => ({}) as TProviderSettingsDocument,
+  writeTargetSettings: () => undefined,
+};
+
+const THEMES: IThemeCatalogueEntry[] = [
+  { id: 'dark', name: 'Dark', appearance: 'dark', source: 'built-in' },
+  { id: 'light', name: 'Light', appearance: 'light', source: 'built-in' },
+];
+const themeCatalogue: IThemeCataloguePort = {
+  listThemes: () => THEMES,
+  getTheme: (id) => THEMES.find((theme) => theme.id === id),
+  getAppearance: () => ({
+    settings: { theme: 'dark', syntaxHighlighting: true, reducedMotion: false },
+  }),
+};
+
+function allPortsGiven(): readonly ITerminalClientCommand[] {
+  return createTerminalClientCommands({
+    keybindingsFile: { ensureFile: async () => '/tmp/keybindings.json' },
+    themeCatalogue,
+  });
+}
+
+function find(commands: readonly ITerminalClientCommand[], name: string): ITerminalClientCommand {
+  const command = commands.find((candidate) => candidate.name === name);
+  if (!command) throw new Error(`no terminal client command "${name}"`);
+  return command;
+}
+
+/** A terminal the command cannot take over: a host with no interactive TTY. */
+function hostWithoutTerminal(): ICommandHostTerminalHandoff & ICommandHostWorkspace {
+  return {
+    canHandoffTerminal: () => false,
+    runWithTerminal: vi.fn(async () => {
+      throw new Error('a refused handoff must not be attempted');
+    }),
+    getCwd: () => '/tmp',
+    getCommandInvocationSource: () => 'user',
+  };
+}
+
+/** What the in-process command answers for the same host and arguments. */
+async function inProcess(module: ICommandModule, host: unknown, args: string) {
+  const command = module.systemCommands?.[0];
+  if (!command) throw new Error(`module ${module.name} has no command`);
+  return command.execute(host as ICommandHostContext, args);
+}
+
+describe('createTerminalClientCommands (#3189)', () => {
+  it('names exactly the commands the default assembly marks as client-run', () => {
+    const { modules } = createDefaultCommandModules({
+      cwd: '/tmp',
+      userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+      providerDefinitions,
+      providerSettingsAdapter,
+    });
+    const clientRun = modules
+      .flatMap((module) => module.systemCommands ?? [])
+      .filter((command) => command.runner === 'client')
+      .map((command) => command.name)
+      .sort();
+
+    expect(clientRun.length).toBeGreaterThan(0);
+    expect(
+      allPortsGiven()
+        .map((command) => command.name)
+        .sort(),
+    ).toEqual(clientRun);
+  });
+
+  it('leaves out a client command whose module the selection disables, as the default assembly does', () => {
+    const selection = { disabledCommandModules: ['agent-command-shell'] };
+    const { modules } = createDefaultCommandModules({
+      cwd: '/tmp',
+      userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+      providerDefinitions,
+      providerSettingsAdapter,
+      ...selection,
+    });
+    const clientRun = modules
+      .flatMap((module) => module.systemCommands ?? [])
+      .filter((command) => command.runner === 'client')
+      .map((command) => command.name)
+      .sort();
+
+    const names = createTerminalClientCommands({ themeCatalogue, ...selection })
+      .map((command) => command.name)
+      .sort();
+
+    expect(names).not.toContain('shell');
+    expect(names).toEqual(clientRun);
+  });
+
+  it('keeps only the enabled client modules, and a disabled name wins over an enabled one', () => {
+    const names = createTerminalClientCommands({
+      enabledCommandModules: ['agent-command-theme', 'agent-command-editor', 'agent-command-help'],
+      disabledCommandModules: ['agent-command-editor'],
+    }).map((command) => command.name);
+
+    expect(names).toEqual(['theme']);
+  });
+
+  it('with no selection, offers all four client commands', () => {
+    expect(
+      createTerminalClientCommands({})
+        .map((command) => command.name)
+        .sort(),
+    ).toEqual(['editor', 'keybindings', 'shell', 'theme']);
+  });
+
+  it('/shell refuses a host that cannot hand off the terminal exactly as the in-process command does', async () => {
+    const host = hostWithoutTerminal();
+
+    const client = await find(allPortsGiven(), 'shell').execute(host, 'ls');
+
+    expect(client).toEqual(await inProcess(createShellCommandModule(), host, 'ls'));
+    expect(client.success).toBe(false);
+    expect(host.runWithTerminal).not.toHaveBeenCalled();
+  });
+
+  it('/editor and /keybindings refuse a host without a terminal as their in-process commands do', async () => {
+    const keybindingsFile = { ensureFile: vi.fn(async () => '/tmp/keybindings.json') };
+    const commands = createTerminalClientCommands({ keybindingsFile, themeCatalogue });
+
+    const editorHost = hostWithoutTerminal();
+    const editor = await find(commands, 'editor').execute(editorHost, 'draft');
+    expect(editor).toEqual(await inProcess(createEditorCommandModule(), editorHost, 'draft'));
+    expect(editor.success).toBe(false);
+
+    const keybindingsHost = hostWithoutTerminal();
+    const keybindings = await find(commands, 'keybindings').execute(keybindingsHost, '');
+    expect(keybindings).toEqual(
+      await inProcess(createKeybindingsCommandModule(keybindingsFile), keybindingsHost, ''),
+    );
+    expect(keybindings.success).toBe(false);
+    expect(keybindingsFile.ensureFile).not.toHaveBeenCalled();
+  });
+
+  it('/theme with no arguments asks the terminal to open its theme picker', async () => {
+    const result = await find(allPortsGiven(), 'theme').execute(hostWithoutTerminal(), '');
+
+    expect(result).toMatchObject({ success: true, uiIntents: [{ type: 'show-theme-picker' }] });
+    expect(result.hostActions).toBeUndefined();
+  });
+
+  it('/theme with a known id returns one appearance settings patch for the terminal to write', async () => {
+    const result = await find(allPortsGiven(), 'theme').execute(hostWithoutTerminal(), 'light');
+
+    expect(result.success).toBe(true);
+    expect(result.hostActions).toEqual([
+      { type: 'appearance-settings-patch', patch: { theme: 'light' } },
+    ]);
+    expect(result).toEqual(await inProcess(createThemeCommandModule(themeCatalogue), {}, 'light'));
+  });
+
+  it('without their ports, /keybindings and /theme still run on the terminal and answer as in-process', async () => {
+    const commands = createTerminalClientCommands({});
+    // The set does not shrink: a command missing from it would be sent to the daemon instead.
+    expect(commands.map((command) => command.name).sort()).toEqual(
+      allPortsGiven()
+        .map((command) => command.name)
+        .sort(),
+    );
+
+    const host = hostWithoutTerminal();
+    expect(await find(commands, 'keybindings').execute(host, '')).toEqual(
+      await inProcess(createKeybindingsCommandModule(undefined), host, ''),
+    );
+    expect(await find(commands, 'theme').execute(host, 'light')).toEqual(
+      await inProcess(createThemeCommandModule(undefined), host, 'light'),
+    );
+  });
+});

package/src/terminal-client/index.ts

@@ -0,0 +1,5 @@
+export {
+  createTerminalClientCommands,
+  type ITerminalClientCommand,
+  type ITerminalClientCommandOptions,
+} from './terminal-client-commands.js';

package/src/terminal-client/terminal-client-commands.ts

@@ -0,0 +1,109 @@
+/**
+ * #3189: the commands that belong to the terminal the user sits at — the ones the default assembly
+ * marks `runner: 'client'`. A terminal attached to a workspace daemon runs these in its own process,
+ * on its own terminal and working directory, and sends nothing to the daemon.
+ *
+ * Each one is the in-process command's own execute function, so an attached terminal answers exactly
+ * as a standalone one does; only where it runs changes.
+ */
+import { selectCommandModules } from '@robota-sdk/agent-framework';
+
+import { createEditorCommandModule } from '../editor/editor-command-module.js';
+import { executeEditorCommand } from '../editor/editor-command.js';
+import {
+  createKeybindingsCommandModule,
+  executeKeybindingsCommand,
+} from '../keybindings/keybindings-command-module.js';
+import { createShellCommandModule } from '../shell/shell-command-module.js';
+import { executeShellCommand } from '../shell/shell-command.js';
+import { createThemeCommandModule, executeThemeCommand } from '../theme/theme-command-module.js';
+
+import type { IKeybindingsFilePort } from '../keybindings/keybindings-command-module.js';
+import type {
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+  ICommandModule,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult, IThemeCataloguePort } from '@robota-sdk/agent-interface-command';
+
+/** A command the terminal runs itself, with the terminal's own handoff and working directory. */
+export interface ITerminalClientCommand {
+  readonly name: string;
+  execute(
+    host: ICommandHostTerminalHandoff & ICommandHostWorkspace,
+    args: string,
+  ): ICommandResult | Promise<ICommandResult>;
+}
+
+/** The terminal's own capabilities — the same ones its in-process command modules are given. */
+export interface ITerminalClientCommandOptions {
+  /** The shell `/shell` runs; absent → the platform shell, as for the in-process command. */
+  readonly shellExecutable?: string;
+  /** Product-owned prefix for `/editor`'s temporary directory; absent → the command's default. */
+  readonly editorTemporaryDirectoryPrefix?: string;
+  /** Absent → `/keybindings` answers where key bindings live, as the in-process command does. */
+  readonly keybindingsFile?: IKeybindingsFilePort;
+  /** Absent → `/theme` answers where themes live, as the in-process command does. */
+  readonly themeCatalogue?: IThemeCataloguePort;
+  /**
+   * The same module selection the default assembly is given (`agent-command-shell`, …): a module it
+   * leaves out is left out here too, so an attached terminal offers no command a standalone one
+   * would not. Absent → every client-run module.
+   */
+  readonly enabledCommandModules?: readonly string[];
+  /** Applied after `enabledCommandModules`, as in the default assembly (deny > allow). */
+  readonly disabledCommandModules?: readonly string[];
+}
+
+type TClientExecute = ITerminalClientCommand['execute'];
+
+/**
+ * Every client-run command the module selection keeps, whether or not its port is given. The set
+ * shrinks only with the selection, never with a missing port: the attached terminal routes by it, so
+ * a selected command left out would run on the daemon instead — and without its port the command
+ * still answers as its in-process twin does.
+ */
+export function createTerminalClientCommands(
+  options: ITerminalClientCommandOptions,
+): readonly ITerminalClientCommand[] {
+  const {
+    shellExecutable,
+    editorTemporaryDirectoryPrefix,
+    keybindingsFile,
+    themeCatalogue,
+    enabledCommandModules,
+    disabledCommandModules,
+  } = options;
+  // Each client command is paired with its in-process module, so selection matches by the module's
+  // own name and the command keeps that module's command name.
+  const candidates: ReadonlyArray<readonly [ICommandModule, TClientExecute]> = [
+    [
+      createShellCommandModule(shellExecutable),
+      (host, args) => executeShellCommand(host, args, shellExecutable),
+    ],
+    [
+      createEditorCommandModule(editorTemporaryDirectoryPrefix),
+      (host, args) => executeEditorCommand(host, args, editorTemporaryDirectoryPrefix),
+    ],
+    [
+      createKeybindingsCommandModule(keybindingsFile),
+      (host) => executeKeybindingsCommand(keybindingsFile, host),
+    ],
+    [
+      createThemeCommandModule(themeCatalogue),
+      (_host, args) => executeThemeCommand(themeCatalogue, args),
+    ],
+  ];
+  const selected = new Set(
+    selectCommandModules(
+      candidates.map(([module]) => module),
+      enabledCommandModules,
+      disabledCommandModules,
+    ),
+  );
+  return candidates
+    .filter(([module]) => selected.has(module))
+    .flatMap(([module, execute]) =>
+      (module.systemCommands ?? []).map((command) => ({ name: command.name, execute })),
+    );
+}