flutter_agent_harness

Cross-platform AI agent harness for Dart and Flutter — streaming provider
adapters, an agent loop with native tool calling, JSONL session persistence,
context compaction, and a pi-like terminal coding agent (fa). Architecture
ported from pi-mono
(packages/ai + packages/agent), with a pure-Dart core that runs on the
VM, Flutter desktop/mobile, and web.

fa1.dev — the project website: a live in-browser
demo of the full agent (sandboxed shell, git, interpreters — your key
stays in page memory), the iOS public
beta on TestFlight, the
macOS app,
and the CLI installer below.

Design contract

• Pure Dart core. No dart:io, no Flutter imports in lib/ — platform
  capabilities live behind abstractions (ExecutionEnv); the IO
  implementation is a separate entry point (lib/io.dart), so the core
  compiles for web.
• Errors-as-events. Providers never throw: network failures, 429s,
  malformed SSE — everything arrives as an error event with a stop
  reason. The agent loop never dies on a dropped connection.
• Streaming-first, partial-first. Stream<AgentEvent> everywhere;
  every delta event carries the live partial message.
• Native tool calling per provider (OpenAI tools, Anthropic
  tool_use, Google functionCalling). Prompt-based calling exists only
  as an opt-in adapter for chat-only runtimes.
• Token accounting inline, overflow detection per provider, and
  token-based (never message-count-based) context management.
• Cancellation everywhere via CancelToken — providers, loop, tools.

What's inside

• Agent core (lib/src/): the async agent loop, steering + follow-up
  message queues (inject input mid-run), hooks (beforeToolCall,
  afterToolCall, transformContext, prepareNextTurn), model roles
  (default/smol/slow/plan) with fallback chains, API-key rotation,
  429 mid-turn take-over, and stream watchdogs (connect + idle timeouts
  with config overrides).
• Providers: openai-completions (covers OpenRouter/DeepSeek/Kimi/Grok/…),
  Anthropic, Google, ChatGPT (Codex OAuth), Copilot (device flow), DIAL,
  MiniMax, z.ai, CodeMie (SSO), Ollama, plus custom providers saved from
  the REPL. One OpenAI-compatible adapter is reused via baseUrl swap.
• Sessions: append-only JSONL trees (branching, labels, tree
  navigation with branch summaries), token-based auto-compaction with a
  structured summary prompt, and attached-session support (watch a live
  CLI session and hand it input from the Flutter app).
• Tools: read (trailing selectors, archives, SQLite), write, ls,
  bash (background jobs, timeout-retry for transient stalls, per-turn
  approval grants), task (parallel subagents with typed roles and
  output schemas), lsp (diagnostics/definition/references/rename),
  MCP servers (stdio + remote), A2A interop, checkpoint/rewind,
  memory_* (git-backed long-term memory), ask, request_secret.
• Agent skills: <root>/<name>/SKILL.md plus Claude/Copilot/Codex
  layouts (.claude/skills, .github/skills, .codex/skills, user-level
  equivalents) discovered by default with an access prompt; typed
  frontmatter (allowed-tools, paths, context: fork), $ARGUMENTS
  rendering, and per-turn approval grants. See
  docs/migrating-from-claude-copilot-codex.md.
• Approval gate (lib/src/approval/): read/write/exec tiers, session
  modes (always-ask/write/yolo/unattended), per-tool overrides, and a
  critical-pattern interceptor for dangerous bash — even in yolo.
• Trajectory ledger (lib/src/trajectory/): every session projects
  into an immutable snapshot (turns, timeline modes, full-text search)
  rendered by the /trajectory REPL family and the fa trajectory
  headless command.
• Agent messaging: every agent owns a file inbox in a shared fabric —
  two fa instances chat live; subagents are first-class addressable
  mailboxes. A2A (fa serve --a2a) mounts the agent as a remote endpoint.
• Model-agnostic prompts (prompts/): all LLM prompts are versioned
  Markdown with override support — no prompt strings buried in code.

Install

curl -fsSL "https://fa1.dev/install.sh" | sh    # macOS / Linux / WSL
dart pub global activate flutter_agent_harness  # fa + fah on your PATH

The installer detects the OS/architecture, downloads a prebuilt binary
from the latest GitHub
Release,
puts it on your PATH, and (on macOS) strips Gatekeeper quarantine and
re-signs it. More install paths — the web demo, the Flutter app — live on
fa1.dev.

CLI (fa / fah)

A pi-like terminal coding agent: a full-screen TUI (streaming markdown,
mouse wheel scrolling, slash-command completion, live steering) with the
same core as the library. Sessions persist under
~/.fah/sessions/<cwd-slug>/.

export OPENROUTER_API_KEY=sk-or-...   # or ANTHROPIC_API_KEY / GOOGLE_API_KEY
dart run bin/fah.dart                 # defaults: OpenRouter, claude-sonnet-4
dart run bin/fah.dart --provider anthropic --model claude-sonnet-4-5
dart run bin/fah.dart --model openai/gpt-4o-mini --cwd . --session-root /tmp/fah

Headless mode runs a single non-interactive prompt and exits — the response
streams to stdout, tool indicators and notices go to stderr (stdout stays
pipeable), nothing is ever prompted interactively, and the session persists
like a REPL run. Exit codes: 0 ok, 1 provider error, 130 aborted (Ctrl-C).
A first positional naming an existing file becomes the prompt source: text
files (.md, .markdown, .txt) are inlined as the prompt; any other
(binary) file is attached as a path reference for the agent's tools — in
both cases trailing text appends as the instruction. A path that does not
exist is treated as plain prompt text.

fa "summarize the changelog"      # positional prompt
fa -p "fix the typos in README.md"  # -p/--prompt alias
fa CHANGELOG.md "summarize this"  # text file as prompt
fa screenshot.png "describe it"   # binary → path reference
fa "summarize the changelog" | pbcopy  # pipes cleanly

Flags: --model <id>,
--provider openai-completions|anthropic|google|dial|minimax|zai,
--base-url <url>, --cwd <dir>, --session-root <dir>, -p/--prompt <text>, --help, --version.

The chatgpt provider (Codex backend) is also available: sign in with a
ChatGPT account via /provider chatgpt oauth in the REPL (OAuth-only —
there is no headless --provider chatgpt flag). Several ChatGPT accounts
can coexist: the flow offers the saved accounts first, each account keeps
its own named entry and secure-store slot, and re-auth never touches a
sibling account's credentials.

Env preconfig (Docker / headless)

FA_PROVIDER_TYPE + FA_PROVIDER_CONFIG boot a declared provider with
no saved config, and the declaration becomes the session default for
every model role (default/smol/slow/plan) — the same selection a
/provider <name> switch makes:

FA_PROVIDER_TYPE=zai
FA_PROVIDER_CONFIG='{"baseUrl":"https://api.z.ai/api/coding/paas/v4","model":"glm-5.3","apiKeyEnvVar":"ZAI_API_KEY"}'
ZAI_API_KEY=sk-...

baseUrl and model are required — no catalog defaults fill gaps; a
missing field fails loud at boot. apiKeyEnvVar is optional: declared,
the named env var (or its _BASE64 twin) must hold the key; omitted,
the provider boots keyless and the spec's usual env names are never
probed. Every text value has a base64 twin for CI platforms that mangle
special characters — FA_PROVIDER_CONFIG_BASE64, and
<apiKeyEnvVar>_BASE64 for the key: the plain value wins when both
carry the same value; mismatched or malformed twins fail loud.

# base64 twin form (identical boot):
FA_PROVIDER_CONFIG_BASE64=$(printf '%s' "$FA_PROVIDER_CONFIG" | base64)
ZAI_API_KEY_BASE64=$(printf '%s' "$ZAI_API_KEY" | base64)

GitHub Copilot is a first-class provider. /provider copilot connects a
GitHub account via the device-code flow (open the shown
verification_uri, enter the user_code) or by pasting an existing PAT
— the flow works headless too — and the Flutter app offers the same
connect as a sheet. Accounts save as named entries (copilot-<login> by
default); the plan picks the host — individual api.githubcopilot.com,
business api.business.githubcopilot.com, enterprise
api.enterprise.githubcopilot.com, or a custom --base-url override —
and several accounts can coexist side by side. Tokens live only in the
OS secure store (Keychain / Secret Service); config.yaml carries name,
plan, and baseUrl, never a token. CI runs store-less via the
FA_KEY_COPILOT_<NAME> env (plus a _2… ring for more entries), and
headless runs take --provider copilot --model <id> with
COPILOT_GITHUB_TOKEN. Models come from a live GET /models (with
capabilities and limits). The device-flow client id is overridable via
FA_COPILOT_CLIENT_ID — that GitHub endpoint is undocumented, so a
custom client id carries an account-ban risk; override only with cause.

Sleep prevention (power.sleepPrevention, power.hold)

Long-running runs die with the machine: when the Mac sleeps mid-run,
scheduled wake-ups never deliver. A power assertion holds the machine
awake while the agent is WORKING — by default one assertion per RUN,
acquired when the run goes in flight and released when it settles, so
an agent idling between turns never pins the machine awake for hours.
Controlled by ~/.fah/config.yaml:

power:
  sleepPrevention: idle # off | idle (default) | display | system
  hold: per-run # per-run (default) | session (hold the whole session)

Levels are cumulative — idle prevents idle sleep (caffeinate -i),
display also keeps the display awake (-i -d), system also blocks
AC system sleep and declares the user active (-i -d -s -u). hold: session opts into holding the assertion from session start to exit
(always-on deployments). macOS runs caffeinate -w <fa pid> (it
self-exits with fa, so the assertion can never leak); Linux tries
systemd-inhibit --what=idle:sleep behind a pid watchdog; other
platforms no-op. A failed assertion logs a warning and the run
continues; a helper that ignores SIGTERM at release gets a SIGKILL
after 5s and release proceeds. /power shows the level, the hold, and
whether the assertion is currently held (pmset -g assertions on macOS
shows the real thing). Windows (SetThreadExecutionState) is a tracked
stub.

Slash commands (selection)

/provider, /models, /model, /approval, /allow, /tools,
/skills, /agents, /tasks, /trajectory [view|cost|tail|inspect],
/memory [maintain], /power, /compact, /reset, /checkpoint//rewind,
/mcp, /a2a, /dap, /stats, /mouse, /settings, /help — plus
every discovered skill as /skill:<name> (a bare /<name> alias works
too). While a run streams, typed input steers the agent; Ctrl-C aborts
the current run (Ctrl-C at the idle prompt exits).

Tool calls pass the approval gate (see above); mode and always-allowed
tools persist in ~/.fah/config.yaml. Tool availability can be scoped
per project/session via .fah/config.yaml and .tools/<id>.yaml
(see docs/tool-availability.md).

The CLI core (AgentCli + CliIO) is pure Dart and lives in
lib/src/cli/; only bin/fah.dart and lib/io.dart touch dart:io.

Agent-to-agent messaging (DAP)

The CLI ships a default-on DAP/1 hub plugin (bin/fah_hub_plugin.dart +
the hosted fah_hub_client pub package): agents connect to a hub over a signed
WebSocket, exchange end-to-end encrypted channel messages and DMs (the
hub only ever sees ciphertext), and see each other's presence. Inbound
hub mail is drained into the agent loop as steering messages; /dap and
the dap_* tools drive the connection. See docs/dap.md
for the protocol, the hub server, and an end-to-end setup walkthrough.

Browser extension

browser_ext/ pairs a local fa with Chrome over a loopback WebSocket
bridge — or runs the agent fully self-contained in the extension's
service worker: docs/browser-extension.md.

Outlook add-in

fa also runs as an Outlook taskpane (approval-gated mail tools on top
of the same agent core) — install guide and troubleshooting:
docs/outlook-addin.md.

Mobile automation (Android)

Two Android flavors: store (Play; mobile.launch + mobile.logs) and
god (sideload only, same release key, distinct applicationId; adds
hierarchy / tap / swipe / text / screenshot + opt-in mobile.shell over
Shizuku), gated by the issue #19 availability floor:

Details — tiers, sideload, Shizuku, consent, security, E2E checklist:
docs/android-automation.md · god build.

Development

dart pub get
dart test --coverage=coverage --exclude-tags integration
dart run coverage:format_coverage --lcov -i coverage -o coverage/lcov.info
python3 scripts/check_coverage.py

Pre-commit hook (analyze + tests + coverage ≥ 80% + duplication < 1%):

cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

License

MIT — see LICENSE.