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

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@robota-sdk/agent-command",
+  "version": "3.0.0-beta.100",
+  "description": "Slash-command modules for Robota SDK sessions (/help, /permissions, /mcp, /rewind, …)",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "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": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@robota-sdk/agent-core": "3.0.0-beta.100",
+    "@robota-sdk/agent-framework": "3.0.0-beta.100",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.100",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.100",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.100",
+    "@robota-sdk/agent-preset": "3.0.0-beta.100"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "rimraf": "^5.0.10",
+    "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota"
+  },
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "homepage": "https://robota.io/",
+  "scripts": {
+    "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';