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

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

@@ -0,0 +1,53 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  BACKGROUND_COMMAND_DESCRIPTION,
+  buildBackgroundCommandSubcommands,
+} from '@robota-sdk/agent-framework';
+import { executeBackgroundCommand } from './background-command.js';
+
+export function createBackgroundCommandEntry(): ICommand {
+  return {
+    name: 'background',
+    displayName: 'Background Tasks',
+    description: BACKGROUND_COMMAND_DESCRIPTION,
+    source: 'background',
+    modelInvocable: false,
+    subcommands: buildBackgroundCommandSubcommands(),
+  };
+}
+
+function createBackgroundSystemCommand(): ISystemCommand {
+  const entry = createBackgroundCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    subcommands: entry.subcommands,
+    execute: executeBackgroundCommand,
+  };
+}
+
+export class BackgroundCommandSource implements ICommandSource {
+  readonly name = 'background';
+
+  getCommands(): ICommand[] {
+    return [createBackgroundCommandEntry()];
+  }
+}
+
+export function createBackgroundCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-background',
+    commandSources: [new BackgroundCommandSource()],
+    systemCommands: [createBackgroundSystemCommand()],
+  };
+}

package/src/background/background-command.ts

@@ -0,0 +1,63 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import {
+  BACKGROUND_COMMAND_USAGE,
+  cancelCommandBackgroundTask,
+  closeCommandBackgroundTask,
+  formatCommandBackgroundTaskList,
+  listCommandBackgroundTasks,
+  parseCommandBackgroundLogCursor,
+  readCommandBackgroundTaskLog,
+} from '@robota-sdk/agent-framework';
+
+function parseCommandParts(args: string): string[] {
+  return args.trim().split(/\s+/).filter(Boolean);
+}
+
+export async function executeBackgroundCommand(
+  context: ICommandHostContext,
+  args: string,
+): Promise<ICommandResult> {
+  const [action = 'list', taskId, ...reasonParts] = parseCommandParts(args);
+  if (action === 'list') {
+    const tasks = listCommandBackgroundTasks(context);
+    return {
+      message: formatCommandBackgroundTaskList(tasks),
+      success: true,
+      data: { count: tasks.length },
+    };
+  }
+
+  if (!taskId) {
+    return {
+      message: BACKGROUND_COMMAND_USAGE,
+      success: false,
+    };
+  }
+
+  if (action === 'read' || action === 'log' || action === 'open') {
+    const page = await readCommandBackgroundTaskLog(
+      context,
+      taskId,
+      parseCommandBackgroundLogCursor(reasonParts[0]),
+    );
+    const next = page.nextCursor ? `\nNext offset: ${page.nextCursor.offset}` : '';
+    return {
+      message:
+        page.lines.length > 0 ? `${page.lines.join('\n')}${next}` : `No log lines: ${taskId}`,
+      success: true,
+      data: { taskId, nextOffset: page.nextCursor?.offset },
+    };
+  }
+
+  if (action === 'cancel' || action === 'stop') {
+    await cancelCommandBackgroundTask(context, taskId, reasonParts.join(' ') || undefined);
+    return { message: `Background task cancelled: ${taskId}`, success: true, data: { taskId } };
+  }
+
+  if (action === 'close' || action === 'dismiss') {
+    await closeCommandBackgroundTask(context, taskId);
+    return { message: `Background task closed: ${taskId}`, success: true, data: { taskId } };
+  }
+
+  return { message: `Unknown background action: ${action}`, success: false };
+}

package/src/background/index.ts

@@ -0,0 +1,6 @@
+export {
+  BackgroundCommandSource,
+  createBackgroundCommandEntry,
+  createBackgroundCommandModule,
+} from './background-command-module.js';
+export { executeBackgroundCommand } from './background-command.js';

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

@@ -0,0 +1,162 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
+import { InteractiveSession, SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createCompactCommandModule } from '../compact-command-module.js';
+
+type TContextWindowState = ReturnType<ICommandHostContext['getContextState']>;
+type TPermissionMode = ReturnType<ICommandSessionRuntime['getPermissionMode']>;
+
+const BEFORE_CONTEXT: TContextWindowState = {
+  usedTokens: 80,
+  maxTokens: 100,
+  usedPercentage: 80,
+  remainingPercentage: 20,
+};
+
+const AFTER_CONTEXT: TContextWindowState = {
+  usedTokens: 35,
+  maxTokens: 100,
+  usedPercentage: 35,
+  remainingPercentage: 65,
+};
+
+function createRuntime(): ICommandSessionRuntime {
+  let mode: TPermissionMode = 'default';
+  return {
+    clearHistory: vi.fn(),
+    compact: vi.fn().mockResolvedValue(undefined),
+    getContextState: vi.fn().mockReturnValue(AFTER_CONTEXT),
+    getPermissionMode: () => mode,
+    setPermissionMode: (nextMode) => {
+      mode = nextMode;
+    },
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 1,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => 0.835,
+  };
+}
+
+function createCommandHostContext(): ICommandHostContext & {
+  compactContext: ReturnType<typeof vi.fn>;
+} {
+  const runtime = createRuntime();
+  const getContextState = vi
+    .fn()
+    .mockReturnValueOnce(BEFORE_CONTEXT)
+    .mockReturnValue(AFTER_CONTEXT);
+  return {
+    getSession: () => runtime,
+    getContextState,
+    getAutoCompactThreshold: () => 0.835,
+    compactContext: vi.fn().mockResolvedValue(undefined),
+    getCwd: () => '/workspace',
+    listCommands: () => [],
+    listEditCheckpoints: () => [],
+    restoreEditCheckpoint: vi.fn(),
+    rollbackEditCheckpoint: vi.fn(),
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: vi.fn(),
+    listBackgroundTasks: () => [],
+    readBackgroundTaskLog: vi.fn().mockResolvedValue({ taskId: 'task_1', lines: [] }),
+    cancelBackgroundTask: vi.fn(),
+    closeBackgroundTask: vi.fn(),
+  };
+}
+
+describe('createCompactCommandModule', () => {
+  it('provides compact metadata and a blocking executable command', () => {
+    const module = createCompactCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-compact');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'compact',
+        description: 'Compress context window',
+        argumentHint: '[instructions]',
+        modelInvocable: true,
+        safety: 'write',
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'compact',
+        lifecycle: 'blocking',
+        modelInvocable: true,
+        safety: 'write',
+      }),
+    );
+  });
+
+  it('projects compact as a model-invocable descriptor through the command executor', () => {
+    const executor = new SystemCommandExecutor([
+      ...(createCompactCommandModule().systemCommands ?? []),
+    ]);
+
+    expect(executor.listModelInvocableCommands()).toEqual([
+      {
+        name: 'compact',
+        kind: 'builtin-command',
+        description: 'Compress context window',
+        userInvocable: true,
+        modelInvocable: true,
+        argumentHint: '[instructions]',
+        safety: 'write',
+      },
+    ]);
+  });
+
+  it('compacts context through the command host facade', async () => {
+    const context = createCommandHostContext();
+    const executor = new SystemCommandExecutor([
+      ...(createCompactCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('compact', context, ' focus on tests ');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Context compacted: 80% -> 35%');
+    expect(result?.data).toEqual({ before: 80, after: 35 });
+    expect(context.compactContext).toHaveBeenCalledWith('focus on tests');
+  });
+
+  it('runs through InteractiveSession foreground lifecycle when composed', async () => {
+    let resolveCompact: () => void;
+    const runtime = createRuntime();
+    const compact = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveCompact = resolve;
+        }),
+    );
+    const session = new InteractiveSession({
+      session: {
+        ...runtime,
+        compact,
+      } as never,
+      commandModules: [createCompactCommandModule()],
+    });
+    const thinkingStates: boolean[] = [];
+    session.on('thinking', (isThinking) => thinkingStates.push(isThinking));
+
+    const pending = session.executeCommand('compact', 'focus on tests');
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    const blocked = await session.executeCommand('compact', '');
+
+    expect(session.isExecuting()).toBe(true);
+    expect(thinkingStates).toEqual([true]);
+    expect(blocked?.success).toBe(false);
+    expect(blocked?.message).toContain('already running');
+    expect(compact).toHaveBeenCalledWith('focus on tests');
+
+    resolveCompact!();
+    const result = await pending;
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('Context compacted');
+    expect(session.isExecuting()).toBe(false);
+    expect(thinkingStates).toEqual([true, false]);
+  });
+});

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

@@ -0,0 +1,51 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import { executeCompactCommand } from './compact-command.js';
+
+export function createCompactCommandEntry(): ICommand {
+  return {
+    name: 'compact',
+    displayName: 'Compact Context',
+    description: 'Compress context window',
+    source: 'compact',
+    modelInvocable: true,
+    argumentHint: '[instructions]',
+    safety: 'write',
+  };
+}
+
+function createCompactSystemCommand(): ISystemCommand {
+  const entry = createCompactCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: entry.modelInvocable,
+    argumentHint: entry.argumentHint,
+    safety: entry.safety,
+    lifecycle: 'blocking',
+    execute: executeCompactCommand,
+  };
+}
+
+export class CompactCommandSource implements ICommandSource {
+  readonly name = 'compact';
+
+  getCommands(): ICommand[] {
+    return [createCompactCommandEntry()];
+  }
+}
+
+export function createCompactCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-compact',
+    commandSources: [new CompactCommandSource()],
+    systemCommands: [createCompactSystemCommand()],
+  };
+}

package/src/compact/compact-command.ts

@@ -0,0 +1,21 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import { compactCommandContext } from '@robota-sdk/agent-framework';
+
+function parseInstructions(args: string): string | undefined {
+  const instructions = args.trim();
+  return instructions.length > 0 ? instructions : undefined;
+}
+
+export async function executeCompactCommand(
+  context: ICommandHostContext,
+  args: string,
+): Promise<ICommandResult> {
+  const result = await compactCommandContext(context, parseInstructions(args));
+  const before = result.before.usedPercentage;
+  const after = result.after.usedPercentage;
+  return {
+    message: `Context compacted: ${Math.round(before)}% -> ${Math.round(after)}%`,
+    success: true,
+    data: { before, after },
+  };
+}

package/src/compact/index.ts

@@ -0,0 +1,6 @@
+export {
+  CompactCommandSource,
+  createCompactCommandEntry,
+  createCompactCommandModule,
+} from './compact-command-module.js';
+export { executeCompactCommand } from './compact-command.js';

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

@@ -0,0 +1,294 @@
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  ICommandHostContext,
+  IContextReferenceAddResult,
+  IContextReferenceClearResult,
+  IContextReferenceItem,
+  IContextReferenceRemoveResult,
+  ICommandSessionRuntime,
+  TAutoCompactThresholdSource,
+} from '@robota-sdk/agent-framework';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createContextCommandModule } from '../context-command-module.js';
+
+type TContextWindowState = ReturnType<ICommandHostContext['getContextState']>;
+type TPermissionMode = ReturnType<ICommandSessionRuntime['getPermissionMode']>;
+
+const CONTEXT_STATE: TContextWindowState = {
+  usedTokens: 5000,
+  maxTokens: 200000,
+  usedPercentage: 2.5,
+  remainingPercentage: 97.5,
+};
+
+const MANUAL_REFERENCE: IContextReferenceItem = {
+  id: 'manual:AGENTS.md',
+  sourcePath: '/workspace/AGENTS.md',
+  relativePath: 'AGENTS.md',
+  originalReference: '@AGENTS.md',
+  loadType: 'manual',
+  status: 'active',
+  byteLength: 42,
+  loadedAt: '2026-05-05T00:00:00.000Z',
+  lastUsedAt: '2026-05-05T00:00:00.000Z',
+};
+
+const PROMPT_REFERENCE: IContextReferenceItem = {
+  id: 'prompt-reference:packages/agent-sdk/docs/SPEC.md',
+  sourcePath: '/workspace/packages/agent-sdk/docs/SPEC.md',
+  relativePath: 'packages/agent-sdk/docs/SPEC.md',
+  originalReference: '@packages/agent-sdk/docs/SPEC.md',
+  loadType: 'prompt-reference',
+  status: 'observed',
+  byteLength: 200,
+  loadedAt: '2026-05-05T00:00:01.000Z',
+  lastUsedAt: '2026-05-05T00:00:01.000Z',
+};
+
+function createRuntime(state: { threshold: number | false }): ICommandSessionRuntime {
+  let mode: TPermissionMode = 'default';
+  return {
+    clearHistory: vi.fn(),
+    compact: vi.fn().mockResolvedValue(undefined),
+    getContextState: () => CONTEXT_STATE,
+    getPermissionMode: () => mode,
+    setPermissionMode: (nextMode) => {
+      mode = nextMode;
+    },
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 1,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => state.threshold,
+    setAutoCompactThreshold: (threshold) => {
+      state.threshold = threshold;
+    },
+  };
+}
+
+function createCommandHostContext(threshold: number | false = 0.835): ICommandHostContext & {
+  settings: Record<string, number | false>;
+  source: TAutoCompactThresholdSource;
+  references: IContextReferenceItem[];
+} {
+  const state = {
+    threshold,
+    source: 'settings' as TAutoCompactThresholdSource,
+    settings: {} as Record<string, number | false>,
+    references: [] as IContextReferenceItem[],
+  };
+  const runtime = createRuntime(state);
+  return {
+    get settings() {
+      return state.settings;
+    },
+    get source() {
+      return state.source;
+    },
+    get references() {
+      return state.references;
+    },
+    getSession: () => runtime,
+    getContextState: () => CONTEXT_STATE,
+    getAutoCompactThreshold: () => state.threshold,
+    getAutoCompactThresholdSource: () => state.source,
+    setAutoCompactThreshold: (nextThreshold, source = 'session') => {
+      state.threshold = nextThreshold;
+      state.source = source;
+    },
+    getCommandHostAdapters: () => ({
+      settings: {
+        read: () => state.settings,
+        write: (settings) => {
+          const value = settings.autoCompactThreshold;
+          state.settings =
+            typeof value === 'number' || value === false ? { autoCompactThreshold: value } : {};
+        },
+      },
+    }),
+    compactContext: vi.fn(),
+    listContextReferences: () => [...state.references],
+    addContextReference: async (path): Promise<IContextReferenceAddResult> => {
+      const reference = {
+        ...MANUAL_REFERENCE,
+        relativePath: path,
+        sourcePath: `/workspace/${path}`,
+        originalReference: `@${path}`,
+      };
+      state.references = [...state.references, reference];
+      return { reference, evicted: [], diagnostics: [] };
+    },
+    removeContextReference: (path): IContextReferenceRemoveResult => {
+      const removed = state.references.find((reference) => reference.relativePath === path);
+      state.references = state.references.filter((reference) => reference.relativePath !== path);
+      return removed ? { removed } : {};
+    },
+    clearContextReferences: (): IContextReferenceClearResult => {
+      const removed = [...state.references];
+      state.references = [];
+      return { removed };
+    },
+    getCwd: () => '/workspace',
+    listCommands: () => [],
+    listEditCheckpoints: () => [],
+    restoreEditCheckpoint: vi.fn(),
+    rollbackEditCheckpoint: vi.fn(),
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: vi.fn(),
+    listBackgroundTasks: () => [],
+    readBackgroundTaskLog: vi.fn().mockResolvedValue({ taskId: 'task_1', lines: [] }),
+    cancelBackgroundTask: vi.fn(),
+    closeBackgroundTask: vi.fn(),
+  };
+}
+
+function createExecutor(): SystemCommandExecutor {
+  return new SystemCommandExecutor([...(createContextCommandModule().systemCommands ?? [])]);
+}
+
+describe('createContextCommandModule', () => {
+  it('provides context metadata and an executable command', () => {
+    const module = createContextCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-context');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'context',
+        description: 'Context window info, reference inventory, and auto-compact controls',
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'context',
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('formats context usage and enabled auto compact policy', async () => {
+    const result = await createExecutor().execute('context', createCommandHostContext(0.75), '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('Context: 5,000 / 200,000 tokens (3%)');
+    expect(result?.message).toContain('Auto compact: 75% (settings)');
+    expect(result?.message).toContain('References: 0 active, 0 observed');
+    expect(result?.data).toEqual({
+      usedTokens: 5000,
+      maxTokens: 200000,
+      percentage: 2.5,
+      autoCompactThreshold: 0.75,
+      autoCompactThresholdSource: 'settings',
+      references: [],
+    });
+  });
+
+  it('lists active and observed context references', async () => {
+    const context = createCommandHostContext();
+    context.references.push(MANUAL_REFERENCE, PROMPT_REFERENCE);
+
+    const result = await createExecutor().execute('context', context, 'list');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('AGENTS.md [manual, active] 42 B');
+    expect(result?.message).toContain(
+      'packages/agent-sdk/docs/SPEC.md [prompt-reference, observed] 200 B',
+    );
+    expect(result?.data?.references).toEqual([MANUAL_REFERENCE, PROMPT_REFERENCE]);
+  });
+
+  it('adds manual context references through the SDK command API', async () => {
+    const context = createCommandHostContext();
+
+    const result = await createExecutor().execute('context', context, 'add AGENTS.md');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('Context reference added: AGENTS.md [manual, active] 42 B.');
+    expect(context.references[0]?.relativePath).toBe('AGENTS.md');
+  });
+
+  it('removes context references through the SDK command API', async () => {
+    const context = createCommandHostContext();
+    context.references.push(MANUAL_REFERENCE);
+
+    const result = await createExecutor().execute('context', context, 'remove AGENTS.md');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Context reference removed: AGENTS.md [manual, active] 42 B.');
+    expect(context.references).toEqual([]);
+  });
+
+  it('clears context references through the SDK command API', async () => {
+    const context = createCommandHostContext();
+    context.references.push(MANUAL_REFERENCE, PROMPT_REFERENCE);
+
+    const result = await createExecutor().execute('context', context, 'clear');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Context references cleared: 2 removed.');
+    expect(context.references).toEqual([]);
+  });
+
+  it('formats disabled auto compact policy', async () => {
+    const result = await createExecutor().execute('context', createCommandHostContext(false), '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('Auto compact: disabled');
+    expect(result?.data?.autoCompactThreshold).toBe(false);
+  });
+
+  it('sets auto compact threshold and persists the setting', async () => {
+    const context = createCommandHostContext();
+    const result = await createExecutor().execute('context', context, 'auto 85%');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Auto compact threshold set to 85% (settings).');
+    expect(context.settings.autoCompactThreshold).toBe(0.85);
+    expect(context.source).toBe('settings');
+    expect(context.getAutoCompactThreshold()).toBe(0.85);
+  });
+
+  it('disables auto compact and persists false', async () => {
+    const context = createCommandHostContext();
+    const result = await createExecutor().execute('context', context, 'auto off');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Auto compact disabled (settings).');
+    expect(context.settings.autoCompactThreshold).toBe(false);
+    expect(context.getAutoCompactThreshold()).toBe(false);
+  });
+
+  it('enables auto compact at the documented default', async () => {
+    const context = createCommandHostContext(false);
+    const result = await createExecutor().execute('context', context, 'auto on');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Auto compact enabled at 84% (settings).');
+    expect(context.settings.autoCompactThreshold).toBe(0.835);
+    expect(context.getAutoCompactThreshold()).toBe(0.835);
+  });
+
+  it('resets auto compact to the documented default and removes persisted override', async () => {
+    const context = createCommandHostContext(0.5);
+    await createExecutor().execute('context', context, 'auto 70%');
+
+    const result = await createExecutor().execute('context', context, 'auto reset');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Auto compact reset to default: 84% (settings).');
+    expect(context.settings).toEqual({});
+    expect(context.source).toBe('default');
+    expect(context.getAutoCompactThreshold()).toBe(0.835);
+  });
+
+  it('rejects invalid auto compact thresholds', async () => {
+    const result = await createExecutor().execute(
+      'context',
+      createCommandHostContext(),
+      'auto 150%',
+    );
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('greater than 0% and at most 100%');
+  });
+});