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

package/src/shell/shell-command.ts

@@ -6,24 +6,28 @@
 import { resolveShell } from './resolve-shell.js';
 import { spawnInherited } from './spawn-inherited.js';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type {
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 export const SHELL_COMMAND_DESCRIPTION =
   'Drop to an interactive shell (or run `/shell <command>` interactively), then return to the agent.';
 
 export async function executeShellCommand(
-  context: ICommandHostContext,
+  context: ICommandHostTerminalHandoff & ICommandHostWorkspace,
   args: string,
+  executable?: string,
 ): Promise<ICommandResult> {
-  if (context.canHandoffTerminal?.() !== true || context.runWithTerminal === undefined) {
+  if (!context.canHandoffTerminal()) {
     return {
       message: 'An interactive shell is unavailable here (no interactive terminal).',
       success: false,
     };
   }
 
-  const shell = resolveShell();
+  const shell = resolveShell(executable);
   const cwd = context.getCwd();
   const command = args.trim();
 

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

@@ -1,10 +1,38 @@
 import { describe, expect, it, vi } from 'vitest';
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { InteractiveSession, SystemCommandExecutor } from '@robota-sdk/agent-framework';
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import {
+  createNodeHostContributionSource,
+  InteractiveSession,
+  SystemCommandExecutor,
+  WorkspaceTrustService,
+} from '@robota-sdk/agent-framework';
 import { createSkillsCommandModule } from '../skills-command-module.js';
+import {
+  createTestCommandHost,
+  type ICreateTestCommandHostOptions,
+} from '@robota-sdk/agent-framework/testing';
+
+import type { IWorkspaceIdentity, IWorkspaceTrustStore } from '@robota-sdk/agent-framework';
+
+async function createTrustedProjectAccess(cwd: string) {
+  const root = realpathSync(cwd);
+  const identity: IWorkspaceIdentity = {
+    repositoryKey: `skills-command-test:${root}`,
+    displayPath: root,
+    worktreeRoot: root,
+  };
+  const store: IWorkspaceTrustStore = {
+    inspect: () => Promise.resolve({ state: 'trusted', generation: 1 }),
+    grant: () => Promise.resolve({ state: 'trusted', generation: 1 }),
+    revoke: () => Promise.resolve({ state: 'revoked', generation: 2 }),
+  };
+  return new WorkspaceTrustService({
+    identityResolver: { resolve: () => identity },
+    store,
+  }).inspect(root);
+}
 
 function createTempSkill(cwd: string): void {
   const skillDir = join(cwd, '.agents', 'skills', 'audit');
@@ -28,34 +56,39 @@ function makeParentSession() {
     }),
     injectMessage: vi.fn(),
     getSessionId: vi.fn().mockReturnValue('parent-session-id'),
+    // SELFHOST-004 P6: the span collector subscribes to the session bus each turn.
+    getEventService: vi.fn().mockReturnValue({ subscribe: vi.fn(), unsubscribe: vi.fn() }),
     getSystemMessage: vi.fn().mockReturnValue('# system'),
     getToolSchemas: vi.fn().mockReturnValue([]),
   };
 }
 
-function createMockContext(overrides?: Partial<ICommandHostContext>): ICommandHostContext {
-  return {
-    getSession: vi.fn(),
-    getContextState: vi.fn(),
-    getAutoCompactThreshold: vi.fn().mockReturnValue(0.835),
-    compactContext: vi.fn(),
-    getCwd: vi.fn().mockReturnValue('/workspace'),
-    listEditCheckpoints: vi.fn().mockReturnValue([]),
-    restoreEditCheckpoint: vi.fn(),
-    rollbackEditCheckpoint: vi.fn(),
-    getUsedMemoryReferences: vi.fn().mockReturnValue([]),
-    recordMemoryEvent: vi.fn(),
-    listBackgroundTasks: vi.fn().mockReturnValue([]),
-    readBackgroundTaskLog: vi.fn(),
-    cancelBackgroundTask: vi.fn(),
-    closeBackgroundTask: vi.fn(),
-    ...overrides,
-  } as ICommandHostContext;
+function createMockContext(overrides?: ICreateTestCommandHostOptions['overrides']) {
+  // ARCH-029: overrides over a conformant host rather than a 20-member literal asserting it IS one.
+  return createTestCommandHost({
+    overrides: {
+      getSession: vi.fn(),
+      getContextState: vi.fn(),
+      getAutoCompactThreshold: vi.fn().mockReturnValue(0.835),
+      compactContext: vi.fn(),
+      getCwd: vi.fn().mockReturnValue('/workspace'),
+      listEditCheckpoints: vi.fn().mockReturnValue([]),
+      restoreEditCheckpoint: vi.fn(),
+      rollbackEditCheckpoint: vi.fn(),
+      getUsedMemoryReferences: vi.fn().mockReturnValue([]),
+      recordMemoryEvent: vi.fn(),
+      listBackgroundTasks: vi.fn().mockReturnValue([]),
+      readBackgroundTaskLog: vi.fn(),
+      cancelBackgroundTask: vi.fn(),
+      closeBackgroundTask: vi.fn(),
+      ...overrides,
+    },
+  });
 }
 
 describe('createSkillsCommandModule', () => {
   it('exposes skills as a normal model-invocable command module', () => {
-    const module = createSkillsCommandModule({ cwd: '/workspace' });
+    const module = createSkillsCommandModule({ contributionSources: [] });
     const command = module.systemCommands?.[0];
 
     expect(module.name).toBe('agent-command-skills');
@@ -64,18 +97,19 @@ describe('createSkillsCommandModule', () => {
     ]);
     expect(command).toMatchObject({
       name: 'skills',
+      semanticRole: 'skillActivation',
       userInvocable: true,
       modelInvocable: true,
       lifecycle: 'inline',
       argumentHint: '[list | <skill-name> [args]]',
       safety: 'read-only',
     });
-    expect(command?.description).toContain('projected skills command tool');
+    expect(command?.modelDescription).toContain('projected skills command tool');
   });
 
   it('lists skill metadata from the SDK host context', async () => {
     const executor = new SystemCommandExecutor([
-      ...(createSkillsCommandModule({ cwd: '/workspace' }).systemCommands ?? []),
+      ...(createSkillsCommandModule({ contributionSources: [] }).systemCommands ?? []),
     ]);
 
     const result = await executor.execute(
@@ -109,7 +143,7 @@ describe('createSkillsCommandModule', () => {
       data: { skill: 'repo-writing' },
     });
     const executor = new SystemCommandExecutor([
-      ...(createSkillsCommandModule({ cwd: '/workspace' }).systemCommands ?? []),
+      ...(createSkillsCommandModule({ contributionSources: [] }).systemCommands ?? []),
     ]);
 
     const result = await executor.execute(
@@ -130,13 +164,21 @@ describe('createSkillsCommandModule', () => {
   });
 
   it('lets the SDK normalize virtual /skill-name commands into the composed skills command', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'robota-skills-command-module-'));
+    const cwd = realpathSync(mkdtempSync(join(tmpdir(), 'robota-skills-command-module-')));
     createTempSkill(cwd);
     const parentSession = makeParentSession();
     const session = new InteractiveSession({
       session: parentSession as never,
       cwd,
-      commandModules: [createSkillsCommandModule({ cwd })],
+      projectAccess: await createTrustedProjectAccess(cwd),
+      contributionSources: [createNodeHostContributionSource(cwd)],
+      skillRoots: [{ root: join('.agents', 'skills'), kind: 'skills' }],
+      commandModules: [
+        createSkillsCommandModule({
+          contributionSources: [createNodeHostContributionSource(cwd)],
+          skillRoots: [{ root: join('.agents', 'skills'), kind: 'skills' }],
+        }),
+      ],
     });
 
     const result = await session.executeCommand('audit', 'src/index.ts');
@@ -147,7 +189,6 @@ describe('createSkillsCommandModule', () => {
         skill: 'audit',
         sessionExecution: true,
       }),
-      effects: [{ type: 'session-execution-started' }],
     });
     expect(parentSession.run).toHaveBeenCalledWith(
       expect.stringContaining('Audit src/index.ts'),

package/src/skills/index.ts

@@ -3,4 +3,5 @@ export {
   createSkillsCommandModule,
   SkillsCommandSource,
 } from './skills-command-module.js';
+export type { ISkillsCommandModuleOptions } from './skills-command-module.js';
 export { executeSkillsCommand, SKILLS_COMMAND_DESCRIPTION } from './skills-command.js';

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

@@ -1,12 +1,22 @@
 import { SkillCommandSource } from '@robota-sdk/agent-framework';
 
-import { executeSkillsCommand, SKILLS_COMMAND_DESCRIPTION } from './skills-command.js';
+import {
+  executeSkillsCommand,
+  SKILLS_COMMAND_DESCRIPTION,
+  SKILLS_COMMAND_MODEL_DESCRIPTION,
+} from './skills-command.js';
 
-import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type {
+  ICommandModule,
+  IContributionSource,
+  ISystemCommand,
+  ISkillRootDescriptor,
+} from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export interface ISkillsCommandModuleOptions {
-  readonly cwd: string;
+  readonly contributionSources: readonly IContributionSource[];
+  readonly skillRoots?: readonly ISkillRootDescriptor[];
 }
 
 export function createSkillsCommandEntry(): ICommand {
@@ -14,6 +24,9 @@ export function createSkillsCommandEntry(): ICommand {
     name: 'skills',
     displayName: 'Skills',
     description: SKILLS_COMMAND_DESCRIPTION,
+    // Model-invocable: activating a skill is how the model follows one; a skill's own
+    // `disable-model-invocation` frontmatter still refuses it per skill.
+    modelDescription: SKILLS_COMMAND_MODEL_DESCRIPTION,
     source: 'skills',
     modelInvocable: true,
     userInvocable: true,
@@ -26,6 +39,8 @@ function createSkillsSystemCommand(): ISystemCommand {
   const entry = createSkillsCommandEntry();
   return {
     name: entry.name,
+    semanticRole: 'skillActivation',
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
     displayName: entry.displayName,
     description: entry.description,
     requiresPermission: false,
@@ -48,7 +63,9 @@ export class SkillsCommandSource implements ICommandSource {
 
 export function createSkillsCommandModule(options: ISkillsCommandModuleOptions): ICommandModule {
   const commandSources: ICommandSource[] = [new SkillsCommandSource()];
-  commandSources.push(new SkillCommandSource(options.cwd));
+  commandSources.push(
+    new SkillCommandSource(options.contributionSources, options.skillRoots ?? []),
+  );
 
   return {
     name: 'agent-command-skills',

package/src/skills/skills-command.ts

@@ -1,8 +1,15 @@
-import type { ICommandHostContext, ICommandSkillListEntry } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type {
+  ICommandHostCatalog,
+  ICommandHostWorkspace,
+  ICommandSkillListEntry,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
-export const SKILLS_COMMAND_DESCRIPTION =
-  'Skill command. Before following a matching registered skill from the system prompt Skills section, invoke the projected skills command tool with args "<skill-name> [args]". Without arguments, list registered skills. With a skill name, activate that skill. Slash syntax is a UI input/display concern; the SDK command identity is "skills".';
+export const SKILLS_COMMAND_DESCRIPTION = 'List registered skills, or activate one by name';
+
+/** What the model is told about `skills`; `SKILLS_COMMAND_DESCRIPTION` is the `/help` line. */
+export const SKILLS_COMMAND_MODEL_DESCRIPTION =
+  'Skill command. Before following a matching registered skill from the system prompt Skills section, invoke the projected skills command tool with args "<skill-name> [args]". Without arguments, list registered skills. With a skill name, activate that skill; a skill that declares it is not model-invocable is refused. Returns the skill list with each skill\'s description, or the activated skill\'s instructions to follow. Slash syntax is a UI input/display concern; the SDK command identity is "skills".';
 
 interface IParsedSkillsArgs {
   readonly action: 'list' | 'activate';
@@ -66,20 +73,14 @@ function parseSkillsArgs(args: string): IParsedSkillsArgs {
 }
 
 export async function executeSkillsCommand(
-  context: ICommandHostContext,
+  context: ICommandHostCatalog & ICommandHostWorkspace,
   args = '',
 ): Promise<ICommandResult> {
   const parsed = parseSkillsArgs(args);
   if (parsed.action === 'activate' && parsed.skillName !== undefined) {
-    if (!context.executeSkillCommandByName) {
-      return {
-        success: false,
-        message: 'Skill activation is not available in this session.',
-      };
-    }
     const displayInput = `/${parsed.skillName}${parsed.skillArgs ? ` ${parsed.skillArgs}` : ''}`;
     const result = await context.executeSkillCommandByName(parsed.skillName, parsed.skillArgs, {
-      invocationSource: context.getCommandInvocationSource?.() ?? 'user',
+      invocationSource: context.getCommandInvocationSource(),
       displayInput,
       rawInput: displayInput,
     });
@@ -91,7 +92,7 @@ export async function executeSkillsCommand(
     );
   }
 
-  const skills = context.listSkills?.() ?? [];
+  const skills = context.listSkills();
   return {
     success: true,
     message: formatSkillsMessage(skills),

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

@@ -2,8 +2,9 @@ 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 = {} as ICommandHostContext;
+const COMMAND_CONTEXT = createTestCommandHost();
 
 describe('createStatusLineCommandModule', () => {
   it('provides statusline metadata and user-only executable command from one module owner', () => {
@@ -76,12 +77,12 @@ describe('createStatusLineCommandModule', () => {
       expect(result).toEqual({
         success: true,
         message,
-        effects: [{ type: 'statusline-settings-patch', patch }],
+        hostActions: [{ type: 'statusline-settings-patch', patch }],
       });
     },
   );
 
-  it('reports usage for unsupported arguments without effects', async () => {
+  it('reports usage for unsupported arguments without host actions', async () => {
     const executor = new SystemCommandExecutor([
       ...(createStatusLineCommandModule().systemCommands ?? []),
     ]);
@@ -90,6 +91,6 @@ describe('createStatusLineCommandModule', () => {
 
     expect(result?.success).toBe(false);
     expect(result?.message).toContain('Usage: /statusline');
-    expect(result?.effects).toBeUndefined();
+    expect(result?.hostActions).toBeUndefined();
   });
 });

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

@@ -7,7 +7,7 @@ import {
 import { executeStatusLineCommand } from './statusline-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createStatusLineCommandEntry(): ICommand {
   return {
@@ -17,6 +17,7 @@ export function createStatusLineCommandEntry(): ICommand {
     source: 'statusline',
     argumentHint: STATUSLINE_COMMAND_ARGUMENT_HINT,
     subcommands: buildStatusLineCommandSubcommands('statusline'),
+    // User-only: UI preference.
     modelInvocable: false,
   };
 }

package/src/statusline/statusline-command.ts

@@ -1,10 +1,10 @@
 import { DEFAULT_STATUS_LINE_COMMAND_SETTINGS } from '@robota-sdk/agent-framework';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandHostNoCapability } from '@robota-sdk/agent-framework';
 import type {
   ICommandResult,
   TStatusLineCommandSettingsPatch,
-} from '@robota-sdk/agent-interface-transport';
+} from '@robota-sdk/agent-interface-command';
 
 interface IStatusLineCommandSuccessAction {
   success: true;
@@ -64,7 +64,7 @@ function parseStatusLineArgs(args: string): TStatusLineCommandAction {
 }
 
 export function executeStatusLineCommand(
-  _context: ICommandHostContext,
+  _context: ICommandHostNoCapability,
   args: string,
 ): ICommandResult {
   const action = parseStatusLineArgs(args);
@@ -75,6 +75,6 @@ export function executeStatusLineCommand(
   return {
     success: true,
     message: action.message,
-    effects: [{ type: 'statusline-settings-patch', patch: action.patch }],
+    hostActions: [{ type: 'statusline-settings-patch', patch: action.patch }],
   };
 }

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

@@ -0,0 +1,204 @@
+/**
+ * SCREEN-2002 TC-09 — `/theme`.
+ *
+ * Three properties carry this command. It emits EXACTLY ONE patch per invocation, so a submission
+ * cannot half-apply. An unknown id writes NOTHING — not the theme, and not the toggles submitted
+ * beside it — because a user who mistyped an id did not also ask for the rest. And `motion on`
+ * means `reducedMotion: false`: the inversion is the easy thing to read backwards, and a user
+ * asking for motion and getting stillness would look like the command doing nothing at all.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { executeThemeCommand } from '../theme-command-module.js';
+
+import type { TAppearanceSettingsPatch } from '@robota-sdk/agent-framework';
+import type {
+  IThemeAppearanceState,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+  TReducedMotionOverride,
+} from '@robota-sdk/agent-interface-command';
+
+const THEMES: IThemeCatalogueEntry[] = [
+  { id: 'dark', name: 'Dark', appearance: 'dark', source: 'built-in' },
+  { id: 'light', name: 'Light', appearance: 'light', source: 'built-in' },
+  {
+    id: 'dark-daltonized',
+    name: 'Dark (daltonized)',
+    appearance: 'dark',
+    source: 'built-in',
+  },
+];
+
+function catalogue(
+  state: Partial<IThemeAppearanceState['settings']> = {},
+  reducedMotionOverride?: TReducedMotionOverride,
+  reducedMotionForRun?: boolean,
+): IThemeCataloguePort {
+  const settings = {
+    theme: 'dark',
+    syntaxHighlighting: true,
+    reducedMotion: false,
+    ...state,
+  };
+  return {
+    listThemes: () => THEMES,
+    getTheme: (id) => THEMES.find((theme) => theme.id === id),
+    getAppearance: () => ({
+      settings,
+      ...(reducedMotionOverride === undefined
+        ? {}
+        : {
+            reducedMotionPin: {
+              tier: reducedMotionOverride,
+              reducedMotion: reducedMotionForRun ?? true,
+            },
+          }),
+    }),
+  };
+}
+
+function patchOf(result: { hostActions?: readonly unknown[] }): TAppearanceSettingsPatch {
+  expect(result.hostActions).toHaveLength(1);
+  const action = result.hostActions?.[0] as {
+    type: string;
+    patch: TAppearanceSettingsPatch;
+  };
+  expect(action.type).toBe('appearance-settings-patch');
+  return action.patch;
+}
+
+describe('/theme without a catalogue (SCREEN-2002 TC-09)', () => {
+  it('reports its unavailability instead of failing silently or writing anything', () => {
+    const result = executeThemeCommand(undefined, 'light');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBe('Themes are not available in this environment.');
+    expect(result.hostActions).toBeUndefined();
+  });
+});
+
+describe('/theme with no argument (SCREEN-2002 TC-09)', () => {
+  it('asks the surface for the picker rather than changing anything', () => {
+    const result = executeThemeCommand(catalogue(), '   ');
+
+    expect(result.success).toBe(true);
+    expect(result.uiIntents).toEqual([{ type: 'show-theme-picker' }]);
+    expect(result.hostActions).toBeUndefined();
+  });
+});
+
+describe('/theme list (SCREEN-2002 TC-09)', () => {
+  it('marks the active theme and names each source, and writes nothing', () => {
+    const result = executeThemeCommand(catalogue({ theme: 'light' }), 'list');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('* light — Light (light, built-in)');
+    expect(result.message).toContain('  dark — Dark (dark, built-in)');
+    expect(result.message).toContain('syntax highlighting: on');
+    expect(result.message).toContain('reduced motion: off');
+    expect(result.hostActions).toBeUndefined();
+  });
+
+  it('reports what THIS RUN does and what is saved, never one in place of the other', () => {
+    // SCREEN-2002 TC-13 found this at the PTY level: reporting the persisted value beside the tier
+    // printed `reduced motion: off (… pinned by flag)` on a `--reduced-motion` run — a line that
+    // contradicts itself, and that answers "is motion reduced right now" with the wrong word.
+    const pinnedOn = executeThemeCommand(catalogue({ reducedMotion: false }, 'flag', true), 'list');
+    expect(pinnedOn.message).toContain(
+      'reduced motion: on for this run (pinned by flag; saved off)',
+    );
+
+    // `--no-reduced-motion` is an override too, and it pins the opposite value: a surface that
+    // renders the TIER alone cannot tell these two runs apart.
+    const pinnedOff = executeThemeCommand(
+      catalogue({ reducedMotion: true }, 'flag', false),
+      'list',
+    );
+    expect(pinnedOff.message).toContain(
+      'reduced motion: off for this run (pinned by flag; saved on)',
+    );
+  });
+});
+
+describe('/theme <id> (SCREEN-2002 TC-09)', () => {
+  it('emits exactly one patch naming the theme', () => {
+    const result = executeThemeCommand(catalogue(), 'dark-daltonized');
+
+    expect(result.success).toBe(true);
+    expect(patchOf(result)).toEqual({ theme: 'dark-daltonized' });
+    expect(result.message).toContain('Dark (daltonized)');
+  });
+
+  it('refuses an unknown id, names the catalogue, and writes NOTHING', () => {
+    const result = executeThemeCommand(catalogue(), 'solarized');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('Unknown theme "solarized"');
+    expect(result.message).toContain('dark, light, dark-daltonized');
+    expect(result.hostActions).toBeUndefined();
+  });
+
+  it('does not apply the toggles submitted beside an unknown id', () => {
+    const result = executeThemeCommand(catalogue(), 'solarized syntax off');
+
+    expect(result.success).toBe(false);
+    expect(result.hostActions).toBeUndefined();
+  });
+
+  it('carries the theme and its toggles in ONE patch', () => {
+    const result = executeThemeCommand(catalogue(), 'light syntax off motion off');
+
+    expect(patchOf(result)).toEqual({
+      theme: 'light',
+      syntaxHighlighting: false,
+      reducedMotion: true,
+    });
+  });
+});
+
+describe('the motion inversion (SCREEN-2002 TC-09)', () => {
+  it('reads `motion on` as animation, which is reducedMotion FALSE', () => {
+    expect(patchOf(executeThemeCommand(catalogue({ reducedMotion: true }), 'motion on'))).toEqual({
+      reducedMotion: false,
+    });
+  });
+
+  it('reads `motion off` as stillness, which is reducedMotion TRUE', () => {
+    expect(patchOf(executeThemeCommand(catalogue(), 'motion off'))).toEqual({
+      reducedMotion: true,
+    });
+  });
+
+  it('reports the change in the user s words, not the settings key s', () => {
+    expect(executeThemeCommand(catalogue(), 'motion off').message).toContain('motion off');
+  });
+
+  it('persists the setting but says this run keeps what pinned it', () => {
+    const result = executeThemeCommand(catalogue({ reducedMotion: true }, 'flag'), 'motion on');
+
+    expect(patchOf(result)).toEqual({ reducedMotion: false });
+    expect(result.message).toContain('Saved, but this run keeps reduced motion pinned by flag');
+  });
+});
+
+describe('/theme syntax (SCREEN-2002 TC-09)', () => {
+  it('toggles highlighting without touching the theme', () => {
+    expect(patchOf(executeThemeCommand(catalogue(), 'syntax off'))).toEqual({
+      syntaxHighlighting: false,
+    });
+  });
+});
+
+describe('a malformed argument (SCREEN-2002 TC-09)', () => {
+  it.each(['motion', 'syntax', 'motion yes', 'syntax enable', 'light motion', 'light nonsense on'])(
+    'refuses %o with the usage line rather than guessing',
+    (args) => {
+      const result = executeThemeCommand(catalogue(), args);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain('Usage: /theme');
+      expect(result.hostActions).toBeUndefined();
+    },
+  );
+});

package/src/theme/index.ts

@@ -0,0 +1,12 @@
+export {
+  createThemeCommandEntry,
+  createThemeCommandModule,
+  executeThemeCommand,
+  ThemeCommandSource,
+} from './theme-command-module.js';
+export type {
+  IThemeAppearanceState,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+  TReducedMotionOverride,
+} from '@robota-sdk/agent-interface-command';