Description
The Vault-Aware Agent Tool Loop wraps a tool-capable LLMProvider and carries a conversation through repeated model and workspace-tool turns until the model produces a final answer or a bound is reached. It offers five read tools, one authority-gated row-creation tool, and one HUMAN.md proposal tool through injected executors. Returned tool calls are executed, serialized into tool messages, appended to history, and sent back to the model.
Tool availability and execution are policy-aware. Callers can deny named tools, disable all tools with an empty source scope, confine reads to a row-grain retrieval wall, and forward the turn's acting principal to row creation. Canonical dotted tool names are mapped to provider-safe underscore aliases on the wire and restored for execution and telemetry. Buffered and streaming paths accumulate usage across every inner call.
Selling Points
- Turns a direct completion provider into an agent that can ground answers in live workspace knowledge.
- Injected executors keep data access, authorization, confirmation, and storage policy outside the provider package.
- Source and row-level restrictions make retrieval scope an enforced input rather than prompt advice.
- Streaming exposes final-answer deltas and live tool activity while preserving one durable terminal result.
- Deadlines and iteration caps finalize gracefully, preventing an endless tool loop without discarding accumulated context.
User Story
A Chat turn asks an OpenRouter-backed agent to compare several project rows and capture a resulting action item. The wrapper offers the allowed vault tools, executes scoped searches and row reads, then forwards the acting principal when the model requests creation. The concrete executor checks authority and approval. The user sees live tool activity and receives a final answer with usage accumulated across all steps.
Extension Surface
Extensible is the first true rung because packages/llm-providers/src/vault-agent.ts defines the injected VaultToolExecutors structural seam and accepts any inner LLMProvider. A composition can implement storage, access, and confirmation behavior without modifying the loop. The fixed seven-tool vocabulary is package-owned, so arbitrary external tool registration is not currently shipped.
Capabilities & Limits
- Executes scoped vault search, query, row read, Dotabase discovery, row creation, and HUMAN.md proposal tools.
- Supports buffered and streaming multi-step execution, tool events, usage accumulation, cancellation, deadlines, and iteration bounds.
- Maps provider-safe wire aliases back to canonical names and carries tool results through message history.
- Limits: a non-tool-capable inner provider or present-empty source scope becomes a single completion with no tools.
- Limits: executors own real authorization; the wrapper forwards policy but does not independently grant access or write data.
Implementation Map
packages/llm-providers/src/vault-agent.tspackages/llm-providers/src/vault-tools.tspackages/llm-providers/src/types.tsapps/web/src/composition/vault-tool-executors.tsapps/web/src/composition/playbook-scope-wiring.ts