feat(kimi-code): support automatic updates for native installations via staged swap

.changeset/native-staged-auto-update.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Support automatic updates for native (single-binary) installations, including Windows: new versions download in the background, verify against the release checksum, and swap in on the next launch. Run `kimi upgrade` to update now, or let the background updater handle it.

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

@@ -15,13 +15,15 @@ export type MainCommandHandler = (opts: CLIOptions) => void;
 export type MigrateCommandHandler = () => void;
 export type PluginNodeRunnerHandler = (entry: string, args: readonly string[]) => void;
 export type UpgradeCommandHandler = () => void | Promise<void>;
+export type UpdateDownloadHandler = (version: string) => void;
 
 export function createProgram(
   version: string,
   onMain: MainCommandHandler,
   onMigrate: MigrateCommandHandler,
   onPluginNodeRunner: PluginNodeRunnerHandler = () => {},
   onUpgrade: UpgradeCommandHandler = () => {},
+  onUpdateDownload: UpdateDownloadHandler = () => {},
 ): Command {
   const program = new Command(CLI_COMMAND_NAME)
     .description('The Starting Point for Next-Gen Agents')
@@ -138,6 +140,15 @@ export function createProgram(
       onPluginNodeRunner(entry, args);
     });
 
+  // Self-spawned worker for native staged updates (detached background
+  // download, or foreground from `kimi upgrade`). Hidden: not user-facing.
+  program
+    .command('__update_download', { hidden: true })
+    .argument('<version>')
+    .action((targetVersion: string) => {
+      onUpdateDownload(targetVersion);
+    });
+
   program.argument('[args...]').action((args: string[]) => {
     if (args.length > 0) {
       program.error(`unknown command '${args[0]}'. See '${CLI_COMMAND_NAME} --help'.`);

apps/kimi-code/src/cli/sub/update-download.ts

@@ -0,0 +1,104 @@
+/**
+ * Hidden `kimi __update_download <version>` sub-command: the self-spawned
+ * worker behind native staged updates. Preflight spawns it detached in the
+ * background (and the `upgrade` command in the foreground); it downloads,
+ * verifies and stages the binary next to the running exe. The swap into
+ * place happens on the next startup (see `cli/update/native-swap.ts`).
+ */
+
+import { log } from '@moonshot-ai/kimi-code-sdk';
+
+import {
+  readUpdateInstallLockVersion,
+  tryAcquireUpdateInstallLock,
+} from '#/cli/update/install-lock';
+import { stageNativeUpdate } from '#/cli/update/native-stage';
+import { detectNativeInstall } from '#/cli/update/source';
+
+export async function runUpdateDownloadCommand(version: string): Promise<number> {
+  if (!detectNativeInstall()) {
+    process.stderr.write('error: update download is only available in the native build\n');
+    return 1;
+  }
+  let lock = await tryAcquireUpdateInstallLock({ version });
+  if (lock === null) {
+    // Another instance holds the lock. Same target version → its outcome is
+    // ours, exit quietly. A different version (or a lock that vanished
+    // between acquire and read) must not surface as a successful download.
+    const holderVersion = await readUpdateInstallLockVersion();
+    if (holderVersion === version) return 0;
+    if (holderVersion === undefined) {
+      // The lock was released between the two reads — retry the acquire once.
+      lock = await tryAcquireUpdateInstallLock({ version });
+    }
+    if (lock === null) {
+      process.stderr.write(
+        `error: another update (${holderVersion ?? 'unknown version'}) is already downloading\n`,
+      );
+      return 1;
+    }
+  }
+  const out = process.stdout;
+  const label = `Downloading Kimi Code ${version} (${process.platform}-${process.arch})…`;
+  const onProgress = createDownloadProgress(out, label);
+  try {
+    const result = await stageNativeUpdate({
+      version,
+      exePath: process.execPath,
+      onProgress,
+    });
+    if (out.isTTY) out.write('\n');
+    if (result.status === 'already-staged') {
+      out.write(`Kimi Code ${version} is already downloaded; it applies on the next start.\n`);
+    }
+    return 0;
+  } catch (error) {
+    if (out.isTTY) out.write('\n');
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`error: failed to download update ${version}: ${message}\n`);
+    log.warn('native update download failed', { version, error: message });
+    return 1;
+  } finally {
+    await lock.release().catch(() => {});
+  }
+}
+
+const PROGRESS_FRAME_INTERVAL_MS = 100;
+const PROGRESS_LINE_INTERVAL_BYTES = 32 * 1024 * 1024;
+
+function formatDownloadProgress(label: string, downloaded: number, total: number | null): string {
+  const mb = Math.floor(downloaded / (1024 * 1024));
+  if (total === null || total <= 0) return `${label} ${mb} MB`;
+  const totalMb = Math.max(1, Math.round(total / (1024 * 1024)));
+  const percent = Math.min(100, Math.floor((downloaded / total) * 100));
+  return `${label} ${percent}% (${mb}/${totalMb} MB)`;
+}
+
+/**
+ * Download progress renderer for the (foreground) downloader: a single
+ * in-place line on a TTY (`\r` + clear-line, throttled to 10 fps, final frame
+ * always rendered), or one line per 32 MB when piped to a file. The caller
+ * owns the trailing newline.
+ */
+export function createDownloadProgress(
+  out: NodeJS.WriteStream,
+  label: string,
+): (downloadedBytes: number, totalBytes: number | null) => void {
+  const isTTY = out.isTTY;
+  let lastFrameAt = 0;
+  let lastLineAt = 0;
+  if (!isTTY) out.write(`${label}\n`);
+  return (downloaded, total) => {
+    const done = total !== null && downloaded >= total;
+    if (isTTY) {
+      const now = Date.now();
+      if (!done && now - lastFrameAt < PROGRESS_FRAME_INTERVAL_MS) return;
+      lastFrameAt = now;
+      out.write(`\r\u001B[K${formatDownloadProgress(label, downloaded, total)}`);
+      return;
+    }
+    if (!done && downloaded - lastLineAt < PROGRESS_LINE_INTERVAL_BYTES) return;
+    lastLineAt = downloaded;
+    out.write(`${formatDownloadProgress(label, downloaded, total)}\n`);
+  };
+}

apps/kimi-code/src/cli/update/install-lock.ts

@@ -93,3 +93,27 @@ export async function tryAcquireUpdateInstallLock(
     throw error;
   }
 }
+
+/**
+ * Return the version recorded in the held lock file, or undefined when the
+ * lock is gone or unreadable. Lets a downloader that failed to acquire the
+ * lock distinguish "another instance is staging the SAME version" (its
+ * outcome is ours — report success) from "a different version is in flight"
+ * (must not be reported as success to a foreground `kimi upgrade`).
+ */
+export async function readUpdateInstallLockVersion(
+  filePath: string = getUpdateInstallLockFile(),
+): Promise<string | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(filePath, 'utf-8');
+  } catch {
+    return undefined;
+  }
+  try {
+    const version: unknown = (JSON.parse(raw) as { version?: unknown }).version;
+    return typeof version === 'string' && version.length > 0 ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}

apps/kimi-code/src/cli/update/native-manifest.ts

@@ -0,0 +1,94 @@
+/**
+ * Per-release native artifact manifest (`/binaries/<version>/manifest.json`).
+ *
+ * Published alongside the release and consumed by the install scripts; the
+ * staged updater reuses the same file so checksums and file names have a
+ * single source of truth. Entries point at the bare platform binary
+ * (`kimi-code-<target>[.exe]`), not an archive.
+ */
+
+import { valid } from 'semver';
+import { z } from 'zod';
+
+import { KIMI_CODE_CDN_BINARIES_BASE } from '#/constant/app';
+
+const MANIFEST_FETCH_TIMEOUT_MS = 10_000;
+
+const PlatformEntrySchema = z.object({
+  filename: z.string().min(1),
+  checksum: z.string().regex(/^[a-f0-9]{64}$/, { error: 'invalid sha256' }),
+});
+
+/**
+ * Deliberately NOT `.strict()` — unknown fields are ignored so future
+ * manifest additions never break shipped clients (same contract philosophy
+ * as the rollout manifest in `cdn.ts`).
+ */
+export const NativeReleaseManifestSchema = z.object({
+  version: z.string().refine((value) => valid(value) !== null, { error: 'invalid semver' }),
+  platforms: z.record(z.string(), PlatformEntrySchema),
+});
+
+export type NativeReleaseManifest = z.infer<typeof NativeReleaseManifestSchema>;
+export type NativePlatformEntry = z.infer<typeof PlatformEntrySchema>;
+
+export function nativeManifestUrl(version: string): string {
+  return `${KIMI_CODE_CDN_BINARIES_BASE}/${version}/manifest.json`;
+}
+
+export function nativeBinaryUrl(version: string, filename: string): string {
+  return `${KIMI_CODE_CDN_BINARIES_BASE}/${version}/${filename}`;
+}
+
+/**
+ * Fetch and parse the per-release manifest. **Throws** on any failure
+ * (network, non-2xx, malformed body, unknown version) — callers treat a
+ * throw as "staging failed" and record an install failure.
+ *
+ * `version` goes into the URL, so it must be a valid semver (it always is:
+ * upstream sources are the CDN `latest.json` / the `upgrade` command).
+ * `fetchImpl` is injectable for tests.
+ */
+export async function fetchNativeReleaseManifest(
+  version: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<NativeReleaseManifest> {
+  if (valid(version) === null) {
+    throw new Error(`invalid semver for native manifest lookup: ${JSON.stringify(version)}`);
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, MANIFEST_FETCH_TIMEOUT_MS);
+  // The timeout must stay armed until the BODY is fully consumed: a CDN or
+  // proxy can deliver headers within the limit and then stall mid-body, and
+  // resolving `fetch()` alone would clear the timer and hang the worker.
+  try {
+    const response = await fetchImpl(nativeManifestUrl(version), { signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`native manifest for ${version} returned HTTP ${response.status}`);
+    }
+    return NativeReleaseManifestSchema.parse(JSON.parse(await response.text()));
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Pick the entry for the running platform. The release pipeline keys
+ * platforms by `<node platform>-<node arch>` (win32-x64, darwin-arm64, …).
+ * **Throws** when the platform is missing — a silent skip would strand the
+ * update in a retry loop.
+ */
+export function selectPlatformEntry(
+  manifest: NativeReleaseManifest,
+  platform: NodeJS.Platform,
+  arch: string,
+): NativePlatformEntry {
+  const target = `${platform}-${arch}`;
+  const entry = manifest.platforms[target];
+  if (entry === undefined) {
+    throw new Error(`platform ${target} not found in native manifest for ${manifest.version}`);
+  }
+  return entry;
+}