0013: Results by reference and background jobs¶
Status: proposed for M2 (step 3 of proposal 0010). Covers spec RES-5 and the long-running report pilot. Builds on the store from proposal 0011.
Problem¶
A large result could only be trimmed to the budget or refused. A slow tool held the call open until its deadline, and nothing let an agent come back for the answer later.
Proposal¶
OunceServer(handles=True) registers two read tools: handles.read(handle, cursor, limit) (115 tokens) and jobs.get(job) (151 tokens). They are opt-in, so existing catalogs do not change.
await ctx.store_result(items, ttl_s=3600)stores a list and returns a handle.handles.readpages it with the budget-aware pager, so a page never exceeds the result budget and cursors resume without gaps (RES-9).await ctx.start_job(work, ttl_s=3600)runsworkin the background and returns a job id at once.workreturns a summary (model or dict) orJobResult(summary=..., items=[...]); items are stored behind a handle.jobs.getreportsrunning,done(summary, handle, item count),failed(category and message, never internal details) orinterrupted.- Handles and job ids are signed state tokens (SEC-6) bound to the caller and tenant, with an expiry. Another caller gets
invalid_state. - Data and job records live in the store, so with a shared store any replica serves them and they survive a restart. A job runs in the process that started it and renews a 30-second lease; if the process stops, the lease runs out and
jobs.getreportsinterruptedwith "start it again".
Measured on the report pilot: all 2,000 rows would cost 52,002 tokens; jobs.get costs 168 and one 50-row page 1,351.
Alternatives considered¶
- Spilling over-budget results to a handle automatically. The result would no longer match the tool's output schema (RES-8). Authors return a handle field explicitly instead.
- The MCP tasks extension for jobs. It is an extension, not core 2026-07-28, and client support varies. Plain tools work with every client; mapping jobs onto tasks can come later.
- Resuming interrupted jobs. Needs durable work queues; out of scope for M2.
Impact on tokens and task success¶
Two extra definitions (266 tokens) when enabled. Large results cost a summary plus the pages the agent actually reads.
Migration notes¶
None; handles are off by default.