agent_harness 0.0.1-alpha.0

A protocol-neutral Dart SDK for local AI coding agents.

agent_harness

agent_harness is a protocol-neutral Dart API for local AI coding agents. It exposes one lifecycle across Claude Code, Codex, and Grok Build:

1. Create a lazy AgentProvider.
2. Probe the local CLI and required ACP bridge.
3. Launch an initialized Agent.
4. Create or resume an AgentSession and run prompts.
5. Close the Agent to terminate its owned process.

The package is native-only: it launches and supervises local processes, so it is not for Flutter web. It began life as ai_sdk in conceptadev/orbit and now lives in the Stargate Dart workspace.

Install

dart pub add agent_harness

Inside this workspace it resolves as a path member; no extra configuration is needed.

ACP providers and bridges

Agent Client Protocol (ACP) is the wire boundary used by the SDK. Claude Code and Codex need adapter processes because their normal CLIs do not provide the ACP command path consumed by agent_harness; Grok Build exposes ACP natively.

Provider factory	ACP command path	Reviewed release versions
claudeCode()	claude-agent-acp → claude	bridge 0.66.0, Claude Code 2.1.226
codex()	codex-acp → codex	bridge 1.1.14, Codex 0.145.0
grokBuild()	native grok agent stdio	Grok Build 1.0.0

Install the release-pinned Claude Code and Codex bridges with:

npm install -g @agentclientprotocol/claude-agent-acp@0.66.0 \
  @agentclientprotocol/codex-acp@1.1.14

Install and authenticate each provider CLI separately. probe() validates the required CLI and bridge without launching an agent and reports a diagnostic when either executable is unavailable or incompatible. The SDK never installs providers, manages their credentials, or silently substitutes another one.

import 'dart:io';

import 'package:agent_harness/agent_harness.dart';

Future<void> main() async {
  final provider = claudeCode();
  final readiness = await provider.probe();
  if (!readiness.isAvailable) {
    stderr.writeln(readiness.diagnostic);
    return;
  }

  final agent = await provider.launch();
  try {
    final session = await agent.createSession(
      AgentSessionOptions(cwd: Directory.current.path),
    );
    final turn = session.startPrompt(AgentPrompt.text('Summarize this repo.'));
    await turn.completed;
    stdout.writeln(session.snapshot.assistantText);
  } finally {
    await agent.close();
  }
}

Provider configuration accepts CLI and bridge executable overrides, a scoped environment, and an injectable ProcessExecutor. Factories are lazy: no discovery or process launch happens until probe() or launch().

Claude Code sessions enter plan mode by default. Codex starts in read-only mode. Permission requests without an installed handler are cancelled. These safe defaults can fail explicitly if a provider bridge cannot honor them.

Register client MCP servers explicitly with AgentSessionOptions.mcpServers. Prompts, updates, cancellation, session working directories, and resume all remain on the standard Agent and AgentSession APIs.

Low-level ACP transports, wire models, launch commands, and AcpAgent are available from package:agent_harness/acp.dart for advanced integrations.

Shared data, client-owned presentation

Read tool calls from session.snapshot.toolCalls, where the SDK has already merged partial updates. AgentToolCallDetails.fromUpdate(tool, providerId: provider.info.id) resolves known Claude Code, Codex, and Grok Build command, search, and MCP fields. It prefers ACP content, preserves unknown content, and leaves structured MCP results as JSON. It does not change the canonical update, infer completion, or sanitize content for display.

session.snapshot.availableCommands exposes typed AgentCommand values. AgentConfigOption exposes typed labels, its current value, and immutable AgentConfigChoice values while retaining the complete raw advertisement in value. Unsupported choice shapes fail explicitly. Clients still decide which command names and setting types their interface can use.

Consumers keep their own selected-session policy, permission queue, history, and rendering. Shared provider interpretation belongs here; UI notices, JSON pretty-printing, and terminal widgets do not. There is no runtime wrapper and no dependency on Flutter.

Provider compatibility uses sanitized, exact-version ACP recordings that replay fully offline. Capture always runs through the public provider lifecycle and writes a separate candidate; reviewed fixtures are never updated by a live or CI command. See doc/fixtures.md for the capture, validation, replay, and explicit-review workflow.