[fpliger]

Summary

Discovery-only change for #14426 (parent epic #14023, building on #14425). It adds
migration-tracking/technical-notes/baseline/cloud-agent-contracts.md, which maps
how the cloud agent consumers currently talk to the Kilo runtime and dispositions
each one for the v2 migration. No source code changes in any repository.

Base: kilo-v2 (782263326). Two commits, one new file (392 lines).

What this PR contains

A single document:

• migration-tracking/technical-notes/baseline/cloud-agent-contracts.md

It is the deliverable for #14426: a per-consumer contract mapping across all seven
areas (startup, session admission, streaming, tools, credentials, persistence,
cancellation), a disposition summary, and concrete implementation gaps for #14427.

Scope and method

In scope (from #14425): cloud-agent-next, auto-routing-benchmark,
MCP catalog generator (CI), and session-ingest (contract-coupled).

Each consumer is mapped with code-level evidence from:

• the cloud repo at 3de933dd85070e9d15c41d8ff3af6c91ca856fd4 (read-only),
• v1 runtime on origin/main at 62f674d4,
• v2 runtime on kilo-v2 at 78226332,
• upstream opencode origin/v2 at f20f5b68ee.

Owners, pinning, and recommended gates are reused from #14425, not re-derived.
The /remote relay (#14019) is noted but not re-assessed.

Key findings

• No consumer is "no change." Every disposition includes a v2
  contract/packaging change in this repo; cloud-agent-next additionally needs a
  cloud client adaptation.
• packages/kilo-cli is a thin, diverged fork of upstream v2's packages/cli.
  Several first-pass "must build" gaps are really "sync kilo-v2 forward":
  upstream origin/v2 already has a headless serve --hostname/--port, a
  streaming run --format json, and session import from a file or URL.
• Packaging/channel is the main blocker: v2 @kilocode/cli is private,
  has no bin, and builds kilo2.
• A v1→v2 session-history migration already exists upstream
  (v1-migration.bun.ts, PR #40723 + follow-ups); kilo-v2 vendors an older copy
  and does not wire the user-facing flow.
• session-ingest has a reduced, explicit-share-only v2 producer; continuous
  shipping, session_close/diff/status/notifications, and the
  session_share/import bridge are absent.

Owner decisions recorded (2026-10-07)

1. v2 ships on a new next (or something else if better) pre-release channel; @kilocode/cli@latest stays
   on the v1 line during the migration.
2. Keep the kilo2 binary for the duration of the migration.
3. An import tool for users (including auth) is acceptable; v2 does not share v1
   auth automatically, but import paths exist.
4. Use upstream opencode's v1→v2 session migration (confirmed available).
5. Restore path to be resolved from both kilo-v2 and upstream v2.
6. No v2 consumers are deployed and versions are pinned; the next channel
   removes the residual floating-consumer risk.

Gaps for #14427

The document lists G1–G11 with repo, proposed "Touches", dependencies/cross-repo
ordering, and cloud-coordination flags: kilo2 serve contract, packaging +
next channel, N9 handshake, consumer SDK surface, cloud-agent-next adaptation,
credential seeding, run argv/output, restore/import compatibility,
session-ingest producer continuity, event/entity projection, and sync + wire the
v1→v2 migration.

Notes for reviewers

• Discovery/documentation only — no runtime, package, or cloud changes.
• Not a GitHub-posted document; plans/kilo-opencode-v2-plan-progress.md is not
  edited. Proposed plan-row changes for N7 are included in the document.
• Prior art: Identify cloud agent consumers, repositories, owners and migration scope #14425 (consumer inventory).

References

• Closes / delivers Map cloud consumer contracts and disposition each (adapt / repackage / no change) #14426
• Parent epic: Assess and integrate cloud agent consumers with v2 #14023
• Prerequisite inventory: Identify cloud agent consumers, repositories, owners and migration scope #14425 (migration-tracking/technical-notes/baseline/cloud-agent-consumers.md)
• Follow-ups: Implement confirmed cloud consumer adaptation gaps through public interfaces #14427 (adaptation), Validate cloud agent local contracts and hosted execution (external-gated) #14428 (validation)
• Out of scope: Complete remote session consumer acceptance #14019 (/remote relay), Complete original Kilo VS Code client parity #14016 (VS Code Agent Manager)

[fpliger]

mistakely opened towards the wrong base. Superseded by #14908

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (1 file)

• migration-tracking/technical-notes/baseline/cloud-agent-contracts.md

---

_{Reviewed by deepseek-v4.1-flash · Input: 43.8K · Output: 7.7K · Cached: 413.2K}

_{Review guidance: REVIEW.md from base branch main}