AgentProvider: command, stdin, parser
Walk the clean-room TypeScript seam from prompt to parsed Factory result.
Pinned upstream commit: b189869b7755d2b482969acf6c92da3ecfeffd36
- Read the AgentProvider contract as a narrow waist.
- Explain why prompts travel through `/dev/stdin`.
- Distinguish provider options from production model routing.
The big idea
The provider has two jobs. Before launch, it turns Factory options into a safe Grok command and sends the prompt through standard input. During the run, it translates each JSONL line into Alembic's small event vocabulary. Everything else—sandbox launch, timeout, accumulation, and result return—stays with Factory.
Think of it like… The provider is an electrical plug adapter: it changes the shape at the boundary without rebuilding either appliance or wall. It breaks because the adapter also validates unsupported session behavior and translates a live event stream.
`buildPrintCommand` returns a shell command plus optional stdin. The prompt never enters argv, avoiding shell interpretation and per-argument size limits. The model and enum-like flags are shell-escaped. Factory's public AFK `run()` path requests permission bypass; containment remains the SandboxProvider's job.
The provider always disables Grok's built-in web search so Alembic research stays on the Bright Data CLI. Optional effort and environment map to the CLI; the fixed production roster remains unchanged. In the AFK run path, approval bypass is requested by the Orchestrator and containment comes from SandboxProvider.
Evidence: Pinned headless mode guide
Compare the boundaries
Safe: shell-escape model/flags and place the prompt in stdin.
Risky: interpolate user prompt into a shell command string.
| Surface | Upstream | Alembic | Verdict |
|---|---|---|---|
| Prompt transport | Could be inline argv | `--prompt-file /dev/stdin` | STDIN |
| Permissions | CLI supports approval modes | AFK run requests bypass; sandbox contains | LAYERED |
| Routing | Provider can be constructed | Fixed roster unchanged | SEPARATE |
The provider always disables Grok's built-in web search so Alembic research stays on the Bright Data CLI. Optional effort and environment map to the CLI; the fixed production roster remains unchanged. In the AFK run path, approval bypass is requested by the Orchestrator and containment comes from SandboxProvider.
Real code and commands
packages/factory/src/GrokAgentProvider.ts
return {
command: `grok --prompt-file /dev/stdin \
--output-format streaming-json --model ${shellEscape(model)} \
--disable-web-search`,
stdin: prompt,
};How to reach it
sed -n '1,170p' packages/factory/src/GrokAgentProvider.ts rg -n "export.*grok|GrokOptions" packages/factory/src/index.ts
Evidence: RESOURCES.md
Visual atlas
Practice and feedback
The prompt contains quotes and shell syntax. Which field should carry it?
Retrieval cards
Build the command safely
Choose an option set and inspect what changes—and what stays out of argv.
Four-slide summary
Check your model
What should never be interpolated into the command?