feat(api): add the durable Agent Session API

[Yevanchen]

Parent

• feat(platform): pivot Mosoo to an API-first managed Agent runtime #546

What to build

Introduce one Workspace-scoped, API-first contract:

Agent + Input + Resources → durable Session

The first request creates a durable Session and starts its first turn. Later Input continues the same Session, workspace, and native Harness conversation.

The public request accepts:

• Agent: either a Mosoo-managed Codex or Claude Code slug, immediately callable without Agent creation, or a Workspace-private immutable Agent revision, immediately callable without Publish.
• Input: the task for the first or a follow-up turn.
• Resources: optional typed material such as files and Git repositories. Repository refs resolve and freeze to an exact commit before Harness startup.

The Session contract provides one primary public session_id, sequential follow-up Input, stable events, approval responses, cancellation of the active turn, terminal status, result, artifacts, raw usage, idempotent creation, and exactly one active turn at a time in v1.

Internal Run, response, and retry Attempt records may remain execution and observability details, but callers must not manage a second mandatory lifecycle ID. Events use their own stable IDs and a turn sequence for correlation.

A Session records the exact Agent revision, managed Environment revision, Harness version, and frozen Resources used for every turn. Existing Sessions do not silently adopt later Agent changes. Internal retry Attempts preserve frozen Input and Resource identities and stay inside the same public Session.

Environment is Mosoo-managed in v1:

• It is not required request input.
• Users do not create or select an Environment before the first useful request.
• Mosoo records the resolved immutable Environment revision for reproducibility.
• A public Environment catalog, custom Environment selection, and Environment Builder are outside this issue.

Durability means follow-up Input retains the Session workspace and reuses Codex or Claude Code native resume state where supported. A reclaimed runtime restores the promised durable state or fails visibly; it must not silently start a new conversation.

Use one external contract for Codex and Claude Code. Harness-specific request, resume, event, approval, and cancellation protocols remain behind the Driver boundary.

Remove the product-level Pet | Cattle dual type from Mosoo main as part of this vertical slice:

• Public and active internal contracts no longer ask callers or owners to choose an Agent kind.
• Session admission, sandbox subject, checkpoint, reset, lease, terminal, and resume policy no longer branch merely to make Pet and Cattle coexist in one product.
• Retain the neutral long-lived workspace, native resume, process control, and restoration primitives needed by durable Sessions and reusable mosoo-agent-driver consumers.
• Do not retain a permanent compatibility field that always says cattle.
• Mosoo Computer owns Pet product behavior; porting that product is outside this issue.

Billing, balances, subscription routing, invoices, and BYOK settlement are non-goals. Capturing truthful provider and runtime usage remains in scope.

Acceptance criteria

• A new Workspace uses its Workspace API key and a managed Codex slug to complete a real tool-using Session without creating an Agent, publishing anything, or configuring an Environment.
• The same external contract completes a real tool-using Session with Claude Code.
• A private Agent revision is callable immediately by its owning Workspace without Publish, Unpublish, Draft, or Live state.
• The first response exposes session_id as the only primary execution handle; no run_id, environment_id, or published agent_id is required by the caller.
• A second Input continues the same Session, observes files created during the first turn, and uses native Harness resume rather than silently starting a new conversation.
• Only one turn executes at a time; a conflicting follow-up fails deterministically without creating a second public execution object.
• Repeating an idempotent create request returns the original Session and does not start duplicate work.
• Every turn records the exact Agent revision, Harness version, Environment revision, and frozen Resource identities.
• Public and private Git repository Resources are materialized before Harness startup; a requested ref freezes to an exact commit reused by internal retries.
• Unauthorized private Agent or Resource references fail before Sandbox allocation, and materialization-only credentials do not enter the Harness process or public records.
• Events, approval, cancellation, terminal status, artifacts, and raw usage work through the Session contract.
• Active product, API, persistence, runtime policy, generated clients, UI, and documentation contain no Pet/Cattle selector or compatibility branch.
• Durable Session workspace restoration and native resume still work after removing the dual Agent type.
• A ghfind-compatible end-to-end test invokes a private evaluator revision with a typed Git repository Resource, follows one Session to terminal, and downloads validated analysis JSON, evidence JSON, and Markdown report artifacts.
• The ghfind-compatible flow requires no Agent Publish, Environment setup, or public Run ID; ghfind remains responsible for its own analysis ID, queue, validation, storage, and UI.
• Generated API clients and public documentation show both the managed-slug quickstart and private-revision ghfind flow.
• No billing, credit, invoice, subscription proxy, or BYOK settlement implementation is introduced.

Blocked by

• refactor(workspace)!: replace App and add Workspace API keys #581 — Workspace identity and key authentication must land before the new Session API replaces App-bound admission.