@robota-sdk/agent-command 3.0.0-beta.78 → 3.0.0-beta.81

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

@@ -6,10 +6,15 @@ import {
   createBackgroundCommandModule,
   executeBackgroundCommand,
 } from '../index.js';
-import type { IBackgroundTaskState } from '@robota-sdk/agent-interface-transport';
+import type { IBackgroundTaskState } from '@robota-sdk/agent-interface-execution';
+import { createTestSessionRuntime } from '@robota-sdk/agent-framework/testing';
+import {
+  createTestCommandHost,
+  type ICreateTestCommandHostOptions,
+} from '@robota-sdk/agent-framework/testing';
 
-function createSessionRuntime(): ICommandSessionRuntime {
-  return {
+function createSessionRuntime() {
+  return createTestSessionRuntime({
     clearHistory: () => undefined,
     compact: async () => undefined,
     getContextState: () => ({
@@ -26,10 +31,10 @@ function createSessionRuntime(): ICommandSessionRuntime {
     getAutoCompactThreshold: () => false,
     getFullHistory: () => [],
     getHistory: () => [],
-  };
+  });
 }
 
-function createTask(overrides?: Partial<IBackgroundTaskState>): IBackgroundTaskState {
+function createTask(overrides?: Partial<IBackgroundTaskState<'agent'>>): IBackgroundTaskState {
   return {
     id: 'agent_1',
     kind: 'agent',
@@ -47,53 +52,55 @@ function createTask(overrides?: Partial<IBackgroundTaskState>): IBackgroundTaskS
   };
 }
 
-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,
-  };
+function createCommandHostContext(overrides?: ICreateTestCommandHostOptions['overrides']) {
+  return createTestCommandHost({
+    overrides: {
+      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', () => {

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

@@ -6,7 +6,7 @@ import {
 import { executeBackgroundCommand } from './background-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createBackgroundCommandEntry(): ICommand {
   return {
@@ -14,6 +14,7 @@ export function createBackgroundCommandEntry(): ICommand {
     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(),
   };

package/src/background/background-command.ts

@@ -8,15 +8,15 @@ import {
   readCommandBackgroundTaskLog,
 } from '@robota-sdk/agent-framework';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+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: ICommandHostContext,
+  context: ICommandHostBackgroundTasks,
   args: string,
 ): Promise<ICommandResult> {
   const [action = 'list', taskId, ...reasonParts] = parseCommandParts(args);

package/src/command-module-utils.ts

@@ -0,0 +1,33 @@
+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 } : {}),
+    ...(behavior.semanticRole !== undefined ? { semanticRole: behavior.semanticRole } : {}),
+    lifecycle: behavior.lifecycle,
+    requiresPermission: behavior.requiresPermission,
+    execute: behavior.execute,
+  };
+}

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

@@ -2,8 +2,13 @@ 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<ICommandHostContext['getContextState']>;
+type TContextWindowState = ReturnType<ICommandHostContextWindow['getContextState']>;
 type TPermissionMode = ReturnType<ICommandSessionRuntime['getPermissionMode']>;
 
 const BEFORE_CONTEXT: TContextWindowState = {
@@ -20,10 +25,10 @@ const AFTER_CONTEXT: TContextWindowState = {
   remainingPercentage: 65,
 };
 
-function createRuntime(beforeCount = 10, afterCount = 3): ICommandSessionRuntime {
+function createRuntime(beforeCount = 10, afterCount = 3) {
   let mode: TPermissionMode = 'default';
   const getMessageCount = vi.fn().mockReturnValueOnce(beforeCount).mockReturnValue(afterCount);
-  return {
+  return createTestSessionRuntime({
     clearHistory: vi.fn(),
     compact: vi.fn().mockResolvedValue(undefined),
     getContextState: vi.fn().mockReturnValue(AFTER_CONTEXT),
@@ -37,10 +42,10 @@ function createRuntime(beforeCount = 10, afterCount = 3): ICommandSessionRuntime
     getAutoCompactThreshold: () => 0.835,
     getFullHistory: () => [],
     getHistory: () => [],
-  };
+  });
 }
 
-function createCommandHostContext(): ICommandHostContext & {
+function createCommandHostContext(): ReturnType<typeof createTestCommandHost> & {
   compactContext: ReturnType<typeof vi.fn>;
 } {
   const runtime = createRuntime();
@@ -48,23 +53,25 @@ function createCommandHostContext(): ICommandHostContext & {
     .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(),
-  };
+  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', () => {
@@ -86,6 +93,7 @@ describe('createCompactCommandModule', () => {
     expect(command).toEqual(
       expect.objectContaining({
         name: 'compact',
+        semanticRole: 'contextReduction',
         lifecycle: 'blocking',
         modelInvocable: true,
         safety: 'write',
@@ -102,7 +110,7 @@ describe('createCompactCommandModule', () => {
       {
         name: 'compact',
         kind: 'builtin-command',
-        description: 'Compress context window',
+        description: expect.stringContaining('Summarize older conversation turns'),
         userInvocable: true,
         modelInvocable: true,
         argumentHint: '[instructions]',

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

@@ -1,13 +1,20 @@
 import { executeCompactCommand } from './compact-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+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]',
@@ -20,8 +27,10 @@ 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,

package/src/compact/compact-command.ts

@@ -1,7 +1,10 @@
 import { compactCommandContext } from '@robota-sdk/agent-framework';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+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();
@@ -9,7 +12,7 @@ function parseInstructions(args: string): string | undefined {
 }
 
 export async function executeCompactCommand(
-  context: ICommandHostContext,
+  context: ICommandHostContextWindow & ICommandHostSessionAccess,
   args: string,
 ): Promise<ICommandResult> {
   const result = await compactCommandContext(context, parseInstructions(args));