@robota-sdk/agent-transport-headless

@robota-sdk/agent-transport-headless

Headless transport adapter for non-interactive InteractiveSession execution. Used by @robota-sdk/agent-cli print mode (-p) to run one-shot prompts with structured output.

Installation

npm install @robota-sdk/agent-transport-headless

Usage

The headless runner is invoked via the CLI's print mode flag (-p). It does not perform interactive startup update checks, so stdout/stderr remain deterministic for scripts and CI jobs. Three output formats are supported:

Text (default)

Plain text output, suitable for piping:

robota -p "Explain this error"
robota -p "List all TypeScript files" | head -20
robota -p "/repo-writing backlog markdown format"

Prompts that start with /skill-name are passed to InteractiveSession.executeCommand(). When the upstream session composes @robota-sdk/agent-command-skills, the SDK normalizes the virtual skill alias to /skills <skill-name> [args] and loads the full skill file before the model turn.

JSON

Single JSON object with result and session metadata:

robota -p "Summarize the project" --output-format json

Output:

{ "type": "result", "result": "...", "session_id": "abc-123", "subtype": "success" }

Stream JSON

Newline-delimited JSON with real-time content_block_delta events, followed by a final result:

robota -p "Write a function" --output-format stream-json

Each line is a JSON object:

{
  "type": "stream_event",
  "event": { "type": "content_block_delta", "delta": { "type": "text_delta", "text": "..." } },
  "session_id": "abc-123",
  "uuid": "..."
}

Stdin Pipe

When no positional argument follows -p, input is read from stdin:

echo "Explain this code" | robota -p
cat error.log | robota -p "What went wrong?"
git diff | robota -p "Review this diff" --output-format json

System Prompt Flags

robota -p "query" --system-prompt "You are a code reviewer"
robota -p "query" --append-system-prompt "Focus on security issues"

API

import { createHeadlessRunner } from '@robota-sdk/agent-transport-headless';

const runner = createHeadlessRunner({
  session, // InteractiveSession from @robota-sdk/agent-sdk
  outputFormat, // 'text' | 'json' | 'stream-json'
});

const exitCode = await runner.run(prompt);
process.exit(exitCode);

ITransportAdapter

The headless transport implements the ITransportAdapter interface from @robota-sdk/agent-sdk:

import { createHeadlessTransport } from '@robota-sdk/agent-transport-headless';
import type { ITransportAdapter } from '@robota-sdk/agent-sdk';

const transport: ITransportAdapter = createHeadlessTransport({
  outputFormat: 'json',
  prompt: 'List all files',
});

transport.attach(interactiveSession);
await transport.start(); // Runs the prompt and writes output
const exitCode = transport.getExitCode();

Exit Codes

Code	Meaning
0	Success
1	Error

Documentation

See docs/SPEC.md for the full specification.

License

MIT