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

[Yevanchen]

Decision

This issue is the decision source for the Mosoo main pivot. Implementation must update the canonical product and architecture documents before changing the corresponding boundaries.

Mosoo becomes an API-first managed Agent runtime:

Select an Agent, provide Input and Resources, and receive a durable cloud Session with events, artifacts, and usage.

The first-use experience is OpenRouter-like: create one Workspace API key, select a callable Agent, and make a request. This describes the developer experience, not OpenAI wire compatibility.

This decision replaces the previous environment-first, Agentless Run proposal in this issue and supersedes the Harness Marketplace implementation direction explored in #561.

Product boundary

Mosoo does not define the customer's vertical workflow.

The calling application owns its domain logic, end-user identity, queue, validation, storage, and UI. Mosoo owns Agent execution, managed sandboxing, durable continuation, approvals, events, artifacts, usage measurement, and cleanup.

The console supports the API product:

• Manage Workspace keys and private Agent revisions.
• Inspect Sessions, events, artifacts, and usage.
• Answer approvals and continue or cancel work.
• It is not an App deployment or hosting surface.

Public model

Agent + Input + Resources → durable Session

Concept	Meaning
Agent	An executable Mosoo-managed Agent or a Workspace-private immutable Agent revision.
Input	The instruction or message for the current turn.
Resources	Typed application-supplied material such as repositories and files, authorized, resolved, and frozen before execution.
Session	The durable continuation boundary: workspace, native Harness resume, events, artifacts, approvals, status, and usage.
Environment	Mosoo-managed execution infrastructure resolved internally from the Agent and runtime requirements. It is not required first-request input or a public v1 catalog.

A managed Codex or Claude Code Agent is immediately callable. No Agent creation or publishing is required.

Applications with reusable instructions, Skills, tools, policies, or output contracts may create a Workspace-private immutable Agent revision and call it directly with their Workspace key. Creating a revision is optional; publishing is never an execution prerequisite.

Illustrative SDK shape:

const session = await mosoo.sessions.create({
  agent: "codex",
  input: "Analyze this repository and produce a report.",
  resources: [
    {
      type: "git_repository",
      url: "https://github.com/example/project",
      ref: "main",
    },
  ],
});

await mosoo.sessions.sendInput(session.id, {
  input: "Now turn the findings into an implementation plan.",
});

Endpoint, SDK method, and concrete slug names remain open. The first request must require only:

1. A Workspace API key.
2. A managed Agent or private revision.
3. Input.
4. Optional Resources.

session_id is the single primary public lifecycle handle. A Session permits one active turn at a time. Internal Runs, responses, and retry Attempts may exist for execution isolation and observability, but callers must not manage a second mandatory lifecycle ID.

Durable Session semantics

The selected direction is multi-turn:

• Follow-up Input continues the same Session.
• The Session retains its workspace and uses native Harness resume.
• The Session pins its resolved Agent, Harness, and managed Environment revisions.
• Each turn records the exact Input, Resources, events, artifacts, and usage that produced it.
• Runtime retry Attempts preserve the frozen Input and Resource identities for that turn.
• Approval, cancellation, terminal status, and cleanup are available through the Session lifecycle.

This is Session-scoped durability, not a Pet identity or permanent personal computer.

Environment and Resource boundary

Environment is managed execution infrastructure: image, packages, setup, sandbox policy, and network policy. Mosoo resolves it from the Agent revision and runtime requirements.

Resources are application-supplied inputs or attachments:

• A repository ref resolves to an exact commit before execution.
• Private Resources use credential references, never raw secrets in the request or durable plaintext snapshots.
• Resource authorization and readiness are checked before Sandbox allocation.
• Retries use the same frozen Resource identity.

An advanced Environment customization surface may be introduced only when a demonstrated use case requires it. It is not part of v1 onboarding.

Repository and product split

Mosoo Computer owns the Pet product: personal Agent identity, user-facing computer lifecycle, Channels, and other persistent-machine experiences.

Mosoo main owns the API-first managed Agent runtime. It has no product-level Pet | Cattle dual type:

• Remove AgentKind and behavior that exists only to switch or coexist between Pet and Cattle.
• Do not retain permanent compatibility branches or a field that always says cattle.
• Durable Sessions, persistent workspace, and native resume remain valid Mosoo capabilities; they do not make the product a Pet.
• mosoo-agent-driver remains the neutral execution substrate and may expose runtime primitives needed by both repositories.
• Mosoo Computer may reuse the Driver, but Mosoo main must not depend on Pet product semantics.

v1 scope

• API-first onboarding with one Workspace key.
• Managed Agents for Codex and Claude Code.
• Optional Workspace-private immutable Agent revisions.
• Durable multi-turn Sessions with native resume.
• Typed Resources, beginning with Git repositories and files.
• Stable events, approvals, cancellation, artifacts, terminal status, and truthful usage.
• Console views for keys, Sessions, approvals, artifacts, and usage.

Commercial direction

The default direction is unified Mosoo billing, with BYOK available to advanced users where supported.

Billing implementation, settlement, plans, and pricing are not part of this refactor. Usage must still be measured accurately so a future billing layer has trustworthy input.

Non-goals

• App or website deployment and hosting.
• Repo-first or Vercel-like Project semantics.
• Requiring Agent Publish or Unpublish before execution.
• A public Environment catalog as the primary API.
• General Agent-framework adapters.
• Automatic Agent routing or silent fallback.
• A Harness or Agent marketplace, gallery, or public distribution system.
• Pet identity, Channels, schedules, or personal-computer lifecycle in Mosoo main.
• Billing implementation in this iteration.

Reference acceptance use case: ghfind

ghfind is the reference integration for the first API shape.

ghfind Workspace key
+ private ghfind evaluator Agent revision
+ evaluation Input
+ frozen Git repository Resource
→ one durable Mosoo Session
→ analysis JSON + evidence JSON + Markdown report Artifacts

The target integration must satisfy:

• ghfind does not publish an Agent or create an App Deployment.
• ghfind does not select an Environment.
• ghfind keeps its own analysis ID, queue, rubric, validation, storage, and UI.
• Mosoo owns execution, sandboxing, lifecycle, events, approvals, artifacts, and usage.
• ghfind stores one Mosoo Session ID as its runtime handle.
• The repository resolves to an exact commit and is reproducible across retries.
• The three output artifacts are discoverable from the Session and schema-validatable by ghfind.

ghfind validates the backend-to-backend, idempotent, artifact-producing path. A separate acceptance test must validate multi-turn follow-up and native resume because ghfind currently performs one evaluation per Session.

Execution slices

Each child issue owns an end-to-end, independently verifiable slice with its own migration plan and rollback point:

• refactor(channels)!: remove Channels from Mosoo end to end #579 — remove Channels from Mosoo main.
• refactor(deployment)!: remove App Deployment and bound capabilities #580 — remove App Deployment and bound-capability coupling.
• refactor(workspace)!: replace App and add Workspace API keys #581 — replace App with Workspace and introduce Workspace API keys.
• feat(api): add the durable Agent Session API #582 — introduce the managed Agent + durable Session API and remove the Pet/Cattle dual type.
• refactor(agent)!: remove packages, manifests, and fork #583 — remove Agent Package import/export/fork/manifest lifecycle.
• refactor(builder)!: reduce Builder to private Agent revisions #584 — shrink Agent Builder to optional private revision configuration and testing.

The Builder slice removes Publish, Unpublish, Draft/Live visibility, deployment history, and marketplace-oriented state. A private revision becomes callable immediately by its owning Workspace.

The sequence is deliberate. A child may use an additive transition before destructive cutover where necessary to preserve a working migration path, but temporary compatibility code must be removed before that child closes.

Acceptance criteria

• A new developer can create one Workspace key and start Codex or Claude Code without creating an App, Deployment, Environment, or published Agent.
• The first request is expressible as Agent + Input + optional Resources.
• A managed Agent and private immutable Agent revision use the same Session contract.
• Follow-up Input continues the same workspace and native Harness conversation through one public Session ID.
• Events, approvals, cancellation, artifacts, terminal status, and usage are available through the Session.
• Every Session and turn records the exact execution and Resource revisions needed for reproducibility.
• ghfind passes the reference acceptance flow.
• Mosoo main exposes no Pet/Cattle type or compatibility path.
• Channels, App Deployment, Agent Packages, and publishing requirements are absent from the target product.
• Billing is not implemented as part of this refactor.

Migration guardrail

This issue defines the target; it does not authorize destructive production data removal.

Each destructive child issue must inventory production data and active runtime state, preserve promised user history, define backup and rollback procedures, and follow the append-only D1 migration policy. Historical storage may remain inert without keeping removed product semantics executable.

Related work

• YEF-1057: experiment with Harness Profile Marketplace #561 — discovery draft superseded by this decision.
• feat(platform): define a repo-first Cattle runtime and framework adapter boundary #544 and feat(runtime): compose Sessions from Agent, Environment, and typed Resources #545 — retained only where their details do not conflict with this issue.
• feat(runtime): unify lifecycle observability across Harnesses #574 — lifecycle observability remains relevant, but internal Run correlation must not force callers to manage a public Run ID.
• feat(driver): define community-contributed Harness packages #566 — community Harness packages are deferred until real demand; they are not part of the v1 wedge.
• ghfind use case
• ghfind repository
• Mosoo Computer
• mosoo-agent-driver

[Yevanchen]

Design correction: remove the dual Agent Type architecture from Mosoo main

This is a hard cleanup decision for the future implementation of #546.

Pet execution capabilities still matter to Mosoo Computer, so the Agent Driver must continue to support the underlying primitives that product needs: long-lived sessions, native resume, process control, terminal access, and persistent workspace integration. That does not justify retaining the product-level Pet | Cattle type system in Mosoo main.

The target should be designed counterfactually:

If Mosoo main had always been a Cattle-only product, what would the clean model be?

An optional saved/versioned Agent configuration may still exist, and an Agent ID does not have to be deleted merely because the direct Run API is Agentless. What must disappear is every compatibility rule whose only purpose is allowing Pet and Cattle to coexist in one product.

Source audit: where the dual-Type design currently leaks

The scan found Type-dependent behavior across all product layers:

• Public contracts and comparison policy: pkgs/contracts/src/agent/agent.contract.ts
• Agent/version/session/sandbox persistence: pkgs/db/src/schema/agent.schema.ts, pkgs/db/src/schema/session/core.schema.ts, and pkgs/db/src/schema/runtime.schema.ts
• Subject scope, checkpoint, lease, restore, reset, and terminal policy: apps/api/src/modules/runtime/domain/runtime-kind-policy.ts
• Agent-scoped versus Session-scoped sandbox identity: apps/api/src/modules/runtime/domain/runtime-sandbox-subject.ts
• Pet owner terminal: apps/api/src/modules/runtime/application/owner-debug-terminal.service.ts
• Type/runtime changes forcing Fork and live-machine operations: pkgs/contracts/src/agent/agent-config-change-plan.contract.ts
• Fork with a target Type: apps/api/src/modules/agents/application/agent-fork.service.ts
• Type embedded in portable manifests and package import/export: pkgs/contracts/src/agent/agent-manifest.contract.ts, apps/api/src/modules/agents/application/agent-package-import.service.ts, and apps/api/src/modules/agents/application/agent-package-export.service.ts
• Type selector, comparison UI, Fork dialog, Terminal mode, and Pet reset UI under apps/web/src/routes/agent/
• GraphQL, Public Thread responses, readiness, analytics, generated clients, and tests also expose or branch on Type.

The Driver Kernel itself does not currently model AgentKind; the Pet/Cattle policy is mainly imposed by the Mosoo host/control plane. The Driver’s neutral runtime primitives should stay. Its Agent-specific host snapshot (apps/driver/src/protocol/boot/host-snapshot.ts) should only be generalized where the Agentless Run contract requires it; do not add a new Pet/Cattle abstraction to Driver.

Counterfactual Cattle-only target

The implementation should remove, not hide or default:

• AgentKind, Type selectors, Type comparison copy, and Type fields from public APIs.
• kind from Agent, AgentDeploymentVersion, Session, Sandbox, manifests, packages, and analytics where it means Pet/Cattle.
• Policy maps keyed by Type. Cattle isolation, subject ownership, lease, cleanup, and resume rules become the single direct runtime contract.
• Stable Agent-scoped sandbox selection from Mosoo main.
• Owner debug Terminal, Pet memory/checkpoint/restore/reset, and “recreate while preserving Agent state” product behavior.
• “Fork to switch Type” and A-Type-to-B-Type migration paths.
• Permanent compatibility parsers or branches whose only job is accepting the removed Type model.

Do not remove unrelated fields named kind; only the Agent Type concept is in scope.

Re-open Agent lifecycle and version semantics

The current lifecycle mixes two different concerns:

1. a versioned capability definition; and
2. patching or preserving a live Pet machine.

Once Pet is removed from Mosoo main, every configuration change must be reconsidered without the live-machine assumption.

The future design must explicitly decide:

• Is an Agent version pinned per Run or per multi-turn Session?
• Does the next Run resolve the current version automatically, or must the caller pin it?
• Which edits create an immutable version, and which are draft-only metadata edits?
• Is publish/unpublish still needed for the Cattle product, or only for a gallery/distribution surface?
• Does Fork remain merely “copy as a new saved configuration,” rather than a required lifecycle transition?

Default direction: each Run records the exact immutable capability/configuration revision it used; prior Runs remain reproducible. Do not preserve restart/recreate/fork machinery just because it exists today.

Import/export/package consequences

Portable packages currently persist manifest.kind and Fork can select a new Type. The future implementation must:

• remove Type from the new manifest/package format;
• bump the format version when required;
• remove target-Type Fork;
• choose an explicit policy for old packages: one-time offline conversion or a clear unsupported-version error.

Do not keep a permanent dual-Type runtime path just to parse historical packages.

Production data migration is part of the feature

Before deleting code, inventory production rows and active runtime state for Agents, deployment versions, Sessions, Sandboxes, backups, native resume references, and stored/exported manifests.

Migration requirements:

1. Stop creation/activation of new Pet state.
2. Drain or visibly cancel active Pet Runs and revoke owner Terminal sessions.
3. Preserve durable user history: Agent configuration, versions, messages, artifacts, usage, and audit records.
4. Do not relabel an Agent-scoped Pet Sandbox as Cattle in place. Pet machine state has no truthful Cattle equivalent. Export/checkpoint only what the product explicitly promises, then destroy the Pet runtime and start future work in a clean Cattle execution.
5. Migrate surviving business entities to the single Cattle semantic, then remove the Type columns/contracts rather than leaving a forever-"cattle" field.
6. Historical Pet Sessions may remain readable, but continuing them must create a clean Cattle Run from explicit durable context; no implicit native resume into the old machine.
7. Because production D1 is append-only and dropping these columns may require table rebuilds, implementation requires explicit approval, backup, verification queries, and a rollback plan.

Required future Grill Me gate

Do not run Grill Me as part of this issue-writing pass. Run the Grill Me skill immediately before implementation planning/issue decomposition, using this source inventory as input.

It must challenge at least:

• Would this field, branch, mutation, page, or migration exist in a greenfield Cattle-only Mosoo?
• Is any surviving compatibility code truly temporary and operationally required? What is its deletion date?
• Are Agent version rules describing reproducibility, or accidentally preserving Pet machine semantics?
• What user data is preserved, exported, invalidated, or destroyed when Pet Terminal and runtime state disappear?
• Can Mosoo Computer consume Driver primitives without making Mosoo main depend on Pet?
• Did the audit include contracts, DB, GraphQL, runtime subject lifecycle, UI, import/export, Fork, analytics, generated clients, tests, and production migration?

The implementation plan is not ready until the Grill Me output is attached to #546 and every surviving dual-Type branch has an explicit justification.