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

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

@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, 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 { createSkillsCommandModule } from '../skills-command-module.js';
+
+function createTempSkill(cwd: string): void {
+  const skillDir = join(cwd, '.agents', 'skills', 'audit');
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(
+    join(skillDir, 'SKILL.md'),
+    ['---', 'name: audit', 'description: Audit code', '---', 'Audit $ARGUMENTS'].join('\n'),
+    'utf8',
+  );
+}
+
+function makeParentSession() {
+  return {
+    run: vi.fn().mockResolvedValue('parent response'),
+    abort: vi.fn(),
+    getHistory: vi.fn().mockReturnValue([]),
+    getContextState: vi.fn().mockReturnValue({
+      usedPercentage: 10,
+      usedTokens: 100,
+      maxTokens: 1000,
+    }),
+    injectMessage: vi.fn(),
+    getSessionId: vi.fn().mockReturnValue('parent-session-id'),
+    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;
+}
+
+describe('createSkillsCommandModule', () => {
+  it('exposes skills as a normal model-invocable command module', () => {
+    const module = createSkillsCommandModule({ cwd: '/workspace' });
+    const command = module.systemCommands?.[0];
+
+    expect(module.name).toBe('agent-command-skills');
+    expect(module.commandSources?.[0]?.getCommands().map((entry) => entry.name)).toEqual([
+      'skills',
+    ]);
+    expect(command).toMatchObject({
+      name: 'skills',
+      userInvocable: true,
+      modelInvocable: true,
+      lifecycle: 'inline',
+      argumentHint: '[list | <skill-name> [args]]',
+      safety: 'read-only',
+    });
+    expect(command?.description).toContain('projected skills command tool');
+  });
+
+  it('lists skill metadata from the SDK host context', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSkillsCommandModule({ cwd: '/workspace' }).systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute(
+      'skills',
+      createMockContext({
+        listSkills: vi.fn().mockReturnValue([
+          {
+            name: 'repo-writing',
+            description: 'Repository writing rules',
+            source: 'skill',
+            modelInvocable: true,
+            userInvocable: true,
+          },
+        ]),
+      }),
+      '',
+    );
+
+    expect(result?.message).toContain('repo-writing: Repository writing rules');
+    expect(result?.message).toContain('Use /skills <skill-name> [args]');
+    expect(result?.data?.['activationContract']).toMatchObject({
+      activateWith: '/skills <skill-name> [args]',
+      activationRequiredBeforeWorkflow: true,
+    });
+  });
+
+  it('activates skills through the SDK host skill activation API', async () => {
+    const executeSkillCommandByName = vi.fn().mockResolvedValue({
+      success: true,
+      message: 'Skill activated: repo-writing',
+      data: { skill: 'repo-writing' },
+    });
+    const executor = new SystemCommandExecutor([
+      ...(createSkillsCommandModule({ cwd: '/workspace' }).systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute(
+      'skills',
+      createMockContext({
+        getCommandInvocationSource: vi.fn().mockReturnValue('model'),
+        executeSkillCommandByName,
+      }),
+      'repo-writing update docs',
+    );
+
+    expect(executeSkillCommandByName).toHaveBeenCalledWith('repo-writing', 'update docs', {
+      invocationSource: 'model',
+      displayInput: '/repo-writing update docs',
+      rawInput: '/repo-writing update docs',
+    });
+    expect(result?.message).toBe('Skill activated: repo-writing');
+  });
+
+  it('lets the SDK normalize virtual /skill-name commands into the composed skills command', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'robota-skills-command-module-'));
+    createTempSkill(cwd);
+    const parentSession = makeParentSession();
+    const session = new InteractiveSession({
+      session: parentSession as never,
+      cwd,
+      commandModules: [createSkillsCommandModule({ cwd })],
+    });
+
+    const result = await session.executeCommand('audit', 'src/index.ts');
+
+    expect(result).toMatchObject({
+      success: true,
+      data: expect.objectContaining({
+        skill: 'audit',
+        sessionExecution: true,
+      }),
+      effects: [{ type: 'session-execution-started' }],
+    });
+    expect(parentSession.run).toHaveBeenCalledWith(
+      expect.stringContaining('Audit src/index.ts'),
+      '/audit src/index.ts',
+    );
+  });
+});

package/src/skills/index.ts

@@ -0,0 +1,6 @@
+export {
+  createSkillsCommandEntry,
+  createSkillsCommandModule,
+  SkillsCommandSource,
+} from './skills-command-module.js';
+export { executeSkillsCommand, SKILLS_COMMAND_DESCRIPTION } from './skills-command.js';

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

@@ -0,0 +1,62 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import { SkillCommandSource } from '@robota-sdk/agent-framework';
+import { executeSkillsCommand, SKILLS_COMMAND_DESCRIPTION } from './skills-command.js';
+
+export interface ISkillsCommandModuleOptions {
+  readonly cwd?: string;
+}
+
+export function createSkillsCommandEntry(): ICommand {
+  return {
+    name: 'skills',
+    displayName: 'Skills',
+    description: SKILLS_COMMAND_DESCRIPTION,
+    source: 'skills',
+    modelInvocable: true,
+    userInvocable: true,
+    argumentHint: '[list | <skill-name> [args]]',
+    safety: 'read-only',
+  };
+}
+
+function createSkillsSystemCommand(): ISystemCommand {
+  const entry = createSkillsCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: true,
+    argumentHint: entry.argumentHint,
+    safety: entry.safety,
+    lifecycle: 'inline',
+    execute: executeSkillsCommand,
+  };
+}
+
+export class SkillsCommandSource implements ICommandSource {
+  readonly name = 'skills';
+
+  getCommands(): ICommand[] {
+    return [createSkillsCommandEntry()];
+  }
+}
+
+export function createSkillsCommandModule(
+  options: ISkillsCommandModuleOptions = {},
+): ICommandModule {
+  const commandSources: ICommandSource[] = [new SkillsCommandSource()];
+  commandSources.push(new SkillCommandSource(options.cwd ?? process.cwd()));
+
+  return {
+    name: 'agent-command-skills',
+    commandSources,
+    systemCommands: [createSkillsSystemCommand()],
+  };
+}

package/src/skills/skills-command.ts

@@ -0,0 +1,110 @@
+import type {
+  ICommandHostContext,
+  ICommandResult,
+  ICommandSkillListEntry,
+} from '@robota-sdk/agent-framework';
+
+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".';
+
+interface IParsedSkillsArgs {
+  readonly action: 'list' | 'activate';
+  readonly skillName?: string;
+  readonly skillArgs: string;
+}
+
+function formatSkillFlags(skill: ICommandSkillListEntry): string {
+  const flags: string[] = [];
+  if (!skill.modelInvocable) flags.push('model-disabled');
+  if (!skill.userInvocable) flags.push('model-only');
+  if (skill.context) flags.push(`context:${skill.context}`);
+  if (skill.agent) flags.push(`agent:${skill.agent}`);
+  return flags.length > 0 ? ` [${flags.join(', ')}]` : '';
+}
+
+function formatSkillLine(skill: ICommandSkillListEntry): string {
+  const hint = skill.argumentHint ? ` ${skill.argumentHint}` : '';
+  return `- ${skill.name}${hint}: ${skill.description}${formatSkillFlags(skill)}`;
+}
+
+function formatSkillsMessage(skills: readonly ICommandSkillListEntry[]): string {
+  if (skills.length === 0) {
+    return [
+      'No skills are registered for this session.',
+      '',
+      'Skills are metadata until activated. Do not invent or imitate a skill workflow when no matching registered skill exists.',
+    ].join('\n');
+  }
+
+  return [
+    'Registered skills:',
+    ...skills.map(formatSkillLine),
+    '',
+    'Activation contract:',
+    '- Use /skills <skill-name> [args] to activate a matching skill.',
+    '- Treat /<skill-name> as a virtual alias for /skills <skill-name>.',
+    '- The system prompt Skills section is skill selection metadata.',
+    '- Treat descriptions as selection metadata only, not as loaded SKILL.md content.',
+    '- Do not answer by merely naming, recommending, or imitating a matching skill.',
+    '- If no listed skill matches the task, continue without claiming a skill was activated.',
+  ].join('\n');
+}
+
+function parseSkillsArgs(args: string): IParsedSkillsArgs {
+  const trimmed = args.trim();
+  if (trimmed.length === 0 || trimmed === 'list') {
+    return { action: 'list', skillArgs: '' };
+  }
+
+  const [skillName = '', ...rest] = trimmed.split(/\s+/);
+  if (skillName.length === 0) {
+    return { action: 'list', skillArgs: '' };
+  }
+
+  return {
+    action: 'activate',
+    skillName,
+    skillArgs: rest.join(' '),
+  };
+}
+
+export async function executeSkillsCommand(
+  context: ICommandHostContext,
+  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',
+      displayInput,
+      rawInput: displayInput,
+    });
+    return (
+      result ?? {
+        success: false,
+        message: `Unknown skill: ${parsed.skillName}`,
+      }
+    );
+  }
+
+  const skills = context.listSkills?.() ?? [];
+  return {
+    success: true,
+    message: formatSkillsMessage(skills),
+    data: {
+      skills,
+      activationContract: {
+        activateWith: '/skills <skill-name> [args]',
+        activationRequiredBeforeWorkflow: true,
+        metadataIsNotSkillContent: true,
+      },
+    },
+  };
+}

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

@@ -0,0 +1,95 @@
+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';
+
+const COMMAND_CONTEXT = {} as ICommandHostContext;
+
+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,
+        effects: [{ type: 'statusline-settings-patch', patch }],
+      });
+    },
+  );
+
+  it('reports usage for unsupported arguments without effects', 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?.effects).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,56 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  buildStatusLineCommandSubcommands,
+  STATUSLINE_COMMAND_ARGUMENT_HINT,
+  STATUSLINE_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+import { executeStatusLineCommand } from './statusline-command.js';
+
+export function createStatusLineCommandEntry(): ICommand {
+  return {
+    name: 'statusline',
+    displayName: 'Status Line',
+    description: STATUSLINE_COMMAND_DESCRIPTION,
+    source: 'statusline',
+    argumentHint: STATUSLINE_COMMAND_ARGUMENT_HINT,
+    subcommands: buildStatusLineCommandSubcommands('statusline'),
+    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,79 @@
+import type {
+  ICommandHostContext,
+  ICommandResult,
+  TStatusLineCommandSettingsPatch,
+} from '@robota-sdk/agent-framework';
+import { DEFAULT_STATUS_LINE_COMMAND_SETTINGS } from '@robota-sdk/agent-framework';
+
+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: ICommandHostContext,
+  args: string,
+): ICommandResult {
+  const action = parseStatusLineArgs(args);
+  if (!action.success) {
+    return { success: false, message: action.message };
+  }
+
+  return {
+    success: true,
+    message: action.message,
+    effects: [{ type: 'statusline-settings-patch', patch: action.patch }],
+  };
+}