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

package/package.json

@@ -1,21 +1,32 @@
 {
   "name": "@robota-sdk/agent-command",
-  "version": "3.0.0-beta.79",
+  "version": "3.0.0-beta.81",
   "description": "Consolidated command module implementations for Robota SDK CLI",
   "type": "module",
   "main": "dist/node/index.js",
   "types": "dist/node/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/node/index.d.ts",
       "source": "./src/index.ts",
       "node": {
-        "import": "./dist/node/index.js",
-        "require": "./dist/node/index.cjs"
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
       },
       "default": {
-        "import": "./dist/node/index.js",
-        "require": "./dist/node/index.cjs"
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
       }
     }
   },
@@ -24,29 +35,36 @@
     "src"
   ],
   "dependencies": {
-    "@robota-sdk/agent-core": "3.0.0-beta.79",
-    "@robota-sdk/agent-framework": "3.0.0-beta.79",
-    "@robota-sdk/agent-interface-transport": "3.0.0-beta.79",
-    "@robota-sdk/agent-preset": "3.0.0-beta.79"
+    "@robota-sdk/agent-core": "3.0.0-beta.81",
+    "@robota-sdk/agent-framework": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.81",
+    "@robota-sdk/agent-preset": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.81"
   },
   "devDependencies": {
     "@types/node": "^22.19.21",
     "rimraf": "^5.0.10",
-    "tsdown": "^0.22.2",
-    "typescript": "^5.9.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
     "vitest": "^3.2.6"
   },
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "publishConfig": {
     "access": "public"
   },
+  "volta": {
+    "extends": "../../package.json"
+  },
   "scripts": {
-    "build": "tsdown",
-    "build:js": "tsdown --no-dts",
-    "build:types": "tsdown --dts",
-    "typecheck": "tsc --noEmit",
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit && tsgo -p tsconfig.examples.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "scenario:verify": "pnpm scenario:verify:semantic-command-roles",
+    "scenario:verify:semantic-command-roles": "pnpm exec tsx --conditions=source examples/verify-semantic-command-roles.ts",
     "clean": "rimraf dist"
   }
 }

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

@@ -0,0 +1,47 @@
+import { executeAdvisorCommand } from './advisor-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createAdvisorCommandEntry(): ICommand {
+  return {
+    name: 'advisor',
+    displayName: 'Advisor',
+    description: 'Show, set, or turn off the model the main model can consult for advice',
+    source: 'advisor',
+    argumentHint: '<profile> | <profile>:<model> | off',
+    // User-only: choosing a second model changes cost and what sees the conversation; the user decides.
+    modelInvocable: false,
+  };
+}
+
+function createAdvisorSystemCommand(): ISystemCommand {
+  const entry = createAdvisorCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    argumentHint: entry.argumentHint,
+    lifecycle: 'inline',
+    execute: executeAdvisorCommand,
+  };
+}
+
+export class AdvisorCommandSource implements ICommandSource {
+  readonly name = 'advisor';
+
+  getCommands(): ICommand[] {
+    return [createAdvisorCommandEntry()];
+  }
+}
+
+export function createAdvisorCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-advisor',
+    commandSources: [new AdvisorCommandSource()],
+    systemCommands: [createAdvisorSystemCommand()],
+  };
+}

package/src/advisor/advisor-command.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { AdvisorController, createAdvisorTool } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { executeAdvisorCommand } from './advisor-command.js';
+
+import type { IAIProvider } from '@robota-sdk/agent-core';
+import type { ICommandSettingsDocument } from '@robota-sdk/agent-framework';
+
+function advisorController(options: {
+  registered: boolean;
+  allowed?: string[];
+}): AdvisorController {
+  return new AdvisorController({
+    ...(options.registered ? { spec: { profile: 'strong' } } : {}),
+    resolveTarget: (spec) => {
+      if (spec.profile === 'missing') throw new Error('Provider profile "missing" not found.');
+      return {
+        provider: {} as IAIProvider,
+        model: `${spec.profile}-model`,
+        destination: 'vendor-a@default',
+      };
+    },
+    consent: { has: () => true, grant: () => undefined },
+    ...(options.allowed ? { allowedProfiles: options.allowed } : {}),
+  });
+}
+
+function host(advisor: AdvisorController | undefined, initial: ICommandSettingsDocument = {}) {
+  let document: ICommandSettingsDocument = { ...initial };
+  const write = vi.fn((next: ICommandSettingsDocument) => {
+    document = next;
+  });
+  const context = createTestCommandHost({
+    overrides: {
+      getCommandHostAdapters: () => ({
+        ...(advisor ? { advisor } : {}),
+        settings: { read: () => document, write },
+      }),
+    },
+  });
+  return { context, write, read: () => document };
+}
+
+describe('/advisor', () => {
+  it('saves the default and retargets the live advisor without changing the tool', async () => {
+    const advisor = advisorController({ registered: true });
+    const schema = JSON.stringify(createAdvisorTool(advisor).schema);
+    const { context, read } = host(advisor, { theme: 'dark' });
+
+    const result = await executeAdvisorCommand(context, 'other:big');
+
+    expect(result.success).toBe(true);
+    expect(read()).toEqual({ theme: 'dark', advisorModel: 'other:big' });
+    expect(advisor.status()).toMatchObject({ target: 'other:big', enabled: true });
+    expect(JSON.stringify(createAdvisorTool(advisor).schema)).toBe(schema);
+  });
+
+  it('turns the advisor off and removes the saved default', async () => {
+    const advisor = advisorController({ registered: true });
+    const { context, read } = host(advisor, { advisorModel: 'strong', theme: 'dark' });
+
+    const result = await executeAdvisorCommand(context, 'off');
+
+    expect(result.success).toBe(true);
+    expect(read()).toEqual({ theme: 'dark' });
+    expect(advisor.status().enabled).toBe(false);
+  });
+
+  it('says a new advisor takes effect next session when this one started without the tool', async () => {
+    const { context } = host(advisorController({ registered: false }));
+    const result = await executeAdvisorCommand(context, 'strong');
+    expect(result.message).toContain('next session');
+  });
+
+  it('refuses a profile outside the organization allowlist and saves nothing', async () => {
+    const { context, write } = host(advisorController({ registered: true, allowed: ['strong'] }));
+    const result = await executeAdvisorCommand(context, 'elsewhere');
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('organization policy');
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it('refuses a profile that does not exist and saves nothing', async () => {
+    const { context, write } = host(advisorController({ registered: true }));
+    const result = await executeAdvisorCommand(context, 'missing');
+    expect(result.success).toBe(false);
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it('reports the current advisor', async () => {
+    const { context } = host(advisorController({ registered: true }));
+    const result = await executeAdvisorCommand(context, '');
+    expect(result.message).toContain('Advisor: strong');
+  });
+
+  it('fails explicitly on a host without an advisor', async () => {
+    const { context } = host(undefined);
+    expect((await executeAdvisorCommand(context, '')).success).toBe(false);
+  });
+});

package/src/advisor/advisor-command.ts

@@ -0,0 +1,55 @@
+import type {
+  IAdvisorStatus,
+  ICommandHostAdapterAccess,
+  ICommandHostWorkspace,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+/** The user-settings key `/advisor` saves the default advisor under. */
+export const ADVISOR_SETTING_KEY = 'advisorModel';
+
+function describeStatus(status: IAdvisorStatus): string {
+  if (status.killSwitch) return 'Advisor: disabled by the environment kill switch.';
+  if (status.target === undefined || !status.enabled) {
+    return 'Advisor: off. Set one with /advisor <profile> or /advisor <profile>:<model>.';
+  }
+  const availability = status.registered
+    ? `${status.sessionCalls}/${status.maxCallsPerSession} calls used this session`
+    : 'available from the next session';
+  return `Advisor: ${status.target} (${availability}).`;
+}
+
+/**
+ * `/advisor` — show the advisor, set it (`<profile>` or `<profile>:<model>`), or turn it off. A
+ * change the user makes is also saved as the default for later sessions.
+ */
+export async function executeAdvisorCommand(
+  context: ICommandHostAdapterAccess & ICommandHostWorkspace,
+  args: string,
+): Promise<ICommandResult> {
+  const adapters = context.getCommandHostAdapters?.() ?? {};
+  const advisor = adapters.advisor;
+  if (advisor === undefined) {
+    return { success: false, message: 'The advisor is not available in this environment.' };
+  }
+  const value = args.trim();
+  if (value.length === 0) {
+    const status = advisor.status();
+    return { success: true, message: describeStatus(status), data: { advisor: { ...status } } };
+  }
+  const result = advisor.set(value);
+  if (!result.success || result.saved === undefined) {
+    return { success: result.success, message: result.message };
+  }
+  const settings = adapters.settings;
+  if (settings !== undefined && context.getCommandInvocationSource() === 'user') {
+    const current = settings.read();
+    if (result.saved === 'off') {
+      const { [ADVISOR_SETTING_KEY]: _removed, ...rest } = current;
+      settings.write(rest);
+    } else {
+      settings.write({ ...current, [ADVISOR_SETTING_KEY]: result.saved });
+    }
+  }
+  return { success: true, message: result.message, data: { advisor: { ...advisor.status() } } };
+}

package/src/advisor/advisor-cost-functional.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { calculateModelCost } from '@robota-sdk/agent-core';
+import { AdvisorController, createAdvisorTool } from '@robota-sdk/agent-framework';
+import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
+
+import { createSessionCommandModule } from '../session/session-command-module.js';
+
+import type { IAIProvider } from '@robota-sdk/agent-core';
+
+const ADVISOR_MODEL = 'claude-opus-4-6';
+const MAIN_MODEL = 'claude-haiku-4-5';
+
+function advisorProvider(): IAIProvider {
+  return {
+    name: 'advisor-vendor',
+    version: 'test',
+    chat: vi.fn(async () => ({
+      id: 'advice',
+      role: 'assistant' as const,
+      content: 'Run the tests before declaring done.',
+      state: 'complete' as const,
+      timestamp: new Date(),
+      metadata: { inputTokens: 3_000, outputTokens: 400 },
+    })),
+  } as unknown as IAIProvider;
+}
+
+describe('advisor usage in a real session', () => {
+  let harness: ScriptedSessionHarness | undefined;
+
+  afterEach(async () => {
+    await harness?.dispose();
+    harness = undefined;
+  });
+
+  it('/cost totals the turn and the advisor call, pricing the advisor on its model, and both persist', async () => {
+    const controller = new AdvisorController({
+      spec: { profile: 'strong' },
+      resolveTarget: () => ({
+        provider: advisorProvider(),
+        model: ADVISOR_MODEL,
+        destination: 'advisor-vendor@api.test',
+      }),
+      consent: { has: () => true, grant: () => undefined },
+    });
+    harness = scriptedSession({
+      turns: [
+        {
+          toolCalls: [{ name: 'Advisor', args: { question: 'done?' } }],
+          usage: { inputTokens: 1_000, outputTokens: 100 },
+        },
+        { text: 'All done.', usage: { inputTokens: 1_200, outputTokens: 50 } },
+      ],
+      model: MAIN_MODEL,
+      persistence: true,
+      additionalTools: [createAdvisorTool(controller)],
+      commandModules: [createSessionCommandModule()],
+    });
+
+    await harness.submit('finish the task');
+    const result = await harness.command('cost');
+    const data = result?.data as Record<string, number | string[] | undefined>;
+
+    const advisorCost = calculateModelCost(ADVISOR_MODEL, 3_000, 400)!;
+    const persisted = harness.sessionRecord()?.history ?? [];
+    const summaries = persisted
+      .filter((entry) => entry.type === 'usage-summary')
+      .map(
+        (entry) =>
+          entry.data as { promptTokens: number; completionTokens: number; source?: unknown },
+      );
+    const turn = summaries.find((summary) => summary.source === undefined);
+    expect(turn).toBeDefined();
+    expect(summaries).toHaveLength(2);
+    expect(data.inputTokens).toBe(turn!.promptTokens + 3_000);
+    expect(data.outputTokens).toBe(turn!.completionTokens + 400);
+    expect(data.estimatedCostUsd as number).toBeGreaterThan(advisorCost);
+    expect(result?.message).toContain(`Advisor (${ADVISOR_MODEL})`);
+    expect(result?.message).toContain('mixed');
+
+    const advisorObservation = persisted.find(
+      (entry) =>
+        entry.type === 'usage-observation' &&
+        (entry.data as { modelId?: string }).modelId === ADVISOR_MODEL,
+    );
+    expect(advisorObservation?.data).toMatchObject({
+      providerId: 'advisor-vendor',
+      usage: { promptTokens: 3_000, completionTokens: 400, costUsd: advisorCost },
+    });
+  });
+});

package/src/advisor/index.ts

@@ -0,0 +1,6 @@
+export {
+  AdvisorCommandSource,
+  createAdvisorCommandEntry,
+  createAdvisorCommandModule,
+} from './advisor-command-module.js';
+export { ADVISOR_SETTING_KEY, executeAdvisorCommand } from './advisor-command.js';

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

@@ -4,10 +4,12 @@ import {
   SystemCommandExecutor,
   createSystemCommands,
 } from '@robota-sdk/agent-framework';
-import type { IAgentJobHostContext, ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
 import { createAgentCommandModule } from '../agent-command-module.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+import { createTestAgentJobHost } from '@robota-sdk/agent-framework/testing';
 
-function createMockSession(overrides?: Record<string, unknown>): ICommandHostContext {
+function createMockSession(overrides?: Record<string, unknown>) {
   const session = {
     listAgentDefinitions: vi.fn().mockReturnValue([
       { name: 'general-purpose', description: 'General-purpose task execution agent.' },
@@ -67,9 +69,15 @@ function createMockSession(overrides?: Record<string, unknown>): ICommandHostCon
     closeAgentJob: vi.fn(),
     ...overrides,
   };
-  (session as Record<string, unknown>)['getAgentJobCapability'] = () =>
-    session as unknown as IAgentJobHostContext;
-  return session as unknown as ICommandHostContext;
+  // ARCH-029: the literal this replaced injected `getAgentJobCapability` at RUNTIME through a
+  // `Record<string, unknown>` cast, then asserted the result satisfied two contracts. Statically the
+  // object did not have that member at all. It is now declared, and checked.
+  return createTestCommandHost({
+    overrides: {
+      ...session,
+      getAgentJobCapability: () => createTestAgentJobHost(session),
+    },
+  });
 }
 
 describe('agent command module', () => {
@@ -81,6 +89,7 @@ describe('agent command module', () => {
       .map((command) => command.name);
 
     const module = createAgentCommandModule();
+    expect(module.systemCommands?.[0]?.semanticRole).toBe('subagentSpawn');
     const executor = new SystemCommandExecutor([
       ...createSystemCommands(),
       ...(module.systemCommands ?? []),
@@ -100,6 +109,28 @@ describe('agent command module', () => {
     expect(module.systemCommands).toHaveLength(1);
   });
 
+  it('keeps the palette agent actions on the executable command', () => {
+    const module = createAgentCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+
+    expect(palette?.subcommands?.map(({ name }) => name)).toEqual([
+      'list',
+      'run',
+      'parallel',
+      'wait',
+      'read',
+      'send',
+      'stop',
+      'close',
+      'open',
+    ]);
+    expect(executable?.subcommands).toEqual(palette?.subcommands);
+    expect(palette?.subcommands?.find(({ name }) => name === 'open')?.description).toBe(
+      'Read an agent job log page (alias for read)',
+    );
+  });
+
   it('projects agent from its injected command source', () => {
     const module = createAgentCommandModule();
     const registry = new CommandRegistry();
@@ -115,7 +146,7 @@ describe('agent command module', () => {
       modelInvocable: true,
       safety: 'background-agent',
     });
-    expect(agent?.description).toContain('Subagent jobs');
+    expect(agent?.description).toContain('background subagent jobs');
     expect(agent?.description).toContain('parallel');
     expect(agent?.description).toContain('consolidated');
     expect(agent?.description).toContain('When the user explicitly asks');
@@ -484,7 +515,7 @@ describe('agent command module', () => {
     const result = await executor.execute('agent', session, '');
 
     expect(result?.success).toBe(true);
-    expect(result?.effects).toEqual([{ type: 'agent-switcher-requested' }]);
+    expect(result?.uiIntents).toEqual([{ type: 'show-agent-switcher' }]);
   });
 
   it('shows text list when agent list subcommand is used explicitly', async () => {
@@ -499,6 +530,6 @@ describe('agent command module', () => {
 
     expect(result?.success).toBe(true);
     expect(result?.message).toContain('Available agents:');
-    expect(result?.effects).toBeUndefined();
+    expect(result?.uiIntents).toBeUndefined();
   });
 });

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

@@ -2,14 +2,14 @@ import { executeAgentCommand } from './agent-command.js';
 
 import type {
   IAgentJobHostContext,
-  ICommandHostContext,
+  ICommandHostAgentJobs,
   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';
 
-function getAgentHostContext(context: ICommandHostContext): IAgentJobHostContext {
-  const cap = context.getAgentJobCapability?.();
+function getAgentHostContext(context: ICommandHostAgentJobs): IAgentJobHostContext {
+  const cap = context.getAgentJobCapability();
   if (!cap) throw new Error('Agent job capability is not available in this context.');
   return cap;
 }
@@ -24,7 +24,7 @@ function createAgentSubcommands(): ICommand[] {
     { name: 'send', description: 'Send follow-up input to an agent job', source: 'agent' },
     { name: 'stop', description: 'Cancel a running agent job', source: 'agent' },
     { name: 'close', description: 'Dismiss a terminal agent job', source: 'agent' },
-    { name: 'open', description: 'Focus an agent job detail view when supported', source: 'agent' },
+    { name: 'open', description: 'Read an agent job log page (alias for read)', source: 'agent' },
   ];
 }
 
@@ -32,13 +32,17 @@ export function createAgentCommandEntry(): ICommand {
   return {
     name: 'agent',
     displayName: 'Agent Jobs',
-    description: [
-      'Subagent jobs command.',
+    description: 'Start and manage background subagent jobs',
+    // Model-invocable: delegating work to subagents is the model's own decision, and each job runs
+    // under the session's permissions, so starting one widens nothing.
+    modelDescription: [
+      'Start and manage background subagent jobs.',
       'Natural-language arguments start one background agent job.',
       'When the user explicitly asks to create, run, spawn, delegate to, or use agents/subagents, start the requested agent command immediately and do not ask a follow-up question unless execution is impossible or unsafe.',
       'If the target item is unspecified, include target selection inside the agent prompt instead of delaying execution.',
       'The parallel form starts multiple background agent jobs as a wait_all group and returns a consolidated group summary unless --detach is present.',
       'list, wait, read, send, stop, close, and open manage existing agent jobs.',
+      'Returns the started job id (or group summary), the job list, or the requested log page.',
     ].join(' '),
     source: 'agent',
     modelInvocable: true,
@@ -53,14 +57,17 @@ export function createAgentSystemCommand(): ISystemCommand {
   const entry = createAgentCommandEntry();
   return {
     name: entry.name,
+    semanticRole: 'subagentSpawn',
     ...(entry.displayName !== undefined ? { displayName: entry.displayName } : {}),
     description: entry.description,
     requiresPermission: false,
     execute: (context, args) => executeAgentCommand(getAgentHostContext(context), args),
     ...(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 } : {}),
   };
 }
 

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

@@ -1,4 +1,4 @@
-import type { TBackgroundTaskIsolation } from '@robota-sdk/agent-interface-transport';
+import type { TBackgroundTaskIsolation } from '@robota-sdk/agent-interface-execution';
 
 const DEFAULT_AGENT_TYPE = 'general-purpose';
 

package/src/agent/agent-command.ts

@@ -4,8 +4,8 @@ import { parseParallelRequests, parseRunRequest, tokenizeArgs } from './agent-co
 
 import type { IAgentRunRequest } from './agent-command-parser.js';
 import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
-import type { ISubagentJobState } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { ISubagentJobState } from '@robota-sdk/agent-interface-execution';
 
 function formatError<TError>(error: TError): string {
   return error instanceof Error ? error.message : String(error);
@@ -41,7 +41,7 @@ async function spawnAgentJob(
 }
 
 function executeOpenSwitcher(): ICommandResult {
-  return { message: '', effects: [{ type: 'agent-switcher-requested' }], success: true };
+  return { message: '', uiIntents: [{ type: 'show-agent-switcher' }], success: true };
 }
 
 async function executeList(session: IAgentJobHostContext): Promise<ICommandResult> {