Skip to content
sdlc

Headless agent CLI call spec

State: open/verified · Kind: module · Audience: system

Summary

Section titled “Summary”
  • One canonical, agent-agnostic call spec (AgentCallSpec) that best-effort translates into concrete invocations of headless coding-agent CLIs — claude, codex, gemini, opencode — with every approximation recorded as a CapabilityNote (native/approximated/emulated/dropped) instead of silently lost.
  • Pure plan/run split (planCall spec→argv/stdin/env, callAgent spawns and normalizes into a typed AgentResult) plus an optional conversation-capture layer that lifts the raw transcript into a portable agent-conversation/1 model.

Statement

Section titled “Statement”

Any code that shells out to a coding-agent CLI to get work done — run a prompt, set a permission posture, hand it context, ask for structured output, resume a session — otherwise rewrites the same argv builder, JSON-envelope parser, and retry glue per target CLI, and the CLIs disagree on nearly every flag name and behavior. This capability provides that glue once: a typed spec describes intent, per-CLI adapters (claude/codex/gemini/opencode, plus a customAdapter escape hatch for others) translate it, and the library never silently drops a field it can’t express — it reports the gap. It explicitly excludes orchestration (worktrees, queues, parallelism) and is the invocation primitive such tools build on.

What it provides

Section titled “What it provides”
  • AgentCallSpec — typed, agent-agnostic description of one call (prompt, permissions, context, output shape, session behavior).
  • planCall(adapter, spec) — pure, golden-testable spec→argv/stdin/env translation with capability notes; no side effects.
  • callAgent(adapter, spec) — spawns the planned call, applies a library-level timeout, returns a structured AgentResult (text, structured output, session id, usage, cost, raw output) that never throws on agent failure.
  • Built-in adapters for claude, codex, gemini, opencode, plus customAdapter for arbitrary one-shot CLIs.
  • Optional conversation capture (captureConversation: true) normalizing the transcript into agent-conversation/1, with assistantText/toolCalls helpers.

Underlying implementation

Section titled “Underlying implementation”
  • packages/ts/agent-call/src/spec.ts, plan.ts, run.ts, registry.ts, conversation.ts
  • packages/ts/agent-call/src/adapters/{claude,codex,gemini,opencode,custom}.ts

Locations

Section titled “Locations”
  • packages/ts/agent-call/

← Back to Capabilities