feat(api): add the durable Agent Session API

Outcome

Deliver the managed Agent + durable Session execution contract from #546 and SPEC #622. A Project key starts work immediately; a reply seconds or days later continues the same work through one Session ID, including after sandbox reclamation.

API and ownership

The existing Thread routes, conversation IDs and compatible Run response fields may carry the Session contract. There is no required cosmetic rename or old-endpoint sunset. Any incompatible admission, identity, saved/live selection or outcome behavior needs its own compatibility and Cloud transition evidence.

• Accept a managed Codex/Claude Code Agent or a saved Project-private Agent ID, input, and optional files. No Publish, live-version selector, App Deployment, Environment setup, or mandatory public Run ID.
• New Sessions resolve a saved Agent's latest configuration. Internally retain the admitted instructions, Skills, MCP references, runtime/model, and environment identity for that Session. Existing Sessions do not adopt later Agent edits.
• Reuse #581 Project authorization. Project keys remain isolated; CLI login can operate in an explicitly selected owned Project. A first-use managed Agent does not require user-supplied provider credentials.
• Expose creation, input, cancellation, retrieval, persisted history/SSE, and artifact access through one Session lifecycle. Creation idempotency is optional and Project-scoped: identical key/request returns the original Session; changed input under the same key fails explicitly.
• One active turn; reject busy input without queuing or steering. A completed turn leaves the Session open for follow-up.

Continuity and truthful completion

A Session retains prior conversation context, the complete promised workspace, and its admitted execution configuration. Warm follow-up and recovery after runtime reclamation must continue the same work without the caller reconstructing that state.

• Persist required artifacts, events, usage, and a restorable checkpoint before exposing successful completion or reclaiming uncommitted state.
• Use one committed boundary for follow-up admission and restoration. Backup existence alone does not prove usable continuation. Reuse existing state where it satisfies the contract; related #589 work must not duplicate durable payloads.
• Missing, corrupt, failed, or expired recovery state fails explicitly. Do not silently open an empty conversation or substitute selected artifacts for the complete workspace.
• Preserve truthful failure, cancellation, and budget-exhaustion outcomes and available artifacts. A provider error must not appear as a completed task; include the observed Claude insufficient-credit case in outcome checks.
• Recovery remains available for at least 30 days after the last successful turn and renews with successful follow-up. Expiry rejects continuation while preserving history and saved artifacts under their normal lifecycle.
• Keep Project isolation, credential exclusion, and existing necessary backup safety constraints. Live processes, sockets, and machine-wide temporary state are outside the promise.

Execution and inputs

Use full access for already integrated runtimes within the Session sandbox and authorized resources. Interactive tool approvals are deferred. Keep existing remote HTTPS MCP and Skills capabilities; new custom runtimes and local-process MCP support are outside this slice.

Support file upload and output download. ghFind may supply a public repository URL and exact commit for the Agent to fetch with existing tools, or optionally upload material from that commit. Record and independently validate the actual material identity across retries. Do not require typed Git mounting, private Git authorization, or branch/PR workflows.

Provide platform default model access and bounded turn budgets. Models, provider supply, budget defaults, caps, and operational limits must be configured and verified before first-use acceptance. Existing BYOK remains optional. Usage is truthful; billing, balances, settlement, subscriptions, invoices, and payments are not implemented here.

Owner decision (September 18): defer launch allowances and default provider funding values. Continue technical implementation and acceptance using explicit test configuration and the authorized staging providers. Production default supply remains a pre-release decision; this does not authorize production funding or deployment.

Pet/Cattle removal

Remove the product type and behavior existing solely to support both types in Mosoo main: public fields, selectors, GraphQL/client contracts, execution policy, active persistence usage, and UI. Keep Session durability and neutral Driver primitives used by Mosoo Computer. No forever-cattle field or permanent old-Type compatibility branch.

Inventory legacy runtime state and preserve promised history before a cutover. Physical destructive/data-rewrite migration is a separately approved production step, not implicit authorization from this issue.

Acceptance criteria

• A Project key invokes both managed Codex and Claude Code with actual tool calls, without a provider setup, published Agent, Environment selection, or separate public Run ID.
• A private Agent is immediately callable by ID; new Sessions use latest configuration while existing Sessions keep their admitted snapshot.
• ghFind completes one evaluation turn and produces validated analysis JSON, evidence JSON, and a Markdown report from recorded fixed-commit material; duplicate idempotent creation does not repeat work.
• CSV analysis produces verified outputs and successfully modifies them through the same Session seconds later, using prior context and files that were not resupplied.
• The same continuation works after multi-day idle state and forced runtime reclamation, including working files outside published artifacts. Deterministic clock tests and actual delayed live evidence are identified separately.
• Checkpoint failure cannot expose false success, admit a follow-up from mismatched state, or recycle uncommitted work; retry preserves the preceding committed boundary until the new state is ready.
• Missing/corrupt recovery fails explicitly; expiry and renewed retention are verified without deleting history/artifacts.
• Busy rejection, cancellation, budget exhaustion, provider errors, Project isolation, credential protection, events/SSE, and usage have focused coverage.
• Current public API clients/docs use the Session contract and no publishing/version-selection requirement.
• Pet/Cattle product branches and active public fields are removed; migration treatment and rollback are reviewed.
• Default provider supply and budget values are configured and both real acceptance paths pass before release.
• Cutover and Cloudflare notification evidence are complete before closing the shipped issue.

Delivery and migration

The reviewed contract is SPEC in #622; this scope incorporates the owner's September 10 clarification that replies seconds or days later must continue the same Session consistently. Earlier issue text and comments do not reintroduce historical-version invocation, interactive approvals, or typed Git infrastructure into v1.

Intentional breaking changes are accepted with an explicit cutover, treatment of admitted work, preserved promised history, compatible clients, and a rollback point. Production D1 remains append-only. Destructive or data-rewrite operations require separate explicit approval, backup, verification, and rollback procedures. Prepare the affected audience and migration notice before release; use Cloudflare Email Service and reconcile sending outcomes plus sample inbox/content verification. The completed #581 key notice does not cover later Session or Builder changes. Documentation updates do not authorize a production deployment or trigger a new email.

Start by reading SPEC #622 and #546, then trace the existing Thread routes, compatible Run response fields, and #581 Project authorization; check related #589 for durable payload overlap. Done means the listed acceptance paths pass, including session recovery, truthful outcomes, project isolation, API compatibility, and the reviewed migration and notification evidence.