feat: remote environments for SSH and Docker execution targets (phase 1: creation-time binding)

.changeset/disconnect-notice-no-manual-reconnect.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Stop showing a transcript notice when a remote environment disconnects.

.changeset/new-inherits-environment.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Keep the current environment and working directory when `/new` starts a session.

.changeset/remote-environment-share-by-id.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+The same environment id shares one connection across workspaces. Reconnecting that id is process-wide; a different id stays up.

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 dist/
 dist-single/
 dist-native/
+dist-executor/
 .tmp-api-extractor/
 .contract-types-tmp/
 .local/

AGENTS.md

@@ -27,6 +27,7 @@ This is a TypeScript monorepo built for agent-assisted development. Keep the roo
 - `packages/transcript`: the isomorphic transcript rendering data layer — L1 agent-granular store, L2 idempotent operations, L3 `off/turn/block/delta` subscription granularity, L4 framework-free view registry, plus turn-cursor pagination. Pure TypeScript (browser-safe, no engine imports); the sole owner of the transcript contract types (`src/contract/`) and the op-batch sequencing contract.
 - `packages/kap-server`: the Kimi Code server, backed by `@moonshot-ai/agent-core-v2`; exposes sessions over REST + WebSocket (`/api/v1` + `/api/v1/ws`), plus the `/api/v1/debug/*` reflection RPC surface (`--debug-endpoints`, loopback bind + bearer auth).
 - `packages/remote-control`: the Kimi Remote Control tunnel client — registers this machine with the relay and forwards HTTP/WebSocket traffic to the local server, with a machine-wide single-instance lock; consumed by kap-server (the `/api/v1/remote-control` toggle) and by the CLI (`kimi web --remote-control`).
+- `packages/agent-core-v2/src/remote`: the remote execution stack inside the engine — self-contained NDJSON line-framed RPC (codex exec-server dialect) between the local `ExecBridge` (ssh/docker/`command` launchers) and the light `kimi exec-server` executor, plus the fs/process RPC stubs behind the `Environment` interface; exported as `@moonshot-ai/agent-core-v2/remote` and `/remote/server`. The executor stays light — `src/remote/server` may import only node builtins, relative modules, `#/remote/protocol`, `#/os/interface` and `#/_base/execEnv` (enforced by the package's `lint:imports`); the CLI's only engine import is the dynamic `/remote/server` load in `src/cli/exec-server.ts`.
 - `packages/klient`: the client SDK — a contract-driven facade over agent-core-v2 (`global.*` / `session(id).*` / `agent(id).*`, zod-validated); transport via subpath entry (`@moonshot-ai/klient/ipc|memory`, both return the same `Klient`); also hosts the e2e suites. See `packages/klient/AGENTS.md`.
 - `packages/tree-sitter-bash`: a pure-TypeScript bash parser (no runtime deps, no wasm); `parse(source, { timeoutMs, maxNodes })` runs under a deterministic budget and returns a discriminated `ParseResult` — callers must treat aborted/hasError trees as "cannot analyze" and degrade. Parser only, no safety judgments; see the package README's "Known differences" section.
 - `packages/minidb`: the embedded JSON document store (`MiniDb`) behind kap-server's search index — snapshot + WAL persistence with an exclusive write lock, a larger-than-RAM full-text layer, and persistent index generations. See `packages/minidb/AGENTS.md`.

CONTRIBUTING.md

@@ -93,6 +93,11 @@ Every PR opens with the [PR template](.github/pull_request_template.md). PR titl
 - Auto-formatting via `pnpm lint:fix`.
 - Follow existing local patterns when the lint rules do not cover a style choice.
 
+## Engine Invariants
+
+- Two filesystems exist side by side and must not be conflated. Anything workspace-related (project files, project config such as `AGENTS.md` and `.kimi-code/`, skill and instruction discovery, file the model can be told to read) always goes through the session's `environment.fs` — acquire it from the calling agent's environment lease, never from a node-local backend. The App-level `IHostFileSystem` is reserved for server-local data only: session storage, the search index, and the blob store.
+- The same split applies to processes: workspace commands run through the environment's process service; App-level process backends are for host-local jobs (hooks, local MCP servers, server maintenance).
+
 ## Reporting Security Issues
 
 Found a security issue? Please see [SECURITY.md](SECURITY.md) instead of opening a public issue.

apps/kimi-code/AGENTS.md

@@ -42,7 +42,7 @@ Main directories:
 - `reverse-rpc` converts SDK approval/question requests into the data shape a UI panel/dialog needs, and converts the user's choice back into an SDK response.
 - `theme` is the single source of truth for colors and styles. Components must not bypass the theme system and use chalk named colors directly.
 - `utils` holds utility functions with no UI-state dependency. Logic that needs `TUIState` or a component instance must not live under app-level `src/utils`.
-- `apps/kimi-code` may only use core capabilities through `@moonshot-ai/kimi-code-sdk`. Do not import engine packages directly in app code.
+- `apps/kimi-code` may only use core capabilities through `@moonshot-ai/kimi-code-sdk`. Do not import engine packages directly in app code. Sole exception: the `exec-server` light entry dynamically imports `@moonshot-ai/agent-core-v2/remote/server` (see `src/cli/exec-server.ts`).
 
 ## TUI Coding Conventions
 

apps/kimi-code/scripts/native/smoke.mjs

@@ -25,6 +25,96 @@ async function ensureExecutableExists() {
   }
 }
 
+// `kimi exec-server --listen stdio` is the remote-executor light entry: the
+// SEA binary must answer the NDJSON handshake with the package version and a
+// posix environment, keep stdout protocol-only, and exit 0 on stdin EOF.
+async function runExecServerSmoke() {
+  const { spawn } = await import('node:child_process');
+  const startedAt = performance.now();
+  const child = spawn(executablePath, ['exec-server', '--listen', 'stdio'], {
+    cwd: appRoot,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  let stderr = '';
+  child.stderr.setEncoding('utf-8');
+  child.stderr.on('data', (chunk) => {
+    stderr += chunk;
+  });
+
+  const pending = [];
+  const waiters = [];
+  let buffer = '';
+  child.stdout.setEncoding('utf-8');
+  child.stdout.on('data', (chunk) => {
+    buffer += chunk;
+    let index = buffer.indexOf('\n');
+    while (index >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (line.length > 0) {
+        const parsed = JSON.parse(line);
+        const waiter = waiters.shift();
+        if (waiter !== undefined) waiter(parsed);
+        else pending.push(parsed);
+      }
+      index = buffer.indexOf('\n');
+    }
+  });
+
+  const nextFrame = () =>
+    new Promise((resolveFrame, rejectFrame) => {
+      const queued = pending.shift();
+      if (queued !== undefined) {
+        resolveFrame(queued);
+        return;
+      }
+      const timer = setTimeout(() => {
+        rejectFrame(new Error(`timed out waiting for a protocol frame; stderr so far:\n${stderr}`));
+      }, 30_000);
+      waiters.push((frame) => {
+        clearTimeout(timer);
+        resolveFrame(frame);
+      });
+    });
+
+  const send = (message) => child.stdin.write(`${JSON.stringify(message)}\n`);
+
+  try {
+    send({ method: 'initialize', id: 1, params: { clientName: 'native-smoke', clientVersion: expectedVersion } });
+    const initialize = await nextFrame();
+    const handshakeMs = performance.now() - startedAt;
+    const result = initialize.result ?? {};
+    if (initialize.id !== 1 || result.executorVersion !== expectedVersion) {
+      fail(`exec-server handshake mismatch: expected executorVersion ${expectedVersion}, got ${JSON.stringify(initialize)}`);
+    }
+    if (result.environment?.osKind === undefined || result.environment.osKind === 'windows') {
+      fail(`exec-server reported a non-posix environment: ${JSON.stringify(result.environment)}`);
+    }
+    send({ method: 'fs/getMetadata', id: 2, params: { path: '/' } });
+    const metadata = await nextFrame();
+    if (metadata.id !== 2 || metadata.result?.isDirectory !== true) {
+      fail(`exec-server fs/getMetadata mismatch: ${JSON.stringify(metadata)}`);
+    }
+    child.stdin.end();
+    const exitCode = await new Promise((resolveExit) => {
+      const timer = setTimeout(() => {
+        child.kill('SIGKILL');
+        resolveExit(null);
+      }, 30_000);
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        resolveExit(code);
+      });
+    });
+    if (exitCode !== 0) {
+      fail(`exec-server did not exit 0 on stdin EOF (exit=${exitCode}).\n${stderr}`);
+    }
+    console.log(`exec-server smoke passed (handshake in ${handshakeMs.toFixed(0)}ms)`);
+  } finally {
+    child.kill('SIGKILL');
+  }
+}
+
 async function runKimi(args) {
   try {
     const { stdout, stderr } = await execFileAsync(executablePath, args, {
@@ -111,4 +201,6 @@ try {
   await rm(smokeHome, { recursive: true, force: true });
 }
 
+await runExecServerSmoke();
+
 console.log(`Native smoke passed: ${executablePath}`);

apps/kimi-code/scripts/smoke.mjs

@@ -28,7 +28,7 @@ async function ensureRuntimeAssetsExist() {
   try {
     await stat(webIndexPath);
   } catch {
-    fail(`Runtime asset not found at ${webIndexPath}. Run \`pnpm build\` first.`);
+    fail(`Environment asset not found at ${webIndexPath}. Run \`pnpm build\` first.`);
   }
 }
 

apps/kimi-code/src/cli/commands.ts

@@ -2,6 +2,7 @@ import { CLI_COMMAND_NAME } from '#/constant/app';
 import { registerMigrateCommand, type MigrateCommandOptions } from '#/migration/index';
 import { Command, InvalidArgumentError, Option } from 'commander';
 
+import { EXEC_SERVER_COMMAND } from './exec-server';
 import type { CLIOptions } from './options';
 import { registerAcpCommand } from './sub/acp';
 import { registerDoctorCommand } from './sub/doctor';
@@ -19,6 +20,7 @@ export type MigrateCommandHandler = (options: MigrateCommandOptions) => void;
 export type PluginNodeRunnerHandler = (entry: string, args: readonly string[]) => void;
 export type UpgradeCommandHandler = (yes: boolean) => void | Promise<void>;
 export type UpdateDownloadHandler = (version: string, manual: boolean) => void;
+export type ExecServerCommandHandler = (listen: string) => void;
 
 export function createProgram(
   version: string,
@@ -27,6 +29,7 @@ export function createProgram(
   onPluginNodeRunner: PluginNodeRunnerHandler = () => {},
   onUpgrade: UpgradeCommandHandler = () => {},
   onUpdateDownload: UpdateDownloadHandler = () => {},
+  onExecServer: ExecServerCommandHandler = () => {},
 ): Command {
   const program = new Command(CLI_COMMAND_NAME)
     .description('The Starting Point for Next-Gen Agents')
@@ -117,6 +120,12 @@ export function createProgram(
     )
     .addOption(new Option('--yes').hideHelp().default(false))
     .addOption(new Option('--auto-approve').hideHelp().default(false))
+    .addOption(
+      // The [environments] config layer resolves and validates the id (unknown
+      // id / missing defaultCwd → startup error). Hidden from help output.
+      new Option('--environment <id>', 'Bind the new session to the configured environment <id>.')
+        .hideHelp(),
+    )
     .option('--plan', 'Start in plan mode.', false);
 
   registerExportCommand(program);
@@ -159,6 +168,21 @@ export function createProgram(
       onUpdateDownload(targetVersion, options.manual === true);
     });
 
+  // Remote-executor entry (remote-environment spec §6). The exact argv shapes
+  // `exec-server` and `exec-server --listen stdio` are pre-dispatched in
+  // `src/main.ts` before this program is even loaded; this hidden command owns
+  // every other spelling (`--listen=stdio`, unsupported transports, excess
+  // args) so they still route to the executor or fail with a clean stderr
+  // error. `--listen` defaults to stdio, the only supported transport, so a
+  // bare invocation reaching this program agrees with the light path.
+  program
+    .command(EXEC_SERVER_COMMAND, { hidden: true })
+    .option('--listen <transport>', 'Transport to listen on. Only "stdio" is supported.', 'stdio')
+    .allowExcessArguments(false)
+    .action((options: { listen: string }) => {
+      onExecServer(options.listen);
+    });
+
   program.argument('[args...]').action((args: string[]) => {
     if (args.length > 0) {
       program.error(`unknown command '${args[0]}'. See '${CLI_COMMAND_NAME} --help'.`);
@@ -184,6 +208,7 @@ export function createProgram(
       agent: raw['agent'] as string | undefined,
       agentFiles: raw['agentFile'] as string[],
       addDirs: raw['addDir'] as string[],
+      environment: raw['environment'] as string | undefined,
     };
 
     onMain(opts);

apps/kimi-code/src/cli/exec-server.ts

@@ -0,0 +1,88 @@
+/**
+ * `kimi exec-server` (equivalently `--listen stdio`) — the remote-executor
+ * light entry.
+ *
+ * This module is the argv pre-dispatch target of `src/main.ts` and must stay
+ * light: only node builtins plus `./build-info` / `./host-package`. The SDK
+ * mega-module (`@moonshot-ai/kimi-code-sdk`) would pull in full registration
+ * (config/OAuth/telemetry/session services) at import time, so the executor
+ * reaches its implementation exclusively through a dynamic import of
+ * `@moonshot-ai/agent-core-v2/remote/server` — the single engine subpath the
+ * CLI may touch, sanctioned as the exception to the "CLI consumes core
+ * capabilities only via the SDK" rule (remote-environment spec §6/§10). That
+ * subpath is import-graph-isolated from the engine root (enforced by
+ * agent-core-v2's check-import-boundaries), so the light-entry property
+ * holds. `test/cli/exec-server.test.ts` guards this import graph.
+ *
+ * Wire discipline: stdout carries protocol frames only; every diagnostic
+ * (usage errors, startup failures, executor logs) goes to stderr.
+ */
+
+import { readFileSync } from 'node:fs';
+
+import { KIMI_BUILD_INFO } from './build-info';
+import { getHostPackageJsonPath } from './host-package';
+
+export const EXEC_SERVER_COMMAND = 'exec-server';
+
+const EXEC_SERVER_ARGV_SHAPES: readonly (readonly string[])[] = [
+  [EXEC_SERVER_COMMAND],
+  [EXEC_SERVER_COMMAND, '--listen', 'stdio'],
+];
+
+/**
+ * Exact-shape match for the light path: the bare command or the explicit
+ * `--listen stdio` spelling (stdio is the only transport, so the flag is
+ * ceremony kept for compatibility). Node/tsx invoke as
+ * `[exec, script, ...args]`, the SEA binary as `[exec, exec, ...args]` (or
+ * `[exec, ...args]`), so each shape is accepted at either offset. Anything
+ * else named `exec-server` falls through to the full CLI, where the hidden
+ * Commander subcommand in `cli/commands.ts` owns validation and errors.
+ */
+export function isExecServerArgv(argv: readonly string[]): boolean {
+  return hasExecServerShape(argv.slice(1)) || hasExecServerShape(argv.slice(2));
+}
+
+function hasExecServerShape(args: readonly string[]): boolean {
+  return EXEC_SERVER_ARGV_SHAPES.some(
+    (shape) => shape.length === args.length && shape.every((arg, index) => arg === args[index]),
+  );
+}
+
+/**
+ * Executor version reported in the handshake (`executorVersion`): the host
+ * CLI package version, so the client's `MIN_EXECUTOR_VERSION` gate and the
+ * install/update guidance (spec D9) compare against the same version the
+ * binary ships as. Build-info wins when injected (SEA/native bundles);
+ * otherwise read the nearest package.json (npm dist, tsx dev).
+ */
+export function resolveExecutorVersion(): string {
+  if (KIMI_BUILD_INFO.version !== undefined) {
+    return KIMI_BUILD_INFO.version;
+  }
+  const pkg = JSON.parse(readFileSync(getHostPackageJsonPath(), 'utf-8')) as {
+    version: string;
+  };
+  return pkg.version;
+}
+
+/**
+ * Validate the transport and run the executor until the stdio connection
+ * closes. Returns the process exit code: 0 on clean shutdown, 1 on startup
+ * failure, 2 on an unsupported `--listen` transport.
+ */
+export async function runExecServerCommand(listen: string): Promise<number> {
+  if (listen !== 'stdio') {
+    process.stderr.write(`error: exec-server supports only "--listen stdio" (got "--listen ${listen}")\n`);
+    return 2;
+  }
+  try {
+    const { runExecServer } = await import('@moonshot-ai/agent-core-v2/remote/server');
+    return await runExecServer({ version: resolveExecutorVersion() });
+  } catch (error) {
+    process.stderr.write(
+      `error: exec-server failed to start: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return 1;
+  }
+}

apps/kimi-code/src/cli/host-package.ts

@@ -0,0 +1,34 @@
+/**
+ * Locate the host CLI's own package.json.
+ *
+ * Kept free of workspace imports so the exec-server light entry
+ * (`cli/exec-server.ts`) can resolve the package version without pulling in
+ * the SDK module graph.
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+const MODULE_DIR = import.meta.dirname;
+
+export function getHostPackageJsonPath(): string {
+  // Walk upwards from this file's directory until a `package.json` shows up,
+  // so both dev (`tsx src/main.ts` — this file in `src/cli/`, pkg 2 levels
+  // up) and prod (`node dist/main.mjs` — this code bundled into `dist/`,
+  // pkg 1 level up) resolve correctly.
+  let dir = MODULE_DIR;
+  for (let i = 0; i < 6; i += 1) {
+    const candidate = resolve(dir, 'package.json');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`Could not locate package.json near ${MODULE_DIR}`);
+}
+
+export function getHostPackageRoot(): string {
+  return dirname(getHostPackageJsonPath());
+}