feat(web): add history fork for conversations

.gitignore

@@ -190,6 +190,11 @@ package-lock.json
 # Test output
 test-results/
 
+# Local test drafts (force-add intentional new tests with git add -f)
+test/
+test.ts
+*.test.ts
+
 # Auto-Research-Skills (local-only)
 Auto-Research-Skills/
 

scripts/tui-e2e-permission.tsx

@@ -98,6 +98,7 @@ class MockGateway implements Gateway {
   grantSessionPermission = stub({ granted: false }) as Gateway["grantSessionPermission"];
   readSessionMessages = stub({ messages: [], hasMore: false, session: {} as any }) as unknown as Gateway["readSessionMessages"];
   readSubagentMessages = stub({ messages: [], total: 0 }) as unknown as Gateway["readSubagentMessages"];
+  forkSession = stub({ newSessionKey: "web:s_fork", prefillText: "", carriedMessageCount: 0 }) as unknown as Gateway["forkSession"];
   listProjects = stub({ projects: [] }) as Gateway["listProjects"];
   describeProject = stub({ projectKey: "", name: "", root: "", fullPath: "", sessionCount: 0 }) as unknown as Gateway["describeProject"];
 }

src/agent/runtime/AgentRuntimeDependencies.ts

@@ -69,7 +69,12 @@ export type AgentSubagentTranscriptHooks = {
     errored?: boolean;
   }): Promise<void>;
   subagentTranscriptResolver?(subagentId: string): {
-    recordAcceptedInput(sessionId: string, turnId: string, messages: CanonicalMessage[]): Promise<void>;
+    recordAcceptedInput(
+      sessionId: string,
+      turnId: string,
+      messages: CanonicalMessage[],
+      metadata?: Record<string, unknown>,
+    ): Promise<void>;
     recordDurableMessage(sessionId: string, turnId: string, message: CanonicalMessage): Promise<void>;
     transcriptRelativePath: string;
   };

src/agent/sub/SubAgentSession.ts

@@ -87,7 +87,12 @@ export type SubAgentSessionOptions = {
  * (the parent constructs the writer and passes it in).
  */
 export type SidechainTranscriptWriter = {
-  recordAcceptedInput(sessionId: string, turnId: string, messages: CanonicalMessage[]): Promise<void>;
+  recordAcceptedInput(
+    sessionId: string,
+    turnId: string,
+    messages: CanonicalMessage[],
+    metadata?: Record<string, unknown>,
+  ): Promise<void>;
   recordDurableMessage(sessionId: string, turnId: string, message: CanonicalMessage): Promise<void>;
 };
 

src/agent/turn/TurnRunner.ts

@@ -59,7 +59,12 @@ export class TurnRunner {
     const messages = [...options.messages, ...accepted.messages];
 
     try {
-      await this.transcript.recordAcceptedInput(options.sessionId, options.turnId, accepted.messages);
+      await this.transcript.recordAcceptedInput(
+        options.sessionId,
+        options.turnId,
+        accepted.messages,
+        acceptedInputMetadata(options),
+      );
     } catch (error) {
       const agentTranscriptError = agentError("agent_transcript_error", "Failed to record accepted input.", error);
       const result = this.createErrorResult(options, agentTranscriptError);
@@ -156,6 +161,20 @@ export class TurnRunner {
   }
 }
 
+function acceptedInputMetadata(options: TurnRunnerOptions): Record<string, unknown> | undefined {
+  const metadata: Record<string, unknown> = {};
+  if (options.permissionMode) {
+    metadata.permissionMode = options.permissionMode;
+  }
+  if (options.basePermissionMode) {
+    metadata.basePermissionMode = options.basePermissionMode;
+  }
+  if (options.allowPlanModeTools !== undefined) {
+    metadata.allowPlanModeTools = options.allowPlanModeTools;
+  }
+  return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+
 function emptyUsage(): CanonicalUsage {
   return {};
 }

src/cli/createLocalGateway.ts

@@ -64,6 +64,7 @@ import { DEFAULT_JUDGE_TIMEOUT_MS, DEFAULT_SUBAGENT_MAX_TOKENS, DEFAULT_ALLOWED_
 import { createAgentProjectSessionStorage, listProjectSessions, resumeAgentSession } from "../session/index.js";
 import { sanitizeSessionIdForPath } from "../session/storage/ProjectSessionStorage.js";
 import { readWebSessionMessages, readSubagentWebMessages } from "../web/server/readSessionMessages.js";
+import { forkWebSession } from "../web/server/forkSession.js";
 import { describeWebProject, listWebProjects } from "../web/server/listProjects.js";
 import { BackgroundTaskRuntime } from "../task/runtime/BackgroundTaskRuntime.js";
 import { createBuiltinRegistry, createPlanFileManager } from "../tool/index.js";
@@ -269,6 +270,12 @@ export function createLocalGateway(options: CreateLocalGatewayOptions = {}): Cre
         pilotHome,
         now,
       }),
+    forkSession: (input) =>
+      forkWebSession(input, {
+        projectRoot: input.projectKey ? input.projectKey : projectRoot,
+        pilotHome,
+        now,
+      }),
     listProjects: () =>
       listWebProjects({ pilotHome, defaultProjectRoot: options.skipDefaultProject ? undefined : projectRoot }),
     describeProject: (input) =>

src/cli/pilotdeck.ts

@@ -680,6 +680,9 @@ function createFallbackGateway(): Gateway {
     readSubagentMessages: async () => {
       throw new Error("read_subagent_messages is not configured.");
     },
+    forkSession: async () => {
+      throw new Error("fork_session is not configured.");
+    },
     listProjects: async () => ({ projects: [] }),
     describeProject: async (input) => ({
       projectKey: input.projectKey,

src/context/DefaultContextRuntime.ts

@@ -282,7 +282,7 @@ export class DefaultContextRuntime implements ContextRuntime {
       await this.memoryResolver.captureTurn({
         sessionId: input.sessionId,
         projectRoot: this.projectRoot ?? "",
-        messages: input.messages,
+        messages: input.messages.filter((message) => !message.metadata?.forkCarryover),
         errored: input.errored,
       });
     } catch {

src/context/memory/EdgeClawMemoryProvider.ts

@@ -163,7 +163,9 @@ export class EdgeClawMemoryProvider implements MemoryResolver {
   }
 
   async captureTurn(input: MemoryCaptureTurnInput): Promise<void> {
-    const normalizedMessages = canonicalMessagesToMemoryMessages(input.messages);
+    const normalizedMessages = canonicalMessagesToMemoryMessages(input.messages, {
+      includeForkCarryover: false,
+    });
     this.options.telemetry?.trackFeatureLoopStage({
       module: "memory",
       ownerModule: "memory",

src/context/memory/MemoryResolver.ts

@@ -38,8 +38,19 @@ export type MemoryResolver = {
   captureTurn(input: MemoryCaptureTurnInput): Promise<void>;
 };
 
-export function canonicalMessagesToMemoryMessages(messages: CanonicalMessage[]): ContextMemoryMessage[] {
+export type CanonicalMessagesToMemoryMessagesOptions = {
+  includeForkCarryover?: boolean;
+};
+
+export function canonicalMessagesToMemoryMessages(
+  messages: CanonicalMessage[],
+  options: CanonicalMessagesToMemoryMessagesOptions = {},
+): ContextMemoryMessage[] {
   return messages.flatMap((message, index) => {
+    if (options.includeForkCarryover === false && message.metadata?.forkCarryover) {
+      return [];
+    }
+
     const entries: Array<Omit<ContextMemoryMessage, "msgId">> = [];
     const pushEntry = (role: string, text: string) => {
       const content = text.trim();

src/gateway/client/InProcessGateway.ts

@@ -40,6 +40,8 @@ import type {
   WebReadSessionMessagesResult,
   WebReadSubagentMessagesInput,
   WebReadSubagentMessagesResult,
+  WebForkSessionInput,
+  WebForkSessionResult,
 } from "../protocol/types.js";
 import type {
   CronCreateInput,
@@ -92,6 +94,7 @@ export type InProcessGatewayOptions = {
    */
   readSessionMessages?: (input: WebReadSessionMessagesInput) => Promise<WebReadSessionMessagesResult>;
   readSubagentMessages?: (input: WebReadSubagentMessagesInput) => Promise<WebReadSubagentMessagesResult>;
+  forkSession?: (input: WebForkSessionInput) => Promise<WebForkSessionResult>;
   /**
    * Web Phase 3 — pluggable project enumerator + describer.
    */
@@ -616,6 +619,15 @@ export class InProcessGateway implements Gateway {
     return this.options.readSubagentMessages(input);
   }
 
+  async forkSession(input: WebForkSessionInput): Promise<WebForkSessionResult> {
+    if (!this.options.forkSession) {
+      throw new Error(
+        "fork_session is not configured. Wire `forkSession` via createLocalGateway.",
+      );
+    }
+    return this.options.forkSession(input);
+  }
+
   async listProjects(): Promise<WebListProjectsResult> {
     if (!this.options.listProjects) {
       throw new Error("list_projects is not configured.");

src/gateway/client/RemoteGateway.ts

@@ -22,6 +22,8 @@ import type {
   WebReadSessionMessagesResult,
   WebReadSubagentMessagesInput,
   WebReadSubagentMessagesResult,
+  WebForkSessionInput,
+  WebForkSessionResult,
 } from "../protocol/types.js";
 import type {
   SkillAddressInput,
@@ -134,6 +136,10 @@ export class RemoteGateway implements Gateway {
     return (await this.client.request("read_subagent_messages", input)) as WebReadSubagentMessagesResult;
   }
 
+  async forkSession(input: WebForkSessionInput): Promise<WebForkSessionResult> {
+    return (await this.client.request("fork_session", input)) as WebForkSessionResult;
+  }
+
   async listProjects(): Promise<WebListProjectsResult> {
     return (await this.client.request("list_projects", {})) as WebListProjectsResult;
   }

src/gateway/protocol/frames.ts

@@ -36,6 +36,7 @@ export type WsGatewayMethod =
   | "grant_session_permission"
   | "read_session_messages"
   | "read_subagent_messages"
+  | "fork_session"
   | "list_projects"
   | "describe_project"
   | "reload_config"

src/gateway/protocol/types.ts

@@ -25,6 +25,8 @@ import type {
   WebReadSessionMessagesResult as WebUiReadSessionMessagesResult,
   WebReadSubagentMessagesInput as WebUiReadSubagentMessagesInput,
   WebReadSubagentMessagesResult as WebUiReadSubagentMessagesResult,
+  WebForkSessionInput as WebUiForkSessionInput,
+  WebForkSessionResult as WebUiForkSessionResult,
 } from "../../web/client/protocol.js";
 import type {
   SkillCreateInput,
@@ -222,6 +224,8 @@ export type WebReadSessionMessagesInput = WebUiReadSessionMessagesInput;
 export type WebReadSessionMessagesResult = WebUiReadSessionMessagesResult;
 export type WebReadSubagentMessagesInput = WebUiReadSubagentMessagesInput;
 export type WebReadSubagentMessagesResult = WebUiReadSubagentMessagesResult;
+export type WebForkSessionInput = WebUiForkSessionInput;
+export type WebForkSessionResult = WebUiForkSessionResult;
 export type WebProjectSummary = WebUiProjectSummary;
 export type WebListProjectsResult = WebUiListProjectsResult;
 export type WebDescribeProjectInput = { projectKey: string };
@@ -343,6 +347,10 @@ export interface Gateway {
    * the Web `WebMessage` DTO.
    */
   readSessionMessages(input: WebReadSessionMessagesInput): Promise<WebReadSessionMessagesResult>;
+  /**
+   * Fork a session transcript at a prior user turn into a new session file.
+   */
+  forkSession(input: WebForkSessionInput): Promise<WebForkSessionResult>;
   /**
    * Read a subagent's sidechain transcript and return its messages in WebMessage format.
    */

src/gateway/server/GatewayWsConnection.ts

@@ -210,6 +210,8 @@ export class GatewayWsConnection {
         return this.options.gateway.readSessionMessages(frame.params as never);
       case "read_subagent_messages":
         return this.options.gateway.readSubagentMessages(frame.params as never);
+      case "fork_session":
+        return this.options.gateway.forkSession(frame.params as never);
       case "list_projects":
         return this.options.gateway.listProjects();
       case "describe_project":

src/model/protocol/canonical.ts

@@ -131,6 +131,10 @@ export type CanonicalMessageMetadata = {
   /** True for messages injected by the system (e.g. JSON self-correct prompts). */
   synthetic?: boolean;
   purpose?: string;
+  forkCarryover?: {
+    sourceSessionId: string;
+    sourceTurnId?: string;
+  };
 };
 
 export type CanonicalMessage = {

src/session/storage/SessionList.ts

@@ -20,6 +20,8 @@ export type SessionInfo = {
   cwd?: string;
   tag?: string;
   createdAt?: number;
+  parentSessionId?: string;
+  forkedFromTurnId?: string;
 };
 
 export type ListProjectSessionsOptions = {
@@ -73,6 +75,8 @@ export function parseSessionInfoFromLite(
   const customTitle = lastMetadataStringField(source, "title");
   const aiTitle = lastMetadataStringField(source, "aiTitle");
   const tag = lastMetadataStringField(source, "tag");
+  const parentSessionId = lastMetadataStringField(source, "parentSessionId");
+  const forkedFromTurnId = lastMetadataStringField(source, "forkedFromTurnId");
   const firstPrompt = firstAcceptedInputText(lite.head);
   const lastPrompt = lastAcceptedInputText(lite.tail) ?? firstPrompt;
   const summary = customTitle ?? aiTitle ?? lastPrompt;
@@ -92,6 +96,8 @@ export function parseSessionInfoFromLite(
     cwd: projectRoot,
     tag,
     createdAt: firstCreatedAt ? Date.parse(firstCreatedAt) : undefined,
+    parentSessionId,
+    forkedFromTurnId,
   };
 }
 

src/session/transcript/InMemoryTranscriptWriter.ts

@@ -4,7 +4,13 @@ import type { AgentControlBoundaryTranscriptEntry, SessionMetadataValue } from "
 import type { AgentTranscriptWriter, AgentTranscriptWriterState } from "./TranscriptWriter.js";
 
 export type InMemoryTranscriptEntry =
-  | { type: "accepted_input"; sessionId: string; turnId: string; messages: CanonicalMessage[] }
+  | {
+      type: "accepted_input";
+      sessionId: string;
+      turnId: string;
+      messages: CanonicalMessage[];
+      metadata?: Record<string, unknown>;
+    }
   | { type: "durable_message"; sessionId: string; turnId: string; message: CanonicalMessage }
   | { type: "turn_result"; sessionId: string; turnId: string; result: AgentTurnResult }
   | { type: "session_metadata"; sessionId: string; turnId: string; metadata: SessionMetadataValue }
@@ -18,8 +24,19 @@ export type InMemoryTranscriptEntry =
 export class InMemoryTranscriptWriter implements AgentTranscriptWriter {
   readonly entries: InMemoryTranscriptEntry[] = [];
 
-  recordAcceptedInput(sessionId: string, turnId: string, messages: CanonicalMessage[]): void {
-    this.entries.push({ type: "accepted_input", sessionId, turnId, messages });
+  recordAcceptedInput(
+    sessionId: string,
+    turnId: string,
+    messages: CanonicalMessage[],
+    metadata?: Record<string, unknown>,
+  ): void {
+    this.entries.push({
+      type: "accepted_input",
+      sessionId,
+      turnId,
+      messages,
+      ...(metadata && Object.keys(metadata).length > 0 ? { metadata } : {}),
+    });
   }
 
   recordDurableMessage(sessionId: string, turnId: string, message: CanonicalMessage): void {

src/session/transcript/JsonlTranscriptWriter.ts

@@ -66,11 +66,17 @@ export class JsonlTranscriptWriter implements AgentTranscriptWriter {
     };
   }
 
-  recordAcceptedInput(sessionId: string, turnId: string, messages: CanonicalMessage[]): Promise<void> {
+  recordAcceptedInput(
+    sessionId: string,
+    turnId: string,
+    messages: CanonicalMessage[],
+    metadata?: Record<string, unknown>,
+  ): Promise<void> {
     return this.recordEntry({
       type: "accepted_input",
       ...this.baseEntry(sessionId, turnId),
       messages,
+      ...(metadata && Object.keys(metadata).length > 0 ? { metadata } : {}),
     });
   }
 

src/session/transcript/TranscriptEntry.ts

@@ -25,6 +25,7 @@ export type AgentTranscriptEntryBase = {
 export type AgentAcceptedInputTranscriptEntry = AgentTranscriptEntryBase & {
   type: "accepted_input";
   messages: CanonicalMessage[];
+  metadata?: Record<string, unknown>;
 };
 
 export type AgentMessageTranscriptEntry = AgentTranscriptEntryBase & {
@@ -97,6 +98,10 @@ export type SessionMetadataValue = {
     url: string;
     repository: string;
   };
+  /** Parent session when this transcript was created via history fork. */
+  parentSessionId?: string;
+  /** Turn id of the fork point in the parent session. */
+  forkedFromTurnId?: string;
   updatedAt?: string;
 };
 

src/session/transcript/TranscriptWriter.ts

@@ -12,7 +12,12 @@ export type AgentTranscriptWriterState = {
 };
 
 export type AgentTranscriptWriter = {
-  recordAcceptedInput(sessionId: string, turnId: string, messages: CanonicalMessage[]): void | Promise<void>;
+  recordAcceptedInput(
+    sessionId: string,
+    turnId: string,
+    messages: CanonicalMessage[],
+    metadata?: Record<string, unknown>,
+  ): void | Promise<void>;
   recordDurableMessage(sessionId: string, turnId: string, message: CanonicalMessage): void | Promise<void>;
   recordTurnResult(sessionId: string, turnId: string, result: AgentTurnResult): void | Promise<void>;
   recordSessionMetadata?(sessionId: string, turnId: string, metadata: SessionMetadataValue): void | Promise<void>;

src/web/client/GatewayBrowserClient.ts

@@ -204,6 +204,15 @@ export class GatewayBrowserClient {
     );
   }
 
+  readSubagentMessages(
+    input: import("./protocol.js").WebReadSubagentMessagesInput,
+  ) {
+    return this.request<import("./protocol.js").WebReadSubagentMessagesResult>(
+      "read_subagent_messages",
+      input,
+    );
+  }
+
   listProjects(): Promise<import("./protocol.js").WebListProjectsResult> {
     return this.request<import("./protocol.js").WebListProjectsResult>("list_projects", {});
   }