agentlib glossary.

An AgentSpec is the declarative definition of an agent: its name, system instructions, chosen ModelProvider, and available tools/skills. It converts to a RunConfig that the Runner executes, so the same spec runs unchanged on-device or in the cloud.

See: Primitives

The Runner drives the agent loop and emits a stream of typed events — TextDelta, ToolCalled, Finished — so your UI can render tokens as they arrive. Its state is a serialisable RunState, which is what makes suspend/resume possible.

See: Survives backgrounding

Subagents let a parent agent delegate work to child agents that each have an independent context window and compaction. Deep work in a subagent doesn't bloat the parent's context. Dispatch is sync, parallel, or background via the Task API or the task CLI.

See: Primitives

A skill is a markdown bundle whose name and description sit in the orchestrator context, but whose body loads only when the skill is invoked. That progressive disclosure keeps large catalogs cheap: a 30-skill catalog costs roughly 600 tokens instead of thousands.

See: Primitives

Snapshots capture run state so a user can undo an action or a developer can fork to a different model mid-run. They're content-addressed and SQLite-backed, and agentlib auto-snapshots before any tool marked highImpact: true — so a mistaken high-impact action is one revert() away.

See: Primitives

Hooks are deterministic interception points — PreToolUse, PostToolUse, SubagentStart, OnSuspend, OnLowBattery, OnNetworkChange, and more (21 in total). They wire consent sheets, analytics, audit logs, and lifecycle behaviour without prompt hacking.

See: Architecture

The Vfs is a virtual filesystem confined to the app sandbox. It exposes mounts such as /workspace, /scratch, /system, /apps, /bin, /memory, and /snapshots. Tools live under /bin as CLIs the model can compose in the Sh shell.

See: In-app assistant

Sh parses real pipes (|), redirects (>, >>), variables ($VAR), and command substitution ($(cmd)) — the idiom frontier LLMs are most fluent in — but never actually execs anything. Each 'binary' is a registered Dart function; each pipe is an in-memory stream. No & backgrounding, no eval.

See: MCP on mobile

ModelRoute.preferOnDevice([...]) selects the first capable on-device provider and escalates to a cloud provider only when the local one can't satisfy a request. It removes on-device/cloud branching from your app code entirely.

See: On-device

agentlib speaks the Model Context Protocol over HTTP and WebSocket. Connected MCP tools surface as /bin/mcp.<server>.<tool> CLIs, so the model can pipe their output through the Sh shell like any other command.

See: MCP on mobile

A ModelProvider is the common shape for models. Apple Foundation Models, Gemini Nano, llama.cpp (via Fllama), MediaPipe, Anthropic, OpenAI, and Google all implement it, which is what makes on-device and cloud models interchangeable inside an AgentSpec.

See: On-device

RunState captures everything the Runner needs to continue: context, pending tool calls, and progress. Because it's serialisable, you can persist it when the OS is about to suspend the app and rehydrate it later — even from an APNs/FCM push.

See: Survives backgrounding