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

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

@@ -0,0 +1,52 @@
+import {
+  BACKGROUND_COMMAND_DESCRIPTION,
+  buildBackgroundCommandSubcommands,
+} from '@robota-sdk/agent-framework';
+
+import { executeBackgroundCommand } from './background-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createBackgroundCommandEntry(): ICommand {
+  return {
+    name: 'background',
+    displayName: 'Background Tasks',
+    description: BACKGROUND_COMMAND_DESCRIPTION,
+    source: 'background',
+    // User-only: a view onto the user's job panel; the model manages its own jobs through `agent`.
+    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,65 @@
+import {
+  BACKGROUND_COMMAND_USAGE,
+  cancelCommandBackgroundTask,
+  closeCommandBackgroundTask,
+  formatCommandBackgroundTaskList,
+  listCommandBackgroundTasks,
+  parseCommandBackgroundLogCursor,
+  readCommandBackgroundTaskLog,
+} from '@robota-sdk/agent-framework';
+
+import type { ICommandHostBackgroundTasks } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+function parseCommandParts(args: string): string[] {
+  return args.trim().split(/\s+/).filter(Boolean);
+}
+
+export async function executeBackgroundCommand(
+  context: ICommandHostBackgroundTasks,
+  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/command-module-utils.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSystemCommandFromEntry } from './command-module-utils.js';
+
+const behavior = {
+  lifecycle: 'inline',
+  requiresPermission: false,
+  execute: () => ({ success: true, message: 'ran' }),
+} as const;
+
+describe('createSystemCommandFromEntry', () => {
+  it('#3189: carries where the entry says it runs, so the catalog and the palette agree', () => {
+    const command = createSystemCommandFromEntry(
+      {
+        name: 'local',
+        description: 'Runs on the terminal',
+        source: 'test',
+        runner: 'client',
+        surfaces: ['terminal'],
+      },
+      behavior,
+    );
+
+    expect(command.runner).toBe('client');
+    expect(command.surfaces).toEqual(['terminal']);
+  });
+
+  it('leaves an unstated placement unstated rather than guessing one', () => {
+    const command = createSystemCommandFromEntry(
+      { name: 'plain', description: 'Runs on the runtime', source: 'test' },
+      behavior,
+    );
+
+    expect('runner' in command).toBe(false);
+    expect('surfaces' in command).toBe(false);
+  });
+});

package/src/command-module-utils.ts

@@ -0,0 +1,35 @@
+import type { ICommand, ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { ICommandHostContext, ISystemCommand } from '@robota-sdk/agent-framework';
+
+/** Build executable metadata from the palette entry so user and model views cannot drift. */
+export function createSystemCommandFromEntry(
+  entry: ICommand,
+  behavior: {
+    lifecycle: NonNullable<ISystemCommand['lifecycle']>;
+    requiresPermission: boolean;
+    execute: (
+      context: ICommandHostContext,
+      args: string,
+    ) => ICommandResult | Promise<ICommandResult>;
+    semanticRole?: ISystemCommand['semanticRole'];
+  },
+): ISystemCommand {
+  return {
+    name: entry.name,
+    ...(entry.displayName !== undefined ? { displayName: entry.displayName } : {}),
+    description: entry.description,
+    ...(entry.example !== undefined ? { example: entry.example } : {}),
+    ...(entry.modelInvocable !== undefined ? { modelInvocable: entry.modelInvocable } : {}),
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
+    ...(entry.userInvocable !== undefined ? { userInvocable: entry.userInvocable } : {}),
+    ...(entry.argumentHint !== undefined ? { argumentHint: entry.argumentHint } : {}),
+    ...(entry.safety !== undefined ? { safety: entry.safety } : {}),
+    ...(entry.subcommands !== undefined ? { subcommands: entry.subcommands } : {}),
+    ...(entry.runner !== undefined ? { runner: entry.runner } : {}),
+    ...(entry.surfaces !== undefined ? { surfaces: entry.surfaces } : {}),
+    ...(behavior.semanticRole !== undefined ? { semanticRole: behavior.semanticRole } : {}),
+    lifecycle: behavior.lifecycle,
+    requiresPermission: behavior.requiresPermission,
+    execute: behavior.execute,
+  };
+}

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

@@ -0,0 +1,181 @@
+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';
+import type { ICommandHostContextWindow } from '@robota-sdk/agent-framework';
+import {
+  createTestCommandHost,
+  createTestSessionRuntime,
+} from '@robota-sdk/agent-framework/testing';
+
+type TContextWindowState = ReturnType<ICommandHostContextWindow['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(beforeCount = 10, afterCount = 3) {
+  let mode: TPermissionMode = 'default';
+  const getMessageCount = vi.fn().mockReturnValueOnce(beforeCount).mockReturnValue(afterCount);
+  return createTestSessionRuntime({
+    clearHistory: vi.fn(),
+    compact: vi.fn().mockResolvedValue(undefined),
+    getContextState: vi.fn().mockReturnValue(AFTER_CONTEXT),
+    getPermissionMode: () => mode,
+    setPermissionMode: (nextMode) => {
+      mode = nextMode;
+    },
+    getSessionId: () => 'session_1',
+    getMessageCount,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => 0.835,
+    getFullHistory: () => [],
+    getHistory: () => [],
+  });
+}
+
+function createCommandHostContext(): ReturnType<typeof createTestCommandHost> & {
+  compactContext: ReturnType<typeof vi.fn>;
+} {
+  const runtime = createRuntime();
+  const getContextState = vi
+    .fn()
+    .mockReturnValueOnce(BEFORE_CONTEXT)
+    .mockReturnValue(AFTER_CONTEXT);
+  return createTestCommandHost({
+    overrides: {
+      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(),
+    },
+  }) as ReturnType<typeof createCommandHostContext>;
+}
+
+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',
+        semanticRole: 'contextReduction',
+        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: expect.stringContaining('Summarize older conversation turns'),
+        userInvocable: true,
+        modelInvocable: true,
+        argumentHint: '[instructions]',
+        safety: 'write',
+        requiresPermission: false,
+      },
+    ]);
+  });
+
+  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.\n  Removed messages: 7 (70% of total)\n  Context: 80% → 35%',
+    );
+    expect(result?.data).toEqual({
+      before: BEFORE_CONTEXT,
+      after: AFTER_CONTEXT,
+      beforeMessageCount: 10,
+      afterMessageCount: 3,
+    });
+    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,59 @@
+import { executeCompactCommand } from './compact-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createCompactCommandEntry(): ICommand {
+  return {
+    name: 'compact',
+    displayName: 'Compact Context',
+    description: 'Compress context window',
+    // Model-invocable: compaction only summarizes the model's own context, and the model is the one
+    // that notices when it is running out of room.
+    modelDescription:
+      'Summarize older conversation turns to free context-window space. Use it when the context is ' +
+      'nearly full (check with the context command) or before starting a large new task; optional ' +
+      'instructions say what the summary must keep. Returns how many messages were removed and the ' +
+      'context usage before and after.',
+    source: 'compact',
+    modelInvocable: true,
+    argumentHint: '[instructions]',
+    safety: 'write',
+    example: '/compact Summarize the current context',
+  };
+}
+
+function createCompactSystemCommand(): ISystemCommand {
+  const entry = createCompactCommandEntry();
+  return {
+    name: entry.name,
+    semanticRole: 'contextReduction',
+    displayName: entry.displayName,
+    description: entry.description,
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
+    example: entry.example,
+    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,33 @@
+import { compactCommandContext } from '@robota-sdk/agent-framework';
+
+import type {
+  ICommandHostContextWindow,
+  ICommandHostSessionAccess,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+function parseInstructions(args: string): string | undefined {
+  const instructions = args.trim();
+  return instructions.length > 0 ? instructions : undefined;
+}
+
+export async function executeCompactCommand(
+  context: ICommandHostContextWindow & ICommandHostSessionAccess,
+  args: string,
+): Promise<ICommandResult> {
+  const result = await compactCommandContext(context, parseInstructions(args));
+  const { before, after, beforeMessageCount, afterMessageCount } = result;
+  const removedMessages = beforeMessageCount - afterMessageCount;
+  const removedPercent =
+    beforeMessageCount > 0 ? Math.round((removedMessages / beforeMessageCount) * 100) : 0;
+  const message = [
+    'Context compacted.',
+    `  Removed messages: ${removedMessages} (${removedPercent}% of total)`,
+    `  Context: ${Math.round(before.usedPercentage)}% → ${Math.round(after.usedPercentage)}%`,
+  ].join('\n');
+  return {
+    message,
+    success: true,
+    data: { before, after, beforeMessageCount, afterMessageCount },
+  };
+}

package/src/compact/index.ts

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