ContextProvider interface
The public interface exposes name and fetchContext(query, ctx): Promise<string>. Return an empty string to contribute nothing. resolveContextProviders() calls the providers in parallel and joins their results under Markdown ## Context: <name> headings. Thrown errors become labeled context text; they are not silently omitted.
There is no AgentConfig.context or RunOpts.context field in v4. Assemble context in host code before calling the Agent.
Built-in providers
Filesystem paths are checked against
basePath; unreadable files are skipped. Prefer an explicit files list. The v4 glob implementation matches immediate file names; do not assume recursive ** traversal. Character caps are not token budgets.
HTTP non-2xx responses produce a status message; network errors propagate to the resolver’s labeled error text. There is no built-in TTL cache, request timeout, POST body, or retry option. Wrap the public provider contract if your host requires those behaviors.
Plugging into an Agent
This complete host function accepts a model and a verified user ID. Create./agent-notes/returns.md before calling it. It reads the file and a local preferences map, places the resolved text in run metadata, and reads that value through the supported instructions resolver.
resolveContextProviders(providers, query, ctx)
The helper returns one combined string. Inspect required sources before invoking the model if missing or failed data should block an answer. Its default error-as-text behavior is useful for optional context, but does not establish that a required lookup succeeded.
Caching strategies
Cache only data with an explicit owner and expiry. Include tenant, user, query, and relevant permissions in cache keys when they affect the result. A single cached string on a shared provider can leak one user’s context into another run. A wrapper must still implementfetchContext, not fetch.
Per-user context
Usectx.userId and ctx.tenantId to scope application queries. Passing an identity is not authentication, and file/HTTP providers do not infer access rights. A host may select a different base directory or endpoint after authorizing the caller.