zuraffa/agent library
Dedicated barrel for the Zuraffa agent runtime (issue #1344).
Why this barrel exists
zuraffa 6.2.x's agent runtime (src/agent/**: kernel, policy, runtime,
shell, ui_render) was originally re-exported from the default
package:zuraffa/zuraffa.dart barrel. That collided with ecosystem
packages — notably zuraffa_agent — whose own domain entities carry
generic agent-domain names (LlmClient, RiskTier, ToolResult, and
the wider agent-domain name class): every file importing both packages
failed with ambiguous-import errors at load time (5 files / 8 error
sites in zuraffa_agent alone).
The runtime is therefore gated behind THIS dedicated import — the same split pattern as Flutter's material vs widgets libraries. The default barrel no longer re-exports any of it; nothing else changed.
What is exported
The export surface below is byte-for-byte the surface the default
barrel used to carry for the agent runtime (same four entry libraries,
same hide clauses), so consumers migrating from the old default-barrel
imports only swap the import URI:
import 'package:zuraffa/agent.dart';
- ui_render (spec 023): the
ui.rendertool + streaming UI event channel + action-loop closure. Agents author a component tree validated against the UI Vocabulary Schema; user interactions route back as semantic actions.ValidationResult,ValidationError, andMissionTraceRecorderare hidden:ValidationResult/ValidationErrorwould collide with the plugin-lifecycle subsystem when combined with the default barrel, andMissionTraceRecorderis defined by BOTH the ui_render plugin and the policy shell (unrelated features that coincidentally share the name — the policy shell's wins, as it did in the default barrel). Consumers needing ui_render's variants can importpackage:zuraffa/src/agent/ui_render/ui_vocabulary_schema.dartdirectly. - kernel (spec 026): mission coalescing, cancellation, partial
salvage, idempotency cache — the kernel's efficiency + safety core.
CancelToken,Mission,MissionEvent,MissionEventCompleted, andMissionEventFailedare hidden so the runtime plugin's declarations of those names win, exactly as in the old default barrel. - policy shell (spec 027): ToolGatingHook, MissionBudgetHook,
MissionTraceRecorder — the framework-default safety/governance layer.
ToolCallContextis hidden (the same mechanism the default barrel always used). - runtime plugin (spec 028): AgentRuntimePlugin + McpToolProvider
SPI.
McpTool,AgentHook,McpToolRegistry, andAgentKernelare hidden —McpTool/McpToolRegistrybelong to the core MCP module in the default barrel, and the kernel'sAgentKerneldeclaration wins over the runtime's same-named class, preserving the arbitration the default barrel performed.
Consumers importing the runtime's source files directly
(package:zuraffa/src/agent/...) are unaffected: those declarations are
identical to what this barrel exposes.
Classes
- ActionRouter
- Interface the UiRenderTool uses to deliver routed SemanticActions back to the agent (FR-004). Implementations translate to whatever the agent runtime supports (tool result, steering message, etc.).
- ActiveMissionInfo
- Info about one active coalescing group.
- AgentKernel
- The agent kernel — coordinates mission coalescing, cancellation, and partial-salvage (issue #388).
- AgentRuntimePlugin
- The runtime module plugin that assembles the tool registry, wires the kernel, and manages the agent lifecycle (issue #386).
- AgentState
- Per-mission session state (FR-009).
- ArgumentHasher
- Hashes tool-call arguments (FR-008).
- ArtifactReference
- A compact reference to an externally stored large result (FR-010).
- BudgetBreach
- Typed budget-exceeded event (FR-006).
- BudgetTracker
- Tracks current usage against a MissionBudget and detects breaches.
- CancellationResult
- Result of a cancellation sweep.
- CapturingActionRouter
- In-memory ActionRouter capturing delivered actions for test inspection.
- CoalescingGroup
-
A coalescing group: one executing
Mission+ its subscribers (FR-002). - FallbackLLMClient
-
Default LLM client wired by AgentRuntimePlugin (FR-007). Mirrors
dart_agent_core'sFallbackLLMClient: tries the primary client; on failure, falls back to the secondary. - FileStateStorage
- Persistence interface for AgentState (FR-009).
- HookDecision
- Outcome of a tool call evaluation.
- HookDecisionAllow
- HookDecisionCancelMission
- HookDecisionDeny
- HookDecisionNeedsConfirmation
- IdempotencyCache
- A TTL-bounded idempotency cache (FR-007).
- InMemoryFileStateStorage
- In-memory FileStateStorage used for tests and as a no-op fallback when no real storage is configured.
- Introspection
- Provides introspection endpoints for the kernel.
- IntrospectionSnapshot
- Snapshot of the kernel's current state for operator introspection (FR-008).
- KernelConfig
- Configuration for the AgentKernel (FR-010 — configurable coalescing window; FR-009 — single-isolate documentation).
- KernelStatus
- Structured kernel status report (FR-011).
- LlmClient
-
LLM client interface (FR-007). Real implementations delegate to
dart_agent_core'sFallbackLLMClient. - McpToolContext
- Context passed to McpToolProvider.buildTools (FR-001). Acts as a DI accessor so providers can resolve dependencies they were registered with.
- McpToolProvider
- SPI interface implemented by device packages to declare their available MCP tools under a namespace (FR-001, FR-002).
- Mission
- The kernel's structured input (FR-008).
- MissionBudget
- Per-mission budget across four dimensions (FR-005).
- MissionBudgetHook
- Policy hook that enforces four-dimension mission budgets (FR-005, FR-006). On breach, emits a typed BudgetBreach event via onBreach and cancels the mission by returning a HookDecisionCancelMission.
- MissionEvent
-
Typed events streamed by
AgentKernel.runMission(FR-008). - MissionEventAssistantMessage
- MissionEventCancelled
-
Mission was cancelled; partials salvaged as
cancelled_partial. - MissionEventCompleted
- MissionEventFailed
- MissionEventPartial
- Partial result emitted mid-execution.
- MissionEventProgress
- Progress tick — non-result status update.
- MissionEventStarted
- MissionEventToolCallResult
- MissionEventToolCallStart
- MissionKey
- Composite key identifying a coalescable mission (FR-001).
- MissionOutcome
-
Terminal outcome of a mission (one of
completed,cancelled_partial,failed,cached_served). - MissionTrace
- The mission trace (FR-007).
- MissionTraceEntry
- One recorded entry in a mission's render trace.
- MissionTraceRecorder
- Records the mission trace (FR-007, FR-008, FR-009).
- OutcomeCachedServed
- OutcomeCancelledPartial
- OutcomeCompleted
- OutcomeFailed
- OversizedResultGuard
- Intercepts tool results exceeding threshold bytes and replaces them with an ArtifactReference before they enter model context (FR-010).
- PartialSalvager
-
Salvages partial results from a cancelled mission into the mission
record with a
cancelled_partialoutcome (FR-005). - PermissionRegistry
- Registry mapping tool name patterns to RiskLevels (FR-001).
- PolicyDecision
- A pending policy decision for one SemanticAction.
- PolicyGate
-
Intercepts
confirm-tier actions and gates them behind user approval (spec FR-006). - PolicyHook
- A composable policy hook that intercepts the agent loop (FR-011).
- PolicyShell
- Composes policy hooks in registration order (FR-011).
- RemoteMcpServer
- A remote MCP server registered with the runtime plugin.
- RenderedView
- A live, interactive UI instance produced by the agent (spec Key Entities).
- ResourceHandle
- A disposable resource handle that participates in cancellation (FR-004, FR-006). Examples: webview pool entry, network request, open stream.
- SemanticAction
- A user interaction captured from a rendered view (spec Key Entities).
- StatefulAgent
-
SPI for
dart_agent_core'sStatefulAgent(FR-005, FR-013). - StubStatefulAgent
-
A stub StatefulAgent that emits a start + completed event pair.
Used in tests and as a fallback when
dart_agent_coreis not on the path. - SystemPromptComposer
- Composes the system prompt from playbook text + tool manifests (FR-006).
- ToolCallContext
-
Context for a tool call passed to
AgentHook.beforeToolCall. - ToolCallRecord
- A single tool-call record in the mission trace (FR-007).
- ToolDecision
-
Decision returned by
AgentHook.beforeToolCallto short-circuit a tool call. - ToolDecisionAllow
- ToolDecisionDeny
- ToolGatingHook
- Policy hook that gates tool calls based on the PermissionRegistry (FR-001, FR-002, FR-003, FR-004, FR-012).
- ToolResult
- Result returned by a tool.
- UiEventChannel
- A broadcast stream of UiRenderEvents.
- UiNode
- A node in an agent-authored component tree.
- UiRenderEvent
- A single event on the UI render stream.
- UiRenderEventDone
- The render stream is complete (no more partials coming).
- UiRenderEventError
- An error during render / validation. Carries the typed exception so the host UI / agent can branch on the error kind (FR-002).
- UiRenderEventInteraction
- A user interaction has been captured on a rendered tree (FR-004).
- UiRenderEventPolicy
- A policy decision has been made for a confirm-tier action (FR-006).
- UiRenderEventRender
- A tree (or partial tree) has been rendered and is ready for the host UI to paint (FR-001, FR-003).
- UiRenderEventReplace
- A previous view has been replaced by a new tree (FR-001 acceptance 2).
- UiRenderTool
-
The agent-facing
ui.rendertool (spec FR-001). - UiVocabularySchema
- The canonical UI Vocabulary Schema (spec Key Entities).
- VocabularyNarrowingConfig
- Per-mission-type vocabulary configurations. Production apps declare these via configuration, not code (spec Assumptions).
Enums
- ActionTier
-
The risk tier of a semantic action (spec US5 —
confirm-tier gating). - BudgetDimension
- Which budget dimension was breached (FR-006).
- CancelPolicy
- Per-subscriber outcome — used when original cancels but subscribers continue under a new mission (FR-003 escalation policy).
- MissionStatus
- Status of a mission's lifecycle.
- RiskLevel
- Risk tier for a tool call (FR-001).
- RiskTier
- Risk tier declared on the mission (intercepts with the policy shell, see spec 027).
- ToolCallStatus
- Status of a tool call as recorded in the trace (FR-007).
- ValidationErrorKind
Functions
-
buildStatus(
McpToolRegistry registry, {Map< String, String> providers = const <String, String>{}, Map<String, String> remoteServerHealth = const <String, String>{}}) → KernelStatus -
Builds KernelStatus from a
McpToolRegistry+ remote server map. -
computeContentHash(
UiNode tree) → String - Computes a stable content hash for a UiNode tree (FR-008).
-
runCancellation(
CancelToken token, List< ResourceHandle> handles) → Future<CancellationResult> -
Runs the cancellation protocol against
handlesusingtoken. Returns a CancellationResult once the grace period completes. -
vocabularyNarrowing(
String? missionType, UiVocabularySchema baseSchema, {VocabularyNarrowingConfig config = VocabularyNarrowingConfig.empty}) → UiVocabularySchema - Resolve the active schema for a mission type (FR-005). Returns the narrowed schema if one is declared, otherwise returns the base schema.
Typedefs
-
ApprovalCallback
= Future<
bool> Function(String prompt) - Approval callback signature for confirm-tier tools (FR-002).
- BudgetBreachCallback = void Function(BudgetBreach breach)
- Callback fired when a budget breach is detected (FR-006).
- BudgetDegradeCallback = void Function(BudgetBreach breach)
- Budget-degrade integration point (FR-013).
-
MissionExecutor
= Future<
MissionOutcome> Function(Mission mission, CoalescingGroup group, CancelToken cancelToken) - Signature of the executor that runs a single mission to completion. Returns the terminal MissionOutcome.
-
ToolInvoker
= Future<
Object?> Function(String canonicalName, Map<String, Object?> args) -
Invokes a registry tool by canonical name (
"$namespace.$toolName").
Exceptions / Errors
- NamespaceCollisionException
- Thrown when two tool sources register the same canonical name (FR-012).
- NoActiveMissionException
-
Thrown when
ui.renderis called with no active mission (spec Edge Cases). - ToolDeniedException
-
Thrown by
AgentKernel.invokeToolwhen anAgentHookdenies a tool call via ToolDecisionDeny (FR-010). - UiRenderValidationException
-
Typed exception thrown by
UiRenderTool.renderwhen validation fails. - ViewNotFoundException
-
Thrown when
replaceViewIdreferences a view that does not exist (spec Edge Cases).