FAQ
Positioning
Why not just define AI SDK tools by hand? For three tools, do. The costs arrive with scale and stakes: duplicated schemas drifting from your API, ad-hoc auth per tool, string errors leaking internals, nothing audited, no approval story, and a second implementation of every operation your UI already has. oRPC Agent's bet: you already wrote the operation once as an oRPC procedure — govern that, everywhere (migration guide).
Is this an agent framework? No. It has no loop, no planner, no memory, no prompts. It is the layer under your loop (AI SDK, OpenAI Agents SDK, LangGraph, Mastra, hand-rolled) that makes what the loop can do governed. Pick any loop; keep it.
How does it relate to oRPC's own ecosystem (OpenAPI, etc.)? oRPC owns contracts and transports; this project adds agent-specific governance (exposure, policies, approvals, audit) as a separate, independent layer. If oRPC ships overlapping integrations, ours remain a governance wrapper over the same procedures. This is not an official oRPC project (ADR-011).
Does it work with tRPC / plain functions? No. The design leans on oRPC's meta, context, middleware-in-call-path, and Standard Schema support. The concepts port; the code targets oRPC deliberately (narrow and coherent beats broad and vague).
Which model providers are supported? Any the Vercel AI SDK supports, and anything speaking MCP. Core never touches a provider (ADR-003). "Works with every provider" is not claimed — adapters are tested against specific SDK major versions (peer ranges in each package).
Security
Does it prevent prompt injection? No, and distrust anything that says it does. It bounds the impact of a steered model: allowlisted narrow capabilities, execution-time authorization, approvals bound to exact inputs, minimized outputs, full audit (prompt-injection).
If I filter tools per user, isn't that enough? No — filtering shapes conversations; requests can arrive anyway (hallucinated names, other surfaces, bugs). Every invocation re-runs exposure, policies, middleware, approvals (SI-2, ADR-005).
Can the model approve an operation if I give it an "approve" tool? Don't. The design's answer is structural: approval decisions flow through runtime.approvals.decide, which is your authenticated app surface, and the approver must differ from the requesting actor (SI-4). Exposing a decide-capability to a model surface reintroduces self-approval through the side door.
Is execution exactly-once? No, and no library that doesn't own your datastore can honestly claim it. Guaranteed: at-most-once result finalization per execution, single-use approvals, no auto-retry of writes, and stable idempotency keys for your deduplication (idempotency-and-retries).
Why must risk be spelled out even for reads? Because sensitivity ≠ side effect (a salary read is high-risk), and because deriving it would silently misclassify. The friction is the feature: someone decides, in a reviewable diff.
Design
Why an envelope instead of throwing?approval-required is a normal outcome; adapters need exhaustive, typed cases; exceptions across adapter boundaries lose information. unwrap() exists when you want throwing ergonomics (concepts/runtime).
Why can't policies modify input? Silent rewrites make audit records lie ("model asked X, Y executed") and breed heisenbugs. Deny with a message; the model adjusts and re-asks — visibly (SI-6, open-questions Q6).
Why dot-path ids instead of configurable names? One naming truth. Ids feed approvals, audit, policies, tool names — an alias layer would drift. Renaming a path is a breaking change and should feel like one (concepts/registry).
Why is there no built-in approval/audit database? Storage requirements (retention, residency, compliance) diverge too much; interfaces + your store beat a bundled database you'd fight (ADR-010, ADR-007). In-memory implementations ship for dev/test.
Streaming outputs? Deferred. oRPC supports event iterators, but governed streaming (validate/redact/audit chunks?) needs design work — open-questions Q11. Capabilities return complete values; the registry rejects event-iterator outputs with a clear error.
Practical
What does the governance layer cost at runtime? About 65 µs per invocation over a raw oRPC call, and three policies plus an audit sink add nothing measurable on top — policies are deterministic synchronous functions and audit emission is off the critical path. Discovery is the part that scales with catalog size, and scope is the knob. Measured figures and the two things that genuinely cost: cost and performance.
What's the minimum viable adoption? One procedure annotated, one registry, one runtime, toAISDKTools — ~20 lines over what you have (getting-started). Policies, approvals, audit, MCP are additive later.
Can my UI use the runtime too? Yes — surface: "direct" gives UI actions the same audit trail and policy evaluation as agent calls. Optional; your existing oRPC routers keep working unchanged either way.
What happens to my existing oRPC middleware? It runs, unchanged, on every governed invocation — inside the procedure call, as always, and it remains the authoritative authorization layer (ADR-008).
I'm on 1.x — what does upgrading to 2.0 cost? One field read, if you consume the capabilities.discovered audit event; nothing otherwise. Full instructions: migrating 1.x → 2.0.