@robota-sdk/agent-transport 3.0.0-beta.64

package/src/headless/__tests__/headless-skill-activation.integration.test.ts

@@ -0,0 +1,430 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { InteractiveSession } from '@robota-sdk/agent-framework';
+import { createSkillsCommandModule } from '@robota-sdk/agent-command';
+import type { TInteractiveSessionOptions } from '@robota-sdk/agent-framework';
+import { createHeadlessTransport } from '../headless-transport.js';
+
+type TStandardSessionOptions = Extract<
+  TInteractiveSessionOptions,
+  { cwd: string; provider: unknown }
+>;
+type TTestProvider = TStandardSessionOptions['provider'];
+type TChatResponse = Awaited<ReturnType<TTestProvider['chat']>>;
+type TToolCalls = Extract<TChatResponse, { role: 'assistant' }>['toolCalls'];
+type TResolvedConfig = NonNullable<TStandardSessionOptions['config']>;
+
+interface IObservedProvider {
+  provider: TTestProvider;
+  getChatCallCount(): number;
+  getFirstCallToolNames(): string[];
+  getFirstCallSkillsToolArgsDescription(): string | undefined;
+  getFirstPromptContent(): string;
+  getToolResultContent(): string;
+}
+
+interface IObservedPromptProvider {
+  provider: TTestProvider;
+  getChatCallCount(): number;
+  getPromptContent(): string;
+}
+
+interface IObservedUnknownToolProvider {
+  provider: TTestProvider;
+  getChatCallCount(): number;
+  getToolResultContent(): string;
+  getForcedInstruction(): string;
+  getForcedCallToolNames(): string[] | undefined;
+}
+
+function createTempSkill(
+  cwd: string,
+  name: string,
+  description: string,
+  body = 'Run this skill with the real skill runtime: $ARGUMENTS',
+): void {
+  const skillDir = join(cwd, '.agents', 'skills', name);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(
+    join(skillDir, 'SKILL.md'),
+    ['---', `name: ${name}`, `description: ${description}`, '---', body].join('\n'),
+    'utf8',
+  );
+}
+
+function createConfig(): TResolvedConfig {
+  return {
+    defaultTrustLevel: 'moderate',
+    language: 'en',
+    provider: {
+      name: 'headless-test-provider',
+      model: 'headless-test-model',
+      apiKey: 'test-key',
+    },
+    permissions: { allow: [], deny: [] },
+    env: {},
+  };
+}
+
+function assistantMessage(content: string | null, toolCalls?: TToolCalls): TChatResponse {
+  return {
+    id: `assistant-${Math.random().toString(36).slice(2)}`,
+    role: 'assistant',
+    content,
+    state: 'complete',
+    timestamp: new Date(),
+    ...(toolCalls !== undefined ? { toolCalls } : {}),
+  };
+}
+
+function createSkillToolCallingProvider(): IObservedProvider {
+  let chatCallCount = 0;
+  let firstCallToolNames: string[] = [];
+  let firstCallSkillsToolArgsDescription: string | undefined;
+  let firstPromptContent = '';
+  let toolResultContent = '';
+
+  const provider: TTestProvider = {
+    name: 'headless-test-provider',
+    version: '1.0.0',
+    async chat(messages, options) {
+      chatCallCount += 1;
+
+      if (chatCallCount === 1) {
+        firstPromptContent = messages.map((message) => message.content).join('\n');
+        firstCallToolNames = options?.tools?.map((tool) => tool.name) ?? [];
+        const skillsToolSchema = options?.tools?.find(
+          (tool) => tool.name === 'robota_command_skills',
+        );
+        firstCallSkillsToolArgsDescription =
+          skillsToolSchema?.parameters.properties['args']?.description;
+        return assistantMessage(null, [
+          {
+            id: 'call_robota_command_skills',
+            type: 'function',
+            function: {
+              name: 'robota_command_skills',
+              arguments: JSON.stringify({ args: 'repo-writing docs/architecture.md' }),
+            },
+          },
+        ]);
+      }
+
+      const toolMessage = messages.find(
+        (message) => message.role === 'tool' && message.name === 'robota_command_skills',
+      );
+      toolResultContent = toolMessage?.content ?? '';
+      return assistantMessage('Headless skill activated');
+    },
+    async generateResponse() {
+      return { content: 'unused' };
+    },
+    supportsTools() {
+      return true;
+    },
+    validateConfig() {
+      return true;
+    },
+  };
+
+  return {
+    provider,
+    getChatCallCount: () => chatCallCount,
+    getFirstCallToolNames: () => firstCallToolNames,
+    getFirstCallSkillsToolArgsDescription: () => firstCallSkillsToolArgsDescription,
+    getFirstPromptContent: () => firstPromptContent,
+    getToolResultContent: () => toolResultContent,
+  };
+}
+
+function createPromptObservingProvider(response: string): IObservedPromptProvider {
+  let chatCallCount = 0;
+  let promptContent = '';
+
+  const provider: TTestProvider = {
+    name: 'headless-test-provider',
+    version: '1.0.0',
+    async chat(messages) {
+      chatCallCount += 1;
+      promptContent = messages.map((message) => message.content).join('\n');
+      return assistantMessage(response);
+    },
+    async generateResponse() {
+      return { content: 'unused' };
+    },
+    supportsTools() {
+      return true;
+    },
+    validateConfig() {
+      return true;
+    },
+  };
+
+  return {
+    provider,
+    getChatCallCount: () => chatCallCount,
+    getPromptContent: () => promptContent,
+  };
+}
+
+function createUnknownToolCallingProvider(): IObservedUnknownToolProvider {
+  let chatCallCount = 0;
+  let toolResultContent = '';
+  let forcedInstruction = '';
+  let forcedCallToolNames: string[] | undefined;
+
+  const provider: TTestProvider = {
+    name: 'headless-test-provider',
+    version: '1.0.0',
+    async chat(messages, options) {
+      chatCallCount += 1;
+
+      if (chatCallCount <= 2) {
+        return assistantMessage(null, [
+          {
+            id: `call_unknown_agent_${chatCallCount}`,
+            type: 'function',
+            function: {
+              name: 'agent',
+              arguments: JSON.stringify({ prompt: `spawn worker ${chatCallCount}` }),
+            },
+          },
+        ]);
+      }
+
+      const toolMessage = [...messages]
+        .reverse()
+        .find((message) => message.role === 'tool' && message.name === 'agent');
+      toolResultContent = toolMessage?.content ?? '';
+      const userMessage = [...messages].reverse().find((message) => message.role === 'user');
+      forcedInstruction = userMessage?.content ?? '';
+      forcedCallToolNames = options?.tools?.map((tool) => tool.name);
+      return assistantMessage('The agent tool was not executed because it is not registered.');
+    },
+    async generateResponse() {
+      return { content: 'unused' };
+    },
+    supportsTools() {
+      return true;
+    },
+    validateConfig() {
+      return true;
+    },
+  };
+
+  return {
+    provider,
+    getChatCallCount: () => chatCallCount,
+    getToolResultContent: () => toolResultContent,
+    getForcedInstruction: () => forcedInstruction,
+    getForcedCallToolNames: () => forcedCallToolNames,
+  };
+}
+
+function captureStdout(): { writes: string[]; restore(): void } {
+  const writes: string[] = [];
+  const originalWrite = process.stdout.write;
+
+  process.stdout.write = ((chunk: string | Uint8Array, encodingOrCallback?: unknown) => {
+    writes.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+    if (typeof encodingOrCallback === 'function') {
+      encodingOrCallback();
+    }
+    return true;
+  }) as typeof process.stdout.write;
+
+  return {
+    writes,
+    restore() {
+      process.stdout.write = originalWrite;
+    },
+  };
+}
+
+function parseJsonObject(input: string): Record<string, unknown> {
+  const parsed: unknown = JSON.parse(input);
+  expect(parsed).toBeTypeOf('object');
+  expect(parsed).not.toBeNull();
+  return parsed as Record<string, unknown>;
+}
+
+describe('headless transport skill activation integration', () => {
+  let cwd: string | undefined;
+
+  afterEach(() => {
+    if (cwd) rmSync(cwd, { recursive: true, force: true });
+    cwd = undefined;
+  });
+
+  it('executes model-invocable skills through the skills built-in command in a headless session', async () => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-headless-skill-'));
+    createTempSkill(
+      cwd,
+      'repo-writing',
+      'Repository writing rules',
+      'Apply repository writing rules with the real skill runtime: $ARGUMENTS',
+    );
+    const observed = createSkillToolCallingProvider();
+    const session = new InteractiveSession({
+      cwd,
+      provider: observed.provider,
+      config: createConfig(),
+      permissionMode: 'bypassPermissions',
+      bare: true,
+      commandModules: [createSkillsCommandModule({ cwd })],
+    });
+    const stdout = captureStdout();
+
+    try {
+      const transport = createHeadlessTransport({
+        outputFormat: 'json',
+        prompt: 'Use repository writing rules for docs/architecture.md',
+      });
+
+      session.attachTransport(transport);
+      await transport.start();
+
+      const output = parseJsonObject(stdout.writes.join('').trim());
+      expect(transport.getExitCode()).toBe(0);
+      expect(output).toMatchObject({
+        type: 'result',
+        result: 'Headless skill activated',
+        subtype: 'success',
+      });
+      expect(output['session_id']).toBeTypeOf('string');
+      expect(observed.getChatCallCount()).toBe(2);
+      expect(observed.getFirstCallToolNames()).toContain('robota_command_skills');
+      expect(observed.getFirstCallToolNames()).not.toContain('ExecuteCommand');
+      expect(observed.getFirstCallToolNames()).not.toContain('ExecuteSkill');
+      expect(observed.getFirstCallSkillsToolArgsDescription()).toContain(
+        '[list | <skill-name> [args]]',
+      );
+      expect(observed.getFirstPromptContent()).toContain('## Built-in Commands');
+      expect(observed.getFirstPromptContent()).toContain('skills [list | <skill-name> [args]]');
+      expect(observed.getFirstPromptContent()).toContain('## Skills');
+      expect(observed.getFirstPromptContent()).toContain(
+        '- repo-writing: Repository writing rules',
+      );
+      expect(observed.getToolResultContent()).toContain('"success":true');
+      expect(observed.getToolResultContent()).toContain('<skill name=\\"repo-writing\\">');
+      expect(session.getSkillActivationEvents().map((event) => event.invocation)).toEqual([
+        'model-tool',
+        'model-tool',
+      ]);
+      expect(session.getSkillActivationEvents().map((event) => event.status)).toEqual([
+        'started',
+        'completed',
+      ]);
+    } finally {
+      stdout.restore();
+      await session.shutdown({
+        reason: 'prompt_input_exit',
+        message: 'Headless skill activation test complete',
+      });
+    }
+  });
+
+  it('executes explicit slash skills through SDK skill loading in a headless session', async () => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-headless-slash-skill-'));
+    createTempSkill(
+      cwd,
+      'audit',
+      'Audit one file',
+      'Audit this file with the real skill runtime: $ARGUMENTS',
+    );
+    const observed = createPromptObservingProvider('Headless slash skill activated');
+    const session = new InteractiveSession({
+      cwd,
+      provider: observed.provider,
+      config: createConfig(),
+      permissionMode: 'bypassPermissions',
+      bare: true,
+      commandModules: [createSkillsCommandModule({ cwd })],
+    });
+    const stdout = captureStdout();
+
+    try {
+      const transport = createHeadlessTransport({
+        outputFormat: 'json',
+        prompt: '/audit src/index.ts',
+      });
+
+      session.attachTransport(transport);
+      await transport.start();
+
+      const output = parseJsonObject(stdout.writes.join('').trim());
+      expect(transport.getExitCode()).toBe(0);
+      expect(output).toMatchObject({
+        type: 'result',
+        result: 'Headless slash skill activated',
+        subtype: 'success',
+      });
+      expect(observed.getChatCallCount()).toBe(1);
+      expect(observed.getPromptContent()).toContain(
+        'Audit this file with the real skill runtime: src/index.ts',
+      );
+      expect(observed.getPromptContent()).toContain('<skill name="audit">');
+      expect(session.getSkillActivationEvents().map((event) => event.invocation)).toEqual([
+        'user-slash',
+        'user-slash',
+      ]);
+      expect(session.getSkillActivationEvents().map((event) => event.status)).toEqual([
+        'started',
+        'completed',
+      ]);
+    } finally {
+      stdout.restore();
+      await session.shutdown({
+        reason: 'prompt_input_exit',
+        message: 'Headless slash skill activation test complete',
+      });
+    }
+  });
+
+  it('reports skipped unknown native tool calls through the headless execution path', async () => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-headless-unknown-tool-'));
+    const observed = createUnknownToolCallingProvider();
+    const session = new InteractiveSession({
+      cwd,
+      provider: observed.provider,
+      config: createConfig(),
+      permissionMode: 'bypassPermissions',
+      bare: true,
+    });
+    const stdout = captureStdout();
+
+    try {
+      const transport = createHeadlessTransport({
+        outputFormat: 'json',
+        prompt: 'Spawn agents in parallel',
+      });
+
+      session.attachTransport(transport);
+      await transport.start();
+
+      const output = parseJsonObject(stdout.writes.join('').trim());
+      expect(transport.getExitCode()).toBe(0);
+      expect(output).toMatchObject({
+        type: 'result',
+        result: 'The agent tool was not executed because it is not registered.',
+        subtype: 'success',
+      });
+      expect(observed.getChatCallCount()).toBe(3);
+      expect(observed.getToolResultContent()).toContain('not registered');
+      expect(observed.getToolResultContent()).toContain('not executed');
+      expect(observed.getForcedInstruction()).toContain(
+        'Those tool calls were not executed because they are not registered tools.',
+      );
+      expect(observed.getForcedInstruction()).toContain('agent');
+      expect(observed.getForcedCallToolNames()).toBeUndefined();
+    } finally {
+      stdout.restore();
+      await session.shutdown({
+        reason: 'prompt_input_exit',
+        message: 'Headless unknown tool test complete',
+      });
+    }
+  });
+});

package/src/headless/__tests__/headless-transport.test.ts

@@ -0,0 +1,268 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createHeadlessTransport } from '../headless-transport.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { IExecutionResult } from '@robota-sdk/agent-framework';
+
+function createMockSession(): IInteractiveSession {
+  return {
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([]),
+    getContextState: vi
+      .fn()
+      .mockReturnValue({ usedPercentage: 0, usedTokens: 0, maxTokens: 200000 }),
+    isExecuting: vi.fn().mockReturnValue(false),
+    getPendingPrompt: vi.fn().mockReturnValue(null),
+    executeCommand: vi.fn().mockResolvedValue({ message: 'ok', success: true }),
+    listCommands: vi.fn().mockReturnValue([]),
+    getSession: vi.fn().mockReturnValue({ getSessionId: () => 'test-session-id' }),
+    on: vi.fn(),
+    off: vi.fn(),
+  } as unknown as IInteractiveSession;
+}
+
+function createEventDrivenMockSession(
+  behavior: 'complete' | 'error' | 'interrupted' = 'complete',
+  options?: { response?: string; textDeltas?: string[] },
+): IInteractiveSession {
+  const listeners = new Map<string, Array<(...args: unknown[]) => void>>();
+  const response = options?.response ?? 'test output';
+  const textDeltas = options?.textDeltas;
+
+  return {
+    submit: vi.fn(async () => {
+      if (textDeltas) {
+        for (const delta of textDeltas) {
+          for (const h of listeners.get('text_delta') ?? []) {
+            h(delta);
+          }
+        }
+      }
+
+      if (behavior === 'complete') {
+        const result: IExecutionResult = {
+          response,
+          history: [],
+          toolSummaries: [],
+          contextState: {} as IExecutionResult['contextState'],
+        };
+        for (const h of listeners.get('complete') ?? []) {
+          h(result);
+        }
+      } else if (behavior === 'interrupted') {
+        const result: IExecutionResult = {
+          response,
+          history: [],
+          toolSummaries: [],
+          contextState: {} as IExecutionResult['contextState'],
+        };
+        for (const h of listeners.get('interrupted') ?? []) {
+          h(result);
+        }
+      } else if (behavior === 'error') {
+        for (const h of listeners.get('error') ?? []) {
+          h(new Error('test error'));
+        }
+      }
+    }),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([]),
+    getContextState: vi
+      .fn()
+      .mockReturnValue({ usedPercentage: 0, usedTokens: 0, maxTokens: 200000 }),
+    isExecuting: vi.fn().mockReturnValue(false),
+    getPendingPrompt: vi.fn().mockReturnValue(null),
+    executeCommand: vi.fn().mockResolvedValue({ message: 'ok', success: true }),
+    listCommands: vi.fn().mockReturnValue([]),
+    getSession: vi.fn().mockReturnValue({ getSessionId: () => 'test-id' }),
+    on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      if (!listeners.has(event)) listeners.set(event, []);
+      listeners.get(event)!.push(handler);
+    }),
+    off: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      const handlers = listeners.get(event);
+      if (handlers) {
+        const idx = handlers.indexOf(handler);
+        if (idx >= 0) handlers.splice(idx, 1);
+      }
+    }),
+  } as unknown as IInteractiveSession;
+}
+
+describe('createHeadlessTransport', () => {
+  it('returns an adapter with name "headless"', () => {
+    const transport = createHeadlessTransport({ outputFormat: 'text', prompt: 'hello' });
+    expect(transport.name).toBe('headless');
+  });
+
+  it('throws if start() is called without attach()', async () => {
+    const transport = createHeadlessTransport({ outputFormat: 'text', prompt: 'hello' });
+    await expect(transport.start()).rejects.toThrow('No session attached');
+  });
+
+  it('returns exit code 0 by default', () => {
+    const transport = createHeadlessTransport({ outputFormat: 'text', prompt: 'hello' });
+    expect(transport.getExitCode()).toBe(0);
+  });
+
+  it('full lifecycle: attach → start → text output → exit code', async () => {
+    const mockSession = createEventDrivenMockSession();
+
+    // Capture stdout
+    const writes: string[] = [];
+    const originalWrite = process.stdout.write;
+    process.stdout.write = vi.fn((chunk: string) => {
+      writes.push(chunk);
+      return true;
+    }) as never;
+
+    try {
+      const transport = createHeadlessTransport({ outputFormat: 'text', prompt: 'hello' });
+      transport.attach(mockSession as never);
+      await transport.start();
+
+      expect(transport.getExitCode()).toBe(0);
+      expect(writes.join('')).toContain('test output');
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+  });
+});
+
+describe('createHeadlessTransport (json adapter)', () => {
+  let stdoutWriteSpy: any; // allow-any: vi.spyOn process.stdout.write has incompatible MockInstance generic bounds
+
+  beforeEach(() => {
+    stdoutWriteSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stdoutWriteSpy.mockRestore();
+  });
+
+  it('full lifecycle: attach → start → JSON output → exit code', async () => {
+    const mockSession = createEventDrivenMockSession('complete', {
+      response: 'JSON adapter result',
+    });
+
+    const transport = createHeadlessTransport({ outputFormat: 'json', prompt: 'test prompt' });
+    transport.attach(mockSession as never);
+    await transport.start();
+
+    expect(transport.getExitCode()).toBe(0);
+    expect(stdoutWriteSpy).toHaveBeenCalledTimes(1);
+
+    const output = (stdoutWriteSpy.mock.calls[0] as [string])[0];
+    const parsed: unknown = JSON.parse(output.trim());
+    expect(parsed).toEqual({
+      type: 'result',
+      result: 'JSON adapter result',
+      session_id: 'test-id',
+      subtype: 'success',
+    });
+  });
+});
+
+describe('createHeadlessTransport (stream-json adapter)', () => {
+  let stdoutWriteSpy: any; // allow-any: vi.spyOn process.stdout.write has incompatible MockInstance generic bounds
+
+  beforeEach(() => {
+    stdoutWriteSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stdoutWriteSpy.mockRestore();
+  });
+
+  it('full lifecycle: attach → start → stream events + result', async () => {
+    const mockSession = createEventDrivenMockSession('complete', {
+      response: 'Hello world',
+      textDeltas: ['Hello', ' world'],
+    });
+
+    const transport = createHeadlessTransport({
+      outputFormat: 'stream-json',
+      prompt: 'test prompt',
+    });
+    transport.attach(mockSession as never);
+    await transport.start();
+
+    expect(transport.getExitCode()).toBe(0);
+
+    const lines = stdoutWriteSpy.mock.calls.map((call: unknown[]) => (call as [string])[0].trim());
+    const parsed = lines.map((line: string) => JSON.parse(line) as Record<string, unknown>);
+
+    // 2 stream_event lines + 1 final result line
+    expect(parsed).toHaveLength(3);
+
+    const streamEvents = parsed.filter(
+      (p: Record<string, unknown>) => p['type'] === 'stream_event',
+    );
+    expect(streamEvents).toHaveLength(2);
+
+    for (const evt of streamEvents) {
+      expect(evt['session_id']).toBe('test-id');
+      expect(evt['uuid']).toBeDefined();
+      const inner = evt['event'] as Record<string, unknown>;
+      expect(inner['type']).toBe('content_block_delta');
+      const delta = inner['delta'] as Record<string, unknown>;
+      expect(delta['type']).toBe('text_delta');
+    }
+
+    const firstDelta = (streamEvents[0]!['event'] as Record<string, unknown>)['delta'] as Record<
+      string,
+      unknown
+    >;
+    const secondDelta = (streamEvents[1]!['event'] as Record<string, unknown>)['delta'] as Record<
+      string,
+      unknown
+    >;
+    expect(firstDelta['text']).toBe('Hello');
+    expect(secondDelta['text']).toBe(' world');
+
+    const resultLine = parsed.find((p: Record<string, unknown>) => p['type'] === 'result');
+    expect(resultLine).toEqual({
+      type: 'result',
+      result: 'Hello world',
+      session_id: 'test-id',
+      subtype: 'success',
+    });
+  });
+});
+
+describe('createHeadlessTransport (error and interrupted)', () => {
+  let stdoutWriteSpy: any; // allow-any: vi.spyOn process.stdout.write has incompatible MockInstance generic bounds
+
+  beforeEach(() => {
+    stdoutWriteSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stdoutWriteSpy.mockRestore();
+  });
+
+  it('returns exit code 1 on error', async () => {
+    const mockSession = createEventDrivenMockSession('error');
+
+    const transport = createHeadlessTransport({ outputFormat: 'text', prompt: 'test prompt' });
+    transport.attach(mockSession as never);
+    await transport.start();
+
+    expect(transport.getExitCode()).toBe(1);
+  });
+
+  it('returns exit code 0 on interrupted', async () => {
+    const mockSession = createEventDrivenMockSession('interrupted', {
+      response: 'partial output',
+    });
+
+    const transport = createHeadlessTransport({ outputFormat: 'text', prompt: 'test prompt' });
+    transport.attach(mockSession as never);
+    await transport.start();
+
+    expect(transport.getExitCode()).toBe(0);
+    expect(stdoutWriteSpy).toHaveBeenCalledWith('partial output\n');
+  });
+});