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

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

@@ -0,0 +1,54 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import { executeContextCommand } from './context-command.js';
+
+export function createContextCommandEntry(): ICommand {
+  return {
+    name: 'context',
+    displayName: 'Context References',
+    description: 'Context window info, reference inventory, and auto-compact controls',
+    source: 'context',
+    modelInvocable: false,
+    argumentHint: 'list | add <path> | remove <path> | clear | auto ...',
+    subcommands: [
+      { name: 'list', description: 'List loaded context references', source: 'context' },
+      { name: 'add', description: 'Add a file to active context references', source: 'context' },
+      { name: 'remove', description: 'Remove a context reference', source: 'context' },
+      { name: 'clear', description: 'Clear context references', source: 'context' },
+      { name: 'auto', description: 'Inspect or change auto-compact policy', source: 'context' },
+    ],
+  };
+}
+
+function createContextSystemCommand(): ISystemCommand {
+  const entry = createContextCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    execute: executeContextCommand,
+  };
+}
+
+export class ContextCommandSource implements ICommandSource {
+  readonly name = 'context';
+
+  getCommands(): ICommand[] {
+    return [createContextCommandEntry()];
+  }
+}
+
+export function createContextCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-context',
+    commandSources: [new ContextCommandSource()],
+    systemCommands: [createContextSystemCommand()],
+  };
+}

package/src/context/context-command.ts

@@ -0,0 +1,298 @@
+import type {
+  ICommandHostContext,
+  ICommandResult,
+  TAutoCompactThreshold,
+  TAutoCompactThresholdSource,
+} from '@robota-sdk/agent-framework';
+import {
+  addCommandContextReference,
+  clearCommandContextReferences,
+  DEFAULT_AUTO_COMPACT_THRESHOLD,
+  listCommandContextReferences,
+  readAutoCompactThreshold,
+  readAutoCompactThresholdSource,
+  readCommandContextState,
+  removeCommandContextReference,
+  resetAutoCompactThresholdSetting,
+  setCommandAutoCompactThreshold,
+  writeAutoCompactThresholdSetting,
+} from '@robota-sdk/agent-framework';
+import type { IContextReferenceItem } from '@robota-sdk/agent-framework';
+
+const PERCENT = 100;
+const USAGE = [
+  'Usage: /context [list] | add <path> | remove <path> | clear | auto on | off | <percent> | reset',
+  'Examples: /context list, /context add AGENTS.md, /context remove AGENTS.md, /context auto 85%',
+].join('\n');
+
+function formatThreshold(threshold: TAutoCompactThreshold): string {
+  if (threshold === false) {
+    return 'disabled';
+  }
+  return `${Math.round(threshold * PERCENT)}%`;
+}
+
+function formatAutoCompactLine(
+  threshold: TAutoCompactThreshold,
+  source: TAutoCompactThresholdSource,
+): string {
+  if (threshold === false) {
+    return `Auto compact: disabled (${source})`;
+  }
+  return `Auto compact: ${formatThreshold(threshold)} (${source})`;
+}
+
+function formatPersistenceSuffix(persisted: boolean): string {
+  return persisted ? 'settings' : 'current session only';
+}
+
+export async function executeContextCommand(
+  context: ICommandHostContext,
+  args: string,
+): Promise<ICommandResult> {
+  const parts = args
+    .trim()
+    .split(/\s+/)
+    .filter((part) => part.length > 0);
+
+  if (parts.length > 0) {
+    return executeContextSubcommand(context, parts);
+  }
+
+  const state = readCommandContextState(context);
+  const autoCompactThreshold = readAutoCompactThreshold(context);
+  const autoCompactThresholdSource = readAutoCompactThresholdSource(context);
+  return {
+    message: [
+      `Context: ${state.usedTokens.toLocaleString()} / ${state.maxTokens.toLocaleString()} tokens (${Math.round(state.usedPercentage)}%)`,
+      formatAutoCompactLine(autoCompactThreshold, autoCompactThresholdSource),
+      formatContextReferenceSummary(listCommandContextReferences(context)),
+    ].join('\n'),
+    success: true,
+    data: {
+      usedTokens: state.usedTokens,
+      maxTokens: state.maxTokens,
+      percentage: state.usedPercentage,
+      autoCompactThreshold,
+      autoCompactThresholdSource,
+      references: listCommandContextReferences(context),
+    },
+  };
+}
+
+async function executeContextSubcommand(
+  context: ICommandHostContext,
+  parts: readonly string[],
+): Promise<ICommandResult> {
+  const [subcommand, ...rest] = parts;
+  if (subcommand === 'list') {
+    if (rest.length > 0) return { success: false, message: USAGE };
+    return formatContextReferenceList(listCommandContextReferences(context));
+  }
+  if (subcommand === 'add') {
+    return executeAddContextReference(context, rest);
+  }
+  if (subcommand === 'remove') {
+    return executeRemoveContextReference(context, rest);
+  }
+  if (subcommand === 'clear') {
+    if (rest.length > 0) return { success: false, message: USAGE };
+    const result = clearCommandContextReferences(context);
+    return {
+      success: true,
+      message: `Context references cleared: ${result.removed.length} removed.`,
+      data: { removed: result.removed },
+    };
+  }
+  if (subcommand !== 'auto') {
+    return { success: false, message: USAGE };
+  }
+  return executeAutoContextSubcommand(context, rest);
+}
+
+function executeAutoContextSubcommand(
+  context: ICommandHostContext,
+  parts: readonly string[],
+): ICommandResult {
+  const [action, extra] = parts;
+  if (extra !== undefined) return { success: false, message: USAGE };
+  if (action === undefined) {
+    const threshold = readAutoCompactThreshold(context);
+    const source = readAutoCompactThresholdSource(context);
+    return {
+      success: true,
+      message: [formatAutoCompactLine(threshold, source), USAGE].join('\n'),
+      data: { autoCompactThreshold: threshold, autoCompactThresholdSource: source },
+    };
+  }
+
+  if (action === 'on') {
+    return applyAutoCompactThreshold(context, DEFAULT_AUTO_COMPACT_THRESHOLD, 'enabled');
+  }
+  if (action === 'off') {
+    return applyAutoCompactThreshold(context, false, 'disabled');
+  }
+  if (action === 'reset') {
+    const persisted = resetAutoCompactThresholdSetting(context);
+    setCommandAutoCompactThreshold(context, DEFAULT_AUTO_COMPACT_THRESHOLD, 'default');
+    return {
+      success: true,
+      message: `Auto compact reset to default: ${formatThreshold(DEFAULT_AUTO_COMPACT_THRESHOLD)} (${formatPersistenceSuffix(persisted)}).`,
+      data: {
+        autoCompactThreshold: DEFAULT_AUTO_COMPACT_THRESHOLD,
+        autoCompactThresholdSource: 'default',
+        persisted,
+      },
+    };
+  }
+
+  const parsed = parseThreshold(action);
+  if (!parsed.success) {
+    return { success: false, message: `${parsed.message}\n${USAGE}` };
+  }
+  return applyAutoCompactThreshold(context, parsed.threshold, 'threshold set');
+}
+
+async function executeAddContextReference(
+  context: ICommandHostContext,
+  args: readonly string[],
+): Promise<ICommandResult> {
+  const path = args.join(' ').trim();
+  if (!path) return { success: false, message: USAGE };
+
+  const result = await addCommandContextReference(context, path);
+  if (!result.reference) {
+    return {
+      success: false,
+      message: result.diagnostics.join('\n') || `Context reference not found: ${path}`,
+      data: { diagnostics: result.diagnostics },
+    };
+  }
+
+  return {
+    success: true,
+    message: [
+      `Context reference added: ${formatContextReferenceLine(result.reference)}.`,
+      ...(result.evicted.length > 0
+        ? [`Evicted ${result.evicted.length} older context reference(s).`]
+        : []),
+    ].join('\n'),
+    data: { reference: result.reference, evicted: result.evicted },
+  };
+}
+
+function executeRemoveContextReference(
+  context: ICommandHostContext,
+  args: readonly string[],
+): ICommandResult {
+  const path = args.join(' ').trim();
+  if (!path) return { success: false, message: USAGE };
+
+  const result = removeCommandContextReference(context, path);
+  if (!result.removed) {
+    return {
+      success: false,
+      message: `Context reference not found: ${path}`,
+    };
+  }
+
+  return {
+    success: true,
+    message: `Context reference removed: ${formatContextReferenceLine(result.removed)}.`,
+    data: { removed: result.removed },
+  };
+}
+
+function applyAutoCompactThreshold(
+  context: ICommandHostContext,
+  threshold: TAutoCompactThreshold,
+  action: 'enabled' | 'disabled' | 'threshold set',
+): ICommandResult {
+  const persisted = writeAutoCompactThresholdSetting(context, threshold);
+  const source: TAutoCompactThresholdSource = persisted ? 'settings' : 'session';
+  setCommandAutoCompactThreshold(context, threshold, source);
+
+  return {
+    success: true,
+    message: formatApplyMessage(action, threshold, persisted),
+    data: {
+      autoCompactThreshold: threshold,
+      autoCompactThresholdSource: source,
+      persisted,
+    },
+  };
+}
+
+function formatApplyMessage(
+  action: 'enabled' | 'disabled' | 'threshold set',
+  threshold: TAutoCompactThreshold,
+  persisted: boolean,
+): string {
+  const suffix = formatPersistenceSuffix(persisted);
+  if (action === 'disabled') {
+    return `Auto compact disabled (${suffix}).`;
+  }
+  if (action === 'enabled') {
+    return `Auto compact enabled at ${formatThreshold(threshold)} (${suffix}).`;
+  }
+  return `Auto compact threshold set to ${formatThreshold(threshold)} (${suffix}).`;
+}
+
+type TParseThresholdResult =
+  | { success: true; threshold: number }
+  | { success: false; message: string };
+
+function parseThreshold(raw: string): TParseThresholdResult {
+  if (raw.endsWith('%')) {
+    const percent = Number(raw.slice(0, -1));
+    if (!Number.isFinite(percent) || percent <= 0 || percent > PERCENT) {
+      return {
+        success: false,
+        message: 'Auto compact percentage must be greater than 0% and at most 100%.',
+      };
+    }
+    return { success: true, threshold: percent / PERCENT };
+  }
+
+  if (raw.includes('.')) {
+    const fraction = Number(raw);
+    if (!Number.isFinite(fraction) || fraction <= 0 || fraction > 1) {
+      return {
+        success: false,
+        message: 'Auto compact fraction must be greater than 0 and at most 1.',
+      };
+    }
+    return { success: true, threshold: fraction };
+  }
+
+  return {
+    success: false,
+    message: 'Use a percentage such as 85% or a fraction such as 0.85.',
+  };
+}
+
+function formatContextReferenceSummary(references: readonly IContextReferenceItem[]): string {
+  const active = references.filter((reference) => reference.status === 'active').length;
+  const observed = references.filter((reference) => reference.status === 'observed').length;
+  return `References: ${active} active, ${observed} observed`;
+}
+
+function formatContextReferenceList(references: readonly IContextReferenceItem[]): ICommandResult {
+  if (references.length === 0) {
+    return { success: true, message: 'No context references.', data: { references } };
+  }
+
+  return {
+    success: true,
+    message: ['Context references:', ...references.map(formatContextReferenceLine)].join('\n'),
+    data: { references },
+  };
+}
+
+function formatContextReferenceLine(reference: IContextReferenceItem): string {
+  return [
+    reference.relativePath,
+    `[${reference.loadType}, ${reference.status}]`,
+    `${reference.byteLength.toLocaleString()} B`,
+  ].join(' ');
+}

package/src/context/index.ts

@@ -0,0 +1,6 @@
+export {
+  ContextCommandSource,
+  createContextCommandEntry,
+  createContextCommandModule,
+} from './context-command-module.js';
+export { executeContextCommand } from './context-command.js';

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

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ExitCommandSource,
+  createExitCommandEntry,
+  createExitCommandModule,
+  executeExitCommand,
+} from '../index.js';
+
+describe('exit command module', () => {
+  it('provides command metadata and executable registration from one module', () => {
+    const entry = createExitCommandEntry();
+    const module = createExitCommandModule();
+
+    expect(entry).toEqual({
+      name: 'exit',
+      displayName: 'Exit Session',
+      description: 'Exit CLI',
+      source: 'exit',
+      modelInvocable: false,
+    });
+    expect(new ExitCommandSource().getCommands()).toEqual([entry]);
+    expect(module.systemCommands?.map((command) => command.name)).toEqual(['exit']);
+    expect(module.commandSources?.flatMap((source) => source.getCommands())).toEqual([entry]);
+  });
+
+  it('returns the session exit effect without owning process exit', () => {
+    const result = executeExitCommand({} as never, '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Exit requested.',
+      effects: [{ type: 'session-exit-requested' }],
+    });
+  });
+});

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

@@ -0,0 +1,48 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import { EXIT_COMMAND_DESCRIPTION } from '@robota-sdk/agent-framework';
+import { executeExitCommand } from './exit-command.js';
+
+export function createExitCommandEntry(): ICommand {
+  return {
+    name: 'exit',
+    displayName: 'Exit Session',
+    description: EXIT_COMMAND_DESCRIPTION,
+    source: 'exit',
+    modelInvocable: false,
+  };
+}
+
+function createExitSystemCommand(): ISystemCommand {
+  const entry = createExitCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: true,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeExitCommand,
+  };
+}
+
+export class ExitCommandSource implements ICommandSource {
+  readonly name = 'exit';
+
+  getCommands(): ICommand[] {
+    return [createExitCommandEntry()];
+  }
+}
+
+export function createExitCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-exit',
+    commandSources: [new ExitCommandSource()],
+    systemCommands: [createExitSystemCommand()],
+  };
+}

package/src/exit/exit-command.ts

@@ -0,0 +1,10 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import { createSessionExitRequestedEffect } from '@robota-sdk/agent-framework';
+
+export function executeExitCommand(_context: ICommandHostContext, _args: string): ICommandResult {
+  return {
+    success: true,
+    message: 'Exit requested.',
+    effects: [createSessionExitRequestedEffect()],
+  };
+}

package/src/exit/index.ts

@@ -0,0 +1,6 @@
+export {
+  ExitCommandSource,
+  createExitCommandEntry,
+  createExitCommandModule,
+} from './exit-command-module.js';
+export { executeExitCommand } from './exit-command.js';

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

@@ -0,0 +1,106 @@
+import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
+import { describe, expect, it } from 'vitest';
+import { createHelpCommandModule } from '../help-command-module.js';
+import { executeHelpCommand } from '../help-command.js';
+
+function createCommandSessionRuntime(): ICommandSessionRuntime {
+  return {
+    clearHistory: () => undefined,
+    compact: async () => undefined,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getPermissionMode: () => 'default',
+    setPermissionMode: () => undefined,
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 0,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => false,
+  };
+}
+
+function createCommandHostContext(): ICommandHostContext {
+  const checkpoint = {
+    id: 'checkpoint_1',
+    sessionId: 'session_1',
+    sequence: 1,
+    prompt: 'prompt',
+    createdAt: '2026-05-03T00:00:00.000Z',
+    fileCount: 0,
+  };
+  return {
+    getSession: () => createCommandSessionRuntime(),
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getAutoCompactThreshold: () => 0.8,
+    compactContext: async () => undefined,
+    getCwd: () => '/workspace',
+    listCommands: () => [
+      { name: 'help', displayName: 'Help', description: 'Show available commands' },
+      { name: 'provider', displayName: 'Provider Setup', description: 'Manage provider profiles' },
+      { name: 'plugin', displayName: 'Plugins', description: 'Manage plugins' },
+    ],
+    listEditCheckpoints: () => [],
+    restoreEditCheckpoint: async () => ({
+      target: checkpoint,
+      restoredCheckpointCount: 0,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    rollbackEditCheckpoint: async () => ({
+      target: checkpoint,
+      restoredCheckpointCount: 0,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: () => undefined,
+    listBackgroundTasks: () => [],
+    readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+    cancelBackgroundTask: async () => undefined,
+    closeBackgroundTask: async () => undefined,
+  };
+}
+
+describe('createHelpCommandModule', () => {
+  it('contributes help command metadata and executable command', () => {
+    const module = createHelpCommandModule();
+
+    expect(module.name).toBe('agent-command-help');
+    expect(module.commandSources?.[0]?.getCommands()).toEqual([
+      {
+        name: 'help',
+        displayName: 'Help',
+        description: 'Show available commands',
+        source: 'help',
+        modelInvocable: false,
+      },
+    ]);
+    expect(module.systemCommands?.map((command) => command.name)).toEqual(['help']);
+    expect(module.systemCommands?.[0]?.lifecycle).toBe('inline');
+    expect(module.systemCommands?.[0]?.modelInvocable).toBe(false);
+  });
+});
+
+describe('executeHelpCommand', () => {
+  it('renders the composed command list from the host context', () => {
+    const result = executeHelpCommand(createCommandHostContext(), '');
+
+    expect(result).toEqual({
+      success: true,
+      message: [
+        'Available commands:',
+        '  Help (/help)                     — Show available commands',
+        '  Provider Setup (/provider)       — Manage provider profiles',
+        '  Plugins (/plugin)                — Manage plugins',
+      ].join('\n'),
+    });
+  });
+});

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

@@ -0,0 +1,48 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import { HELP_COMMAND_DESCRIPTION } from '@robota-sdk/agent-framework';
+import { executeHelpCommand } from './help-command.js';
+
+export function createHelpCommandEntry(): ICommand {
+  return {
+    name: 'help',
+    displayName: 'Help',
+    description: HELP_COMMAND_DESCRIPTION,
+    source: 'help',
+    modelInvocable: false,
+  };
+}
+
+function createHelpSystemCommand(): ISystemCommand {
+  const entry = createHelpCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeHelpCommand,
+  };
+}
+
+export class HelpCommandSource implements ICommandSource {
+  readonly name = 'help';
+
+  getCommands(): ICommand[] {
+    return [createHelpCommandEntry()];
+  }
+}
+
+export function createHelpCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-help',
+    commandSources: [new HelpCommandSource()],
+    systemCommands: [createHelpSystemCommand()],
+  };
+}

package/src/help/help-command.ts

@@ -0,0 +1,9 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import { formatCommandHelpMessage } from '@robota-sdk/agent-framework';
+
+export function executeHelpCommand(context: ICommandHostContext, _args: string): ICommandResult {
+  return {
+    success: true,
+    message: formatCommandHelpMessage(context),
+  };
+}

package/src/help/index.ts

@@ -0,0 +1,6 @@
+export {
+  createHelpCommandEntry,
+  createHelpCommandModule,
+  HelpCommandSource,
+} from './help-command-module.js';
+export { executeHelpCommand } from './help-command.js';

package/src/index.ts

@@ -0,0 +1,20 @@
+export * from './agent/index.js';
+export * from './background/index.js';
+export * from './compact/index.js';
+export * from './context/index.js';
+export * from './exit/index.js';
+export * from './help/index.js';
+export * from './language/index.js';
+export * from './memory/index.js';
+export * from './mode/index.js';
+export * from './model/index.js';
+export * from './permissions/index.js';
+export * from './plugin/index.js';
+export * from './provider/index.js';
+export * from './reset/index.js';
+export * from './rewind/index.js';
+export * from './session/index.js';
+export * from './settings/index.js';
+export * from './skills/index.js';
+export * from './statusline/index.js';
+export * from './user-local/index.js';