u-foo 2.5.14 → 3.0.0

package/src/code/agent.js

@@ -10,8 +10,36 @@ const {
   saveSessionSnapshot,
   loadSessionSnapshot,
 } = require("./sessionStore");
-const { buildPromptContext } = require("../agents/prompts/native");
 const { buildSkillInjections } = require("./skills");
+const {
+  assembleModelContext,
+  syncMessagesToTranscript,
+  applyContextSideEffects,
+  ensureProjectSnapshot,
+  recordToolCallInSession,
+  commitAfterSegmentEnd,
+  sanitizeModelMessages,
+} = require("./context/assembler");
+const { buildLayeredSystemPrompt } = require("./context/promptLayers");
+const {
+  createProjectPreflightContextV2,
+} = require("./context/projectSnapshot");
+const {
+  ensureTaskContract,
+  ensureStateEpoch,
+  parseStructuredSideEffects,
+  patchTaskContractFromUserMessage,
+} = require("./context/stateCommit");
+const { applyWorkingSetPlan } = require("./context/workingSet");
+const {
+  normalizePlanGraphCommand,
+  runPlanGraphCommand,
+} = require("./context/planGraphService");
+const {
+  shouldFrameAsUserReminder,
+  buildContinuationUserPrompt,
+  clearUserPrompts,
+} = require("./context/userNudge");
 const {
   runUbusCommand,
   parseBusCheckOutput,
@@ -34,6 +62,164 @@ const {
   parseAgentArgs,
 } = require("./repl");
 
+function ensureContextSessionState(state = {}) {
+  if (!Array.isArray(state.workingSet)) state.workingSet = [];
+  if (!state.executionState || typeof state.executionState !== "object") {
+    const { emptyExecutionState } = require("./context/executionSegment");
+    state.executionState = emptyExecutionState();
+  }
+  if (typeof state.executionState.planMode !== "boolean") {
+    state.executionState.planMode = false;
+  }
+  if (!Array.isArray(state.executionState.pendingUserPrompts)) {
+    state.executionState.pendingUserPrompts = [];
+  }
+  if (!state.executionState.planGraph || typeof state.executionState.planGraph !== "object") {
+    state.executionState.planGraph = require("./context/planGraphService").emptyPlanGraphState();
+  }
+  require("./context/planProjection").ensurePlanUiState(state.executionState);
+  if (!state.contextPolicy || typeof state.contextPolicy !== "object") {
+    const { defaultContextPolicy } = require("./context/assembler");
+    state.contextPolicy = defaultContextPolicy();
+  }
+  if (!Number.isFinite(state.toolCallsSinceCommit)) state.toolCallsSinceCommit = 0;
+  ensureStateEpoch(state);
+  return state;
+}
+
+function buildSkillBodyBlocks(skillInjections = {}) {
+  const blocks = Array.isArray(skillInjections.blocks) ? skillInjections.blocks : [];
+  return blocks.map((block) => {
+    const text = String(block || "");
+    if (text.includes("<active_skill>")) return text;
+    return text.replace(/^<skill>/, "<active_skill>").replace(/<\/skill>/, "</active_skill>");
+  });
+}
+
+async function runPlanGraphSteps({
+  command = null,
+  segment = null,
+  workspaceRoot = process.cwd(),
+  sessionId = "",
+  state = {},
+  pushToolLog = () => null,
+} = {}) {
+  if (!state.executionState || typeof state.executionState !== "object") {
+    state.executionState = require("./context/executionSegment").emptyExecutionState();
+  }
+
+  const normalized = command
+    || (segment ? normalizePlanGraphCommand(segment) : null);
+  if (!normalized) {
+    return { ok: false, error: "missing plan_graph command" };
+  }
+
+  const result = runPlanGraphCommand(normalized, {
+    executionState: state.executionState,
+    autoAdvance: true,
+    parallel: true,
+    runTool: ({ node, args, tool, stepId }) => {
+      pushToolLog({
+        tool,
+        phase: "start",
+        args,
+        error: "",
+        origin: {
+          kind: "plan_graph",
+          graphRevision: Number(state.executionState.planGraph && state.executionState.planGraph.revision) || 0,
+          nodeId: stepId || (node && node.id) || "",
+        },
+      });
+      const { runToolCall: dispatchToolCall } = require("./dispatch");
+      const { persistToolResultToContext } = require("./context/assembler");
+      const toolResult = dispatchToolCall(
+        { tool, args },
+        { workspaceRoot, cwd: workspaceRoot, sessionId },
+      );
+      if (!toolResult || toolResult.ok === false) {
+        pushToolLog({
+          tool,
+          phase: "error",
+          args,
+          error: String((toolResult && toolResult.error) || "tool failed"),
+          origin: {
+            kind: "plan_graph",
+            nodeId: stepId || (node && node.id) || "",
+          },
+        });
+        return toolResult;
+      }
+      const persisted = persistToolResultToContext({
+        workspaceRoot,
+        sessionId,
+        tool,
+        args,
+        rawResult: toolResult,
+      });
+      recordToolCallInSession(state, persisted, workspaceRoot);
+      const plan = require("./context/workingSet").defaultContextPlanFromToolEvent(
+        tool,
+        persisted.artifactId || (persisted.modelPayload && persisted.modelPayload.artifactId),
+        args,
+      );
+      if (plan) state.workingSet = applyWorkingSetPlan(state.workingSet, plan, state);
+      if ((tool === "write" || tool === "edit") && args && args.path) {
+        const filePath = String(args.path);
+        const files = Array.isArray(state.executionState.modifiedFiles)
+          ? state.executionState.modifiedFiles.slice()
+          : [];
+        if (!files.includes(filePath)) files.push(filePath);
+        state.executionState.modifiedFiles = files;
+      }
+      return {
+        ...(persisted.modelPayload || toolResult),
+        origin: {
+          kind: "plan_graph",
+          graphRevision: Number(state.executionState.planGraph && state.executionState.planGraph.revision) || 0,
+          nodeId: stepId || (node && node.id) || "",
+        },
+      };
+    },
+  });
+
+  state.executionState = result.executionState || state.executionState;
+  commitAfterSegmentEnd(state, {
+    ok: result.status === "accepted",
+    segmentId: result.graphId || "",
+    error: result.status === "accepted" ? "" : "plan_graph rejected",
+    stoppedAt: result.stoppedAt || "",
+  }, workspaceRoot);
+  return {
+    ok: result.status === "accepted",
+    graphId: result.graphId || "",
+    error: result.status === "accepted"
+      ? ""
+      : (Array.isArray(result.errors) ? result.errors.map((e) => e.message || e.code).join("; ") : "plan_graph rejected"),
+    stoppedAt: result.stoppedAt || "",
+    modelPayload: result.modelPayload || result,
+  };
+}
+
+async function runExecutionSegmentSteps({
+  segment = {},
+  workspaceRoot = process.cwd(),
+  sessionId = "",
+  state = {},
+  pushToolLog = () => null,
+} = {}) {
+  return runPlanGraphSteps({
+    command: normalizePlanGraphCommand(segment) || normalizePlanGraphCommand({
+      type: "execution_segment",
+      ...segment,
+    }),
+    workspaceRoot,
+    sessionId,
+    state,
+    pushToolLog,
+  });
+}
+
+
 function readTextOrFile(value = "") {
   const raw = String(value || "").trim();
   if (!raw) return "";
@@ -137,14 +323,14 @@ function isCliCancelledError(message = "") {
 }
 
 function computeExtendedTimeout(baseTimeoutMs) {
-  const base = Number.isFinite(baseTimeoutMs) ? Math.max(1000, Math.floor(baseTimeoutMs)) : 300000;
-  return Math.min(1800000, Math.max(base * 2, base + 120000));
+  const base = Number.isFinite(baseTimeoutMs) ? Math.max(1000, Math.floor(baseTimeoutMs)) : 43200000;
+  return Math.min(43200000, Math.max(base * 2, base + 120000));
 }
 
 // Reasoning models routinely blew the old 10min budget across a multi-turn
-// tool loop. Total per-task budget defaults to 30min and can be raised per
+// tool loop. Total per-task budget defaults to 12h and can be raised per
 // call, via --timeout-ms, or via UFOO_UCODE_TASK_TIMEOUT_MS.
-const DEFAULT_NL_TASK_TIMEOUT_MS = 1800000;
+const DEFAULT_NL_TASK_TIMEOUT_MS = 43200000;
 
 function resolveNlTaskTimeoutMs(value) {
   if (Number.isFinite(value) && value > 0) return Math.max(1000, Math.floor(value));
@@ -190,7 +376,7 @@ function normalizeToolLogEvent(event = {}) {
   if (!event || typeof event !== "object") return null;
   const tool = String(event.tool || event.name || "").trim().toLowerCase();
   if (!tool) return null;
-  if (tool !== "read" && tool !== "write" && tool !== "edit" && tool !== "bash") return null;
+  if (tool !== "read" && tool !== "write" && tool !== "edit" && tool !== "bash" && tool !== "artifact_read") return null;
   const phase = String(event.phase || "update").trim().toLowerCase();
   const normalizedPhase = phase === "error" ? "error" : (phase === "start" ? "start" : "");
   if (!normalizedPhase) return null;
@@ -247,7 +433,7 @@ function pushSkillWarning(logs = [], onToolLog = null, warning = "") {
 
 function stripSkillBlocksFromText(value = "") {
   return String(value || "")
-    .replace(/<skill>\s*[\s\S]*?<\/skill>\s*/g, "")
+    .replace(/<(?:active_)?skill>\s*[\s\S]*?<\/(?:active_)?skill>\s*/gi, "")
     .trim();
 }
 
@@ -286,94 +472,6 @@ function isProjectAnalysisTask(task = "") {
   return /(?:analy[sz]e|analysis|review|audit|status|architecture|codebase|repo|project|现状|架构|审查|分析|项目|代码库)/i.test(text);
 }
 
-function createProjectPreflightContext({
-  workspaceRoot = process.cwd(),
-  pushToolLog = () => null,
-} = {}) {
-  const root = String(workspaceRoot || process.cwd());
-  const readCandidates = [
-    "AGENTS.md",
-    "README.md",
-    "README.zh-CN.md",
-    "package.json",
-  ];
-  const blocks = [];
-
-  for (const relPath of readCandidates) {
-    pushToolLog({
-      tool: "read",
-      phase: "start",
-      args: { path: relPath },
-      error: "",
-    });
-    const readRes = runToolCall(
-      {
-        tool: "read",
-        args: { path: relPath, maxBytes: 12000 },
-      },
-      {
-        workspaceRoot: root,
-        cwd: root,
-      }
-    );
-    pushToolLog({
-      tool: "read",
-      phase: readRes && readRes.ok === false ? "error" : "",
-      args: { path: relPath },
-      error: readRes && readRes.ok === false ? String(readRes.error || "") : "",
-    });
-    if (!readRes || readRes.ok === false) continue;
-    const content = String(readRes.content || "").trim();
-    if (!content) continue;
-    const clipped = content.length > 2400
-      ? `${content.slice(0, 2400)}\n...[truncated]`
-      : content;
-    blocks.push(`File: ${relPath}\n${clipped}`);
-    if (blocks.length >= 2) break;
-  }
-
-  if (blocks.length === 0) {
-    const command = "ls -la";
-    pushToolLog({
-      tool: "bash",
-      phase: "start",
-      args: { command },
-      error: "",
-    });
-    const bashRes = runToolCall(
-      {
-        tool: "bash",
-        args: { command, timeoutMs: 4000 },
-      },
-      {
-        workspaceRoot: root,
-        cwd: root,
-      }
-    );
-    pushToolLog({
-      tool: "bash",
-      phase: bashRes && bashRes.ok === false ? "error" : "",
-      args: { command },
-      error: bashRes && bashRes.ok === false ? String(bashRes.error || "") : "",
-    });
-    if (bashRes && bashRes.ok !== false) {
-      const stdout = String(bashRes.stdout || "").trim();
-      const clipped = stdout.length > 1200
-        ? `${stdout.slice(0, 1200)}\n...[truncated]`
-        : stdout;
-      if (clipped) {
-        blocks.push(`Command: ${command}\n${clipped}`);
-      }
-    }
-  }
-
-  if (blocks.length === 0) return "";
-  return [
-    "Preflight snapshot (captured by ucode):",
-    ...blocks.map((block) => `---\n${block}`),
-  ].join("\n");
-}
-
 function buildNlFallbackSummary(logs = []) {
   const list = Array.isArray(logs) ? logs : [];
   const started = list.filter((entry) => entry && entry.phase === "start").length;
@@ -427,28 +525,59 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
   const useDecomposition = isBugFixTask && !options.disableDecomposition;
   const analysisTask = isProjectAnalysisTask(taskText);
   const workspaceRoot = String(state.workspaceRoot || process.cwd());
-  const preflightContext = analysisTask
-    ? createProjectPreflightContext({
+  ensureContextSessionState(state);
+
+  let projectSnapshot = state.projectSnapshot || null;
+  if (analysisTask) {
+    projectSnapshot = createProjectPreflightContextV2({
       workspaceRoot,
+      sessionId: String(state.sessionId || ""),
       pushToolLog,
-    })
-    : "";
+      existingSnapshot: state.projectSnapshot,
+    });
+    state.projectSnapshot = projectSnapshot;
+  } else {
+    projectSnapshot = ensureProjectSnapshot(state, workspaceRoot);
+  }
+
+  ensureTaskContract(state, taskText);
+  if (!shouldFrameAsUserReminder(state.executionState)) {
+    state.taskContract = patchTaskContractFromUserMessage(state.taskContract, taskText);
+  }
+
   const taskPrompt = analysisTask
     ? `${taskText}\n\nAnalysis requirements:\n- Inspect repository evidence before concluding.\n- Cite concrete file observations.\n- Keep findings concise and actionable.`
     : taskText;
   const skillInjections = buildSkillInjections({
     prompt: taskPrompt,
     workspaceRoot,
+    sessionId: String(state.sessionId || ""),
+    persistBodies: true,
+    useActiveSkillTag: true,
   });
   for (const warning of skillInjections.warnings || []) {
     pushSkillWarning(logs, onToolLog, warning);
   }
-  const effectiveTaskPrompt = Array.isArray(skillInjections.blocks) && skillInjections.blocks.length > 0
-    ? `${skillInjections.blocks.join("\n\n")}\n\n${taskPrompt}`
-    : taskPrompt;
-  const systemContext = [String(state.context || "").trim(), preflightContext]
-    .filter(Boolean)
-    .join("\n\n");
+  if (Array.isArray(skillInjections.activeSkills) && skillInjections.activeSkills.length > 0) {
+    state.activeSkills = skillInjections.activeSkills;
+  }
+  const skillBodyBlocks = buildSkillBodyBlocks(skillInjections);
+  // Skill body goes into turnDynamic (system layered prompt) to avoid
+  // double injection and mixed system/user privilege semantics.
+  let effectiveTaskPrompt = taskPrompt;
+  if (shouldFrameAsUserReminder(state.executionState)) {
+    effectiveTaskPrompt = buildContinuationUserPrompt(effectiveTaskPrompt, state.executionState);
+  }
+
+  const assembled = assembleModelContext(state, {
+    workspaceRoot,
+    model,
+    provider,
+    turnDynamic: skillBodyBlocks.join("\n\n"),
+    latestUserMessage: effectiveTaskPrompt,
+  });
+  const systemContext = assembled.systemPrompt;
+  state.summary = assembled.summary || state.summary;
 
   const onStream = onDelta
     ? (delta) => {
@@ -468,20 +597,28 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
     : runNativeAgentTask;
   const onPhase = typeof options.onPhase === "function" ? options.onPhase : null;
   const onThinkingDelta = typeof options.onThinkingDelta === "function" ? options.onThinkingDelta : null;
+  let lastTranscriptBaseline = 0;
   const invokeNative = (sessionIdValue = "", timeoutOverrideMs = timeoutMs) => {
     toolEventsThisAttempt = 0;
+    const historyMessages = assembled.messages;
+    // Sanitized length matches what nativeRunner clones before appending this
+    // turn's user/tool/assistant messages — used as the transcript sync baseline.
+    lastTranscriptBaseline = sanitizeModelMessages(historyMessages).length;
     return runNativeAgentImpl({
       workspaceRoot,
       provider,
       model,
       prompt: effectiveTaskPrompt,
       systemPrompt: systemContext,
-      messages: Array.isArray(state.nlMessages) ? state.nlMessages : [],
-      sessionId: String(sessionIdValue || ""),
+      systemBlocks: assembled.systemBlocks || null,
+      messages: historyMessages,
+      sessionId: String(sessionIdValue || state.sessionId || ""),
       timeoutMs: timeoutOverrideMs,
       onStreamDelta: onStream,
       onThinkingDelta,
       onPhase,
+      executionState: state.executionState || null,
+      onArtifactPersisted: (persisted) => recordToolCallInSession(state, persisted, workspaceRoot),
       onToolEvent: (event) => {
         toolEventsThisAttempt += 1;
         pushToolLog(event);
@@ -493,6 +630,31 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
   try {
     let cliRes;
 
+    const requestedPlan = normalizePlanGraphCommand(
+      options.executionSegment || options.nextSegment || options.planGraph || null,
+    );
+    if (requestedPlan) {
+      const planResult = await runPlanGraphSteps({
+        command: requestedPlan,
+        workspaceRoot,
+        sessionId: String(state.sessionId || ""),
+        state,
+        pushToolLog,
+      });
+      if (!planResult.ok) {
+        return {
+          ok: false,
+          summary: "",
+          artifacts: [],
+          logs: logs.slice(),
+          error: planResult.error,
+          metrics: {},
+          streamed: false,
+          streamLastChar: "",
+        };
+      }
+    }
+
     // Use decomposed runner for bug fix tasks
     if (useDecomposition) {
       const decomposedResult = await runDecomposedTask({
@@ -506,6 +668,8 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
         systemPrompt: systemContext,
         messages: Array.isArray(state.nlMessages) ? state.nlMessages : [],
         sessionId: String(state.sessionId || ""),
+        state,
+        systemBlocks: assembled.systemBlocks || null,
       });
 
       if (decomposedResult.ok) {
@@ -538,6 +702,9 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
 
     if (!cliRes || cliRes.ok === false) {
       const errMsg = String((cliRes && cliRes.error) || "");
+      if (isCliCancelledError(errMsg) && state.executionState) {
+        clearUserPrompts(state.executionState);
+      }
       return {
         ok: false,
         summary: "",
@@ -553,16 +720,70 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
     if (cliRes && typeof cliRes.sessionId === "string" && cliRes.sessionId.trim()) {
       state.sessionId = cliRes.sessionId.trim();
     }
+    if (cliRes && cliRes.executionState && typeof cliRes.executionState === "object") {
+      // Preserve planMode if the runner returned a fresh empty state without it.
+      const priorPlanMode = Boolean(state.executionState && state.executionState.planMode);
+      const priorSource = state.executionState && state.executionState.planModeSource
+        ? String(state.executionState.planModeSource)
+        : "";
+      state.executionState = cliRes.executionState;
+      if (typeof state.executionState.planMode !== "boolean") {
+        state.executionState.planMode = priorPlanMode;
+      }
+      if (!state.executionState.planModeSource && priorSource) {
+        state.executionState.planModeSource = priorSource;
+      }
+    }
     if (cliRes && Array.isArray(cliRes.messages)) {
-      state.nlMessages = stripSkillBlocksFromMessages(cliRes.messages);
+      // Sync first so ensureTranscript does not migrate the just-assigned
+      // nlMessages and then append the same delta again.
+      syncMessagesToTranscript(state, cliRes.messages, workspaceRoot, {
+        baselineCount: lastTranscriptBaseline,
+      });
+      state.nlMessages = stripSkillBlocksFromMessages(
+        Array.isArray(state.nlMessages) && state.nlMessages.length > 0
+          ? state.nlMessages
+          : cliRes.messages,
+      );
     }
     const normalized = String(cliRes.output || "").trim();
+    const sideEffects = parseStructuredSideEffects(normalized);
+    if (sideEffects) {
+      applyContextSideEffects(state, sideEffects);
+      const planCommand = normalizePlanGraphCommand(sideEffects);
+      if (planCommand) {
+        await runPlanGraphSteps({
+          command: planCommand,
+          workspaceRoot,
+          sessionId: String(state.sessionId || ""),
+          state,
+          pushToolLog,
+        });
+      }
+    }
     const summary = extractJsonSummary(normalized);
     const resolvedSummary = String(summary || "").trim() || buildNlFallbackSummary(logs);
+    const artifactIds = Array.isArray(state.workingSet)
+      ? state.workingSet.map((entry) => entry.artifactId).filter(Boolean)
+      : [];
+    if (cliRes && cliRes.waitingUserInteraction) {
+      return {
+        ok: true,
+        summary: resolvedSummary || "Waiting for your reply",
+        artifacts: artifactIds,
+        logs: logs.slice(),
+        error: "",
+        metrics: {},
+        streamed: Boolean(streamed || cliRes.streamed),
+        streamLastChar,
+        waitingUserInteraction: true,
+        interactionId: cliRes.interactionId || "",
+      };
+    }
     return {
       ok: true,
       summary: resolvedSummary,
-      artifacts: [],
+      artifacts: artifactIds,
       logs: logs.slice(),
       error: "",
       metrics: {},
@@ -626,8 +847,7 @@ function buildNlContext({
     || readTextOrFile(process.env.UFOO_UCODE_PROMPT_FILE)
     || "";
 
-  // New modular prompt assembly
-  return clampContext(buildPromptContext({
+  return clampContext(resolveWireSystemPrompt({
     workspaceRoot: workspaceRoot || process.cwd(),
     model,
     provider,
@@ -635,6 +855,32 @@ function buildNlContext({
   }));
 }
 
+/**
+ * Single wire entry for system prompt assembly (layered Context Manager).
+ */
+function resolveWireSystemPrompt({
+  workspaceRoot = process.cwd(),
+  model = "",
+  provider = "",
+  appendSystemPrompt = "",
+  overrideSystemPrompt = "",
+  epochDynamic = "",
+  turnDynamic = "",
+  sessionStableExtras = "",
+} = {}) {
+  if (overrideSystemPrompt) return String(overrideSystemPrompt);
+
+  return buildLayeredSystemPrompt({
+    workspaceRoot,
+    model,
+    provider,
+    appendSystemPrompt,
+    epochDynamic,
+    turnDynamic,
+    sessionStableExtras,
+  }).flatText;
+}
+
 function buildSessionSnapshotFromState(state = {}) {
   const source = state && typeof state === "object" ? state : {};
   return {
@@ -645,6 +891,27 @@ function buildSessionSnapshotFromState(state = {}) {
     context: String(source.context || ""),
     nlMessages: Array.isArray(source.nlMessages) ? source.nlMessages : [],
     createdAt: String(source.sessionCreatedAt || "").trim(),
+    summary: String(source.summary || "").trim(),
+    projectSnapshot: source.projectSnapshot && typeof source.projectSnapshot === "object"
+      ? source.projectSnapshot
+      : null,
+    taskContract: source.taskContract && typeof source.taskContract === "object"
+      ? source.taskContract
+      : null,
+    stateEpoch: source.stateEpoch && typeof source.stateEpoch === "object"
+      ? source.stateEpoch
+      : null,
+    workingSet: Array.isArray(source.workingSet) ? source.workingSet : [],
+    executionState: source.executionState && typeof source.executionState === "object"
+      ? source.executionState
+      : null,
+    contextPolicy: source.contextPolicy && typeof source.contextPolicy === "object"
+      ? source.contextPolicy
+      : null,
+    toolCallsSinceCommit: Number.isFinite(source.toolCallsSinceCommit)
+      ? Math.max(0, Math.floor(source.toolCallsSinceCommit))
+      : 0,
+    activeSkills: Array.isArray(source.activeSkills) ? source.activeSkills : [],
   };
 }
 
@@ -708,12 +975,147 @@ function resumeSessionState(state = {}, sessionId = "", workspaceRoot = process.
   state.context = String(snapshot.context || "");
   state.nlMessages = Array.isArray(snapshot.nlMessages) ? snapshot.nlMessages : [];
   state.sessionCreatedAt = String(snapshot.createdAt || "").trim();
+  state.summary = String(snapshot.summary || "").trim();
+  state.projectSnapshot = snapshot.projectSnapshot || null;
+  state.taskContract = snapshot.taskContract || null;
+  state.stateEpoch = snapshot.stateEpoch || null;
+  state.workingSet = Array.isArray(snapshot.workingSet) ? snapshot.workingSet : [];
+  state.executionState = snapshot.executionState || null;
+  state.contextPolicy = snapshot.contextPolicy || null;
+  state.toolCallsSinceCommit = Number.isFinite(snapshot.toolCallsSinceCommit)
+    ? snapshot.toolCallsSinceCommit
+    : 0;
+  state.activeSkills = Array.isArray(snapshot.activeSkills) ? snapshot.activeSkills : [];
+  ensureContextSessionState(state);
+  const { ensureTranscript } = require("./context/assembler");
+  ensureTranscript(state, state.workspaceRoot);
+  if (Array.isArray(state.transcriptEvents) && state.transcriptEvents.length > 0) {
+    const { transcriptEventsToMessages } = require("./context/transcript");
+    state.nlMessages = transcriptEventsToMessages(state.transcriptEvents, { preferArtifact: true });
+  }
 
   return {
     ok: true,
     error: "",
     sessionId: state.sessionId,
-    restoredMessages: state.nlMessages.length,
+    restoredMessages: Array.isArray(state.nlMessages) ? state.nlMessages.length : 0,
+  };
+}
+
+/**
+ * Continue after TUI resolves approval/choice/chat.
+ * ask_user: answer is written as the deferred tool_result (contiguous, no question echo).
+ * checkpoint: short answer-only user message referencing interaction/node.
+ */
+async function resumeAfterUserInteraction(answerText = "", state = {}, options = {}) {
+  ensureContextSessionState(state);
+  const { resolveUserInteraction } = require("./context/userInteraction");
+  const { appendAnswerToolResult } = require("./nativeRunner");
+  const resolved = resolveUserInteraction(state.executionState, answerText);
+  if (!resolved.ok) {
+    return {
+      ok: false,
+      error: resolved.error || "failed to resolve user interaction",
+      code: resolved.code || "",
+      waitingUserInteraction: true,
+    };
+  }
+
+  const logs = [];
+  const pushToolLog = (event) => {
+    try {
+      logs.push(normalizeToolLogEvent(event));
+    } catch { /* ignore */ }
+  };
+
+  let messages = Array.isArray(state.nlMessages) ? state.nlMessages.slice() : [];
+  if (resolved.continueMode === "tool_result" && resolved.resume && resolved.resume.call) {
+    const appended = appendAnswerToolResult(messages, resolved.resume, resolved.answer);
+    if (!appended.ok) {
+      return { ok: false, error: appended.error || "failed to append answer tool_result" };
+    }
+  } else {
+    // Checkpoint / non-tool path: answer-only contiguous user message (no question).
+    messages.push({
+      role: "user",
+      content: JSON.stringify(resolved.answer),
+    });
+  }
+  state.nlMessages = messages;
+
+  const workspaceRoot = state.workspaceRoot || process.cwd();
+  const assembled = assembleModelContext(state, {
+    workspaceRoot,
+    provider: state.provider,
+    model: state.model,
+  });
+  const systemContext = assembled.systemPrompt || "";
+
+  let streamLastChar = "";
+  const onDelta = typeof options.onDelta === "function" ? options.onDelta : null;
+  const trackingOnDelta = onDelta
+    ? (delta) => {
+      const text = String(delta || "");
+      if (text) streamLastChar = text.slice(-1);
+      return onDelta(delta);
+    }
+    : null;
+
+  const cliRes = await runNativeAgentTask({
+    workspaceRoot,
+    provider: state.provider,
+    model: state.model,
+    prompt: "",
+    systemPrompt: systemContext,
+    systemBlocks: assembled.systemBlocks || null,
+    messages,
+    sessionId: String(state.sessionId || ""),
+    onToolEvent: pushToolLog,
+    onStreamDelta: trackingOnDelta,
+    onThinkingDelta: typeof options.onThinkingDelta === "function" ? options.onThinkingDelta : null,
+    onPhase: typeof options.onPhase === "function" ? options.onPhase : null,
+    executionState: state.executionState,
+    signal: options.signal,
+    resume: true,
+  });
+
+  if (cliRes && cliRes.executionState) {
+    state.executionState = cliRes.executionState;
+  }
+  if (cliRes && Array.isArray(cliRes.messages)) {
+    state.nlMessages = stripSkillBlocksFromMessages(cliRes.messages);
+  }
+
+  if (!cliRes || cliRes.ok === false) {
+    return {
+      ok: false,
+      error: (cliRes && cliRes.error) || "resume failed",
+      logs,
+      waitingUserInteraction: false,
+      streamed: false,
+      streamLastChar: "",
+    };
+  }
+
+  if (cliRes.waitingUserInteraction) {
+    return {
+      ok: true,
+      summary: "Waiting for your reply",
+      logs,
+      waitingUserInteraction: true,
+      interactionId: cliRes.interactionId || "",
+      streamed: Boolean(cliRes.streamed),
+      streamLastChar,
+    };
+  }
+
+  return {
+    ok: true,
+    summary: String(cliRes.output || "").trim() || "continued",
+    logs,
+    waitingUserInteraction: false,
+    streamed: Boolean(cliRes.streamed),
+    streamLastChar,
   };
 }
 
@@ -721,12 +1123,15 @@ module.exports = {
   runUcodeCoreAgent,
   runSingleCommand,
   runNaturalLanguageTask,
+  resumeAfterUserInteraction,
   formatNlResult,
   normalizeToolLogEvent,
   isProjectAnalysisTask,
   buildNlFallbackSummary,
   buildNlContext,
+  resolveWireSystemPrompt,
   stripSkillBlocksFromMessages,
+  stripSkillBlocksFromText,
   resolvePlannerProvider,
   extractJsonSummary,
   enrichNativeError,