Documentation
¶
Overview ¶
Package opencode drives OpenCode 1.19.5 headless: one `opencode run` per worker job, resumed by session id, and the bare TUI for an attached foreman chat. Credentials remain in the CLI's own store (`opencode auth login`); the adapter supplies none.
Index ¶
- Constants
- type Adapter
- func (a *Adapter) AttachCommand(job adapter.Job, workdir, resumeSessionID, _ string) (*exec.Cmd, error)
- func (a *Adapter) Command(job adapter.Job, workdir, resumeSessionID string) (*exec.Cmd, error)
- func (a *Adapter) Name() string
- func (a *Adapter) ParseErrEvent(line []byte) (adapter.Event, bool)
- func (a *Adapter) ParseEvent(line []byte) (adapter.Event, bool)
- func (a *Adapter) ProbeCommand(ctx context.Context) *exec.Cmd
- func (a *Adapter) ResultText(events []adapter.Event) string
- func (a *Adapter) WritebackSessionID(ctx context.Context, workdir, resumeSessionID string) (string, error)
Constants ¶
const DefaultModel = "default"
DefaultModel names the CLI's own default, without passing a model flag.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
Binary string // empty means "opencode"
Agent string // optional --agent preset
// contains filtered or unexported fields
}
Adapter drives the opencode CLI. Its zero value resolves opencode on PATH.
func (*Adapter) AttachCommand ¶
func (a *Adapter) AttachCommand(job adapter.Job, workdir, resumeSessionID, _ string) (*exec.Cmd, error)
AttachCommand implements adapter.Interactive (§4.2 item 1): the CLI's own terminal — the bare `opencode` TUI — continuing the foreman's session by id. There is no fork onto a caller-minted id (the CLI has no --session-id to take one), so the chat runs on the id it resumed and the release writes that id back (WritebackSessionID); newSessionID is unused. The opening prompt rides --prompt, which the 1.19.5 TUI places in its input box rather than sending: the chat's first Enter submits it. The bridge rides OPENCODE_CONFIG_DIR and the foreman scope OPENCODE_PERMISSION, both as a headless turn carries them, and OPENCODE_DISABLE_PROJECT_CONFIG keeps the checkout's own config out; the user's global config still loads, its MCP servers beside the bridge. The model and effort ride -m and --variant as in Command, and StatusLine is ignored: the TUI has no status bar a command feeds.
PWD is set to workdir, the reading checkout, by replacePWD above: the attach does not run through the runner's exec, which sets PWD for every worker command (§5.2), so the adapter carries it itself.
func (*Adapter) Command ¶
Command passes the prompt as one positional argument after --. OpenCode permits edits headless by default, matching worker policy, and workerPermissions limits bash to the job's mapped tool scope (none for a review) and denies paths outside the worktree. A foreman job — one carrying an MCP config — instead runs the foreman scope (foremanPermissions), with the bridge offered through a config directory of the adapter's own beside the runner's MCP config. Never pass --auto (or its permission-bypass aliases); permission rules ride the environment, not the CLI's project config.
OpenCode picks its directory as options.root ?? process.env.PWD ?? process.cwd() and chdirs there (packages/cli/src/run/run.ts:74, run/v1.ts:29, mini.ts localDirectory), so cmd.Dir alone is not enough: the runner sets PWD to the worktree on every command it starts.
func (*Adapter) ParseErrEvent ¶
ParseErrEvent recognizes the same JSON shapes on stderr, plus the one fixed-format line the headless run path prints when it auto-rejects a permission ask — never arbitrary prose containing words such as "quota" or "key".
func (*Adapter) ParseEvent ¶
ParseEvent maps completed assistant text, tool states and provider errors. step_start supplies the session id without stealing a message/tool event. The CLI currently emits tool_use only for completed/error states, so real runs have tool ends without starts; do not invent starts from step_start (a model step is not a tool). If a running ToolPart is emitted, its schema maps directly to a start. Unknown tool states and event types stay ignored.
func (*Adapter) ProbeCommand ¶
ProbeCommand implements adapter.Adapter: `opencode --version`, a cheap command that answers when the CLI is well (§8 "Health"), bound to ctx so a hung CLI is killed and reads as a failing probe.
func (*Adapter) ResultText ¶
ResultText is the run's last assistant message, which the worker/review contract reads (§5.4). Tool, session, reasoning and usage events cannot replace it, and earlier assistant messages are never concatenated into it.
func (*Adapter) WritebackSessionID ¶
func (a *Adapter) WritebackSessionID(ctx context.Context, workdir, resumeSessionID string) (string, error)
WritebackSessionID implements adapter.SessionWriteback: an attached opencode chat continues under the id it resumed — the CLI mints no id a caller names — so that id is the write-back unchanged, and a chat that started fresh is discovered from the CLI's own session list afterwards: the newest session of the checkout, which is brigada's alone (the checkout lives under the runner's state, and the attach holds the foreman's live slot while the chat runs, so nothing else starts a session there). A discovery that fails returns an error; the caller falls back to its minted id, which the CLI does not know, and the next headless turn refuses the resume and starts fresh in place (§5.6).
Source Files