lazy-extension
The Project Lazy VS Code extension: the laptop-side host.
It provides the pairing UI, keeps the E2EE session to the relay, and drives a local Kilo Code
or Codex session through an AgentAdapter from @lazy/agent-sdk. Everything reusable comes from
@lazy/host-core, so a future JetBrains or CLI host reuses it with a different adapter; the
agent-specific code lives here.
Codex support
Set lazy.agent to codex and reload the window. Lazy discovers the installed Codex extension's
CLI (or uses lazy.codexCliPath) and starts App Server. Kilo remains the default.
To share the same live thread with the official Codex VS Code extension, configure a shared
Unix App Server and the optional stdio/WebSocket launcher. This requires explicit setup; Lazy
cannot attach to the official extension's default private stdio process. The real Codex engine,
shared launcher, and encrypted relay round trip are tested using a local model stub. Real VS Code
webview behavior still needs the human checks in the
Codex integration runbook.
pnpm test:codex runs the Codex checks; pnpm test includes both agents. The installed-binary
tests are skipped when the corresponding CLI is unavailable.
Spike outcome (M0)
The plan preferred reusing the Kilo extension's already-running kilo serve so remote prompts
would land in the session the developer is watching. That is not possible. Kilo learns its
server port by parsing the child process's stdout and keeps the password only in that child's
environment; there is no state file, no exported API, and no prompt-sending command to borrow.
The fallback is confirmed working instead: the extension spawns its own kilo serve, with a
password it generates, and drives the OpenCode-compatible HTTP API. Running the installed binary
with our own password returns real sessions over authenticated HTTP, and a wrong password is
rejected with 401.
Full evidence, the confirmed endpoint list, and the consequences are in
docs/m0-kilo-integration-spike.md.
What this means
- We own the server process, so we own the password and its lifecycle. The secret never leaves
the laptop, and there is nobody else's secret to discover.
- "Active session" means the session the user picked on the phone, listed from
GET /session.
- Writes through our server may not live-update the Kilo sidebar, because the two servers keep
separate in-memory event buses over the same persisted store. Reconcile by re-reading the
session, and treat one surface as primary.
Questions, not just permissions
Kilo has two interactive prompt types. A permission is "may I do this?" and is answered
approve/deny; a question is "which of these do you want?" and carries one or more questions, each
with options, answered by a set of selected labels. An agent that asks either one blocks until it
is answered, so both are surfaced to the phone. v1 was designed around permissions only, and an
agent that asked a question would have blocked forever with no way to answer.
Implemented
Everything below is plain Node with no VS Code API, so it is testable on its own:
| Module |
Purpose |
src/kilo/locate.ts |
Finds a kilo CLI: explicit path, else the newest installed Kilo Code extension's bundled binary, else kilo on PATH. Reusing the installed binary avoids shipping our own 259 MB copy |
src/kilo/server.ts |
Spawns kilo serve --port 0 with a password we generate, and learns the port the same way Kilo does: by parsing the child's stdout |
src/kilo/client.ts |
Authenticated HTTP plus the /event SSE stream: sessions, messages, prompt_async, abort, permission and question replies |
src/kilo/adapter.ts |
AgentAdapter: session and message mapping, streamed text deltas until session.idle, permission and question fan-out, and the Kilo-specific translations |
src/host/kilo-host.ts |
Brings up the CLI, our own kilo serve, the adapter, and a @lazy/host-core host in one call |
src/host/runtime.ts |
Keeps the host serving over the relay with backoff and reconnect |
src/vscode/* |
The thin part: SecretStorage-backed secret store, the QR pairing panel, and activate() with its commands and status bar |
Verified in test/kilo-integration.test.ts against the real installed binary: our own server
starts, authenticated reads return real sessions, a wrong password is refused, and the adapter
maps real session and message history. Those tests are read-only on purpose, because sending a
prompt would invoke a model and could let an agent modify the working tree.
The extension itself
activate() brings the whole laptop side up without being asked to: it locates a kilo CLI,
starts our own kilo serve, builds the adapter on top, and — if a phone is already paired —
starts serving. Three commands:
| Command |
What it does |
Project Lazy: Pair a Phone |
Mints an invite, shows it as a QR code, and waits for the phone to scan it |
Project Lazy: Revoke the Paired Phone |
Forgets the pairing and restarts serving so the old phone cannot return |
Project Lazy: Show Status |
Kilo version, relay URL, pairing id, and runtime state |
A status bar item shows what the runtime is doing (not paired, connecting, phone connected,
retrying). Settings: lazy.relayUrl (required for pairing) and lazy.kiloCliPath (optional
override).
The host's static identity, the pairing record, and the relay device token all live in VS Code's
SecretStorage, which is the OS keychain, rather than in settings.
src/host/runtime.ts keeps a host serving: it connects, stays connected for the life of the
session, then backs off and reconnects. An unpaired host is a configuration state and not a
failure, so it parks instead of retrying into the void, and it is poked awake when a pairing is
created or revoked. A poke also cuts a backoff short, so re-pairing reconnects immediately.
Contraptions worth knowing
- The two permission endpoints disagree.
POST /permission/{id}/reply takes { reply };
POST /session/{id}/permissions/{id} takes { response }. We use the global one.
- Reasoning is not the answer. Assistant parts include
reasoning, tool, step-start and
step-finish. Only text parts are concatenated for display; a test asserts reasoning never
leaks into a message.
- A turn ends on
session.idle, not on the last delta. Streaming completes when the session
goes idle, and session.error fails the prompt.
provider/model splits on the first slash, which matches Kilo's { providerID, modelID }
even for nested model ids like openrouter/deepseek/deepseek-v4.1-flash.
Not implemented yet
- The pairing webview shows a QR code but has not been driven by a real phone yet.
- The extension has not been launched inside VS Code;
activate() is typechecked and bundled but
unexercised.
lazy-web implements the browser client; real-phone validation is still pending.
- Nothing is published; every
@lazy/* dependency is a link: into the neighbouring repo.