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

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

@@ -0,0 +1,589 @@
+import { describe, expect, it, vi } from 'vitest';
+import { calculateModelCost } from '@robota-sdk/agent-core';
+import type {
+  ICommandCostBudget,
+  ICommandCostBudgetAdapter,
+  ICommandHostContext,
+  ICommandSessionRuntime,
+  ISessionUsageRecord,
+} from '@robota-sdk/agent-framework';
+import { InteractiveSession, SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createSessionCommandModule } from '../session-command-module.js';
+import {
+  createTestCommandHost,
+  createTestSessionRuntime,
+} from '@robota-sdk/agent-framework/testing';
+
+function createRuntime() {
+  return createTestSessionRuntime({
+    clearHistory: vi.fn(),
+    compact: async () => undefined,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 0,
+      usedPercentage: 0,
+      remainingPercentage: 100,
+    }),
+    getPermissionMode: () => 'default',
+    setPermissionMode: () => undefined,
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 5,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
+    getHistory: () => [],
+  });
+}
+
+function createCommandContext() {
+  const runtime = createRuntime();
+  return createTestCommandHost({
+    overrides: {
+      getSession: () => runtime,
+      getContextState: () => runtime.getContextState(),
+      getAutoCompactThreshold: () => 0.835,
+      compactContext: async () => undefined,
+      getCwd: () => '/workspace',
+      listEditCheckpoints: () => [],
+      restoreEditCheckpoint: async () => {
+        throw new Error('not used');
+      },
+      rollbackEditCheckpoint: async () => {
+        throw new Error('not used');
+      },
+      getUsedMemoryReferences: () => [],
+      recordMemoryEvent: () => undefined,
+      listBackgroundTasks: () => [],
+      readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+      cancelBackgroundTask: async () => undefined,
+      closeBackgroundTask: async () => undefined,
+    },
+  });
+}
+
+describe('createSessionCommandModule', () => {
+  it('provides clear metadata and user-only executable command from one module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'clear');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'clear');
+
+    expect(module.name).toBe('agent-command-session');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'clear',
+        description: 'Clear conversation history',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'clear',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('provides rename metadata and user-only executable command from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'rename');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'rename');
+
+    expect(module.commandSources?.[0]?.getCommands().map((item) => item.name)).toEqual([
+      'clear',
+      'rename',
+      'cd',
+      'resume',
+      'cost',
+      'validate-session',
+    ]);
+    expect(module.systemCommands?.map((item) => item.name)).toEqual([
+      'clear',
+      'rename',
+      'cd',
+      'resume',
+      'cost',
+      'validate-session',
+    ]);
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'rename',
+        description: 'Rename the current session',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'rename',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+    expect(entry?.argumentHint).toBe('<name>');
+    expect(command?.argumentHint).toBe(entry?.argumentHint);
+  });
+
+  it('provides resume metadata and user-only executable command from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'resume');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'resume');
+
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'resume',
+        description: 'Resume a previous session',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'resume',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('provides cost metadata and a model-invocable report with a user-only budget from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'cost');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'cost');
+
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'cost',
+        description: expect.stringContaining('token usage'),
+        source: 'session',
+        modelInvocable: true,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'cost',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: true,
+      }),
+    );
+    expect(entry?.argumentHint).toBe('[budget [<amount>|clear]]');
+    expect(command?.argumentHint).toBe(entry?.argumentHint);
+    expect(entry?.subcommands).toEqual([
+      expect.objectContaining({ name: 'budget', modelInvocable: false }),
+    ]);
+    expect(command?.subcommands).toEqual(entry?.subcommands);
+  });
+
+  it('provides validate-session metadata and user-only executable command from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'validate-session');
+    const entry = module.commandSources?.[0]
+      ?.getCommands()
+      .find((item) => item.name === 'validate-session');
+
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'validate-session',
+        description: 'Validate current session replay log',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'validate-session',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('clears conversation history through the session command API', async () => {
+    const clearConversationHistory = vi.fn();
+    const context = {
+      ...createCommandContext(),
+      clearConversationHistory,
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(clearConversationHistory).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({
+      success: true,
+      message: 'Conversation cleared.',
+    });
+  });
+
+  it('CMD-004: confirms before clearing and proceeds on yes', async () => {
+    const clearConversationHistory = vi.fn();
+    const context = {
+      ...createCommandContext(),
+      clearConversationHistory,
+      getUserInteraction: () => ({
+        ask: async () => ({ type: 'answer' as const, values: ['yes'] }),
+      }),
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(clearConversationHistory).toHaveBeenCalledTimes(1);
+    expect(result?.success).toBe(true);
+  });
+
+  it('CMD-004: cancels the clear when the user declines', async () => {
+    const clearConversationHistory = vi.fn();
+    const context = {
+      ...createCommandContext(),
+      clearConversationHistory,
+      getUserInteraction: () => ({
+        ask: async () => ({ type: 'answer' as const, values: ['no'] }),
+      }),
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(clearConversationHistory).not.toHaveBeenCalled();
+    expect(result?.message).toBe('Clear cancelled.');
+  });
+
+  it('ARCH-029 TC-09: /clear takes the host path only — it never reaches past it into the runtime', async () => {
+    // The deleted fallback called `getSession().clearHistory()` when the host member was absent.
+    // Those are not the same operation: the host's clear also broadcasts `history_cleared` to
+    // every attached surface (CMD-004 Stage E), so the fallback cleared ONE surface and left the
+    // others still showing the transcript. With the member required there is one path, and this
+    // pins that the runtime is not reached behind the host's back.
+    const runtime = createRuntime();
+    const clearConversationHistory = vi.fn();
+    const context = {
+      ...createCommandContext(),
+      getSession: () => runtime,
+      clearConversationHistory,
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(clearConversationHistory).toHaveBeenCalledTimes(1);
+    expect(runtime.clearHistory).not.toHaveBeenCalled();
+    expect(result?.success).toBe(true);
+  });
+
+  it('clears InteractiveSession history when executed through a composed session', async () => {
+    const clearHistory = vi.fn();
+    const runtime = {
+      ...createRuntime(),
+      clearHistory,
+      run: vi.fn().mockResolvedValue('answer'),
+      abort: vi.fn(),
+      assertInputAllowed: vi.fn(),
+      getHistory: vi.fn().mockReturnValue([]),
+      injectMessage: vi.fn(),
+      getSystemMessage: vi.fn().mockReturnValue('system'),
+      getToolSchemas: vi.fn().mockReturnValue([]),
+      // SELFHOST-004 P6: the span collector subscribes to the session bus each turn.
+      getEventService: () => ({ subscribe: () => {}, unsubscribe: () => {} }),
+    };
+    const session = new InteractiveSession({
+      session: runtime as never,
+      commandModules: [createSessionCommandModule()],
+    });
+    await session.submit('hello');
+    expect(session.getFullHistory().length).toBeGreaterThan(0);
+
+    const result = await session.executeCommand('clear', '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Conversation cleared.',
+    });
+    expect(clearHistory).toHaveBeenCalledTimes(1);
+    expect(session.getFullHistory()).toEqual([]);
+  });
+
+  it('renames the current session through a typed host effect', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('rename', createCommandContext(), ' my-session ');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Session renamed to "my-session".',
+      data: { name: 'my-session' },
+      hostActions: [{ type: 'session-rename', name: 'my-session' }],
+    });
+  });
+
+  it('returns usage when rename is missing a session name', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('rename', createCommandContext(), '  ');
+
+    expect(result).toEqual({
+      success: false,
+      message: 'Usage: rename <name>',
+    });
+  });
+
+  it('requests the host session picker through a typed effect', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('resume', createCommandContext(), '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Opening session picker...',
+      data: { triggerResumePicker: true },
+      uiIntents: [{ type: 'show-session-picker' }],
+    });
+  });
+
+  it('shows session info through the session command API (no token data yet)', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('cost', createCommandContext(), '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('session_1');
+    expect(result?.message).toContain('Messages: 5');
+    expect(result?.message).toContain('not yet available');
+  });
+
+  function costContext(records: readonly ISessionUsageRecord[], modelId = 'claude-sonnet-4-5') {
+    const runtime = { ...createRuntime(), getModelId: () => modelId };
+    return { ...createCommandContext(), getSession: () => runtime, getSessionUsage: () => records };
+  }
+
+  async function cost(records: readonly ISessionUsageRecord[], modelId?: string) {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+    return executor.execute('cost', costContext(records, modelId), '');
+  }
+
+  const advisorRecord: ISessionUsageRecord = {
+    promptTokens: 5_000,
+    completionTokens: 2_000,
+    costUsd: 1.5,
+    source: { scope: 'tool', id: 'advisor:big-model', label: 'Advisor (big-model)' },
+  };
+
+  it('shows token counts and estimated cost when session has usage data', async () => {
+    const result = await cost([{ promptTokens: 45_000, completionTokens: 12_000 }]);
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('45,000');
+    expect(result?.message).toContain('12,000');
+    expect(result?.message).toContain('$');
+    expect((result?.data as Record<string, unknown>)?.inputTokens).toBe(45_000);
+    expect((result?.data as Record<string, unknown>)?.outputTokens).toBe(12_000);
+    expect((result?.data as Record<string, unknown>)?.estimatedCostUsd).toBeDefined();
+  });
+
+  it('totals main and advisor usage, pricing the advisor on its own model', async () => {
+    const own = calculateModelCost('claude-sonnet-4-5', 40_000, 10_000)!;
+    const result = await cost([{ promptTokens: 40_000, completionTokens: 10_000 }, advisorRecord]);
+    const data = result?.data as Record<string, unknown>;
+
+    expect(data.inputTokens).toBe(45_000);
+    expect(data.outputTokens).toBe(12_000);
+    expect(data.estimatedCostUsd).toBeCloseTo(own + 1.5, 10);
+    expect(result?.message).toContain('mixed: claude-sonnet-4-5, Advisor (big-model)');
+  });
+
+  it('keeps the advisor price when the main model has none, and says the total is partial', async () => {
+    const result = await cost(
+      [{ promptTokens: 40_000, completionTokens: 10_000 }, advisorRecord],
+      'unpriced-model',
+    );
+    const data = result?.data as Record<string, unknown>;
+    expect(data.estimatedCostUsd).toBe(1.5);
+    expect(data.costPartial).toBe(true);
+    expect(result?.message).toContain('some usage could not be priced');
+  });
+
+  it('does not price an unpriced advisor model at the main model rate', async () => {
+    const own = calculateModelCost('claude-sonnet-4-5', 40_000, 10_000)!;
+    const { costUsd: _price, ...unpricedAdvisor } = advisorRecord;
+    const result = await cost([
+      { promptTokens: 40_000, completionTokens: 10_000 },
+      unpricedAdvisor,
+    ]);
+    const data = result?.data as Record<string, unknown>;
+    expect(data.estimatedCostUsd).toBeCloseTo(own, 10);
+    expect(data.costPartial).toBe(true);
+  });
+
+  /**
+   * CMD-007 (issue #2058): the command talks to an injected `ICommandCostBudgetAdapter` and never to
+   * the filesystem — so the tests hold the budget in memory, with no casts and no temp directory.
+   * The file adapter's own policy (atomic write, symlink refusal) is tested where it lives, in agent-cli.
+   */
+  function memoryBudgetAdapter(initial?: ICommandCostBudget): ICommandCostBudgetAdapter & {
+    writes: string[];
+  } {
+    let stored = initial;
+    const adapter = {
+      writes: [] as string[],
+      read: () => stored,
+      write: (budget: ICommandCostBudget) => {
+        adapter.writes.push(`write:${budget.monthly}`);
+        stored = budget;
+      },
+      clear: () => {
+        adapter.writes.push('clear');
+        stored = undefined;
+      },
+    };
+    return adapter;
+  }
+
+  function budgetContext(adapter: ICommandCostBudgetAdapter | undefined) {
+    return {
+      ...createCommandContext(),
+      getCommandHostAdapters: () => (adapter ? { costBudget: adapter } : {}),
+    };
+  }
+
+  it('sets a monthly budget via /cost budget subcommand through the injected adapter', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+    const adapter = memoryBudgetAdapter();
+
+    const result = await executor.execute('cost', budgetContext(adapter), 'budget 5.00');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('$5.00');
+    expect(adapter.read()).toEqual({ monthly: 5 });
+  });
+
+  it('reads back a persisted budget and clears it through the adapter (set → restart → read)', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+    // "restart": a fresh context over the same stored document
+    const adapter = memoryBudgetAdapter({ monthly: 5 });
+    const shown = await executor.execute('cost', budgetContext(adapter), 'budget');
+    expect(shown?.message).toContain('Monthly budget: $5.00');
+
+    const cleared = await executor.execute('cost', budgetContext(adapter), 'budget clear');
+    expect(cleared?.success).toBe(true);
+    expect(adapter.writes).toEqual(['clear']);
+    const after = await executor.execute('cost', budgetContext(adapter), 'budget');
+    expect(after?.message).toContain('No budget set');
+  });
+
+  it("surfaces the adapter's typed write failure instead of a filesystem error", async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+    const refusing: ICommandCostBudgetAdapter = {
+      read: () => undefined,
+      write: () => {
+        throw new Error('Refused: budget.json is a symbolic link');
+      },
+      clear: () => {
+        throw new Error('Refused: budget.json is a symbolic link');
+      },
+    };
+    for (const args of ['budget clear', 'budget 5.00']) {
+      const result = await executor.execute('cost', budgetContext(refusing), args);
+      expect(result?.success).toBe(false);
+      expect(result?.message).toContain('symbolic link');
+    }
+  });
+
+  it('says budget persistence is unavailable when the host composed no adapter', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+    const result = await executor.execute('cost', budgetContext(undefined), 'budget 5.00');
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('not available');
+  });
+
+  it('rejects invalid budget amount', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('cost', createCommandContext(), 'budget notanumber');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('Usage:');
+  });
+
+  it('validates the current session replay log through the SDK common API', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+    const context = {
+      ...createCommandContext(),
+      validateCurrentSessionReplayLog: () => ({
+        logFile: '/workspace/.fixture-state/logs/session_1.jsonl',
+        entryCount: 2,
+        validation: {
+          ok: false,
+          issues: [
+            {
+              code: 'PROVIDER_NATIVE_RAW_PAYLOAD_MISSING' as const,
+              message: 'Provider request exec-1:1 has no provider-native payload.',
+              executionId: 'exec-1',
+              round: 1,
+            },
+          ],
+        },
+      }),
+    };
+
+    const result = await executor.execute('validate-session', context, '');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('PROVIDER_NATIVE_RAW_PAYLOAD_MISSING');
+    expect(result?.data).toEqual({
+      logFile: '/workspace/.fixture-state/logs/session_1.jsonl',
+      entryCount: 2,
+      issueCount: 1,
+      ok: false,
+    });
+  });
+});
+
+describe('/cd (issue #3081)', () => {
+  it('requests the host-executed move with the path as typed, and is user-only', async () => {
+    const module = createSessionCommandModule();
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'cd');
+    const command = module.systemCommands?.find((item) => item.name === 'cd');
+    expect(entry?.modelInvocable).toBe(false);
+    expect(entry?.userInvocable).toBe(true);
+    const result = await command!.execute({} as never, ' ../api ');
+    expect(result.hostActions).toEqual([{ type: 'workspace-move', path: '../api' }]);
+    const usage = await command!.execute({} as never, '   ');
+    expect(usage.success).toBe(false);
+  });
+});

package/src/session/index.ts

@@ -0,0 +1,17 @@
+export {
+  executeClearCommand,
+  executeCostCommand,
+  executeRenameCommand,
+  executeResumeCommand,
+  executeValidateSessionCommand,
+  CLEAR_COMMAND_MESSAGE,
+} from './session-command.js';
+export {
+  SessionCommandSource,
+  createClearCommandEntry,
+  createCostCommandEntry,
+  createRenameCommandEntry,
+  createResumeCommandEntry,
+  createSessionCommandModule,
+  createValidateSessionCommandEntry,
+} from './session-command-module.js';

package/src/session/model-pricing.ts

@@ -0,0 +1,26 @@
+import { calculateModelCost } from '@robota-sdk/agent-core';
+
+/**
+ * Returns USD cost, or undefined if the model is not in the pricing table.
+ * Delegates to the agent-core pricing SSOT (`calculateModelCost`); this package owns only the
+ * command-facing display helpers below.
+ */
+export function calculateCost(
+  modelId: string,
+  inputTokens: number,
+  outputTokens: number,
+): number | undefined {
+  return calculateModelCost(modelId, inputTokens, outputTokens);
+}
+
+/** Format a USD amount for display (e.g. "$0.0043"). */
+export function formatUsd(amount: number): string {
+  if (amount < 0.01) return `$${amount.toFixed(4)}`;
+  if (amount < 1) return `$${amount.toFixed(3)}`;
+  return `$${amount.toFixed(2)}`;
+}
+
+/** Format a token count with comma separators (e.g. "45,000"). */
+export function formatTokens(count: number): string {
+  return count.toLocaleString('en-US');
+}