flutter_agent_harness library

Cross-platform AI agent harness for Dart and Flutter.

Ported architecture of pi-mono (packages/ai + packages/agent): streaming provider adapters with an errors-as-events contract, an agent loop with native tool calling, JSONL session persistence, and context compaction. See GOAL.md for the full roadmap.

Classes

ActiveToolsChangeRecord
Records a change of the active tool set.
AfterToolCallContext
Context passed to AfterToolCallHook.
AfterToolCallResult
Partial override returned from AfterToolCallHook.
Agent
Stateful wrapper around the low-level agent loop.
AgentCli
The CLI harness: agent + built-in tools + session persistence + compaction, driven by a CliIO.
AgentCliConfig
Static configuration for an AgentCli session.
AgentEndEvent
The loop finished. Always the last event; carries every message produced by this run (prompts included for agentLoop, excluded for agentLoopContinue).
AgentEvent
Events emitted by the agent loop.
AgentEventStream
The event stream returned by agentLoop and agentLoopContinue.
AgentLoopConfig
Configuration for one agent loop run.
AgentLoopTurnUpdate
Replacement runtime state used by the loop before another provider request. Ported subset of pi's AgentLoopTurnUpdate (no thinkingLevel: reasoning levels are not ported yet).
AgentMode
A system-prompt mode for the CLI (e.g. /architect, /code, /review).
AgentOutputManager
Manages agent output id allocation to ensure uniqueness (port of omp's AgentOutputManager).
AgentOutputStore
Session-scoped store of subagent outputs addressable via agent://.
AgentSessionManager
Manages several concurrent agent sessions.
AgentStartEvent
The loop started processing a prompt or continuation.
AgentState
Public agent state. Ported from pi's AgentState.
AgentTool
A tool the model may invoke: name, description, JSON-schema parameters, and the Dart callback that executes it.
AgentUrlResolution
A resolved agent:// resource.
AnthropicOptions
Options for streamAnthropic.
ApiKeyCredential
One credential in an ApiKeyRing: its secrets-store name and secret value. The value must never be logged or sent to the model.
ApiKeyRing
A rotating view over one provider's API-key stack.
ApprovalManager
Holds the approval state of a session and resolves policy per tool call.
ApprovalOutcome
The outcome of an ApprovalManager.authorize check.
ApprovalRequest
One approval prompt, handed to the ApprovalPrompt callback.
ArchiveDirectoryEntry
A direct child of an archive directory (omp's ArchiveDirectoryEntry).
ArchiveNode
Metadata for one archive node (omp's ArchiveNode).
ArchivePathCandidate
One {archivePath, subPath} split of an archive.ext:inner/path reference (omp's ArchivePathCandidate).
ArchiveReader
An indexed, read-only view over a single archive (omp's ArchiveReader, reduced to read/list). Decoding happens up front in ArchiveReader.decode via package:archive; member bytes are inflated on demand by readFileBytes.
AskAnswer
The user's answer to one AskQuestion: selected option labels and/or free text.
AskOption
One selectable option of an AskQuestion.
AskQuestion
One structured question for the host's AskCallback.
AssistantMessage
A message produced by the assistant (the model), final or partial.
AssistantMessageEvent
Event protocol for AssistantMessageEventStream.
AssistantMessageEventStream
The event stream returned by provider stream calls.
BeforeToolCallContext
Context passed to BeforeToolCallHook.
BeforeToolCallResult
Result returned from BeforeToolCallHook.
BranchPreparation
Messages and file operations extracted for a branch summary (omp's BranchPreparation).
BranchSummaryRecord
Marks a branch the conversation navigated away from, with an optional summary projected into the context of the new branch.
BranchSummaryResult
Outcome of generateBranchSummary (omp's BranchSummaryResult): success carries summary plus the tracked file lists; failure carries error (or aborted) instead of throwing.
BraveSearchProvider
Brave web search via the official REST API, keyed by BRAVE_API_KEY.
CancelToken
Cooperative cancellation, the Dart counterpart of the web AbortSignal.
CancelTokenSource
The writable side of a CancelToken. Keep it private to the caller that owns the operation; hand only the token to callees.
ChainEntry
One entry of a FallbackStreamFunction's chain: the model to call, its key ring, and the per-key stream factory.
CheckpointRecord
Marks a self-service context checkpoint created by the checkpoint tool so a later rewind can collapse the exploratory detour into a report.
CheckpointRewindController
Orchestrates the checkpoint/rewind flow for one Agent.
CheckpointSessionSink
The host seam for session persistence the controller drives.
CheckpointState
The captured checkpoint mark (omp's CheckpointState).
CliArgs
A parsed run configuration (interactive or headless).
CliArgsHelp
--help/-h was passed: print usage and exit 0.
CliArgsResult
The outcome of parsing the fah argument list.
CliArgsVersion
--version was passed: print the version and exit 0.
CliIO
Terminal IO abstracted for testability.
CompactionManager
The compaction pipeline over a Session, mirroring pi's harness-level compact().
CompactionPreparation
Prepared inputs for a compaction run.
CompactionPrompts
The four summarization prompts used by the compaction pipeline, bundled so CLI prompt overrides (the prompts: config section, see lib/src/prompts/prompt_overrides.dart) can replace them without changing the pipeline's shape. The defaults are the built-in prompts: defaultCompactionPrompts is byte-identical to the historical constants.
CompactionRecord
Marks a compaction point: summary replaces everything before firstKeptEntryId when the context is rebuilt.
CompactionResult
Generated compaction data ready to persist as a CompactionRecord.
CompactionSettings
Compaction thresholds and retention settings.
CompletedRewind
A completed rewind retained for the repeat-call guard (omp's CompletedRewindState).
ContentBlock
A content block of a Message.
Context
Everything a provider needs to produce the next assistant message.
ContextUsageEstimate
Estimated context-token usage for a message list.
CriticalBashPattern
A destructive shell pattern with a human-readable label, surfaced in the approval prompt's reason.
CustomMessageRecord
An application-defined record that projects into model context as a user message.
CustomRecord
An application-defined record that is omitted from model context by default.
CutPointResult
Cut point selected for compaction.
DoneEvent
Terminal event: the message completed successfully.
DuckDuckGoSearchProvider
DuckDuckGo search via the keyless no-JS HTML frontend.
Err<T, E>
A failed Result.
ErrorEvent
Terminal event: the stream failed or was aborted.
EventStream<T, R>
A push-based stream of events with an awaitable final result.
ExecutionEnv
Filesystem and process execution environment used by the harness.
FahPlugin
Base interface for a fah plugin / package extension.
FallbackNotice
The no-silent-degrade note: emitted through the listener callback before every retry/rotation/failover so the degradation is always visible.
FallbackStreamFunction
A StreamFunction over an ordered ChainEntry list with omp's rate-limit policy: rotate keys for free, retry the entry with capped exponential backoff, then fail over to the next entry — every step announced through onNotice.
FileInfo
Metadata for one filesystem object.
FileOperations
File paths touched by a compaction range.
FileSystem
Filesystem capability used by the harness.
GoogleOptions
Options for streamGoogle.
GoogleThinking
Thinking configuration for Gemini models.
HashlineAnchor
A line-number anchor (1-indexed).
HashlineApplyResult
Result of applying a parsed set of edits to a text body.
HashlineCursor
Where an insert edit should land relative to existing content.
HashlineCursorAfter
Insert immediately after anchor (INS.POST N:).
HashlineCursorBefore
Insert immediately before anchor (INS.PRE N:).
HashlineCursorBof
Insert at the very start of the file (INS.HEAD:).
HashlineCursorEof
Insert at the very end of the file (INS.TAIL:).
HashlineDelete
Delete the line at anchor.
HashlineEdit
A single low-level edit produced by the parser and consumed by the applier. Multi-line replacements decompose to one insert per replacement line plus one delete per consumed line. Replacement payloads are tagged so the applier can distinguish literal insertion from new content for a deleted line.
HashlineInsert
Insert text at cursor. replacement marks payload lines lowered from a SWAP N.=M: hunk (new content for the deleted range).
HashlineParseResult
Result of parsing one section body: the flat edit list plus diagnostics.
HashlinePatch
A parsed hashline patch — zero or more HashlinePatchSections, each rooted at a [PATH#HASH] header.
HashlinePatcher
High-level patcher. Wires an ExecutionEnv and a HashlineSnapshotStore together with the parsing + applying core. Construct once per session; reuse across patches.
HashlinePatcherApplyResult
Aggregate result of HashlinePatcher.apply.
HashlinePatchSection
One section of a parsed HashlinePatch: a target file plus the lazily-parsed list of edits that should land on it.
HashlinePreparedSection
Opaque token returned by HashlinePatcher.prepare. Carries the section, the raw file content read off the filesystem, and the in-memory apply result. HashlinePatcher.commit just writes it.
HashlineRange
A parsed [A.=B] line range (1-indexed, inclusive on both ends).
HashlineSectionResult
Per-section result returned by HashlinePatcher.apply / HashlinePatcher.commit.
HashlineSnapshot
One full-file version observed at a point in time. The tag the model sees is hash; diagnostics replay against text.
HashlineSnapshotStore
In-memory snapshot store: a bounded set of paths, each with a short history of full-file versions so in-session edit chains can still recover against the version a stale tag names.
HtmlTag
One scanned HTML tag (open, close, or self-closing).
HtmlText
A plain-text chunk between tags.
ImageContent
An image supplied by the user or a tool result.
InMemorySecretsStore
A SecretsStore backed by a plain map. This is the web/default implementation and is convenient in tests.
InspectImageConfig
Configuration for the inspectImageTool vision model.
InspectImagePlugin
Plugin that contributes the inspect_image tool.
JsonlSessionCreateOptions
Options for JsonlSessionRepo.create.
JsonlSessionRepo
JSONL session repository on top of a FileSystem.
JsonlSessionStorage
Append-only JSONL session storage on top of a FileSystem.
KeyEvent
A single key press from an interactive terminal in raw mode.
LabelRecord
Attaches (or removes, when label is null) a human-readable label to another record, e.g. a bookmark in the tree UI.
LeafRecord
Marks the active leaf of the tree after a branch navigation.
LineRange
Inclusive line range described by one selector segment (e.g. 50-100, 301-, or 50+10). A null endLine means open-ended ("to EOF").
LspAppliedChange
One applied change, for the tool's report (omp's applied-change lines).
LspClient
A live connection to one language server process.
LspClientManager
Owns the LspClient pool for one lsp tool instance.
LspConfig
The resolved server configuration for a workspace (omp's LspConfig).
LspDiagnostic
LSP diagnostic.
LspLocation
LSP location: a range inside a document.
LspMessageFramer
Incremental Content-Length framer. Not thread-safe (Dart is single threaded); one framer per server connection.
LspPosition
LSP position (0-indexed line and character on the wire).
LspRange
LSP range.
LspServerConfig
One language server definition (omp's ServerConfig, reduced).
LspTextEdit
LSP text edit: replace range with newText.
LspToolConfig
Configuration for the lsp tool; one per agent session (the client pool is session-scoped through it, like the task tool's stores).
LspTransport
A live byte channel to a language server process: framed JSON-RPC goes out through write, raw server output arrives on messages.
LspWorkspaceEdit
A parsed WorkspaceEdit (omp's WorkspaceEdit, reduced to text edits).
ManagedSession
One managed session: the Agent, its persistent Session, and the metadata that identifies it.
MemoryExecutionEnv
In-memory ExecutionEnv: MemoryFileSystem plus a Shell.
MemoryFileSystem
In-memory FileSystem with POSIX-style (/-separated) paths.
Message
A message in a conversation context.
MessageEndEvent
A message is complete: the final assistant message, a prompt, or a tool result.
MessageRecord
A conversation message appended to the tree.
MessageStartEvent
A message entered the transcript: a prompt, a (partial) assistant message, or a tool result.
MessageUpdateEvent
The streamed assistant message advanced. Only emitted for assistant messages; message is the live partial snapshot carried by assistantMessageEvent.
Model
A model the harness can call.
ModelChangeRecord
Records a change of the active model.
ModelCost
Per-million-token pricing for a model, in USD.
ModelRef
One entry of a role's fallback chain: a concrete model plus an optional API-key base-name override.
ModelRolesConfig
Model-role configuration: role → ordered fallback chains, path-scoped overrides, and the retry policy.
ModelRolesResolver
Builds per-role fallback chains from configuration and secrets.
ModelRolesRetryPolicy
Knobs for the rate-limit retry/fallback engine, mirroring omp's non-compaction retry policy (retry.* settings).
NextTurnContext
Context passed to PrepareNextTurnHook after a turn fully completes.
Ok<T, E>
A successful Result.
OpenAICompletionsCompat
Compatibility flags for OpenAI-compatible chat-completions endpoints.
OpenAICompletionsOptions
Options for streamOpenAICompletions.
PathRoleOverride
A path-scoped set of role chains, applied when the cwd matches pattern.
PluginContext
Context passed to FahPlugin.register. Plugins use it to contribute capabilities to the running agent session.
PluginIO
IO surface exposed to plugins for writing to the terminal.
ProjectContextFile
One discovered context file.
PromptOverrides
Resolved prompt overrides: canonical prompt name → override text.
PromptTemplate
A prompt template loaded from a markdown file.
PromptToolOptions
Options for promptToolStreamFunction.
ProviderSpec
Static description of a supported provider.
PubDevHandler
Renders pub.dev package pages (/packages/<name>) from the pub.dev API instead of scraping the HTML page (ported from omp's scrapers/pub-dev.ts): metadata, score metrics, SDK constraints, dependencies, and recent versions as structured markdown.
ReadSelector
The parsed trailing selector of a read path (omp's ParsedSelector).
ReadSelectorLines
One or more (sorted, merged) line ranges, optionally with raw output (:range:raw / :raw:range).
ReadSelectorNone
No selector (or an unrecognized one left for archive/SQLite/URL readers).
ReadSelectorRaw
:raw alone — verbatim whole-resource output.
Result<T, E>
Result of a fallible operation. Expected failures are returned as Err instead of thrown — FileSystem operations must never throw.
SecretRedactor
Holds secret values and replaces them with SecretRedactor.mask in text.
SecretsExecutionEnv
An ExecutionEnv that injects secret env vars into every exec.
SecretsStore
A read-only bulk source of secrets, name → value.
Semaphore
Simple counting semaphore for limiting concurrency across independently scheduled async work (port of omp's Semaphore).
ServerSentEvent
A parsed Server-Sent Event.
Session
A session: an append-only tree of records with an active leaf.
SessionContext
The model-derived state of a session along the active branch.
SessionHeader
The session header — always the first line of a JSONL session file.
SessionInfoRecord
Records session-level information such as a display name.
SessionMetadata
Metadata describing a stored session.
SessionRecord
One entry in the append-only session tree.
SessionRepo
The repository contract for sessions.
SessionStorage
The storage contract behind a Session tree.
Shell
Shell execution capability used by the harness.
ShellExecOptions
Options for Shell.exec.
ShellExecResult
Outcome of a completed Shell.exec invocation.
Skill
One discovered skill (metadata only; the body stays on disk for progressive disclosure via the read tool).
SplitReadPath
Result of splitting a read path into its filesystem path and an optional trailing selector string (omp's { path, sel? }).
SqliteDatabase
An open SQLite database. All methods are synchronous: the underlying FFI calls are synchronous too.
SqliteEngine
Opens SQLite databases for the read tool. The FFI-backed implementation lives behind lib/io.dart; web hosts pass no engine.
SqliteListSelector
db.sqlite — list non-sqlite_% tables with row counts.
SqlitePathCandidate
One {sqlitePath, subPath, queryString} split of a db.sqlite:table?query reference (omp's SqlitePathCandidate).
SqlitePkLookup
Lookup by primary-key column.
SqliteQuerySelector
db.sqlite:table?limit=…&offset=…&order=…&where=… — paged table query.
SqliteRawSelector
db.sqlite?q=SELECT … — raw read-only SQL.
SqliteRowidLookup
Lookup by rowid (tables without a primary key).
SqliteRowLookup
How a row lookup resolves: by the single primary-key column, or by rowid (omp's SqliteRowLookup).
SqliteRows
A query result: column names plus rows as column→value maps.
SqliteRowSelector
db.sqlite:table:key — row lookup by primary key (or rowid).
SqliteSchemaSelector
db.sqlite:table — schema plus sample rows.
SqliteSelector
The parsed SQLite target selector (omp's SqliteSelector).
SqliteTablePage
A paged table query result with the total row count for continuation notes (omp's queryRows return shape).
SqliteTableSummary
Row count for a table in the listing: exact when the table is provably small, otherwise a lower bound (omp's TableRowCount, minus the sqlite_stat1 estimate variant).
SseDecoder
Decodes a stream of text chunks into ServerSentEvents.
StartEvent
Emitted once before any content events.
StructuredTaskOutput
Parsed structured completion plus its validation metadata (omp's StructuredSubagentOutput, reduced: no source/mode — v1 schemas always come from the call item).
SummarizationRequest
A single summarization request handed to a SummarizeFn.
SummarizationResult
Result of a SummarizeFn call. Success carries text; failure carries error and optionally marks the call as isAborted.
TaskAgentDefinition
Definition of a subagent type spawnable through the task tool (omp's AgentDefinition, reduced: no spawns, thinkingLevel, frontmatter output, or file source).
TaskAgentRegistry
Resolves agent types for task calls: TaskAgentRegistry.resolve finds a type by name, TaskAgentRegistry.toolSurfaceFor computes a type's restricted child tool surface.
TaskExecutor
Runs task batch items as child Agents under a session Semaphore.
TaskItem
One unit of work in a task batch call (omp's TaskItem, reduced: no isolated, no schemaMode).
TaskJob
One background subagent job (omp's type: "task" async job, reduced). The job id IS the allocated agent id (omp semantics), so a settling job's result stays addressable as agent://<id>.
TaskJobManager
Session-scoped registry of background task jobs (reduced port of omp's AsyncJobManager role for task spawns).
TaskSingleResult
Result of a single subagent execution (omp's SingleResult, reduced).
TaskToolConfig
Configuration for taskTool. One config per session: the semaphore, outputs store, and jobManager are session-scoped through it, so repeated (and concurrent) task calls share the concurrency bound and the agent:// id space (omp's session-scoped TaskTool instance).
TavilySearchProvider
Tavily search via the agent-focused API, keyed by TAVILY_API_KEY.
TextContent
Plain text produced by the model.
TextDeltaEvent
Incremental text for the block at contentIndex.
TextEndEvent
The text block at contentIndex is complete.
TextStartEvent
A text content block started at contentIndex.
ThinkingContent
Model reasoning ("thinking") produced before or alongside the answer.
ThinkingDeltaEvent
Incremental thinking text for the block at contentIndex.
ThinkingEndEvent
The thinking block at contentIndex is complete.
ThinkingLevelChangeRecord
Records a change of the model's thinking level.
ThinkingStartEvent
A thinking content block started at contentIndex.
Tool
A tool the model may invoke, with a JSON Schema for its parameters.
ToolCall
A request by the model to invoke a tool.
ToolCallDeltaEvent
Incremental JSON argument text for the tool call at contentIndex.
ToolCallEndEvent
The tool call at contentIndex is complete; toolCall has fully parsed ToolCall.arguments.
ToolCallStartEvent
A tool call started at contentIndex.
ToolExecutionEndEvent
Execution of a tool call finished (successfully or with an error result).
ToolExecutionResult
Final or partial result produced by a tool execution.
ToolExecutionStartEvent
Execution of a tool call started.
ToolExecutionUpdateEvent
A tool reported a partial execution result.
ToolRegistry
A named collection of AgentTools with a ready-made executor for the agent loop.
ToolResultMessage
The result of executing a tool the model asked to invoke.
TranscribeAudioConfig
Configuration for the transcribeAudioTool transcription endpoint.
TranscribeAudioPlugin
Plugin that contributes the transcribe_audio tool.
TtsrConfig
A parsed TTSR configuration: manager settings plus the rules to monitor.
TtsrController
Orchestrates TTSR for one Agent.
TtsrManager
Registry + matcher for time-traveling stream rules.
TtsrMatchContext
Context about the stream content currently checked against TTSR rules (omp's TtsrMatchContext, minus file-path candidates).
TtsrRule
A time-traveling stream rule (omp's Rule, reduced to regex conditions).
TtsrScope
The streams a rule monitors (omp's parsed TtsrScope).
TtsrSessionSink
The host seam for session persistence the controller drives.
TtsrSettings
TTSR settings (omp's TtsrSettings, reduced).
TurnEndEvent
A turn finished: the assistant message completed and its tool calls (if any) produced toolResults.
TurnStartEvent
A new turn (assistant response + tool calls) started.
UnavailableShell
A Shell that reports ExecutionErrorCode.shellUnavailable for every command — the correct behavior on platforms without a process shell (web, or any sandboxed environment).
Usage
Token accounting for one assistant response, reported inline by providers.
UsageAccumulator
Mutable accumulator summing Usage across turns of an agent run.
UsageCost
Monetary cost of a request, in USD.
UserMessage
A message authored by the user.
WebFetchContext
The extraction context handed to WebSiteHandlers: shared HTTP plumbing so handlers reuse the tool's client, timeout, and byte cap.
WebFetchResult
One extracted page: structured markdown plus the method that produced it (omp's RenderResult, reduced).
WebPage
A fetched web page: status, content type, and decoded body.
WebSearchConfig
Configuration for webSearchTool and webFetchTool.
WebSearchProvider
A search backend the web_search tool can walk in its fallback chain.
WebSearchRequest
One search request passed down the provider chain.
WebSearchResponse
One provider's answer to a search query (omp's SearchResponse).
WebSearchSource
One ranked search result: title, URL, and an optional snippet.
WebSiteHandler
A site-specific extraction handler (omp's SpecialHandler). Handlers are tried in order before the generic HTML→markdown converter; the first non-null result wins.

Enums

ApprovalDecision
The user's answer to an approval prompt.
ApprovalMode
Session-wide approval posture.
ApprovalPolicy
The resolved policy for one tool call.
ApprovalTier
How much damage a tool call can do, worst case.
ArchiveFormat
Recognized archive containers.
CompactionErrorCode
Stable error codes for CompactionException, ported from pi's CompactionError kinds.
ExecutionErrorCode
Stable, backend-independent error codes returned by Shell.exec.
FallbackNoticeKind
What the wrapper is about to do after a rate-limit failure.
FileErrorCode
Stable, backend-independent error codes returned by FileSystem operations.
FileKind
Kind of filesystem object addressed by a FileSystem.
ForkPosition
Where a fork cut point sits relative to JsonlSessionRepo.fork's entryId.
HashlineSectionOp
Per-section outcome of HashlinePatcher.commit.
KeyType
Kinds of keys recognized by the TUI input loop.
LineEnding
Line-ending style of a text body.
LspClientStatus
Client lifecycle state (omp's status).
LspDiagnosticSeverity
LSP diagnostic severity (1=error, 2=warning, 3=information, 4=hint).
PromptToolFormat
Which wire format the wrapper teaches the model and parses back.
QueueMode
Controls how many queued messages are injected when the loop reaches a queue drain point. Ported from pi's QueueMode.
SessionErrorCode
Stable error codes for SessionException, ported from pi's SessionErrorCode union.
SkillScope
Where a skill was discovered (listing order in the prompt).
StopReason
Why the assistant message stream terminated.
StructuredValidationStatus
Final validation state of a schema-bearing spawn (omp's StructuredSubagentValidationStatus).
TaskJobStatus
Background job states (omp's async job states, reduced).
TaskSpawnPhase
Lifecycle phases reported through TaskSpawnProgressCallback.
TaskSpawnStatus
Terminal state of one spawn (omp's exitCode/aborted pair as an enum: completed ↔ 0, failed ↔ 1, aborted ↔ caller cancellation).
ThinkingFormat
How a provider expects the reasoning/thinking parameter to be shaped.
ToolExecutionMode
How tool calls from a single assistant message are executed.
TtsrContextMode
What happens to the violating partial assistant output before the retry (omp's ttsr.contextMode).
TtsrMatchSource
Which stream a TTSR delta belongs to (omp's TtsrMatchSource).
TtsrRepeatMode
How often a rule may re-trigger (omp's ttsr.repeatMode).

Extensions

ApprovalModeLabel on ApprovalMode
The CLI/config spelling of an ApprovalMode (always-ask, write, yolo).

Constants

agentUrlScheme → const String
The internal URL scheme addressing subagent outputs.
architectModePromptName → const String
Canonical prompt name for the CLI architect mode.
bareBodyAutoPipedWarning → const String
Bare body rows auto-converted to literal + rows.
bashToolName → const String
The canonical name of the shell tool the interceptor applies to (shellTool in builtin_tools.dart registers under this name).
branchSummaryPrefix → const String
Prefix wrapping a branch summary when it is projected into the model context. Ported from pi's BRANCH_SUMMARY_PREFIX.
branchSummaryPrompt → const String
Structured summary instructions for the branch abandoned during session-tree navigation, ported verbatim from oh-my-pi's branch-summary compaction prompt.
branchSummarySuffix → const String
Suffix closing branchSummaryPrefix. Ported from pi's BRANCH_SUMMARY_SUFFIX.
braveSearchUrl → const String
Brave Search API endpoint (omp's BRAVE_SEARCH_URL).
checkpointToolName → const String
The checkpoint tool name.
cliProviderKinds → const Set<String>
The provider kinds accepted by --provider.
codeModePromptName → const String
Canonical prompt name for the CLI code mode (the default mode).
compactionSummaryPrefix → const String
Prefix wrapping a compaction summary when it is projected into the model context. Ported from pi's COMPACTION_SUMMARY_PREFIX.
compactionSummarySuffix → const String
Suffix closing compactionSummaryPrefix. Ported from pi's COMPACTION_SUMMARY_SUFFIX.
defaultArchiveListLimit → const int
Default entry cap for archive directory listings (omp's #readArchiveDirectory DEFAULT_LIMIT).
defaultCompactionPrompts → const CompactionPrompts
The built-in compaction prompts (no overrides).
defaultCompactionSettings → const CompactionSettings
Default compaction settings (pi's DEFAULT_COMPACTION_SETTINGS): reserve 16384 tokens, keep ~20000 recent tokens.
defaultDiagnosticsWait → const Duration
How long diagnostics waits for a fresh publish after opening a file (omp's SINGLE_DIAGNOSTICS_WAIT_TIMEOUT_MS).
defaultLsEntryLimit → const int
Default entry cap for the ls tool (pi's DEFAULT_LIMIT).
defaultLspRequestTimeout → const Duration
Default per-request timeout (omp's DEFAULT_REQUEST_TIMEOUT_MS).
defaultModelRole → const String
The role used for ordinary agent runs.
defaultSqliteQueryLimit → const int
Default row limit for table queries (omp's DEFAULT_QUERY_LIMIT).
defaultSqliteSchemaSampleLimit → const int
Sample row count shown with a table schema (omp's DEFAULT_SCHEMA_SAMPLE_LIMIT).
defaultTaskAgentName → const String
Default agent type when an item omits agent (omp's DEFAULT_SPAWN_AGENT).
defaultTaskMaxConcurrent → const int
Default session concurrency cap (omp's task.maxConcurrency default; 0 means unbounded — see normalizeConcurrencyLimit).
defaultToolMaxBytes → const int
Default byte limit for tool output truncation (pi's DEFAULT_MAX_BYTES).
defaultToolMaxLines → const int
Default line limit for tool output truncation (pi's DEFAULT_MAX_LINES).
defaultWebSearchCount → const int
Default number of results per search (omp's DEFAULT_NUM_RESULTS).
duckDuckGoHtmlUrl → const String
DuckDuckGo's no-JS HTML search frontend. POST q=… to receive a static results page we can parse without a real browser (omp's endpoint choice; see the note on DuckDuckGoSearchProvider).
estimatedImageChars → const int
Estimated character cost of an image block (pi's ESTIMATED_IMAGE_CHARS: 4800 chars ≈ 1200 tokens at 4 chars/token).
headTailDriftWarning → const String
INS.HEAD:/INS.TAIL: applied despite a stale snapshot tag.
hlDeleteBlockKeyword → const String
Hunk-header keyword: DEL.BLK N (tree-sitter block delete; unsupported).
hlDeleteKeyword → const String
Hunk-header keyword for concrete line deletion.
hlFileHashExamples → const List<String>
Representative file-hash tags for use in user-facing error messages and prompt examples.
hlFileHashLength → const int
Number of hex characters in a content-derived file-hash tag.
hlFileHashReRaw → const String
Canonical uppercase hexadecimal content-hash tag carried by a hashline section header.
hlFileHashSep → const String
Separator between a hashline file path and its snapshot tag.
hlFilePrefix → const String
File-section header delimiters: [path#hash].
hlFileSuffix → const String
hlHeaderColon → const String
Colon terminating a hunk header that takes a body.
hlInsertAfter → const String
Insert position keyword for inserting after a concrete line.
hlInsertAfterBlockKeyword → const String
Hunk-header keyword: INS.BLK.POST N: (insert after a tree-sitter block; unsupported).
hlInsertBefore → const String
Insert position keyword for inserting before a concrete line.
hlInsertHead → const String
Insert position keyword for inserting at the start of the file.
hlInsertKeyword → const String
Hunk-header keyword for insertion operations.
hlInsertTail → const String
Insert position keyword for inserting at the end of the file.
hlLineBodySep → const String
Separator between a line number and displayed line content in hashline mode.
hlMoveKeyword → const String
File-level keyword: MV DEST moves the file (unsupported).
hlPayloadReplace → const String
Payload sigil for literal body rows.
hlRangeSep → const String
Separator between two line numbers in a range, e.g. 5.=10.
hlRemKeyword → const String
File-level keyword: REM deletes the whole file (unsupported).
hlReplaceBlockKeyword → const String
Hunk-header keyword: SWAP.BLK N: (tree-sitter block replace; recognized by the parser but rejected as unsupported by this port).
hlReplaceKeyword → const String
Hunk-header keyword for concrete line replacement.
knownHtmlTags → const Set<String>
HTML tag names the scanner recognizes. Unknown names without a dash are treated as literal text so code generics (List<String>) inside <pre> survive conversion; custom elements (which always carry a dash) still parse as tags. SVG names are included so subtree skipping matches open/close tags correctly.
lspConfigFileName → const String
Config file consulted in the workspace root (documented location; see LspConfig.load).
maxArchiveBytes → const int
Cap on the on-disk size of an archive read into memory for indexing (omp's MAX_TAR_ARCHIVE_BYTES, applied to every format here because all decoding is in-memory).
maxArchiveMemberBytes → const int
Cap on a single archive member's declared (uncompressed) size — the declared size is attacker-controlled metadata (omp's MAX_ARCHIVE_MEMBER_BYTES).
maxSqliteColumnWidth → const int
Maximum per-column render width (omp's MAX_COLUMN_WIDTH).
maxSqliteQueryLimit → const int
Hard cap on an explicit ?limit= (omp's MAX_QUERY_LIMIT).
maxSqliteRawQueryRows → const int
Row cap for raw ?q= SQL — protects against SELECT * on multi-million-row tables (omp's MAX_RAW_QUERY_ROWS).
maxSqliteRenderWidth → const int
Maximum ASCII-table render width (omp's MAX_RENDER_WIDTH).
maxSqliteTableListEntries → const int
Cap on the rendered table list (omp's #readSqlite list limit).
maxTaskOutputBytes → const int
Maximum bytes of a subagent's raw output kept in the in-memory store and the per-item result (omp's MAX_OUTPUT_BYTES).
maxTaskOutputLines → const int
Maximum lines of a subagent's raw output (omp's MAX_OUTPUT_LINES).
maxTranscribeAudioBytes → const int
Largest accepted audio payload: 25MB, matching OpenAI's upload cap for the transcription endpoint.
maxWebSearchCount → const int
Maximum number of results per search (omp's MAX_NUM_RESULTS).
modelRoleIds → const List<String>
The model roles supported by ModelRolesConfig, in declaration order.
overridablePromptNames → const Map<String, String>
The prompt names accepted in the CLI config prompts: section, mapped to a short description. Names mirror the prompts/ tree ids used by scripts/gen_prompts.dart; systemPromptAlias is an alias for codeModePromptName.
projectContextFileNames → const List<String>
The context filenames collected per directory, in priority order (all present files are included, each as its own block).
projectContextMaxBytes → const int
The merged-content budget, allocated leaf-first so deeper (more specific) files are never truncated in favor of shallower ones (kimi's _AGENTS_MD_MAX_BYTES).
providerCatalog → const Map<String, ProviderSpec>
The built-in provider table.
reviewModePromptName → const String
Canonical prompt name for the CLI review mode.
rewindReportCustomType → const String
The custom_message type carrying the retained rewind report in the session tree (omp's rewind-report custom message).
rewindToolName → const String
The rewind tool name.
rowCountProbeCap → const int
Upper bound on rows scanned when counting a table for the listing. SQLite has no stored row count, so COUNT(*) is a full b-tree scan; the listing counts exactly only when a table is provably small, reading at most this many rows (omp's ROW_COUNT_PROBE_CAP).
seenLineRevealCap → const int
Upper bound on the number of unseen anchor lines whose actual file content is inlined into a rejection error (omp's SEEN_LINE_REVEAL_CAP).
seenLineRevealMaxColumns → const int
Per-revealed-line character cap, so a revealed anchor line can never dump a minified megabyte-wide line into the tool error and model context (omp's SEEN_LINE_REVEAL_MAX_COLUMNS).
smolModelRole → const String
The role compaction summarization resolves through when configured.
sqliteBusyTimeoutMs → const int
PRAGMA busy_timeout applied on open (omp: 3000 ms).
summarizationPrompt → const String
Structured checkpoint prompt for a first-time compaction summary. Ported verbatim from pi SUMMARIZATION_PROMPT.
summarizationSystemPrompt → const String
System prompt for the compaction summarization LLM. Ported verbatim from pi SUMMARIZATION_SYSTEM_PROMPT.
supportedAudioExtensions → const Set<String>
Audio file extensions accepted by the tool (Whisper-compatible formats).
systemPromptAlias → const String
The system config key: an alias for codeModePromptName (the base CLI system prompt).
taskOutputPreviewChars → const int
Per-item output preview cap inside the blocking tool result text; the full output stays addressable as agent://<id> (omp's fullOutputThreshold).
taskToolName → const String
The task tool name.
tavilySearchUrl → const String
Tavily search endpoint (omp's TAVILY_SEARCH_URL).
ttsrInjectionCustomType → const String
The custom_message type carrying the injected reminder in the session tree (omp's ttsr-injection custom message).
ttsrInjectionRecordType → const String
The custom record type persisting injected rule names (omp's ttsr_injection entry).
turnPrefixSummarizationPrompt → const String
Prompt for summarizing the prefix of a split turn during compaction. Ported verbatim from pi TURN_PREFIX_SUMMARIZATION_PROMPT.
updateSummarizationPrompt → const String
Prompt for updating an existing compaction summary with new messages. Ported verbatim from pi UPDATE_SUMMARIZATION_PROMPT.
voidHtmlTags → const Set<String>
Tags that have no content model and never need a close tag.
webSearchUserAgent → const String
Shared browser-profiled user agent for the keyless scrape endpoints.

Properties

builtinExploreAgent → TaskAgentDefinition
omp's scout ported under the name explore: read-only research on the smol role.
final
builtinReviewAgent → TaskAgentDefinition
omp's reviewer ported under the name review: read-only code review on the slow role.
final
builtinTaskAgent → TaskAgentDefinition
omp's general-purpose worker (prompts/agents/task.md): full tool surface, inherits the parent model.
final
builtinTaskAgentTypes → List<TaskAgentDefinition>
The built-in agent types, in registry order.
final
criticalBashPatterns → List<CriticalBashPattern>
Patterns that force an approval prompt for any matching bash command.
final
defaultWebSearchProviders → List<WebSearchProvider>
The default provider set in chain order: keyless DuckDuckGo first, then the keyed providers (filtered by key availability when the chain runs).
final

Functions

agentLoop({required List<Message> prompts, required Context context, required AgentLoopConfig config, required StreamFunction streamFunction, required ToolExecutor toolExecutor, CancelToken? cancelToken}) → AgentEventStream
Starts an agent loop with new prompt messages.
agentLoopContinue({required Context context, required AgentLoopConfig config, required StreamFunction streamFunction, required ToolExecutor toolExecutor, CancelToken? cancelToken}) → AgentEventStream
Continues an agent loop from context without adding a new message.
applyHashlineEdits(String text, List<HashlineEdit> edits) → HashlineApplyResult
Applies edits to text and returns the post-edit result. Throws HashlineFormatException if an anchor is out of bounds.
applyTextEditsToString(String content, List<LspTextEdit> edits) → String
Applies edits to content in-memory, bottom-to-top (omp's applyTextEditsToString). Call sortAndValidateTextEdits first (this function re-sorts defensively).
applyWorkspaceEdit(ExecutionEnv env, LspWorkspaceEdit edit, {Map<String, int> openFileVersions = const {}}) → Future<List<LspAppliedChange>>
Applies edit through env and returns the per-file changes.
approvalModeFromLabel(String? value) → ApprovalMode?
Parses a CLI/config label into an ApprovalMode; null when unknown.
architectMode(String cwd, {PromptOverrides? overrides}) → AgentMode
High-level design and planning mode.
archiveFormatFromPath(String filePath) → ArchiveFormat?
Infers the archive format from a filesystem path's extension (omp's archiveFormatFromPath).
askTool({AskCallback? callback}) → AgentTool
Creates the ask tool bound to callback.
attachApproval(Agent agent, ApprovalManager manager) → void
Composes the approval gate for manager onto agent, preserving any BeforeToolCallHook already registered (approval runs first).
attachSecretRedactor(Agent agent, SecretRedactor redactor) → void
Composes the redaction hooks for redactor onto agent, preserving any hooks already registered (existing hooks run first, redaction runs last so content they produce is masked too).
buildCatalogModel(String provider, String modelId, {String? baseUrl, int? contextWindow, int? maxTokens}) → Model
Builds a Model for provider/modelId with catalog defaults, overrid- able per reference (see ModelRef).
buildCliDefaultModel(String providerKind, {String? modelId, String? baseUrl}) → Model
Builds the legacy single Model the fah executable runs when no roles are configured (--provider/--model/--base-url flags).
buildSqliteAsciiTable(List<String> columns, List<Map<String, Object?>> rows) → String
Renders rows as a width-capped ASCII table (omp's buildAsciiTable).
builtInAgentModes(String cwd, {PromptOverrides? overrides}) → Map<String, AgentMode>
All built-in modes keyed by name.
builtinTools(ExecutionEnv env, {HashlineSnapshotStore? snapshots, WebSearchConfig? webSearch, Model? model()?, SqliteEngine? sqlite, LspToolConfig? lsp}) → List<AgentTool>
Creates the four built-in tools (readFileTool, writeFileTool, listDirTool, shellTool) bound to env.
calculateContextTokens(Usage usage) → int
Calculate total context tokens from provider usage.
calculateCost(Usage usage, Model model) → Usage
Fills in Usage.cost from the model's ModelCost rates.
catalogProvider(String name) → ProviderSpec?
Resolves name against the providerCatalog.
clampWebSearchCount(int? count) → int
Clamps a requested result count to 1..[maxWebSearchCount], defaulting to defaultWebSearchCount (omp's clampNumResults).
cliHelpText(String version) → String
The full --help output printed by the fa executable. version is threaded through from the executable (_version in bin/fah.dart) — the single source of truth shared with --version — and rendered in the header line.
collectEntriesForBranchSummary(Session session, String? oldLeafId, String targetId) → Future<CollectBranchEntries>
Collect the entries to summarize when navigating from oldLeafId to targetId: walks from the old leaf back to the common ancestor, returning entries in chronological order (omp's collectEntriesForBranchSummary). Compaction boundaries do NOT stop the walk — their summaries become context for the branch summary.
collectKeyStack(Map<String, String> secrets, String baseName) → List<ApiKeyCredential>
Collects a key stack for baseName from secrets: the bare name first, then _2, _3, ... in numeric order. Returns an empty list when the base name is absent.
compactProviderError(String message) → String
Reduces a provider error blob to something readable on one line: unwraps OpenRouter's metadata.raw upstream JSON recursively, prefers the most specific message, and caps the result at 300 chars.
computeFileHash(String text) → String
Computes the content-derived hash tag carried by a hashline section header: the low 16 bits of xxHash32 (seed 0) over the UTF-8 bytes of the normalized text, as 4 uppercase hex characters.
computeFileLists(FileOperations fileOps) → ({List<String> modifiedFiles, List<String> readFiles})
Compute sorted read-only and modified file lists from accumulated operations. Ported from pi's computeFileLists.
containsRecognizableHashlineOperations(String input) → bool
Returns true when the input contains at least one line that the tokenizer recognizes as a hashline op.
createAssistantMessageEventStream() → AssistantMessageEventStream
Creates an AssistantMessageEventStream.
createFileOps() → FileOperations
Create an empty file-operation accumulator. Ported from pi's createFileOps.
createSessionId() → String
Creates a new session id (time-ordered uuidv7).
decodeHtmlEntities(String text) → String
Decodes the small set of HTML entities seen in search results and page content (named, decimal, and hexadecimal forms).
decodeUtf8Text(Uint8List bytes) → String?
Decodes bytes as strict UTF-8 text, or returns null for binary content (omp's decodeUtf8Text: NUL bytes or malformed UTF-8 mark binary).
defaultAgentCliSystemPrompt(String cwd) → String
The default system prompt for the CLI agent.
defaultAgentMode(String cwd, {PromptOverrides? overrides}) → AgentMode
The default coding-agent mode.
defaultSkillRoots({required String cwd, String? homeDir}) → ({List<String> projectRoots, List<String> userRoots})
The default skill roots for a host: <cwd>/.fah/skills + <cwd>/.agents/skills (project) and, when a home directory exists, ~/.fah/skills + ~/.agents/skills (user). Web/sandbox hosts pass their sandbox cwd and no home (the sandbox FS carries project skills).
defaultWebSiteHandlers() → List<WebSiteHandler>
The site handlers tried, in order, before the generic HTML→markdown converter.
describeAnchorExamples([String linePrefix = '']) → String
Formats a comma-separated list of example anchors with an optional line-number prefix, quoted for inclusion in error messages: "160", "42", "7".
detectLineEnding(String content) → LineEnding
Detects the first line ending style in content. Defaults to LineEnding.lf when neither is present.
discoverSkills(ExecutionEnv env, {List<String> projectRoots = const [], List<String> userRoots = const []}) → Future<List<Skill>>
Discovers skills under projectRoots then userRoots (kimi's precedence: project > user), first-name-wins case-insensitively. Missing roots are silently skipped.
editFileTool(ExecutionEnv env, {HashlineSnapshotStore? snapshots}) → AgentTool
Creates the edit tool: edits a file in one of two modes.
estimateContextTokens(List<Message> messages) → ContextUsageEstimate
Estimate context tokens for messages using provider usage when available.
estimateTokens(Message message) → int
Estimate token count for one message using pi's character heuristic.
executeSqliteReadQuery(SqliteDatabase db, String sql) → SqliteRows
Runs a raw read-only query (omp's executeReadQuery): rejects bound parameters and caps row collection at maxSqliteRawQueryRows.
expandPromptTemplate(String text, List<PromptTemplate> templates) → String
Expands a /name args... template invocation if it matches a known template. Returns text unchanged when it is not a template command.
extractFileOpsFromMessage(Message message, FileOperations fileOps) → void
Add file operations from assistant read/write/edit tool calls to fileOps. Ported from pi's extractFileOpsFromMessage.
extractHtmlTitle(String html) → String?
Extracts and decodes the <title> of an HTML document, or null when absent or empty.
fileToUri(String path) → String
Converts an absolute file path to a file:// URI (omp's fileToUri).
findCutPoint(List<SessionRecord> entries, int startIndex, int endIndex, int keepRecentTokens) → CutPointResult
Find the compaction cut point that keeps approximately keepRecentTokens recent tokens.
findTurnStartIndex(List<SessionRecord> entries, int entryIndex, int startIndex) → int
Find the user-visible message that starts the turn containing an entry.
formatAnchoredContext(List<int> anchorLines, List<String> fileLines) → List<String>
Numbered LINE:TEXT rows around anchorLines (±mismatchContextLines), *-marking anchors, ... between non-adjacent runs. Out-of-range anchors contribute no rows.
formatFileOperations(List<String> readFiles, List<String> modifiedFiles) → String
Format file lists as summary metadata tags. Ported from pi's formatFileOperations.
formatHashlineHeader(String filePath, String fileHash) → String
Formats a hashline section header for a file path and snapshot tag.
formatLineRanges(List<int> lines) → String
Compresses a line list into a sorted 1-4, 7, 10-12 range string.
formatNumberedLine(int lineNumber, String line) → String
Formats a single numbered line as LINE:TEXT.
formatNumberedLines(String text, [int startLine = 1]) → String
Formats file text with hashline-mode line-number prefixes for display.
formatPathRelativeToCwd(String path, String cwd) → String
Renders path relative to cwd when it sits underneath it (omp's formatPathRelativeToCwd, reduced to the common case).
formatProjectContext(List<ProjectContextFile> files) → String
Renders the context files as a system-prompt section (kimi's wrapper, reduced): each file annotated with its source path, precedence note for deeper-vs-shallower rules. Empty when nothing was discovered.
formatSkillsForPrompt(List<Skill> skills) → String
Renders the progressive-disclosure block for the system prompt (pi's <available_skills>): metadata only — the agent loads a skill's file with the read tool when the task matches its description. Empty when there are no skills.
formatToolSize(int bytes) → String
Formats a byte count as a human-readable size (pi's formatSize).
formatWebSearchResults(WebSearchResponse response) → String
Formats a response for the model (omp's formatForLLM, reduced to the fields the ported providers produce): the answer first when present, then [n] title / url / snippet sources.
generateBranchSummary(List<SessionRecord> entries, {required SummarizeFn summarize, int tokenBudget = 0, String? customInstructions, CancelToken? cancelToken}) → Future<BranchSummaryResult>
Generate a summary of abandoned-branch entries (omp's generateBranchSummary): serializes them into <conversation> tags, ends with the fixed branch-summary prompt (or customInstructions), and prepends the branch preamble plus the file-operation tags. Never throws: failures surface as BranchSummaryResult.error.
generateSummary(List<Message> messages, {required SummarizeFn summarize, String? customInstructions, String? previousSummary, CancelToken? cancelToken, CompactionPrompts prompts = defaultCompactionPrompts}) → Future<String>
Generate (or update) a conversation summary for compaction.
getSqliteRow(SqliteDatabase db, String table, SqliteRowLookup lookup, String key) → Map<String, Object?>?
Looks a row up by primary key or rowid (omp's getRowByKey / getRowByRowId). Returns null when no row matches.
getSqliteTableSchema(SqliteDatabase db, String table) → String
The CREATE TABLE statement for table (omp's getTableSchema).
htmlToMarkdown(String html, {Uri? baseUrl}) → String
Converts an HTML document to structured Markdown. baseUrl resolves relative link/image targets; when null they are emitted verbatim.
inspectImageTool(ExecutionEnv env, InspectImageConfig config) → AgentTool
Creates the inspect_image tool.
isContextOverflow(AssistantMessage message, {int? contextWindow}) → bool
Whether message represents a context overflow.
isDuckDuckGoAnomalyPage(String html) → bool
true when DDG returned its bot-challenge page instead of results. DDG mixes 200/202 statuses on these, so the body marker is the reliable signal (omp's isAnomalyResponse).
isKnownHtmlTag(String tagName) → bool
Whether tagName parses as a markup tag (vs. literal text).
isRateLimitOrQuota(AssistantMessage message, {Duration? retryAfter}) → bool
Whether message is a rate-limit/quota failure the chain may retry.
isRawSelector(ReadSelector parsed) → bool
Whether the selector requested verbatim/raw output (alone or combined with a range) — omp's isRawSelector.
isWebSearchProviderAvailable(WebSearchProvider provider, Map<String, String> secrets) → bool
Whether provider can serve searches given secrets: keyless providers are always available, keyed ones need their non-empty key.
listDirTool(ExecutionEnv env) → AgentTool
Creates the ls tool: lists directory entries sorted alphabetically (case-insensitive), directories suffixed with /, capped at limit entries (default defaultLsEntryLimit) and defaultToolMaxBytes bytes.
listSqliteTables(SqliteDatabase db, {int probeCap = rowCountProbeCap}) → List<SqliteTableSummary>
Lists non-sqlite_% tables with bounded row counts (omp's listTables).
loadJsonlSessionMetadata(FileSystem fs, String filePath) → Future<SessionMetadata>
Reads just the header of a session file and returns its metadata.
loadProjectContextFiles(ExecutionEnv env, {String? userFile}) → Future<List<ProjectContextFile>>
Loads every projectContextFileNames file walking from cwd up to the git root (or the filesystem root). Returns files farthest-first, closest (most specific) last. A userFile (e.g. ~/.fah/AGENTS.md) is merged first when present (pi's global layer).
loadPromptTemplates(ExecutionEnv env, List<String> dirs) → Future<List<PromptTemplate>>
Loads prompt templates from a list of directories.
loadWebPage(Client client, Uri uri, {required Duration timeout, required int maxBytes, Map<String, String>? headers}) → Future<WebPage>
Fetches uri with a browser profile, following redirects and capping the body at maxBytes (omp's loadPage, reduced: no user-agent rotation or 429 retry — the tool surfaces failures directly).
lspTool(ExecutionEnv env, {required LspToolConfig config}) → AgentTool
Creates the lsp tool bound to env. Registered from builtinTools only when the host supplies an LspToolConfig — process-capable envs (CLI/desktop) do; web/stub construction leaves the tool out.
matchCriticalBashCommand(String command) → String?
Returns the label of the first criticalBashPatterns entry matching command, or null when the command matches nothing critical.
messageFromJson(Map<String, dynamic> json) → Message
Deserializes a Message from its JSON map, dispatching on role.
Navigate session to targetId (omp's tree navigation with branch summarization): the branch being left is summarized via summarize into a branch_summary record prepended to the context of the branch being entered, and the active leaf moves. Returns the new branch_summary record id, or null when no summary was written (no-op navigation, nothing to summarize, or summarization failed/aborted).
noChangeDiagnostic(String path) → String
The patch parsed and applied cleanly but produced no change — the +literal body rows matched the file content at the targeted lines byte-for-byte (omp's noChangeDiagnostic).
normalizeArchiveLookupPath(String? rawPath) → String?
Normalizes a member lookup path: / separators, . segments dropped. Returns null when the path escapes via .. (omp's normalizeArchiveLookupPath).
normalizeConcurrencyLimit(num max) → int
Normalizes a configured concurrency cap (omp's normalizeConcurrencyLimit): max <= 0 (or any non-finite input) means unbounded — every Semaphore.acquire resolves immediately, matching task.maxConcurrency = 0's "Unlimited" semantics in omp's settings UI.
normalizeLocationResult(Object? result) → List<LspLocation>
Normalizes a textDocument/definition-family result: accepts null, Location, Location[], LocationLink, or LocationLink[] and returns a flat location list (omp's normalizeLocationResult, reduced).
normalizeToLF(String text) → String
Normalizes every line ending to LF.
parseArchivePathCandidates(String filePath) → List<ArchivePathCandidate>
Splits an archive.ext:inner/path reference into every plausible {archivePath, subPath} pair, longest archive prefix first. A path may contain more than one archive extension, so each candidate is a guess at where the archive ends and the member portion begins (omp's parseArchivePathCandidates).
parseCliArgs(List<String> args) → CliArgsResult
Parses the fah argument list.
parseCommandArgs(String input) → List<String>
Parses bash-style quoted arguments from the text after a /command.
parseDuckDuckGoResults(String html, {int? limit}) → List<WebSearchSource>
Walks the DDG results page and pulls out result blocks in document order (omp's parseHtmlResults, rebuilt on the forgiving scanHtml tokenizer so minor markup rot — attribute order, quote style, extra classes, snippet element variants — does not break parsing).
parseFrontmatter(String content) → ({String body, Map<String, dynamic> frontmatter})
Splits markdown content into YAML frontmatter and body.
parseHashlinePatch(String diff) → HashlineParseResult
Parses one section body (diff) into edits plus warnings. The input must NOT contain the [path#tag] section header — section splitting happens in input.dart (omp's parsePatch).
parseLineRangeChunk(String sel) → LineRange?
Parses a single N, N-M, N-, N+K, or ..-aliased (N..M, N..) chunk. Returns null when sel is not range-shaped; throws StateError on invalid bounds (omp's ToolError messages, verbatim).
parseLineRanges(String sel) → List<LineRange>?
Parses a comma-separated list of line ranges (e.g. 5-16,960-973). Returns the ranges in ascending order with overlapping/adjacent ranges merged so downstream consumers can stream the file in a single forward pass per range. Returns null when any chunk is not range-shaped.
parsePromptOverrideMap(Object? node) → Map<String, String>
Validates the raw prompts: yaml section into a prompt name → raw source map (values stay raw: a file path or inline text — classified later, at file-resolution time).
parseRoleChains(Object? node, {String? source}) → Map<String, List<ModelRef>>
Parses a roles: map (role name → chain). Shared by the top-level section and PathRoleOverride; source labels errors.
parseSel(String? sel) → ReadSelector
Parses a selector string (as returned by SplitReadPath.sel) into a ReadSelector. Unrecognized selectors fall through to ReadSelectorNone — archive/SQLite readers consume their own colon syntax — but compounds that LOOK read-like yet are malformed throw (omp's invalidSelector), so a mistyped selector never silently widens into a whole-file read.
parseSqlitePathCandidates(String filePath) → List<SqlitePathCandidate>
Splits a db.sqlite:table?query reference into every plausible candidate, longest database prefix first (omp's parseSqlitePathCandidates). Database detection is by extension only; existence and readability are checked by the caller.
parseSqliteSelector(String subPath, String queryString) → SqliteSelector
Parses the table/query selector tail of a SQLite path (omp's parseSqliteSelector). Throws StateError with omp's messages on unsupported combinations.
pathPatternMatches(String pattern, String cwd, {String? homeDir}) → bool
Whether pattern matches the working directory cwd.
prepareBranchEntries(List<SessionRecord> entries, {int tokenBudget = 0}) → BranchPreparation
Prepare entries for summarization within tokenBudget (omp's prepareBranchEntries): walks NEWEST to OLDEST, keeping the most recent context when the branch is too long. File operations accumulate from ALL entries — including nested branch-summary details — even past the budget. tokenBudget: 0 means no limit.
promptToolInstructions(List<Tool> tools, {bool slim = false}) → String
Renders the tool-instruction section promptToolStreamFunction appends to the system prompt when tools is non-empty (the prompts/tools/tool_calling.md template with the numbered name/description/schema list).
promptToolStreamFunction(StreamFunction inner, {PromptToolOptions? options}) → StreamFunction
Wraps inner with prompt-based tool calling.
providerStreamFunction(String kind, String apiKey) → StreamFunction
Builds the StreamFunction for a provider adapter kind (openai-completions, anthropic, google) with a static apiKey. Throws ConfigException for unknown kinds.
querySqliteRows(SqliteDatabase db, String table, {required int limit, required int offset, String? order, String? where}) → SqliteTablePage
Runs a paged table query (omp's queryRows).
readFileTool(ExecutionEnv env, {HashlineSnapshotStore? snapshots, Model? model()?, SqliteEngine? sqlite}) → AgentTool
Creates the read tool: reads a text file or image with optional offset (1-indexed) and limit, truncating text output to defaultToolMaxLines lines or defaultToolMaxBytes bytes with an actionable continuation notice. Images are decoded, optionally resized to the inline dimension/byte limits, and returned as base64 content.
readPersistedTtsrInjections(Session session) → Future<List<String>>
Reads the persisted injected-rule names along the session's active branch (omp's getInjectedTtsrRules), for TtsrManager.restoreInjected on session resume.
redactionHooks(SecretRedactor redactor) → RedactionHooks
Builds the agent hooks that redact redactor's values:
renderSqliteRow(Map<String, Object?> row) → String
Renders a single row as column: value lines (omp's renderRow).
renderSqliteSchema(String createSql, SqliteRows sampleRows) → String
Renders a table schema plus sample rows (omp's renderSchema).
renderSqliteTable(List<String> columns, List<Map<String, Object?>> rows, {required int totalCount, required int offset, required int limit, required String table}) → String
Renders a paged table plus the continuation note when more rows remain (omp's renderTable).
renderSqliteTableList(List<SqliteTableSummary> tables) → String
Renders the table list (omp's renderTableList).
repr(String text) → String
Renders text with JSON-style quoting for diagnostics.
resolveAgentUrl(String url, AgentOutputStore store) → AgentUrlResolution
Resolves an agent:// URL against store (port of omp's AgentProtocolHandler.resolve, reduced to the dot-path query subset).
resolveSqliteRowLookup(SqliteDatabase db, String table) → SqliteRowLookup
Resolves the row-lookup strategy for table (omp's resolveTableRowLookup).
resolveWebSearchChain(List<String> providerIds, {required Map<String, String> secrets}) → List<WebSearchProvider>
Resolves providerIds (auto expands to the default chain) into an ordered, deduplicated list of available providers (omp's resolveProviderCandidates, reduced). Keyed providers without a key in secrets are skipped; unknown ids throw.
restoreLineEndings(String text, LineEnding ending) → String
Re-encodes LF text with the requested line ending.
reviewMode(String cwd, {PromptOverrides? overrides}) → AgentMode
Code-review mode.
runAgentLoop({required List<Message> prompts, required Context context, required AgentLoopConfig config, required StreamFunction streamFunction, required ToolExecutor toolExecutor, required AgentEventSink emit, CancelToken? cancelToken}) → Future<List<Message>>
Starts an agent loop with new prompt messages, delivering events to emit and resolving with the messages produced by the run.
runAgentLoopContinue({required Context context, required AgentLoopConfig config, required StreamFunction streamFunction, required ToolExecutor toolExecutor, required AgentEventSink emit, CancelToken? cancelToken}) → Future<List<Message>>
Continues an agent loop from context, delivering events to emit.
scanHtml(String html) → Iterable<Object>
Scans html sequentially, yielding HtmlTag and HtmlText tokens in document order. Comments, doctypes, and processing instructions are skipped. Malformed input degrades to text instead of throwing.
serializeConversation(List<Message> messages) → String
Serialize messages to plain text for summarization prompts.
shellTool(ExecutionEnv env) → AgentTool
Creates the bash tool: executes a shell command via ExecutionEnv.exec and returns stdout followed by stderr, truncated to the last defaultToolMaxLines lines / defaultToolMaxBytes bytes. A non-zero exit code, timeout, or abort throws (the loop turns it into an error tool result, pi semantics).
shouldCompact(int contextTokens, int contextWindow, CompactionSettings settings) → bool
Whether context usage exceeds the compaction threshold.
skipHtmlSubtree(List<Object> tokens, int openIndex) → int
Returns the index of the token closing the subtree rooted at the open tag openIndex within tokens (depth-counted on the same tag name). Returns openIndex itself for self-closing tags, or the last token index when the close tag is missing (malformed input).
sortAndValidateTextEdits(List<LspTextEdit> edits) → List<LspTextEdit>
Sorts edits bottom-to-top for in-place application and rejects overlaps (omp's sortAndValidateTextEdits).
splitPathAndSel(String rawPath) → SplitReadPath
Splits a trailing :sel off rawPath when the tail matches the selector grammar (a range list or raw, optionally one of each in either order — path:1-50:raw / path:raw:1-50). Anything else stays part of the path so archive and SQLite targets keep their colon syntax.
splitPathAndSelPreferringLiteral(String rawPath, FileSystem env) → Future<SplitReadPath>
Async sibling of splitPathAndSel that prefers a literal filesystem path over selector interpretation (omp's splitPathAndSelPreferringLiteral, issue #4618): filenames whose tail matches the selector grammar (e.g. test:1-2, log:raw) are legal on POSIX; without this the strict splitter peels the tail and read refuses to open the real file. The literal wins whenever env reports the raw path exists — and also when the existence check itself fails — so an unreachable literal is never silently reinterpreted as path + selector.
streamAnthropic(Model model, Context context, [AnthropicOptions? options, Client? client]) → AssistantMessageEventStream
Streams an assistant message from an Anthropic messages endpoint.
streamFunctionSummarizer(StreamFunction streamFunction, Model model, {CompactionPrompts prompts = defaultCompactionPrompts}) → SummarizeFn
Adapts a provider StreamFunction into a SummarizeFn.
streamGoogle(Model model, Context context, [GoogleOptions? options, Client? client]) → AssistantMessageEventStream
Streams an assistant message from a Google Generative AI endpoint.
streamOpenAICompletions(Model model, Context context, [OpenAICompletionsOptions? options, Client? client]) → AssistantMessageEventStream
Streams an assistant message from an OpenAI-compatible chat-completions endpoint.
stringifySqliteValue(Object? value) → String
Renders a SQLite value for a table cell (omp's stringifySqliteValue).
stripBom(String content) → BomStripResult
Strips a UTF-8 BOM if present and returns both the BOM and the trailing text.
stripHtmlTags(String html) → String
Strips all tags, decodes entities, and collapses whitespace — the text content of an HTML fragment (omp's decodeHtmlText).
substituteArgs(String content, List<String> args) → String
Substitutes positional arguments into a template body.
taskItemAgentName(TaskItem item) → String
The agent type item runs as: its agent, or defaultTaskAgentName when omitted (omp's spawn-policy default).
taskItemNameBase(TaskItem item) → String
The requested id base for item (omp's sanitizeAgentId): its name scrubbed to A-Za-z0-9_- (≤48 chars), defaulting to the capitalized agent type name (omp's AdjectiveNoun name-generator is not ported).
taskTool({required TaskToolConfig config}) → AgentTool
Creates the task tool bound to config (omp's TaskTool).
transcribeAudioTool(ExecutionEnv env, TranscribeAudioConfig config) → AgentTool
Creates the transcribe_audio tool.
truncateSqliteWidth(String value, int width) → String
Truncates value to width characters, ending with an ellipsis when cut (omp's truncateToWidth, measured in code units).
unwrapDuckDuckGoUrl(String href) → String?
Resolves a DDG result href back to the underlying target URL (omp's unwrapResultUrl): DDG routes outbound clicks through //duckduckgo.com/l/?uddg=<encoded>; also handles protocol-relative and plain absolute URLs.
uriToFile(String uri) → String
Converts a file:// URI back to a file path (omp's uriToFile).
validateJsonValue({required Object? value, required Map<String, dynamic> schema}) → List<String>
Validates an arbitrary value against the same JSON-schema subset validateToolArguments enforces and returns every violation as a path.with.dots: message string ((root) for the top level). An empty result means valid.
validateToolArguments({required Map<String, dynamic> arguments, required Map<String, dynamic> schema, required String toolName}) → Map<String, dynamic>
Validates arguments against the tool's JSON-schema schema and returns a new map with coerced values and injected defaults. Undeclared keys pass through unchanged. The input map is never mutated.
webFetchTool({required WebSearchConfig config}) → AgentTool
Creates the web_fetch tool, sharing WebSearchConfig's HTTP plumbing.
webSearchTool({required WebSearchConfig config}) → AgentTool
Creates the web_search tool.
writeFileTool(ExecutionEnv env) → AgentTool
Creates the write tool: creates or overwrites a file, creating parent directories as needed.
xxHash32(Uint8List data, [int seed = 0]) → int
Computes xxHash32 of data with seed (both treated as unsigned 32-bit).

Typedefs

AfterToolCallHook = FutureOr<AfterToolCallResult?> Function(AfterToolCallContext context, CancelToken? cancelToken)
Called after a tool finishes executing, before tool_execution_end and the tool-result message events are emitted (pi's afterToolCall).
AgentEventSink = FutureOr<void> Function(AgentEvent event)
Sink receiving every event the loop emits (pi's AgentEventSink).
AgentListener = FutureOr<void> Function(AgentEvent event, CancelToken cancelToken)
Listener for agent lifecycle events (pi's Agent.subscribe callback).
AgentToolExecute = Future<ToolExecutionResult> Function(Map<String, dynamic> arguments, CancelToken? cancelToken, ToolUpdateCallback? onUpdate)
Runs one invocation of an AgentTool.
ApprovalPrompt = FutureOr<ApprovalDecision> Function(ApprovalRequest request)
Renders an approval prompt and resolves with the user's ApprovalDecision.
AskCallback = Future<List<AskAnswer>?> Function(List<AskQuestion> questions)
Answers questions on behalf of the user — the host UI surface (CLI menu, Flutter sheet). Returns one AskAnswer per question, or null when the user cancels (dismiss/escape): the tool then resolves with an "ask cancelled by user" result so the model continues gracefully.
BeforeToolCallHook = FutureOr<BeforeToolCallResult?> Function(BeforeToolCallContext context, CancelToken? cancelToken)
Called before a tool is executed (pi's beforeToolCall).
BomStripResult = ({String bom, String text})
Result of stripping a leading UTF-8 BOM from a text body.
CollectBranchEntries = ({String? commonAncestorId, List<SessionRecord> entries})
Entries collected for a branch summary plus the common ancestor between the old and the new position.
LspTransportFactory = Future<LspTransport> Function(LspServerConfig config, String cwd)
Spawns a language server for config rooted at cwd.
PrepareNextTurnHook = FutureOr<AgentLoopTurnUpdate?> Function(NextTurnContext context)
Called after turn_end and before the loop decides whether another provider request should start (pi's prepareNextTurn).
QueuedMessagesSource = FutureOr<List<Message>> Function()
Returns queued messages to inject into the conversation.
RedactionHooks = ({AfterToolCallHook afterToolCall, TransformContextHook transformContext})
Agent hooks that mask registered secrets, see redactionHooks.
SlashCommand = Future<void> Function(List<String> args)
A slash-command handler registered by a plugin.
StreamFunction = AssistantMessageEventStream Function(Model model, Context context, {CancelToken? cancelToken})
Provider adapter contract consumed by the agent loop.
SummarizeFn = Future<SummarizationResult> Function(SummarizationRequest request)
The injectable summary LLM call.
TaskSpawnProgressCallback = void Function(int index, String id, TaskSpawnPhase phase)
Progress sink for spawn lifecycle transitions. Items without a report are still waiting on the session semaphore.
ToolExecutor = Future<ToolExecutionResult> Function(ToolCall toolCall, CancelToken? cancelToken, ToolUpdateCallback? onUpdate)
Executes a single tool call and returns its result.
ToolUpdateCallback = void Function(ToolExecutionResult partialResult)
Callback used by a tool executor to stream partial execution updates.
TransformContextHook = FutureOr<List<Message>> Function(List<Message> messages, CancelToken? cancelToken)
Rewrites the message list sent to the provider before each call (pi's transformContext). The transcript itself is never modified.

Exceptions / Errors

AgentHarnessException
Base class for all harness exceptions. Sealed so consumers can exhaustively switch on the exception type.
AgentUrlException
Thrown when an agent:// URL cannot be resolved (port of omp's model-visible protocol errors).
CancelledException
Thrown by CancelToken.throwIfCancelled and by operations that abort early due to cancellation.
CliArgsException
Invalid command line: the executable prints message plus a usage hint to stderr and exits with code 64 (EX_USAGE).
CompactionException
Thrown when the compaction pipeline cannot produce a summary.
ConfigException
Thrown when harness configuration is invalid (e.g. malformed config files or missing required settings).
ExecutionError
Error returned by Shell.exec.
FileError
Error returned by FileSystem operations.
HashlineFormatException
Error thrown for malformed hashline patch input (parse-time), distinct from HashlineMismatchError-style apply-time rejections.
HashlineMismatchError
Raised when a hashline section's snapshot tag doesn't match the live file's content. The formatted message tells the model exactly which tag the file currently hashes to and shows the live content around the anchored lines, so the recovery path is "re-read / re-anchor", never a blind retry.
LspNoServerException
Thrown when no configured server handles a file's extension.
LspRequestException
Thrown when an LSP request fails: server error response, timeout, or a dead connection.
LspServerUnavailableException
Thrown by an LspTransportFactory when the server process cannot be started (e.g. the command is not on PATH). The lsp tool converts this into a clean error result — never a crash.
SessionException
Thrown when a session storage operation fails (read, write, or corrupt JSONL records).
ToolNotFoundException
Thrown when a tool referenced by the model is not registered.
ToolValidationException
Thrown when tool call arguments fail validation against the tool's declared parameter schema.
WebSearchException
A provider failure carrying the originating provider id and, for HTTP failures, the status code (omp's SearchProviderError).