docs(kilo): map cloud agent consumer contracts (#14426) by fpliger · Pull Request #14908 · Kilo-Org/kilocode

fpliger · 2026-10-07T20:31:14Z

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 moved to kilo-v2 7232720; #14758 is merged.

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)

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.
Keep the kilo2 binary for the duration of the migration.
An import tool for users (including auth) is acceptable; v2 does not share v1
auth automatically, but import paths exist.
Use upstream opencode's v1→v2 session migration (confirmed available).
Restore path to be resolved from both kilo-v2 and upstream v2.
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

Part of Map cloud consumer contracts and disposition each (adapt / repackage / no change) #14426 — delivers the contract mapping and dispositions; the progress-plan row is proposed for N7 to apply (see the document's "Proposed progress-plan row changes").
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)

)

Copilot

🟡 Changes recommended

The document has factual inconsistencies, a missing prerequisite reference, and does not apply the plan update required by #14426.

6 open findings

Progress-plan row was not updated as required by issue #14426 · New
Missing prerequisite inventory leaves repository references unsupported · New
Incorrectly claims v2 ignores KILO_DISABLE_SESSION_INGEST · New
Shared CLI state directory is hidden by disposable cwd description · New
Summary understates cross-repository cloud invocation work · New
Conflates headless and interactive kilo2 artifacts · New

What changed in this PR

Maps cloud-agent consumer contracts and identifies v2 migration gaps for #14427.

Changes:

Documents four in-scope consumers across seven contract areas.
Records migration dispositions and implementation gaps.
Summarizes upstream v2 migration capabilities.

File	Description
`migration-tracking/technical-notes/baseline/cloud-agent-contracts.md`	Adds the consumer contract and migration-gap assessment.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

fpliger · 2026-10-07T23:50:07Z

+## Proposed progress-plan row changes (for N7; do not apply here)
+
+File: `migration-tracking/plans/kilo-opencode-v2-plan-progress.md`, section
+"Remote, sharing and distribution".


Intentionally not applied. Plan rows are applied by N7, not by discovery PRs; the merged #14425 inventory likewise proposed its row without editing the plan (the plan still has no cloud-agent row). The document now states this convention.

+| This repo, `origin/main` (v1) | `62f674d4a91969ac077e4a7b6ceeb8a99de80e47` |
+| This repo, `kilo-v2` (v2) | `782263326df5be50081517ddedd937f1080a89cf` |
+| Upstream opencode, `origin/v2` | `f20f5b68ee318721c453fb19d20e46d2b9225bc0` (clone `/Users/fpliger/dev/opencode`) |
+| #14425 inventory | `migration-tracking/technical-notes/baseline/cloud-agent-consumers.md` |


+| Session admission | One fresh `kilo run` per case; no session ids/continuation; runs serialized because the CLI store is not concurrency-safe (`container/server.mjs:37-41`; `src/run.ts:1258`). | v2 `run` accepts positional prompt, `-s/--session`, `-m/--model`, `--agent`, `--auto`, `--file`, `--directory`, `--format text|json` (`kilo-v2:packages/kilo-cli/src/commands.ts:283-352`). There is no standalone `--variant` flag, but upstream v2 encodes the variant in the model ref as `provider/model#variant` (`origin/v2:packages/cli/src/commands/commands.ts`, `run` model help). | yes | Pass the variant as `-m kilo/<model>#<variant>`, or add a `--variant` compatibility flag. | both |
+| Streaming | Parses one JSON event per stdout line: completed `type:text` parts and `step_finish` cost (`cloud@3de933dd src/kilo-events.ts:52-85`; emitted by `origin/main:packages/opencode/src/cli/cmd/run.ts:876-891`). | kilo2's `run --format json` prints one completed `{sessionID,text}` object (`kilo-v2:packages/kilo-cli/src/tui-preview.ts:231`), but **upstream v2 preserves the streaming event log**: `noninteractive.ts` emits `{type,timestamp,sessionID,part}` for `text`/`step_start`/`step_finish`/`tool_use`/`reasoning` and `{type,error}` for errors (`origin/v2:packages/cli/src/run/noninteractive.ts`). The parser works against upstream v2; it fails only against kilo2 today. | yes (kilo2 only) | Align kilo2's `run` with upstream v2's non-interactive path (preferred), or adapt the parser to the single-object result. | this repo |
+| Tools | None; `--auto` only. | `--auto` exists; no tool/permission flags passed. No break. | no | none | — |
+| Credentials | Injects `KILO_AUTH_CONTENT {kilo:{type:api,key,organizationId}}`, `KILO_API_URL`, `KILO_ORG_ID`, `KILO_DISABLE_SESSION_INGEST=1` (`cloud@3de933dd container/server.mjs:66-79`). v1 reads them (`origin/main:packages/core/src/plugin/provider/kilo.ts:18-19`; `packages/opencode/src/auth/index.ts:61`). | v2 reads none of `KILO_AUTH_CONTENT`/`KILO_ORG_ID`/`KILO_DISABLE_SESSION_INGEST`; only `KILO_API_URL` as the gateway (`kilo-v2:packages/kilo-cli/src/tui-preview.ts:141`). Credentials can be seeded with `import-v1 --auth` or by writing an `auth.json` the DB migration imports (§5, G6). | yes | Seed v2 credentials via `import-v1 --auth`/`auth.json` before `run`, or add a v2 env path. | both |


+| Streaming | Parses one JSON event per stdout line: completed `type:text` parts and `step_finish` cost (`cloud@3de933dd src/kilo-events.ts:52-85`; emitted by `origin/main:packages/opencode/src/cli/cmd/run.ts:876-891`). | kilo2's `run --format json` prints one completed `{sessionID,text}` object (`kilo-v2:packages/kilo-cli/src/tui-preview.ts:231`), but **upstream v2 preserves the streaming event log**: `noninteractive.ts` emits `{type,timestamp,sessionID,part}` for `text`/`step_start`/`step_finish`/`tool_use`/`reasoning` and `{type,error}` for errors (`origin/v2:packages/cli/src/run/noninteractive.ts`). The parser works against upstream v2; it fails only against kilo2 today. | yes (kilo2 only) | Align kilo2's `run` with upstream v2's non-interactive path (preferred), or adapt the parser to the single-object result. | this repo |
+| Tools | None; `--auto` only. | `--auto` exists; no tool/permission flags passed. No break. | no | none | — |
+| Credentials | Injects `KILO_AUTH_CONTENT {kilo:{type:api,key,organizationId}}`, `KILO_API_URL`, `KILO_ORG_ID`, `KILO_DISABLE_SESSION_INGEST=1` (`cloud@3de933dd container/server.mjs:66-79`). v1 reads them (`origin/main:packages/core/src/plugin/provider/kilo.ts:18-19`; `packages/opencode/src/auth/index.ts:61`). | v2 reads none of `KILO_AUTH_CONTENT`/`KILO_ORG_ID`/`KILO_DISABLE_SESSION_INGEST`; only `KILO_API_URL` as the gateway (`kilo-v2:packages/kilo-cli/src/tui-preview.ts:141`). Credentials can be seeded with `import-v1 --auth` or by writing an `auth.json` the DB migration imports (§5, G6). | yes | Seed v2 credentials via `import-v1 --auth`/`auth.json` before `run`, or add a v2 env path. | both |
+| Persistence | Only a temp cwd, removed after each run (`cloud@3de933dd container/server.mjs:46,119`); no CLI home/config read. | v2 uses isolated `kilo2` paths (`kilo-v2:packages/kilo-cli/src/paths.ts:6,26`); a fresh temp cwd still works. | no | none (v2 store is created in-container). | — |


+No in-scope consumer is "no change". Every disposition includes a v2
+contract/packaging change in this repo; cloud-agent-next additionally owns a
+client adaptation. Because v2 ships on `next`, the two floating consumers are
+not forced to adapt until they opt in.


+- Problem: the cloud wrapper spawns `kilo serve --hostname/--port` and waits for
+  `kilo server listening`; kilo2 is named `kilo2`, prints `URL:`/`Password file:`,
+  and its `serve` lacks `--hostname`/`--port`.


fpliger · 2026-10-07T23:50:31Z

All comments have been addressed. Ready for review

fpliger added 2 commits October 5, 2026 21:44

docs(kilo): map cloud consumer contracts (#14426)

6dee1e3

docs(kilo): correct cloud consumer contracts against upstream v2 (#14426

ceb1794

)

fpliger mentioned this pull request Oct 7, 2026

docs(kilo): map cloud agent consumer contracts (#14426) #14907

Closed

fpliger requested a balanced review from Copilot October 7, 2026 21:34

Copilot started reviewing on behalf of fpliger October 7, 2026 21:35

View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

kirillk approved these changes Oct 8, 2026

View reviewed changes

fpliger merged commit 879b89e into kilo-v2 Oct 8, 2026
7 of 10 checks passed

fpliger deleted the 14426-cloud-consumer-contracts branch October 8, 2026 15:05

Navigation Menu

Repository navigation

docs(kilo): map cloud agent consumer contracts (#14426) - #14908

docs(kilo): map cloud agent consumer contracts (#14426)#14908
fpliger merged 2 commits into
kilo-v2from
14426-cloud-consumer-contracts

fpliger commented Oct 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

fpliger Oct 7, 2026

Uh oh!

fpliger commented Oct 7, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

fpliger commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What this PR contains

Scope and method

Key findings

Owner decisions recorded (2026-10-07)

Gaps for #14427

Notes for reviewers

References

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

fpliger Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

fpliger commented Oct 7, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fpliger commented Oct 7, 2026 •

edited

Loading