@robota-sdk/agent-command 3.0.0-beta.86 → 3.0.0-beta.88

package/src/rewind/rewind-command.ts

@@ -15,8 +15,13 @@ import type {
   IEditCheckpointRestoreResult,
   IEditCheckpointSummary,
 } from '@robota-sdk/agent-framework';
+import type { ICommandProductVocabulary } from '@robota-sdk/agent-framework';
 import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
+type TRewindCommandContext = ICommandHostCheckpoints & {
+  getCommandProductVocabulary?(): ICommandProductVocabulary | undefined;
+};
+
 const SUBCOMMAND_INDEX = 0;
 const CHECKPOINT_ID_INDEX = 1;
 const PROMPT_PREVIEW_LENGTH = 120;
@@ -123,17 +128,18 @@ function formatRollbackResult(result: IEditCheckpointRestoreResult): ICommandRes
 }
 
 /** A restricted workspace is the one case the user fixes with a command; the rest say why. */
-function unavailableMessage(error: EditCheckpointsUnavailableError): string {
-  return error.reason === 'restricted-workspace'
-    ? 'Edit checkpoints need a trusted workspace: run robota trust --yes, then restart robota.'
-    : error.message;
+function unavailableMessage(error: EditCheckpointsUnavailableError, cliName?: string): string {
+  if (error.reason !== 'restricted-workspace') return error.message;
+  return cliName === undefined
+    ? 'Edit checkpoints need a trusted workspace. Trust it from a terminal, then restart the session.'
+    : `Edit checkpoints need a trusted workspace: run ${cliName} trust --yes, then restart ${cliName}.`;
 }
 
-function formatError(error: Error | string): ICommandResult {
+function formatError(error: Error | string, cliName?: string): ICommandResult {
   return {
     message:
       error instanceof EditCheckpointsUnavailableError
-        ? unavailableMessage(error)
+        ? unavailableMessage(error, cliName)
         : error instanceof Error
           ? error.message
           : String(error),
@@ -141,53 +147,53 @@ function formatError(error: Error | string): ICommandResult {
   };
 }
 
-function list(context: ICommandHostCheckpoints): ICommandResult {
+function list(context: TRewindCommandContext): ICommandResult {
   try {
     return formatList(listCommandEditCheckpoints(context));
   } catch (error) {
-    return formatError(error instanceof Error ? error : String(error));
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
   }
 }
 
 function inspect(
-  context: ICommandHostCheckpoints,
+  context: TRewindCommandContext,
   checkpointId: string | undefined,
 ): ICommandResult {
   if (!checkpointId) return usage();
   try {
     return formatInspection(inspectCommandEditCheckpoint(context, checkpointId));
   } catch (error) {
-    return formatError(error instanceof Error ? error : String(error));
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
   }
 }
 
 async function restore(
-  context: ICommandHostCheckpoints,
+  context: TRewindCommandContext,
   checkpointId: string | undefined,
 ): Promise<ICommandResult> {
   if (!checkpointId) return usage();
   try {
     return formatRestoreResult(await restoreCommandEditCheckpoint(context, checkpointId));
   } catch (error) {
-    return formatError(error instanceof Error ? error : String(error));
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
   }
 }
 
 async function rollback(
-  context: ICommandHostCheckpoints,
+  context: TRewindCommandContext,
   checkpointId: string | undefined,
 ): Promise<ICommandResult> {
   if (!checkpointId) return usage();
   try {
     return formatRollbackResult(await rollbackCommandEditCheckpoint(context, checkpointId));
   } catch (error) {
-    return formatError(error instanceof Error ? error : String(error));
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
   }
 }
 
 // SELFHOST-007: branching time-travel handlers.
 async function fork(
-  context: ICommandHostCheckpoints,
+  context: TRewindCommandContext,
   checkpointId: string | undefined,
 ): Promise<ICommandResult> {
   if (!checkpointId) return usage();
@@ -202,12 +208,12 @@ async function fork(
       data: { target: result.target, restoredFileCount: result.restoredFileCount },
     };
   } catch (error) {
-    return formatError(error instanceof Error ? error : String(error));
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
   }
 }
 
 function switchBranch(
-  context: ICommandHostCheckpoints,
+  context: TRewindCommandContext,
   checkpointId: string | undefined,
 ): ICommandResult {
   if (!checkpointId) return usage();
@@ -215,11 +221,11 @@ function switchBranch(
     switchCommandEditCheckpointBranch(context, checkpointId);
     return { message: `Switched to checkpoint branch ${checkpointId}.`, success: true };
   } catch (error) {
-    return formatError(error instanceof Error ? error : String(error));
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
   }
 }
 
-function branches(context: ICommandHostCheckpoints): ICommandResult {
+function branches(context: TRewindCommandContext): ICommandResult {
   try {
     const tips = listCommandEditCheckpointBranches(context);
     return {
@@ -231,12 +237,12 @@ function branches(context: ICommandHostCheckpoints): ICommandResult {
       data: { branches: tips },
     };
   } catch (error) {
-    return formatError(error instanceof Error ? error : String(error));
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
   }
 }
 
 export async function executeRewindCommand(
-  context: ICommandHostCheckpoints,
+  context: TRewindCommandContext,
   rawArgs: string,
 ): Promise<ICommandResult> {
   const args = rawArgs.trim().split(/\s+/).filter(Boolean);

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

@@ -179,6 +179,6 @@ export function createScheduleCommandModule(options: ILoopCommandOptions = {}):
       createMonitorSystemCommand(),
       createLoopSystemCommand(options),
     ],
-    sessionRequirements: ['agent-runtime'],
+    sessionRequirements: ['runtime'],
   };
 }

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

@@ -544,7 +544,7 @@ describe('createSessionCommandModule', () => {
     const context = {
       ...createCommandContext(),
       validateCurrentSessionReplayLog: () => ({
-        logFile: '/workspace/.robota/logs/session_1.jsonl',
+        logFile: '/workspace/.fixture-state/logs/session_1.jsonl',
         entryCount: 2,
         validation: {
           ok: false,
@@ -565,7 +565,7 @@ describe('createSessionCommandModule', () => {
     expect(result?.success).toBe(false);
     expect(result?.message).toContain('PROVIDER_NATIVE_RAW_PAYLOAD_MISSING');
     expect(result?.data).toEqual({
-      logFile: '/workspace/.robota/logs/session_1.jsonl',
+      logFile: '/workspace/.fixture-state/logs/session_1.jsonl',
       entryCount: 2,
       issueCount: 1,
       ok: false,

package/src/skills/__tests__/skill-read-command.test.ts

@@ -0,0 +1,64 @@
+import { expect, it, vi } from 'vitest';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+import { createSkillsCommandModule } from '../skills-command-module.js';
+
+it('offers supporting reads to the model under the composed semantic command identity', async () => {
+  const module = createSkillsCommandModule({ contributionSources: [] });
+  const executor = new SystemCommandExecutor([...(module.systemCommands ?? [])]);
+  expect(executor.getSemanticRoles().skillResourceRead).toBe('skill-read');
+  expect(executor.isModelInvocable('skill-read')).toBe(true);
+  expect(
+    executor.listModelInvocableCommands().find((command) => command.name === 'skill-read')
+      ?.description,
+  ).toContain('already activated');
+  const resource = {
+    uri: 'skill://demo/reference%20file.txt',
+    digest: 'sha256:verified',
+    size: 7,
+    text: 'content',
+  };
+  const readSkillResource = vi.fn(async () => resource);
+  const context = createTestCommandHost({ overrides: { readSkillResource } });
+  const result = await executor.executeModelInvocable(
+    'skill-read',
+    context,
+    JSON.stringify(['demo', resource.uri]),
+  );
+  expect(readSkillResource).toHaveBeenCalledWith('demo', resource.uri);
+  expect(result).toMatchObject({ success: true, data: resource });
+});
+
+it.each(['', '{}', '["demo"]', '["demo", 3]', '["demo", "uri", "extra"]', '["", "uri"]'])(
+  'refuses malformed resource arguments without calling the host: %s',
+  async (args) => {
+    const executor = new SystemCommandExecutor([
+      ...(createSkillsCommandModule({ contributionSources: [] }).systemCommands ?? []),
+    ]);
+    const readSkillResource = vi.fn();
+    const result = await executor.executeModelInvocable(
+      'skill-read',
+      createTestCommandHost({ overrides: { readSkillResource } }),
+      args,
+    );
+    expect(result?.success).toBe(false);
+    expect(readSkillResource).not.toHaveBeenCalled();
+  },
+);
+
+it('reports an unavailable host instead of acquiring a skill or falling back to filesystem reads', async () => {
+  const executor = new SystemCommandExecutor([
+    ...(createSkillsCommandModule({ contributionSources: [] }).systemCommands ?? []),
+  ]);
+  const executeSkillCommandByName = vi.fn();
+  const result = await executor.executeModelInvocable(
+    'skill-read',
+    createTestCommandHost({ overrides: { executeSkillCommandByName } }),
+    '["demo", "skill://demo/file"]',
+  );
+  expect(result).toMatchObject({
+    success: false,
+    message: expect.stringContaining('does not provide'),
+  });
+  expect(executeSkillCommandByName).not.toHaveBeenCalled();
+});

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

@@ -94,6 +94,7 @@ describe('createSkillsCommandModule', () => {
     expect(module.name).toBe('agent-command-skills');
     expect(module.commandSources?.[0]?.getCommands().map((entry) => entry.name)).toEqual([
       'skills',
+      'skill-read',
     ]);
     expect(command).toMatchObject({
       name: 'skills',
@@ -164,7 +165,7 @@ describe('createSkillsCommandModule', () => {
   });
 
   it('lets the SDK normalize virtual /skill-name commands into the composed skills command', async () => {
-    const cwd = realpathSync(mkdtempSync(join(tmpdir(), 'robota-skills-command-module-')));
+    const cwd = realpathSync(mkdtempSync(join(tmpdir(), 'agent-test-skills-command-module-')));
     createTempSkill(cwd);
     const parentSession = makeParentSession();
     const session = new InteractiveSession({

package/src/skills/skill-read-command.ts

@@ -0,0 +1,60 @@
+import type { ICommand, ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { ICommandHostCatalog, ISystemCommand } from '@robota-sdk/agent-framework';
+
+export function createSkillReadCommandEntry(): ICommand {
+  return {
+    name: 'skill-read',
+    description: 'Read a supporting file from a skill active in this execution',
+    modelDescription:
+      'Read verified supporting bytes from a skill already activated in this execution. Use when its instructions refer to a resource in the returned manifest. Args are a JSON array ["<skill-name>", "<resource-uri>"]. Returns the verified URI, digest, size and text or base64 blob with optional MIME type. This does not activate nested skills or grant consent; unactivated skills, undeclared resources and ended executions are refused. Binary blobs are returned as encoded data, not a rendered image.',
+    argumentHint: '["<skill-name>", "<resource-uri>"]',
+    source: 'skills',
+    userInvocable: true,
+    modelInvocable: true,
+    safety: 'read-only',
+  };
+}
+
+export async function executeSkillReadCommand(
+  context: Pick<ICommandHostCatalog, 'readSkillResource'>,
+  args = '',
+): Promise<ICommandResult> {
+  let input: unknown;
+  try {
+    input = JSON.parse(args);
+  } catch {
+    return { success: false, message: 'Use /skill-read ["<skill-name>", "<resource-uri>"]' };
+  }
+  if (
+    !Array.isArray(input) ||
+    input.length !== 2 ||
+    input.some((value) => typeof value !== 'string' || !value.length)
+  )
+    return { success: false, message: 'Use /skill-read ["<skill-name>", "<resource-uri>"]' };
+  if (!context.readSkillResource)
+    return { success: false, message: 'This host does not provide active skill resource reads.' };
+  try {
+    const resource = await context.readSkillResource(input[0], input[1]);
+    return {
+      success: true,
+      message: `Read verified skill resource: ${resource.uri}`,
+      data: { ...resource },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: `Skill resource read refused: ${error instanceof Error ? error.message : 'host refused the read'}`,
+    };
+  }
+}
+
+export function createSkillReadSystemCommand(): ISystemCommand {
+  const entry = createSkillReadCommandEntry();
+  return {
+    ...entry,
+    semanticRole: 'skillResourceRead',
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: executeSkillReadCommand,
+  };
+}

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

@@ -1,4 +1,5 @@
 import { SkillCommandSource } from '@robota-sdk/agent-framework';
+import { createSkillReadCommandEntry, createSkillReadSystemCommand } from './skill-read-command.js';
 
 import {
   executeSkillsCommand,
@@ -57,7 +58,7 @@ export class SkillsCommandSource implements ICommandSource {
   readonly name = 'skills';
 
   getCommands(): ICommand[] {
-    return [createSkillsCommandEntry()];
+    return [createSkillsCommandEntry(), createSkillReadCommandEntry()];
   }
 }
 
@@ -70,6 +71,6 @@ export function createSkillsCommandModule(options: ISkillsCommandModuleOptions):
   return {
     name: 'agent-command-skills',
     commandSources,
-    systemCommands: [createSkillsSystemCommand()],
+    systemCommands: [createSkillsSystemCommand(), createSkillReadSystemCommand()],
   };
 }

package/src/terminal-client/__tests__/terminal-client-commands.test.ts

@@ -35,7 +35,7 @@ import type {
 } from '@robota-sdk/agent-interface-command';
 
 /** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
-const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'robota-test-'));
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'agent-test-test-'));
 afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
 
 const providerDefinitions: readonly IProviderDefinition[] = [];

package/src/theme/__tests__/theme-command.test.ts

@@ -73,7 +73,7 @@ describe('/theme without a catalogue (SCREEN-2002 TC-09)', () => {
     const result = executeThemeCommand(undefined, 'light');
 
     expect(result.success).toBe(false);
-    expect(result.message).toMatch(/Run \/theme in the robota terminal/);
+    expect(result.message).toMatch(/Run \/theme there/);
     expect(result.hostActions).toBeUndefined();
   });
 });

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

@@ -19,7 +19,7 @@ const THEME_ARGUMENT_HINT = 'list | <theme-id> | syntax on|off | motion on|off';
 // A host without a terminal (the desktop app's sidecar) still answers, so the command is never
 // "unknown" there — it says where themes live instead.
 const THEME_UNAVAILABLE =
-  'Themes belong to the robota terminal, and this surface has none. Run /theme in the robota terminal.';
+  'Themes are available in an interactive terminal. Run /theme there.';
 
 function formatToggle(value: boolean): string {
   return value ? 'on' : 'off';

package/src/user-local/__tests__/user-local-command.test.ts

@@ -22,12 +22,12 @@ afterEach(async () => {
 
 describe('user-local command', () => {
   it('does not advertise a specific product from the neutral command entry', async () => {
-    const module = createUserLocalCommandModule(await createTempRoot('robota-selected-storage-'));
-    expect(module.commandSources?.[0]?.getCommands()[0]?.description).not.toMatch(/Robota/i);
+    const module = createUserLocalCommandModule(await createTempRoot('agent-test-selected-storage-'));
+    expect(module.commandSources?.[0]?.getCommands()[0]?.description).not.toMatch(/ConversationAgent/i);
   });
 
   it('fails closed when a direct caller omits the storage root', async () => {
-    const workspace = await createTempRoot('robota-user-local-missing-root-');
+    const workspace = await createTempRoot('agent-test-user-local-missing-root-');
     const repo = path.join(workspace, 'repo');
     await fs.mkdir(repo);
 
@@ -40,9 +40,9 @@ describe('user-local command', () => {
   });
 
   it('uses the explicit root for slash commands', async () => {
-    const workspace = await createTempRoot('robota-user-local-slash-root-');
+    const workspace = await createTempRoot('agent-test-user-local-slash-root-');
     const repo = path.join(workspace, 'repo');
-    const selectedRoot = path.join(workspace, 'selected', '.robota');
+    const selectedRoot = path.join(workspace, 'selected', '.fixture-state');
     await fs.mkdir(repo);
     vi.stubEnv('HOME', path.join(workspace, 'ambient-home'));
 
@@ -65,7 +65,7 @@ describe('user-local command', () => {
   });
 
   it('prints storage inspection JSON without provider configuration', async () => {
-    const workspace = await createTempRoot('robota-user-local-command-');
+    const workspace = await createTempRoot('agent-test-user-local-command-');
     const repo = path.join(workspace, 'repo');
     const home = path.join(workspace, 'home');
     await fs.mkdir(repo);
@@ -74,7 +74,7 @@ describe('user-local command', () => {
 
     const result = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['storage', 'list'],
       format: 'json',
     });
@@ -84,7 +84,7 @@ describe('user-local command', () => {
     };
 
     expect(result.success).toBe(true);
-    expect(parsed.root).toBe(path.join(home, '.robota'));
+    expect(parsed.root).toBe(path.join(home, '.fixture-state'));
     expect(parsed.categories.map((item) => item.category)).toEqual([
       'preferences',
       'view-state',
@@ -97,7 +97,7 @@ describe('user-local command', () => {
   });
 
   it('stores, lists, inspects, disables, and deletes user-local memory items', async () => {
-    const workspace = await createTempRoot('robota-user-local-memory-command-');
+    const workspace = await createTempRoot('agent-test-user-local-memory-command-');
     const repo = path.join(workspace, 'repo');
     const home = path.join(workspace, 'home');
     await fs.mkdir(repo);
@@ -106,7 +106,7 @@ describe('user-local command', () => {
 
     const setResult = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['memory', 'set', 'view-preference', 'last-panel', 'background'],
       summary: 'Open the background panel',
       source: 'user-input',
@@ -116,7 +116,7 @@ describe('user-local command', () => {
 
     const listResult = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['memory', 'list'],
       format: 'json',
     });
@@ -133,7 +133,7 @@ describe('user-local command', () => {
 
     const inspectResult = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
       format: 'json',
     });
@@ -147,14 +147,14 @@ describe('user-local command', () => {
 
     const disableResult = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['memory', 'disable', 'view-preference', 'last-panel'],
     });
     expect(disableResult.success).toBe(true);
 
     const disabledInspectResult = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
       format: 'json',
     });
@@ -163,14 +163,14 @@ describe('user-local command', () => {
 
     const deleteResult = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['memory', 'delete', 'view-preference', 'last-panel'],
     });
     expect(deleteResult.success).toBe(true);
 
     const missingResult = await executeUserLocalDirectCommand({
       cwd: repo,
-      storageRoot: path.join(home, '.robota'),
+      storageRoot: path.join(home, '.fixture-state'),
       argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
       format: 'json',
     });