Bounded consumption of durable batch results (#6414)

[Guo-Yixin]

Scope proposal for #6414, following the feature form requirement for an Ideas discussion before implementation.

Problem / motivation

At official main 35cdcab1c5492e27e5d4dc525861256344cc5133, durable batch tools expose only batch_task, batch_status and cancel_batch. The database already retains per-item reports, errors, criteria and acceptance verdicts, and owners can export them through HTTP. A later lead-agent turn in the same thread cannot consume that durable output through its registered tools to summarize findings or diagnose an unmet condition. Counts describe execution only; they do not supply the report or acceptance evidence.

The scenario is an explicit independent-item research/review batch followed by an owner requesting synthesis of selected completed items, including after Gateway restart. This proposal preserves the original bounded-context batch design: no automatic push of every result into the lead context, no waiting/polling loop, and no task re-execution.

Proposed scope

• Add read_batch_result to the existing opt-in durable batch tool family, in both Gateway and explicitly bound SubagentRuntime graph assembly.
• Read one stable zero-based item position from the current user's current thread. User/thread identities come from trusted tool runtime, not model arguments. Use the existing repository projection; never return prompt, execution_spec, credentials or lease state.
• Serialize that item's report, execution/error state and separate criteria/verdict into a data document. Return a bounded character window (default 4,000, maximum 8,000), exact document offsets, next_offset, total length and a content revision. Reassemble then parse the document; an individual window need not be valid JSON.
• Require the previous content revision for continuation. If the item changes through completion/retry/cancellation between reads, return a restart-required result, preventing mixed-attempt documents. Reads are non-mutating and do not acquire execution slots.
• Keep execution success distinct from acceptance; pending/running items return current persisted state without waiting. Full JSONL export remains the bulk consumer.
• No SQL migration/dependency/provider/UI changes; no RAG evidence dependency on the still-open feat(subagents): preserve RAG evidence in durable batch exports #6413. The document includes existing report/acceptance fields, not arbitrary future artifacts.

Acceptance

Actual batch submission and deterministic worker completion -> SQL close/reopen -> bound tool through a compiled ToolNode -> bounded continuation -> complete report and stored acceptance verdict. Cover wrong user/thread, unavailable/stopped SDK runtime without global fallback, current schema and real tool registration, Unicode/escaped content, invalid offsets/budgets/revisions, long metadata, empty/nonterminal/failed/cancelled items, retries and changed-state continuation. Ordinary batch tools and bulk export remain compatible. Run before/after full and blocking-I/O suites, relevant controls, lint/format/lock/guidance and independent AI review.

Architecture and alternatives

This extends the native batch service's existing runtime bridge and tool registration; an extension currently has no public capability to read owner/thread-scoped batch results from that service. Reusing the native read projection avoids a second executor, storage or HTTP self-call carrying application credentials. This is a core batch-consumption contract, with no domain-specific business workflow in core.

Automatic ingestion of all reports would undo the large-batch context guard. HTTP JSONL is still useful for humans and bulk clients, but does not provide a model tool in the native graph. This read capability supplies the missing bounded, explicit consumer only.

Duplicate / ownership check

Searched issues and open/merged PRs for batch results, batch read results, batch synthesis, and read_batch_result; found #4998 (native durable batches), #5289 (item acceptance) and #6413 (captured RAG evidence export), not this model-facing bounded consumer. #6411 pause-preserving retry is owned by 97Three and is outside this scope. #5201 scoped Memory management is also a separate owned workflow. No claim of model-quality or performance improvement; no paid experiment planned.