agents_flutter 0.8.0

Flutter integration for the agents framework: a preconfigured harness agent, device-capability context providers and tools, chat history persistence, and configurable model profiles.

Changelog

0.8.0

• Breaking: requires agents: ^2.0.0. Inherits the workflow changes: streamAsync / resumeStreamAsync now return a live run driven in the background (watch StreamingRun.watchStreamAsync() rather than reading outgoingEvents straight after the await), external responses route by request id back to the issuing executor and throw when they cannot be routed, and WireMarshaller.valueConverters lets hosts checkpoint payloads outside the JSON model.
• Breaking: requires extensions: ^0.6.0 and extensions_flutter: ^0.5.0. Inherits the AI function-invocation change: the invocation loop withholds function declarations on a final tool-free round trip instead of returning unanswered tool calls, and throws once maximumConsecutiveErrorsPerRequest is exceeded rather than returning a partial response. Agents configured with a low iteration or error limit will see one extra provider call, or a thrown error where a partial response used to come back.
• Breaking: requires geocoding: ^5.0.0, which moved its top-level functions onto a Geocoding class. The ReverseGeocoder and ForwardGeocoder defaults are now the new top-level reverseGeocodeCoordinates and forwardGeocodeAddress functions in this package, which wrap a shared Geocoding instance. Injected fakes are unaffected, and the Placemark / Location types are unchanged. Reverse geocoding now also works on macOS, via the new geocoding_darwin implementation.
• Breaking: requires anthropic_sdk_dart: ^6.0.0, whose types appear in the configured-chat-client factory surface.
• Verified against the current releases of the unchanged constraints, including background_downloader 9.5.7, connectivity_plus 7.3.1, intl 0.20.3, network_info_plus 8.2.1, timezone 0.11.1, and wakelock_plus 1.7.0.

0.7.0

• Breaking: ConfiguredChatClientFactory.customClientResolver gains an AgentScope? scope parameter, forwarded from createChatClient. Host resolvers can now key per-conversation state (for example a local model's KV-cache lineage) to the conversation a client serves, removing the need for scope-aware factory subclasses.
• Removed the empty, never-exported src/ai_agent_provider.dart placeholder.
• New telemetry/ subsystem, folded in from the downstream app: UsageStore (the durable usage_records ledger implementing UsageRecordSink, now living beside UsageTrackingChatClient), AgentRunTelemetryStore with crash recovery (recoverInterrupted), AgentRunScope (an AgentScope carrying agent and run ids for usage attribution), and AgentCenterOverview time-series aggregation over the two ledgers.
• New activity/ subsystem: AppActivityMonitor (app-wide idle signal; hosts report foreground transitions via reportForeground(bool) — a deliberate change from the app's reportLifecycle(AppLifecycleState) so the class stays free of Flutter imports) and the ToolActivity registry with ToolActivityTrackingChatClient.
• a2a/ gains the host side to match its existing pairing client: A2AHostService (a shelf-backed HTTP server exposing local configured agents to paired devices, with single-use pairing tokens, SHA-256 bearer authorization, and per-caller session isolation) behind an io/stub conditional facade, plus NetworkSharingSettings. Adds shelf and pool dependencies (server platforms only at runtime; the web stub reports hosting unsupported).
• web/ gains the search side folded in from the app: SearchUrlWebSearchSource (query any q=-style endpoint; JSON/SearXNG or HTML parsing with redirect unwrapping), WebSearchSettings (SecretStore-backed multi-endpoint config with categories and user-agent profiles), WebSearchTraceLog + TracingWebPageLoader (opt-in HTTP tracing), and WebPageHtmlRenderer (renamed from the app's WebPageRenderer to avoid colliding with this package's web_page_renderer.dart markdown helpers) with HeadlessWebViewHtmlRenderer — a reimplementation of the app's webview_flutter renderer on flutter_inappwebview, gated by a static isSupported (Android/iOS/macOS/Windows). The app no longer needs webview_flutter; one WebView stack serves both loading and rendering.
• Settings colocated with the subsystems they configure: PushoverSettings (→ pushover/), EmbeddingSettings (→ memory/, it is the MemoryScorer handed to RecordStoreVectorStore), ThinkingSettings (→ configured_agents/), and a new user_profile/ capability folder (UserProfileSettings + UserProfileContextProvider). Persisted key literals are unchanged (including historical agents_app. prefixes) so existing installs keep their data.
• activity/ also gains the chat terminal subsystem, reworked during the fold-in from an xterm-backed buffer to a terminal-widget-free design: ChatTerminalSession records a capped ring of semantic TerminalEvents (command started / output chunk / completed / failed / cleared) with a sync broadcast onEvent stream and events replay, the TerminalActivity registry keys sessions per conversation (delegate scopes fold onto the parent), and TerminalMirroringShellExecutor mirrors any ShellExecutor into a session. Presentation — prompt markers, ANSI colors, CRLF, status lines — is the host renderer's job (the reference app binds events to an xterm buffer).
• New package:agents_flutter/chat_provider.dart entry point: the chat view-model contract folded in from the downstream app — LlmProvider, the UI-facing ChatMessage/Attachment/MessageOrigin/ToolApproval types, LlmException, TokenSmoother, AgentLlmProvider (bridges an AIAgent into the contract with tool-approval pause/resume, run telemetry, and activity reporting), and EchoLlmProvider (renamed from the app's EchoProvider; useful as a UI test double). It is a separate library, not part of the main barrel, because the UI-facing ChatMessage would collide with package:extensions/ai.dart's wire-level ChatMessage in any file importing both.
• New conversations/ subsystem: the Conversation/ConversationSession/ Channel domain, ConversationStore + ConversationSessionStore + ChannelStore (RecordStore-backed, collection names unchanged from the app), ConversationService, the ChatsQuery filter model, the ChatTitleSummarizer background service, and an addConversations() / addChatTitleSummarizer(residentTitleClient:) registration pair.
• New tasks/ subsystem: AgentTask (+ recurrence), AgentTaskStore, TaskSchedulerService, and addTaskScheduler(). The scheduler stays a plain singleton the host starts explicitly.
• chat_history/ gains ChatTranscriptStore, co-located with ChatMessageCodec/ChatMessageRecords whose record shape it reads; a contract test now pins the record field literals and the write→read round-trip.
• logging/ gains PromptLog and PromptLoggingChatClient (+ renderRequest); configured_agents/ gains LoggingConfiguredChatClientFactory (prompt capture, usage attribution, tool-activity tracking in one decorator stack) and chooseLocalWarmupTarget for pre-loading a local model at startup. The chat-client decorator is named PromptLoggingChatClient — not the app's original LoggingChatClient — to avoid colliding with package:extensions/ai.dart's class of that name.

0.6.1

• HeadlessWebViewPageLoader accepts an optional userAgent, sent with every page load in place of the platform WebView's default. Hosts opt in explicitly (for example from a user-managed profile); when omitted, behavior is unchanged and the system default is sent.

0.6.0

• Query-aware ranking (Phase 3 of the web evidence plan) completes the four-tool web surface:
  • open_web_page accepts an optional objective; the returned content is then the blocks most relevant to that question — ranked by a BM25-style lexical scorer with heading-path credit, block-type weights (tables and definitions boosted for numeric questions), and a positional prior — instead of the page's lead content. A Focused on: header line and […] gap markers keep the selection honest; an unmatched objective falls back to lead content with a note.
  • Adjacency grouping: a selected block always brings the headings above it and a short intro paragraph directly before it, so a bare $25 table row never travels without its "Fees" heading.
  • New find_in_page(pageId, query) function ranks a cached page's blocks for a new question and returns the best matches with their b<n> ids; unmatched queries return the outline instead of guesses.
  • Repeated blocks are marked duplicateOf and skipped in rendering and ranking (duplicateBlocks count on page results), so syndication banners and print footers are never mistaken for independent confirmation.
  • BlockScorer seam (FlutterHarnessAgentOptions.webBlockScorer, createWebSearchTools(blockScorer:)) lets hosts substitute a semantic scorer later; scores stay internal and are never exposed to the model.

0.5.0

• Page sessions and the escalation loop (Phase 2 of the web evidence plan): opened pages are cached per tool set so agents can pull more of a page without reloading it.
  • WebPageSessionStore — a small LRU (default 8 pages, configurable via WebSearchToolOptions.maxCachedPages) created per createWebSearchTools call, so page-N ids are scoped to one agent build and never leak across conversations. Reopening a URL replaces its earlier entry.
  • open_web_page results now include a pageId for block-bearing loads, and its description teaches the loop: package → outline → expand_page.
  • New expand_page(pageId, blockIds?, heading?) function returns the full text of chosen blocks or a whole outline section, each run prefixed with its Under: A > B heading context. Expired ids get a "reopen the URL" result; malformed requests return the outline to steer the next call. Budget caps are reported, never silent.

0.4.0

• open_web_page returns structured evidence packages (Phase 1 of the web evidence plan, doc/WEB_EVIDENCE_PLAN.md). The extraction script is now a thin DOM walker emitting typed blocks; Dart classifies them, assigns heading paths, builds the page outline, and renders compact markdown:
  • WebPageContent gains blocks (WebContentBlock with heading paths, links, and table cells), outline, structuredData (JSON-LD, labeled by origin), siteName/publishedTime/modifiedTime/author, contentMarkdown, and omittedBlocks/boilerplateBlocks counts.
  • Tool results carry content markdown plus an outline with b<n> block ranges instead of flat text; the flat shape remains the fallback when block extraction yields nothing. Navigation, header, footer, and aside chrome is suppressed from the markdown and counted, never silently dropped; in-script caps and the character budget are reported through omittedBlocks and truncated.
  • WebPageLoader's interface is unchanged and all new WebPageContent fields are additive with defaults.

0.3.1

• Focus-category search routing for the local web_search function: FlutterHarnessAgentOptions.webSearchSourcesByCategory (and the matching createWebSearchTools and addFlutterHarnessContext parameters) maps category labels — "finance", "technology" — to dedicated search sources. The labels become an enum on the function's category parameter so the model can steer a query to the source suited to its topic; they are the only part of the host's search configuration the model sees. Uncategorized calls use webSearchSource; with no default source, category is required.

0.3.0

• Add vendor-neutral local web search and direct page-opening tools for the Flutter harness. open_web_page renders JavaScript in an isolated, incognito headless WebView, extracts readable text and metadata, and applies a configurable public-network navigation policy.
• A configured local search source replaces the hosted web-search marker. A page loader may instead add only open_web_page while retaining hosted search. Both retain the existing per-agent web-search access gate.
• Add native headless page loading on Android, iOS, macOS, and Windows using flutter_inappwebview, with structured timeout, navigation, HTTP, loading, empty-content, and challenge-detection results. Flutter web reports the capability as unsupported.

0.2.1

• Pushover as a harness capability with per-agent gating:
  • FlutterHarnessAgentOptions.pushoverClient (plus pushoverToolOptions) — when a host attaches a configured PushoverClient, the harness adds the Pushover tools. Client-gated rather than flag-gated: the tools send real notifications, so they exist exactly when the host attached a client.
  • AgentAccessConfig.enablePushover — opt-in per saved agent, false by default. ConfiguredAgentFactory strips the client from agents that have an access record without the opt-in, wherever the client was attached; agents without an access record keep the harness default.
  • createPushoverTools and PushoverToolOptions — builds the send, quota, and receipt tool set from one configuration.

0.2.0

• Require agents: ^1.6.0, including the new live shell output stream and callback APIs and persistent-shell stderr capture.

0.1.0

First public release. Flutter integration layer for the agents framework.

• FlutterHarnessAgent — a one-call HarnessAgent preconfigured with the Flutter capabilities, compaction, function invocation, and per-call chat history persistence. Reachable from a ChatClient via asFlutterHarnessAgent(...), or through dependency injection with addFlutterHarness(...) / useFlutterHarnessAgent(...).
• Device-capability context providers and tools, each registrable on a ServiceCollection or directly on ChatClientAgentOptions:
  • Temporal — TemporalContextProvider plus the get_current_time tool.
  • Connectivity — ConnectivityContextProvider (with ConnectivityMonitor) plus the get_connectivity tool.
  • Device and app info — DeviceContextProvider, get_device_info, and get_app_info, with DeviceInfoHostedService and PackageInfoHostedService for the DI path.
  • Location — LocationContextProvider, get_current_location, and geocode_address.
  • Network — NetworkContextProvider and get_current_network_info.
  • Wake lock — the set_wake_lock tool.
  • Pushover — PushoverClient plus the send_pushover_notification, get_pushover_limits, and check_pushover_receipt tools, registrable with addPushover(...). Credentials stay out of the tool schema, so a model chooses what a notification says but never who receives it. Supports multipart image attachments, resolved from a model-supplied reference through a host-provided PushoverAttachmentResolver, and end-to-end encryption via PushoverAesEncryptor.
• Configured agents (configured_agents/): ConfiguredAgentsManager, ConfiguredAgentFactory, AgentScope, and persistent AgentConfigurationStore / ModelSourceStore for defining and switching agents at runtime.
• Model profiles (configured_agents/model_profile/): per-model chat and tool-call formats (Hermes, Llama 3, Mistral, LFM2), streaming tool-call decoding, think-tag filtering, GGUF metadata inspection, and OpenAiCompatibleChatClient.
• Chat history persistence: FlutterChatHistoryProvider, ChatMessageCodec, and stale tool-result redaction.
• Storage and memory built on sembast: RecordStore with in-memory and sembast backends, RecordStoreAgentFileStore, and RecordStoreVectorStore with a memory scorer.
• Downloads: DownloadService backed by background_downloader, plus a Hugging Face API client and model downloader.
• Logging: AppLogStore, an AppLogStoreLoggerProvider, and AgentTrafficLoggingAgent for recording agent request/response traffic.
• Chat client decorators: UsageTrackingChatClient and TextFileInliningChatClient.
• A2A pairing helpers under a2a/.
• Adaptive layout widgets under layout/.