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

package/src/agent/agent-command-parser.ts

@@ -0,0 +1,180 @@
+import type { TBackgroundTaskIsolation } from '@robota-sdk/agent-framework';
+
+export const DEFAULT_AGENT_TYPE = 'general-purpose';
+
+export type TAgentMode = 'background';
+
+export interface IAgentRunRequest {
+  readonly agentType: string;
+  readonly label: string;
+  readonly mode: TAgentMode;
+  readonly prompt: string;
+  readonly model?: string;
+  readonly isolation?: TBackgroundTaskIsolation;
+}
+
+interface IParsedAgentOptions {
+  readonly agentType?: string;
+  readonly model?: string;
+  readonly isolation?: TBackgroundTaskIsolation;
+  readonly positional: string[];
+}
+
+export function tokenizeArgs(args: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | undefined;
+  let escaped = false;
+
+  for (const char of args) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (quote && char === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (current.length > 0) tokens.push(current);
+  return tokens;
+}
+
+function parseOptions(tokens: readonly string[]): IParsedAgentOptions {
+  const positional: string[] = [];
+  let agentType: string | undefined;
+  let model: string | undefined;
+  let isolation: TBackgroundTaskIsolation | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '--background') {
+      continue;
+    }
+    if (token === '--agent' || token === '--type' || token === '-a') {
+      agentType = tokens[index + 1];
+      index += 1;
+      continue;
+    }
+    if (token === '--model') {
+      model = tokens[index + 1];
+      index += 1;
+      continue;
+    }
+    if (token === '--isolation') {
+      const value = tokens[index + 1];
+      if (value === 'none' || value === 'worktree') isolation = value;
+      index += 1;
+      continue;
+    }
+    if (token !== undefined) positional.push(token);
+  }
+
+  return {
+    positional,
+    ...(agentType ? { agentType } : {}),
+    ...(model ? { model } : {}),
+    ...(isolation ? { isolation } : {}),
+  };
+}
+
+function createRequest(
+  options: IParsedAgentOptions,
+  agentType: string,
+  label: string,
+  prompt: string,
+): IAgentRunRequest {
+  return {
+    agentType,
+    label,
+    mode: 'background',
+    prompt,
+    ...(options.model ? { model: options.model } : {}),
+    ...(options.isolation ? { isolation: options.isolation } : {}),
+  };
+}
+
+export function parseRunRequest(
+  tokens: readonly string[],
+  availableAgentNames: ReadonlySet<string>,
+): IAgentRunRequest | undefined {
+  const options = parseOptions(tokens);
+  const [first, ...rest] = options.positional;
+  let agentType = options.agentType ?? DEFAULT_AGENT_TYPE;
+  let promptParts = options.positional;
+
+  if (!options.agentType && first && availableAgentNames.has(first)) {
+    agentType = first;
+    promptParts = rest;
+  }
+
+  const prompt = promptParts.join(' ').trim();
+  if (!prompt) return undefined;
+  return createRequest(options, agentType, agentType, prompt);
+}
+
+export function parseParallelRequests(
+  tokens: readonly string[],
+  availableAgentNames: ReadonlySet<string>,
+): IAgentRunRequest[] {
+  const options = parseOptions(tokens);
+  return options.positional
+    .map((token) => parseAgentJobToken(token, options, availableAgentNames))
+    .filter((job): job is IAgentRunRequest => job !== undefined);
+}
+
+function parseAgentJobToken(
+  token: string,
+  options: IParsedAgentOptions,
+  availableAgentNames: ReadonlySet<string>,
+): IAgentRunRequest | undefined {
+  const equalsIndex = token.indexOf('=');
+  if (equalsIndex > 0) {
+    const label = token.slice(0, equalsIndex);
+    const spec = token.slice(equalsIndex + 1);
+    return parseAgentPromptSpec(label, spec, options, availableAgentNames);
+  }
+
+  const colonIndex = token.indexOf(':');
+  if (colonIndex <= 0 || colonIndex === token.length - 1) return undefined;
+  const head = token.slice(0, colonIndex);
+  const prompt = token.slice(colonIndex + 1);
+  const agentType =
+    options.agentType ?? (availableAgentNames.has(head) ? head : DEFAULT_AGENT_TYPE);
+  return createRequest(options, agentType, head, prompt);
+}
+
+function parseAgentPromptSpec(
+  label: string,
+  spec: string,
+  options: IParsedAgentOptions,
+  availableAgentNames: ReadonlySet<string>,
+): IAgentRunRequest | undefined {
+  const colonIndex = spec.indexOf(':');
+  if (colonIndex === -1) {
+    const agentType =
+      options.agentType ?? (availableAgentNames.has(label) ? label : DEFAULT_AGENT_TYPE);
+    return createRequest(options, agentType, label, spec);
+  }
+  if (colonIndex === 0 || colonIndex === spec.length - 1) return undefined;
+  return createRequest(options, spec.slice(0, colonIndex), label, spec.slice(colonIndex + 1));
+}

package/src/agent/agent-command.ts

@@ -0,0 +1,235 @@
+import { summarizeBackgroundJobGroup } from '@robota-sdk/agent-framework';
+import type {
+  IAgentJobHostContext,
+  ICommandResult,
+  ISubagentJobState,
+} from '@robota-sdk/agent-framework';
+import { parseParallelRequests, parseRunRequest, tokenizeArgs } from './agent-command-parser.js';
+import type { IAgentRunRequest } from './agent-command-parser.js';
+
+function formatError<TError>(error: TError): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function getAvailableAgentNames(session: IAgentJobHostContext): ReadonlySet<string> {
+  return new Set(session.listAgentDefinitions().map((agent) => agent.name));
+}
+
+function validateAgentType(
+  session: IAgentJobHostContext,
+  agentType: string,
+): ICommandResult | undefined {
+  const agents = session.listAgentDefinitions();
+  if (agents.some((agent) => agent.name === agentType)) return undefined;
+  return {
+    message: `Unknown agent type: ${agentType}\nAvailable agents: ${agents.map((agent) => agent.name).join(', ')}`,
+    success: false,
+  };
+}
+
+async function spawnAgentJob(
+  session: IAgentJobHostContext,
+  request: IAgentRunRequest,
+): Promise<ICommandResult | { state: ISubagentJobState }> {
+  const invalid = validateAgentType(session, request.agentType);
+  if (invalid) return invalid;
+  try {
+    return { state: await session.spawnAgentJob(request) };
+  } catch (error) {
+    return { message: formatError(error), success: false };
+  }
+}
+
+function executeOpenSwitcher(): ICommandResult {
+  return { message: '', effects: [{ type: 'agent-switcher-requested' }], success: true };
+}
+
+async function executeList(session: IAgentJobHostContext): Promise<ICommandResult> {
+  const agents = session.listAgentDefinitions();
+  const jobs = session.listAgentJobs();
+  const lines = [
+    'Available agents:',
+    ...agents.map((agent) => `  ${agent.name} - ${agent.description}`),
+    '',
+    jobs.length === 0 ? 'No active agent jobs.' : 'Agent jobs:',
+    ...jobs.map((job) => `  ${formatAgentJobLine(job)}`),
+  ];
+  return {
+    message: lines.join('\n'),
+    success: true,
+    data: { agents: agents.length, jobs: jobs.length },
+  };
+}
+
+function formatAgentJobLine(job: ISubagentJobState): string {
+  const worktree = [
+    job.worktreePath ? `worktree=${job.worktreePath}` : undefined,
+    job.branchName ? `branch=${job.branchName}` : undefined,
+  ].filter((segment): segment is string => segment !== undefined);
+  const metadata = worktree.length > 0 ? ` ${worktree.join(' ')}` : '';
+  return `${job.id} [${job.status}${metadata}] ${job.label} - ${job.promptPreview}`;
+}
+
+async function executeRun(
+  session: IAgentJobHostContext,
+  tokens: readonly string[],
+): Promise<ICommandResult> {
+  const request = parseRunRequest(tokens, getAvailableAgentNames(session));
+  if (!request) {
+    return {
+      message: 'Usage: agent run [AGENT_NAME] [--agent AGENT_NAME] PROMPT',
+      success: false,
+    };
+  }
+
+  const spawned = await spawnAgentJob(session, request);
+  if ('success' in spawned) return spawned;
+  const { state } = spawned;
+
+  return {
+    message: `Started agent job: ${state.id}`,
+    success: true,
+    data: { agentId: state.id, status: state.status },
+  };
+}
+
+async function executeParallel(
+  session: IAgentJobHostContext,
+  tokens: readonly string[],
+): Promise<ICommandResult> {
+  const wait = tokens.includes('--wait') || !tokens.includes('--detach');
+  const commandTokens = tokens.filter((token) => token !== '--wait' && token !== '--detach');
+  const jobs = parseParallelRequests(commandTokens, getAvailableAgentNames(session));
+
+  if (jobs.length === 0) {
+    return {
+      message: 'Usage: agent parallel [--wait|--detach] LABEL:"PROMPT" [LABEL=AGENT_NAME:"PROMPT"]',
+      success: false,
+    };
+  }
+
+  const invalid = jobs
+    .map((job) => validateAgentType(session, job.agentType))
+    .find((result): result is ICommandResult => result !== undefined);
+  if (invalid) return invalid;
+
+  let states: ISubagentJobState[];
+  try {
+    states = await Promise.all(jobs.map((job) => session.spawnAgentJob(job)));
+  } catch (error) {
+    return { message: formatError(error), success: false };
+  }
+  const group = session.createBackgroundJobGroup({
+    waitPolicy: 'wait_all',
+    taskIds: states.map((state) => state.id),
+    label: 'agent parallel',
+  });
+
+  if (wait) {
+    const completed = await session.waitBackgroundJobGroup(group.id);
+    const summary = summarizeBackgroundJobGroup(completed);
+    return {
+      message: formatGroupSummary(summary),
+      success: true,
+      data: { agentIds: states.map((state) => state.id), groupId: group.id, summary },
+    };
+  }
+
+  return {
+    message: ['Started agent jobs:', ...states.map((state) => `${state.label}: ${state.id}`)].join(
+      '\n',
+    ),
+    success: true,
+    data: { agentIds: states.map((state) => state.id), groupId: group.id },
+  };
+}
+
+async function executeWait(
+  session: IAgentJobHostContext,
+  tokens: readonly string[],
+): Promise<ICommandResult> {
+  const [groupId] = tokens;
+  if (!groupId) return { message: 'Usage: agent wait GROUP_ID', success: false };
+  const completed = await session.waitBackgroundJobGroup(groupId);
+  const summary = summarizeBackgroundJobGroup(completed);
+  return {
+    message: formatGroupSummary(summary),
+    success: true,
+    data: { groupId, summary },
+  };
+}
+
+async function executeRead(
+  session: IAgentJobHostContext,
+  tokens: readonly string[],
+): Promise<ICommandResult> {
+  const [agentId, offset] = tokens;
+  if (!agentId) return { message: 'Usage: agent read AGENT_ID [OFFSET]', success: false };
+  const cursor = offset ? { offset: Number.parseInt(offset, 10) } : undefined;
+  const page = await session.readBackgroundTaskLog(agentId, cursor);
+  const next = page.nextCursor ? `\nNext offset: ${page.nextCursor.offset}` : '';
+  return {
+    message: page.lines.length > 0 ? `${page.lines.join('\n')}${next}` : `No log lines: ${agentId}`,
+    success: true,
+    data: { agentId, nextOffset: page.nextCursor?.offset },
+  };
+}
+
+async function executeSend(
+  session: IAgentJobHostContext,
+  tokens: readonly string[],
+): Promise<ICommandResult> {
+  const [agentId, ...promptParts] = tokens;
+  const prompt = promptParts.join(' ').trim();
+  if (!agentId || !prompt) {
+    return { message: 'Usage: agent send AGENT_ID PROMPT', success: false };
+  }
+  await session.sendAgentJob(agentId, prompt);
+  return { message: `Sent input to agent job: ${agentId}`, success: true, data: { agentId } };
+}
+
+async function executeStop(
+  session: IAgentJobHostContext,
+  tokens: readonly string[],
+): Promise<ICommandResult> {
+  const [agentId, ...reasonParts] = tokens;
+  if (!agentId) return { message: 'Usage: agent stop AGENT_ID [REASON]', success: false };
+  await session.cancelAgentJob(agentId, reasonParts.join(' ') || undefined);
+  return { message: `Agent job stopped: ${agentId}`, success: true, data: { agentId } };
+}
+
+async function executeClose(
+  session: IAgentJobHostContext,
+  tokens: readonly string[],
+): Promise<ICommandResult> {
+  const [agentId] = tokens;
+  if (!agentId) return { message: 'Usage: agent close AGENT_ID', success: false };
+  await session.closeAgentJob(agentId);
+  return { message: `Agent job closed: ${agentId}`, success: true, data: { agentId } };
+}
+
+export async function executeAgentCommand(
+  session: IAgentJobHostContext,
+  args: string,
+): Promise<ICommandResult> {
+  try {
+    if (args.trim() === '') return executeOpenSwitcher();
+    const [action = 'list', ...tokens] = tokenizeArgs(args);
+    if (action === 'list' && tokens.length === 0) return executeList(session);
+    if (action === 'run') return executeRun(session, tokens);
+    if (action === 'parallel') return executeParallel(session, tokens);
+    if (action === 'wait') return executeWait(session, tokens);
+    if (action === 'read' || action === 'open') return executeRead(session, tokens);
+    if (action === 'send') return executeSend(session, tokens);
+    if (action === 'stop' || action === 'cancel') return executeStop(session, tokens);
+    if (action === 'close') return executeClose(session, tokens);
+    return executeRun(session, [action, ...tokens]);
+  } catch (error) {
+    return { message: formatError(error), success: false };
+  }
+}
+
+function formatGroupSummary(summary: ReturnType<typeof summarizeBackgroundJobGroup>): string {
+  const header = `Background job group ${summary.groupId}: ${summary.status} (${summary.completed}/${summary.total} completed, ${summary.failed} failed, ${summary.cancelled} cancelled, ${summary.pending} pending)`;
+  return [header, ...summary.lines].join('\n');
+}

package/src/agent/index.ts

@@ -0,0 +1,7 @@
+export {
+  AgentCommandSource,
+  createAgentCommandEntry,
+  createAgentCommandModule,
+  createAgentSystemCommand,
+} from './agent-command-module.js';
+export { executeAgentCommand } from './agent-command.js';

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

@@ -0,0 +1,255 @@
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  IBackgroundTaskState,
+  ICommandHostContext,
+  ICommandSessionRuntime,
+} from '@robota-sdk/agent-framework';
+import {
+  BackgroundCommandSource,
+  createBackgroundCommandEntry,
+  createBackgroundCommandModule,
+  executeBackgroundCommand,
+} from '../index.js';
+
+function createSessionRuntime(): 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 createTask(overrides?: Partial<IBackgroundTaskState>): IBackgroundTaskState {
+  return {
+    id: 'agent_1',
+    kind: 'agent',
+    label: 'Explore',
+    status: 'running',
+    mode: 'background',
+    parentSessionId: 'session_parent',
+    depth: 1,
+    cwd: '/workspace',
+    updatedAt: '2026-04-30T00:00:00.000Z',
+    lastActivityAt: '2026-04-30T00:00:01.000Z',
+    unread: false,
+    promptPreview: 'Find files',
+    ...overrides,
+  };
+}
+
+function createCommandHostContext(overrides?: Partial<ICommandHostContext>): ICommandHostContext {
+  return {
+    getSession: () => createSessionRuntime(),
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getAutoCompactThreshold: () => 0.8,
+    compactContext: async () => undefined,
+    getCwd: () => '/workspace',
+    listEditCheckpoints: () => [],
+    restoreEditCheckpoint: async () => ({
+      target: {
+        id: 'checkpoint_1',
+        sessionId: 'session_1',
+        sequence: 1,
+        prompt: 'edit',
+        createdAt: '2026-05-03T00:00:00.000Z',
+        fileCount: 0,
+      },
+      restoredCheckpointCount: 1,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    rollbackEditCheckpoint: async () => ({
+      target: {
+        id: 'checkpoint_1',
+        sessionId: 'session_1',
+        sequence: 1,
+        prompt: 'edit',
+        createdAt: '2026-05-03T00:00:00.000Z',
+        fileCount: 0,
+      },
+      restoredCheckpointCount: 1,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: () => undefined,
+    listBackgroundTasks: () => [],
+    readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+    cancelBackgroundTask: async () => undefined,
+    closeBackgroundTask: async () => undefined,
+    ...overrides,
+  };
+}
+
+describe('background command module', () => {
+  it('provides command metadata and executable registration from one module', () => {
+    const entry = createBackgroundCommandEntry();
+    const module = createBackgroundCommandModule();
+
+    expect(entry).toMatchObject({
+      name: 'background',
+      description: 'List and control background tasks',
+      source: 'background',
+      modelInvocable: false,
+    });
+    expect(entry.subcommands?.map((command) => command.name)).toEqual([
+      'list',
+      'read',
+      'cancel',
+      'close',
+    ]);
+    expect(new BackgroundCommandSource().getCommands()).toEqual([entry]);
+    expect(module.systemCommands?.map((command) => command.name)).toEqual(['background']);
+    expect(module.commandSources?.flatMap((source) => source.getCommands())).toEqual([entry]);
+  });
+
+  it('lists background tasks', async () => {
+    const context = createCommandHostContext({
+      listBackgroundTasks: vi.fn().mockReturnValue([createTask()]),
+    });
+
+    const result = await executeBackgroundCommand(context, 'list');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain(
+      'agent_1 [running lastActivityAt=2026-04-30T00:00:01.000Z] agent:Explore',
+    );
+    expect(result.message).toContain('Find files');
+    expect(result.data?.count).toBe(1);
+  });
+
+  it('lists preserved worktree handoff metadata', async () => {
+    const context = createCommandHostContext({
+      listBackgroundTasks: vi.fn().mockReturnValue([
+        createTask({
+          status: 'completed',
+          worktreePath: '/workspace/.robota/worktrees/agent_1',
+          branchName: 'robota/agent_1',
+          worktreeStatus: ' M changed.ts\n?? new.ts',
+          worktreeNextAction: 'Review /workspace/.robota/worktrees/agent_1.',
+        }),
+      ]),
+    });
+
+    const result = await executeBackgroundCommand(context, 'list');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('worktree=/workspace/.robota/worktrees/agent_1');
+    expect(result.message).toContain('branch=robota/agent_1');
+    expect(result.message).toContain('worktreeStatus="M changed.ts ?? new.ts"');
+    expect(result.message).toContain('next="Review /workspace/.robota/worktrees/agent_1."');
+  });
+
+  it('defaults to list when no action is provided', async () => {
+    const context = createCommandHostContext({
+      listBackgroundTasks: vi.fn().mockReturnValue([]),
+    });
+
+    const result = await executeBackgroundCommand(context, '');
+
+    expect(result).toEqual({
+      message: 'No background tasks.',
+      success: true,
+      data: { count: 0 },
+    });
+  });
+
+  it('reads a background task log page with cursor parsing', async () => {
+    const readBackgroundTaskLog = vi.fn().mockResolvedValue({
+      taskId: 'process_1',
+      nextCursor: { offset: 200 },
+      lines: ['[stdout] hello'],
+    });
+    const context = createCommandHostContext({ readBackgroundTaskLog });
+
+    const result = await executeBackgroundCommand(context, 'read process_1 0');
+
+    expect(readBackgroundTaskLog).toHaveBeenCalledWith('process_1', { offset: 0 });
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('[stdout] hello');
+    expect(result.message).toContain('Next offset: 200');
+    expect(result.data).toEqual({ taskId: 'process_1', nextOffset: 200 });
+  });
+
+  it('supports read aliases and omits invalid cursors', async () => {
+    const readBackgroundTaskLog = vi.fn().mockResolvedValue({
+      taskId: 'process_1',
+      lines: [],
+    });
+    const context = createCommandHostContext({ readBackgroundTaskLog });
+
+    const result = await executeBackgroundCommand(context, 'open process_1 nope');
+
+    expect(readBackgroundTaskLog).toHaveBeenCalledWith('process_1', undefined);
+    expect(result.message).toBe('No log lines: process_1');
+  });
+
+  it('cancels a background task with optional reason', async () => {
+    const cancelBackgroundTask = vi.fn().mockResolvedValue(undefined);
+    const context = createCommandHostContext({ cancelBackgroundTask });
+
+    const result = await executeBackgroundCommand(context, 'cancel agent_1 no longer needed');
+
+    expect(cancelBackgroundTask).toHaveBeenCalledWith('agent_1', 'no longer needed');
+    expect(result).toEqual({
+      message: 'Background task cancelled: agent_1',
+      success: true,
+      data: { taskId: 'agent_1' },
+    });
+  });
+
+  it('supports cancel aliases without a reason', async () => {
+    const cancelBackgroundTask = vi.fn().mockResolvedValue(undefined);
+    const context = createCommandHostContext({ cancelBackgroundTask });
+
+    await executeBackgroundCommand(context, 'stop agent_1');
+
+    expect(cancelBackgroundTask).toHaveBeenCalledWith('agent_1', undefined);
+  });
+
+  it('closes a background task', async () => {
+    const closeBackgroundTask = vi.fn().mockResolvedValue(undefined);
+    const context = createCommandHostContext({ closeBackgroundTask });
+
+    const result = await executeBackgroundCommand(context, 'dismiss agent_1');
+
+    expect(closeBackgroundTask).toHaveBeenCalledWith('agent_1');
+    expect(result).toEqual({
+      message: 'Background task closed: agent_1',
+      success: true,
+      data: { taskId: 'agent_1' },
+    });
+  });
+
+  it('returns usage when a task action omits task id', async () => {
+    const result = await executeBackgroundCommand(createCommandHostContext(), 'cancel');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('Usage: background list');
+  });
+
+  it('rejects unknown actions', async () => {
+    const result = await executeBackgroundCommand(createCommandHostContext(), 'pause agent_1');
+
+    expect(result).toEqual({
+      message: 'Unknown background action: pause',
+      success: false,
+    });
+  });
+});