feat(cli): add headless mode

.changeset/headless-scripted-runs.md

@@ -0,0 +1,7 @@
+---
+"@moonshot-ai/kimi-code": minor
+"@moonshot-ai/kimi-code-sdk": minor
+"@moonshot-ai/agent-core": minor
+---
+
+Add headless CLI runs with status polling, file output, goal control, and session run locking.

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

@@ -3,6 +3,7 @@ import { registerMigrateCommand } from '#/migration/index';
 import { Command, Option } from 'commander';
 
 import type { CLIOptions } from './options';
+import { registerHeadlessCommand, type HeadlessCommandHandler } from './headless/commands';
 import { registerAcpCommand } from './sub/acp';
 import { registerDoctorCommand } from './sub/doctor';
 import { registerExportCommand } from './sub/export';
@@ -20,11 +21,13 @@ export function createProgram(
   onMigrate: MigrateCommandHandler,
   onPluginNodeRunner: PluginNodeRunnerHandler = () => {},
   onUpgrade: UpgradeCommandHandler = () => {},
+  onHeadless: HeadlessCommandHandler = () => {},
 ): Command {
   const program = new Command(CLI_COMMAND_NAME)
     .description('The Starting Point for Next-Gen Agents')
     .version(version, '-V, --version')
     .allowUnknownOption(false)
+    .enablePositionalOptions()
     .configureHelp({ helpWidth: 100 })
     .helpOption('-h, --help', 'Show help.')
     .usage('[options] [command]')
@@ -81,6 +84,7 @@ export function createProgram(
   registerLoginCommand(program);
   registerDoctorCommand(program);
   registerMigrateCommand(program, onMigrate);
+  registerHeadlessCommand(program, onHeadless);
   program
     .command('upgrade')
     .description('Upgrade Kimi Code to the latest version.')

apps/kimi-code/src/cli/headless/approval.ts

@@ -0,0 +1,78 @@
+import type { ApprovalHandler, ApprovalRequest, ApprovalResponse } from '@moonshot-ai/kimi-code-sdk';
+
+import type { HeadlessApprovalStatus } from './status-file';
+import type { HeadlessWarning } from './status-file';
+
+export interface HeadlessApprovalOptions {
+  readonly approvePlan: boolean;
+  readonly rejectPlan: boolean;
+  readonly onPlanApprovalRequired: (approval: HeadlessApprovalStatus) => void;
+}
+
+export function createHeadlessApprovalHandler(options: HeadlessApprovalOptions): ApprovalHandler {
+  return (request) => {
+    if (!isPlanApprovalRequest(request)) return { decision: 'approved' };
+
+    const approval: HeadlessApprovalStatus = {
+      kind: 'plan',
+      toolCallId: request.toolCallId,
+      decision: options.approvePlan ? 'approved' : options.rejectPlan ? 'rejected' : 'required',
+      decidedByFlag: options.approvePlan ? 'approve-plan' : options.rejectPlan ? 'reject-plan' : null,
+      message: options.approvePlan
+        ? 'Plan approved by --approve-plan.'
+        : options.rejectPlan
+          ? 'Plan rejected by --reject-plan.'
+          : 'rerun with --approve-plan or --reject-plan',
+    };
+    options.onPlanApprovalRequired(approval);
+
+    if (options.approvePlan) {
+      return approvePlanRequest(request);
+    }
+    if (options.rejectPlan) {
+      return {
+        decision: 'rejected',
+        selectedLabel: 'Reject and Exit',
+        feedback: 'Rejected by --reject-plan.',
+      };
+    }
+    return {
+      decision: 'cancelled',
+      feedback: 'Plan approval requires --approve-plan or --reject-plan in headless mode.',
+    };
+  };
+}
+
+export function getUnusedPlanFlagWarning(options: {
+  readonly approvePlan: boolean;
+  readonly rejectPlan: boolean;
+  readonly planApprovalSeen: boolean;
+}): HeadlessWarning | null {
+  if (options.planApprovalSeen) return null;
+  if (options.approvePlan) {
+    return {
+      code: 'PLAN_FLAG_UNUSED',
+      message: '--approve-plan was set, but no plan approval was requested.',
+    };
+  }
+  if (options.rejectPlan) {
+    return {
+      code: 'PLAN_FLAG_UNUSED',
+      message: '--reject-plan was set, but no plan approval was requested.',
+    };
+  }
+  return null;
+}
+
+function isPlanApprovalRequest(request: ApprovalRequest): boolean {
+  return request.toolName === 'ExitPlanMode' || request.display.kind === 'plan_review';
+}
+
+function approvePlanRequest(request: ApprovalRequest): ApprovalResponse {
+  const firstOption =
+    request.display.kind === 'plan_review' ? request.display.options?.[0]?.label : undefined;
+  return {
+    decision: 'approved',
+    selectedLabel: firstOption,
+  };
+}

apps/kimi-code/src/cli/headless/atomic-file.ts

@@ -0,0 +1,19 @@
+import { mkdir, open, rename } from 'node:fs/promises';
+import path from 'node:path';
+
+export async function writeAtomicTextFile(filePath: string, text: string): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp`;
+  const handle = await open(tempPath, 'w');
+  try {
+    await handle.writeFile(text, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(tempPath, filePath);
+}
+
+export async function writeAtomicJsonFile(filePath: string, value: unknown): Promise<void> {
+  await writeAtomicTextFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}