feat: add experimental turn-level file history snapshots

.changeset/file-history-turn-snapshots.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Add experimental turn-level file snapshots (enable with KIMI_CODE_EXPERIMENTAL_FILE_HISTORY=1): the daemon backs up every file it edits and versions all tracked files at each turn boundary.

packages/agent-core-v2/docs/state-manifest.d.ts

@@ -27,7 +27,7 @@
 // references become '(circular)', and class instances collapse to a '(ClassName)'
 // marker — the wire shape of an entry is the JSON projection of the type here.
 //
-// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 79 keys)
+// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 80 keys)
 //   App
 //   Workspace
 //     workspaceDirs.ephemeralDirs          src/workspace/workspaceDirs/workspaceDirsService.ts
@@ -59,6 +59,7 @@
 //     contextMemory                                   src/agent/contextMemory/contextOps.ts
 //     contextProjector.lastRepairSignature            src/agent/contextProjector/contextProjectorService.ts
 //     externalHooks.stopHookContinuationUsed          src/features/externalHooks/agent/agentExternalHooksService.ts
+//     fileHistory                                     src/features/fileHistory/fileHistoryOps.ts
 //     fullCompaction                                  src/agent/fullCompaction/compactionOps.ts
 //     fullCompaction.activeTurnId                     src/agent/fullCompaction/fullCompactionService.ts
 //     fullCompaction.compactionCountInTurn            src/agent/fullCompaction/fullCompactionService.ts
@@ -1493,6 +1494,23 @@ export interface AgentStateSnapshot {
   }>;
   // src/features/externalHooks/agent/agentExternalHooksService.ts
   'externalHooks.stopHookContinuationUsed': boolean;
+  // src/features/fileHistory/fileHistoryOps.ts
+  // replayable · durable — folds: FileHistoryCheckpointed, FileHistoryTracked
+  'fileHistory': /* FileHistoryState — packages/agent-core-v2/src/features/fileHistory/fileHistory.ts */ {
+    readonly checkpoints: readonly /* FileHistoryCheckpointRecord — packages/agent-core-v2/src/features/fileHistory/fileHistory.ts */ {
+      readonly turnId: number;
+      readonly phase?: 'start' | 'end';
+      readonly entries: Readonly<Record<string, /* FileBackupEntry — packages/agent-core-v2/src/features/fileHistory/fileHistory.ts */ {
+        readonly key: string | null;
+        readonly version: number;
+        readonly contentHash?: string;
+        readonly size?: number;
+        readonly oversize?: boolean;
+        readonly mtimeMs?: number;
+      }>>;
+    }[];
+    readonly tracked: readonly string[];
+  };
   // src/features/plan/injection/planModeInjection.ts
   'plan.wasActive': boolean;
   // src/features/plan/planOps.ts

packages/agent-core-v2/docs/wire-manifest.d.ts

@@ -24,7 +24,7 @@
 // cross-reducers), blobs (the folding states whose blob codec offloads inline
 // media to blob storage), owner (the source file declaring the class).
 
-// Index (55 record types)
+// Index (57 record types)
 //   config.update                      profile                                               src/agent/profile/profileOps.ts
 //   context.append_loop_event          contextMemory, turn                                   src/agent/contextMemory/contextEvents.ts
 //   context.append_message             contextMemory, plan, task.notificationDelivery        src/agent/contextMemory/contextEvents.ts
@@ -34,6 +34,8 @@
 //   cron.add                           (none)                                                src/features/cron/cronOps.ts
 //   cron.cursor                        (none)                                                src/features/cron/cronOps.ts
 //   cron.delete                        (none)                                                src/features/cron/cronOps.ts
+//   file_history.checkpoint            fileHistory                                           src/features/fileHistory/fileHistoryOps.ts
+//   file_history.tracked               fileHistory                                           src/features/fileHistory/fileHistoryOps.ts
 //   forked                             (none)                                                src/features/goal/goalOps.ts
 //   full_compaction.begin              fullCompaction                                        src/agent/fullCompaction/compactionOps.ts
 //   full_compaction.cancel             fullCompaction                                        src/agent/fullCompaction/compactionOps.ts
@@ -214,6 +216,37 @@ interface CronDeletePayload {
   ids: string[];
 }
 
+/**
+ * states: fileHistory
+ * owner: src/features/fileHistory/fileHistoryOps.ts
+ */
+interface FileHistoryCheckpointPayload {
+  _name: 'file_history.checkpoint';
+  agentId: string;
+  turnId: number;
+  phase?: 'start' | 'end';
+  entries: Record<string, object>;
+}
+
+/**
+ * states: fileHistory
+ * owner: src/features/fileHistory/fileHistoryOps.ts
+ */
+interface FileHistoryTrackedPayload {
+  _name: 'file_history.tracked';
+  agentId: string;
+  turnId: number;
+  path: string;
+  entry: {
+    key: string | null;
+    version: number;
+    contentHash?: string;
+    size?: number;
+    oversize?: boolean;
+    mtimeMs?: number;
+  };
+}
+
 /**
  * states: (none)
  * owner: src/features/goal/goalOps.ts
@@ -837,6 +870,8 @@ interface WirePayloadMap {
   "cron.add": CronAddPayload;
   "cron.cursor": CronCursorPayload;
   "cron.delete": CronDeletePayload;
+  "file_history.checkpoint": FileHistoryCheckpointPayload;
+  "file_history.tracked": FileHistoryTrackedPayload;
   "forked": ForkedPayload;
   "full_compaction.begin": FullCompactionBeginPayload;
   "full_compaction.cancel": FullCompactionCancelPayload;

packages/agent-core-v2/src/features/fileHistory/fileHistory.ts

@@ -0,0 +1,58 @@
+import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
+
+export interface FileBackupEntry {
+  readonly key: string | null;
+  readonly version: number;
+  readonly contentHash?: string;
+  readonly size?: number;
+  readonly oversize?: boolean;
+  readonly mtimeMs?: number;
+}
+
+export type FileHistoryCheckpointPhase = 'start' | 'end';
+
+export interface FileHistoryCheckpointRecord {
+  readonly turnId: number;
+  readonly phase?: FileHistoryCheckpointPhase;
+  readonly entries: Readonly<Record<string, FileBackupEntry>>;
+}
+
+export interface FileHistoryState {
+  readonly checkpoints: readonly FileHistoryCheckpointRecord[];
+  readonly tracked: readonly string[];
+}
+
+export type FileHistoryChangeStatus = 'added' | 'modified' | 'deleted';
+
+export interface FileHistoryChange {
+  readonly path: string;
+  readonly status: FileHistoryChangeStatus;
+  readonly additions: number;
+  readonly deletions: number;
+  readonly binary?: boolean;
+  readonly oversize?: boolean;
+}
+
+export interface FileHistoryContent {
+  readonly version: number;
+  readonly content?: string;
+  readonly binary?: boolean;
+}
+
+export interface IAgentFileHistoryService {
+  readonly _serviceBrand: undefined;
+
+  enabled(): boolean;
+  history(): FileHistoryState;
+  settled(): Promise<void>;
+  captureForActiveTurn(path: string): Promise<void>;
+  changes(turnId: number): Promise<FileHistoryChange[]>;
+  contentAt(
+    turnId: number,
+    path: string,
+    phase?: FileHistoryCheckpointPhase,
+  ): Promise<FileHistoryContent | undefined>;
+}
+
+export const IAgentFileHistoryService: ServiceIdentifier<IAgentFileHistoryService> =
+  createDecorator<IAgentFileHistoryService>('agentFileHistoryService');

packages/agent-core-v2/src/features/fileHistory/fileHistoryFeature.ts

@@ -0,0 +1,17 @@
+import { Feature } from '#/features/feature';
+import { registerFeature } from '#/features/featureRegistry';
+
+import './flag';
+import { IAgentFileHistoryService } from './fileHistory';
+import { AgentFileHistoryService } from './fileHistoryService';
+
+export class FileHistoryFeature extends Feature {
+  static override readonly name = 'fileHistory';
+
+  constructor() {
+    super();
+    this.contributeAgentService(IAgentFileHistoryService, AgentFileHistoryService);
+  }
+}
+
+registerFeature(FileHistoryFeature);

packages/agent-core-v2/src/features/fileHistory/fileHistoryOps.ts

@@ -0,0 +1,120 @@
+/* oxlint-disable typescript-eslint/no-unsafe-declaration-merging, eslint-plugin-import/namespace -- Event2 class+payload-interface declaration merging is the sanctioned event-declaration idiom. */
+import { z } from 'zod';
+
+import { AgentEvent2 } from '#/app/event/event2';
+import { defineState } from '#/state/state';
+
+import type {
+  FileBackupEntry,
+  FileHistoryCheckpointPhase,
+  FileHistoryState,
+} from './fileHistory';
+
+export const FILE_HISTORY_CHECKPOINT_CAP = 400;
+export const FILE_HISTORY_RECORD_PREFIX = 'file_history.';
+
+const backupEntrySchema = z.object({
+  key: z.string().nullable(),
+  version: z.number(),
+  contentHash: z.string().optional(),
+  size: z.number().optional(),
+  oversize: z.boolean().optional(),
+  mtimeMs: z.number().optional(),
+});
+
+const fileHistoryTrackedSchema = z.object({
+  agentId: z.string(),
+  turnId: z.number(),
+  path: z.string(),
+  entry: backupEntrySchema,
+});
+
+export class FileHistoryTracked extends AgentEvent2<z.infer<typeof fileHistoryTrackedSchema>> {
+  static override readonly type = 'file_history.tracked';
+  static override readonly durable = true;
+  static override readonly schema = fileHistoryTrackedSchema;
+}
+export interface FileHistoryTracked {
+  readonly agentId: string;
+  readonly turnId: number;
+  readonly path: string;
+  readonly entry: FileBackupEntry;
+}
+
+const fileHistoryCheckpointedSchema = z.object({
+  agentId: z.string(),
+  turnId: z.number(),
+  phase: z.enum(['start', 'end']).optional(),
+  entries: z.record(z.string(), backupEntrySchema),
+});
+
+export class FileHistoryCheckpointed extends AgentEvent2<
+  z.infer<typeof fileHistoryCheckpointedSchema>
+> {
+  static override readonly type = 'file_history.checkpoint';
+  static override readonly durable = true;
+  static override readonly schema = fileHistoryCheckpointedSchema;
+}
+export interface FileHistoryCheckpointed {
+  readonly agentId: string;
+  readonly turnId: number;
+  readonly phase?: FileHistoryCheckpointPhase;
+  readonly entries: Readonly<Record<string, FileBackupEntry>>;
+}
+
+export function checkpointPhaseOf(record: {
+  readonly phase?: FileHistoryCheckpointPhase;
+}): FileHistoryCheckpointPhase {
+  return record.phase ?? 'start';
+}
+
+function cloneEntries(
+  entries: Readonly<Record<string, FileBackupEntry>>,
+): Record<string, FileBackupEntry> {
+  const clone: Record<string, FileBackupEntry> = Object.create(null) as Record<
+    string,
+    FileBackupEntry
+  >;
+  for (const [path, entry] of Object.entries(entries)) clone[path] = entry;
+  return clone;
+}
+
+export const fileHistoryKey = defineState(
+  'fileHistory',
+  (): FileHistoryState => ({ checkpoints: [], tracked: [] }),
+)
+  .replayable({ schema: z.custom<FileHistoryState>() })
+  .on(FileHistoryCheckpointed, (s, e) => {
+    const phase = checkpointPhaseOf(e);
+    const existing = s.checkpoints.find(
+      (c) => c.turnId === e.turnId && checkpointPhaseOf(c) === phase,
+    );
+    if (existing !== undefined) {
+      existing.entries = cloneEntries(e.entries);
+      return;
+    }
+    s.checkpoints.push({ turnId: e.turnId, phase, entries: cloneEntries(e.entries) });
+    if (s.checkpoints.length > FILE_HISTORY_CHECKPOINT_CAP) {
+      const removed = s.checkpoints.splice(0, s.checkpoints.length - FILE_HISTORY_CHECKPOINT_CAP);
+      const head = s.checkpoints[0]!;
+      const folded = cloneEntries({});
+      for (const record of removed) {
+        for (const [path, entry] of Object.entries(record.entries)) folded[path] = entry;
+      }
+      for (const [path, entry] of Object.entries(head.entries)) folded[path] = entry;
+      head.entries = folded;
+    }
+  })
+  .on(FileHistoryTracked, (s, e) => {
+    if (!s.tracked.includes(e.path)) s.tracked.push(e.path);
+    let checkpoint = s.checkpoints.find(
+      (c) => c.turnId === e.turnId && checkpointPhaseOf(c) === 'start',
+    );
+    if (checkpoint === undefined) {
+      s.checkpoints.push({ turnId: e.turnId, phase: 'start', entries: {} });
+      checkpoint = s.checkpoints.at(-1);
+    }
+    if (checkpoint !== undefined && !Object.hasOwn(checkpoint.entries, e.path)) {
+      checkpoint.entries[e.path] = { ...e.entry };
+    }
+  });