flutter_agent_harness 0.1.0

Cross-platform AI agent harness for Dart and Flutter: streaming provider adapters, agent loop with tools, session persistence, and context compaction. Ported architecture of pi-mono (packages/ai + pac [...]

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, and context compaction. Architecture ported from pi-mono (packages/ai + packages/agent), with a pure-Dart core that runs on the VM, Flutter desktop/mobile, and web.

Status: early development (Phase 0). See GOAL.md for the roadmap, quality gates, and design contract. The API is not yet stable.

Highlights (target design)

• Streaming-first: Stream<AgentEvent> from every provider, partial-first deltas — each event carries the current partial message.
• Errors-as-events: providers never throw; failures arrive as error events with a stopReason, so the agent loop never dies on a 429 or a dropped connection.
• Native tool calling (OpenAI tools, Anthropic tool_use, Google functionCalling) — no prompt-based JSON scraping.
• Token-based context management: inline usage accounting, overflow detection, LLM-powered compaction.
• Sessions as append-only JSONL trees behind a storage abstraction — portable to web and mobile.
• Cancellation everywhere via CancelToken.

Usage (current seed)

import 'package:flutter_agent_harness/flutter_agent_harness.dart';

void main() async {
  final source = CancelTokenSource();

  // Pass source.token into any long-running operation.
  final cancelled = source.token.onCancel.then((_) => print('aborted'));

  source.cancel('user pressed stop');
  await cancelled;
}

Provider adapters and the agent loop land in the next phases — see the roadmap in GOAL.md.

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.