minimal-agent 0.11.0 → 0.12.0

package/src/tools/worktree/sessionWorktree.ts

@@ -0,0 +1,158 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import type { SessionState } from '../../session/sessionState.js';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { join } from 'node:path';
+import {
+  readRuntimeJson,
+  sessionRuntimeDir,
+  writeRuntimeJson,
+} from '../../session/runtimeStore.js';
+import {
+  applyAgentWorktree,
+  commitWorktreeChanges,
+  createAgentWorktree,
+  hasWorktreeChanges,
+  removeAgentWorktree,
+} from '../agent/worktree.js';
+
+const enterSchema = z.object({
+  name: z
+    .string()
+    .regex(/^[a-zA-Z0-9._-]{1,48}$/)
+    .optional(),
+});
+const exitSchema = z.object({ action: z.enum(['apply', 'keep', 'discard']) });
+async function persist(
+  ctx: ToolCallContext,
+  state: SessionState['activeWorktree'],
+) {
+  await writeRuntimeJson(join(sessionRuntimeDir(ctx), 'worktree.json'), {
+    active: state ?? null,
+  });
+}
+export async function hydrateSessionWorktree(
+  ctx: ToolCallContext,
+): Promise<void> {
+  if (!ctx.sessionState || ctx.sessionState.activeWorktree) return;
+  const saved = await readRuntimeJson<{
+    active?: NonNullable<SessionState['activeWorktree']> | null;
+  }>(join(sessionRuntimeDir(ctx), 'worktree.json'), {});
+  if (saved.active) ctx.sessionState.activeWorktree = saved.active;
+}
+async function enter(
+  input: z.infer<typeof enterSchema>,
+  ctx: ToolCallContext,
+): Promise<ToolResult> {
+  const state = ctx.sessionState;
+  if (!state) return { ok: false, error: 'EnterWorktree 需要会话状态' };
+  if (state.activeWorktree)
+    return {
+      ok: true,
+      content: `当前已在 worktree ${state.activeWorktree.path}`,
+    };
+  const slug = `session-${input.name ?? randomUUID().slice(0, 8)}`;
+  const wt = await createAgentWorktree(slug, ctx.cwd);
+  if (!wt.ok) return wt;
+  state.activeWorktree = {
+    id: slug,
+    path: wt.path,
+    branch: wt.branch,
+    baseSha: wt.baseSha,
+    gitRoot: wt.gitRoot,
+  };
+  await persist(ctx, state.activeWorktree);
+  return {
+    ok: true,
+    content: `已进入主 Agent 隔离 worktree：${wt.path}\n分支：${wt.branch}\n后续工具调用立即使用该目录。`,
+  };
+}
+async function exit(
+  input: z.infer<typeof exitSchema>,
+  ctx: ToolCallContext,
+): Promise<ToolResult> {
+  const state = ctx.sessionState,
+    wt = state?.activeWorktree;
+  if (!state || !wt) return { ok: false, error: '当前会话没有活动 worktree' };
+  if (input.action === 'keep') {
+    state.activeWorktree = undefined;
+    await persist(ctx, undefined);
+    return {
+      ok: true,
+      content: `已退出有效 cwd，但保留 worktree：${wt.path}\n分支：${wt.branch}`,
+    };
+  }
+  const changed = await hasWorktreeChanges(wt.path, wt.baseSha);
+  if (input.action === 'discard' && changed) {
+    const committed = await commitWorktreeChanges(
+      wt.path,
+      `archive: preserve discarded session ${wt.id}`,
+    );
+    if (committed.ok) {
+      state.activeWorktree = undefined;
+      await persist(ctx, undefined);
+    }
+    return committed.ok
+      ? {
+          ok: true,
+          content: `检测到成果，未永久删除。已归档到分支 ${wt.branch}，worktree 保留在 ${wt.path}。`,
+        }
+      : {
+          ok: false,
+          error: `无法安全归档，worktree 保持活动：${committed.error}`,
+        };
+  }
+  if (input.action === 'discard') {
+    await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+    state.activeWorktree = undefined;
+    await persist(ctx, undefined);
+    return {
+      ok: true,
+      content: 'worktree 无改动，已通过 Git worktree 管理安全清理。',
+    };
+  }
+  const committed = await commitWorktreeChanges(
+    wt.path,
+    `minimal-agent: apply session ${wt.id}`,
+  );
+  if (!committed.ok)
+    return {
+      ok: false,
+      error: `提交隔离改动失败，worktree 保持活动：${committed.error}`,
+    };
+  const applied = await applyAgentWorktree(wt.gitRoot, wt.id);
+  if (!applied.ok)
+    return {
+      ok: false,
+      error: `应用检查失败，worktree 保持活动：${applied.error}`,
+    };
+  state.activeWorktree = undefined;
+  await persist(ctx, undefined);
+  return {
+    ok: true,
+    content: `已通过 git apply --check 并将变更应用到原工作区；未自动提交。`,
+  };
+}
+export const enterWorktreeTool: Tool<z.infer<typeof enterSchema>> = {
+  name: 'EnterWorktree',
+  description:
+    'Creates and enters a session-scoped Git worktree for the main Agent. Later tool calls use it immediately while project memory keeps the original workspace identity.',
+  inputSchema: enterSchema,
+  parameters: toToolParameters(enterSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  call: async () => ({ ok: false, error: 'requires session context' }),
+  callWithContext: (i, _s, c) => enter(i, c),
+};
+export const exitWorktreeTool: Tool<z.infer<typeof exitSchema>> = {
+  name: 'ExitWorktree',
+  description:
+    'Leaves the current session worktree. apply checks and applies its patch to the original workspace; keep preserves it; discard never destroys uncommitted results and archives changed work.',
+  inputSchema: exitSchema,
+  parameters: toToolParameters(exitSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  call: async () => ({ ok: false, error: 'requires session context' }),
+  callWithContext: (i, _s, c) => exit(i, c),
+};

package/src/tools/write/write.js

@@ -22,6 +22,7 @@ import { filePathField } from '../shared/schemas.js';
 import { assertFresh, hashFileBytes, recordRead } from '../shared/fileState.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
 import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 /** 写入内容上限：1GB。防止模型试图写入超大内容撑爆内存/磁盘。 */
 const MAX_WRITE_SIZE_BYTES = 1024 * 1024 * 1024;
 // ---------------- 1. Zod 输入 schema ----------------
@@ -69,9 +70,11 @@ async function call(input, state, cwd) {
             catch { }
         }
         let contentToWrite = input.content;
+        let originalContent = '';
         let bomEncoding = 'utf8';
         if (fileExisted) {
             const snapshot = await readTextFile(filePath);
+            originalContent = snapshot.content;
             bomEncoding = snapshot.encoding;
             contentToWrite = applyLineEnding(input.content, snapshot.lineEnding);
         }
@@ -88,10 +91,11 @@ async function call(input, state, cwd) {
         const bomInfo = bomEncoding === 'utf8-bom'
             ? '，已保留 UTF-8 BOM'
             : bomEncoding === 'utf16le' ? '，已保留 UTF-16 LE' : '';
+        const patch = buildPatchSummary(originalContent, contentToWrite, input.file_path);
         return {
             ok: true,
-            content: `${action} ${filePath}${sizeInfo}${bomInfo}`,
-            metadata: await fileActivityMetadata(filePath, fileExisted ? 'modified' : 'created', 'not_run', 'support', cwd),
+            content: `${action} ${filePath}${sizeInfo}${bomInfo}\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+            metadata: await fileActivityMetadata(filePath, fileExisted ? 'modified' : 'created', 'not_run', 'support', cwd, patch),
         };
     }
     catch (e) {

package/src/tools/write/write.ts

@@ -31,6 +31,7 @@ import { filePathField } from '../shared/schemas.js';
 import { assertFresh, hashFileBytes, recordRead, type FileReadState } from '../shared/fileState.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
 import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 
 /** 写入内容上限：1GB。防止模型试图写入超大内容撑爆内存/磁盘。 */
 const MAX_WRITE_SIZE_BYTES = 1024 * 1024 * 1024;
@@ -86,9 +87,11 @@ async function call(input: WriteInput, state?: FileReadState, cwd?: string): Pro
     }
 
     let contentToWrite = input.content;
+    let originalContent = '';
     let bomEncoding: Awaited<ReturnType<typeof readTextFile>>['encoding'] = 'utf8';
     if (fileExisted) {
       const snapshot = await readTextFile(filePath);
+      originalContent = snapshot.content;
       bomEncoding = snapshot.encoding;
       contentToWrite = applyLineEnding(input.content, snapshot.lineEnding);
     }
@@ -106,11 +109,12 @@ async function call(input: WriteInput, state?: FileReadState, cwd?: string): Pro
     const bomInfo = bomEncoding === 'utf8-bom'
       ? '，已保留 UTF-8 BOM'
       : bomEncoding === 'utf16le' ? '，已保留 UTF-16 LE' : '';
+    const patch = buildPatchSummary(originalContent, contentToWrite, input.file_path);
 
     return {
       ok: true,
-      content: `${action} ${filePath}${sizeInfo}${bomInfo}`,
-      metadata: await fileActivityMetadata(filePath, fileExisted ? 'modified' : 'created', 'not_run', 'support', cwd),
+      content: `${action} ${filePath}${sizeInfo}${bomInfo}\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+      metadata: await fileActivityMetadata(filePath, fileExisted ? 'modified' : 'created', 'not_run', 'support', cwd, patch),
     };
   } catch (e) {
     return { ok: false, error: `写入失败：${(e as Error).message}` };

package/src/types.ts

@@ -191,6 +191,8 @@ export interface AgentResultMetadata {
   kind: 'agent';
   agentType: 'explore' | 'general';
   description: string;
+  agentId?: string;
+  status?: 'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
   isolation: 'none' | 'worktree';
   turns: number;
   toolCalls: number;
@@ -214,6 +216,15 @@ export interface AgentResultMetadata {
 export type FileActivityKind = 'read' | 'created' | 'modified' | 'generated' | 'deleted';
 export type FileVerification = 'passed' | 'failed' | 'not_run';
 export type ConversationFilePurpose = 'source' | 'deliverable' | 'support';
+export interface FilePatchSummary {
+  unifiedDiff?: string;
+  beforeHash?: string;
+  afterHash: string;
+  additions: number;
+  deletions: number;
+  truncated: boolean;
+  omittedReason?: 'too_large';
+}
 
 /** Structured local file output. Paths are always workspace-relative. */
 export interface FileActivityMetadata {
@@ -225,6 +236,7 @@ export interface FileActivityMetadata {
     mime?: string;
     verification: FileVerification;
     purpose: ConversationFilePurpose;
+    patch?: FilePatchSummary;
   }>;
 }
 

package/src/ui/hooks/useChat.js

@@ -27,6 +27,7 @@ import { resolveSessionFile, sessionFileFor, } from '../../context/sessionPath.j
 import { buildBaseSystemPrompt, buildTransientPromptBundle } from '../../prompts/system.js';
 import { createPromptCacheContext } from '../../llm/promptCache.js';
 import { createAgentRuntimeContext, filterToolsForRuntime, memoryContextFromRuntime, } from '../../runtime/agentRuntimeContext.js';
+import { startTurnJournal } from '../../memory/turnJournal.js';
 import { ALL_TOOLS, getToolByName } from '../../tools/index.js';
 import { createInputQueue } from '../../messageQueue.js';
 import { createAskCoordinator, setAskHandler, } from '../../askBridge.js';
@@ -34,6 +35,7 @@ import { createAskSlot } from './askSlot.js';
 import { figures } from '../figures.js';
 import { clearFileState } from '../../tools/shared/fileState.js';
 import { getOrCreateSessionState, sessionStateKey } from '../../session/sessionState.js';
+import { hydrateSessionWorktree } from '../../tools/worktree/sessionWorktree.js';
 import { runAdvisor } from '../../tools/advisor/advisor.js';
 import { runWithPlugins } from '../../plugins/pluginRunner.js';
 import { dlog } from '../../utils/debugLog.js';
@@ -394,6 +396,8 @@ export function useChat(args) {
         const ac = new AbortController();
         abortRef.current = ac;
         let releaseContextLock = null;
+        let turnJournal = null;
+        let turnJournalStart = 0;
         dlog('ui', 'turn START', { input: trimmed.slice(0, 80) });
         // 长时间运行时（如工作流 agent 步骤）的定时 token 刷新：
         // runQuery 的 text/reasoning 事件不触发 bump，导致 StatusLine token 数
@@ -441,10 +445,20 @@ export function useChat(args) {
                 })
                 : undefined;
             const toolGate = computerRun ? createComputerUseHostGate(computerRun) : undefined;
+            const turnSessionState = getOrCreateSessionState(sessionStateKey({
+                surface: 'tui', workspaceId: workspace?.id,
+                cwd: workspace?.id ? undefined : getWorkingDir(),
+                sessionId: activeSessionIdRef.current,
+            }));
+            await hydrateSessionWorktree({
+                sessionState: turnSessionState, workspaceId: workspace?.id,
+                sessionId: activeSessionIdRef.current, cwd: getWorkingDir(),
+            });
+            const effectiveCwd = turnSessionState.activeWorktree?.path ?? getWorkingDir();
             const runtimeContext = createAgentRuntimeContext({
                 surface: 'tui',
                 profile: 'main',
-                cwd: getWorkingDir(),
+                cwd: effectiveCwd,
                 workspaceId: workspace?.id,
                 sessionId: activeSessionIdRef.current,
                 owner: 'local-owner',
@@ -455,9 +469,9 @@ export function useChat(args) {
                 toolGate,
             });
             const turnTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
-            const toolSignature = turnTools.map((tool) => tool.name).join(',');
+            const toolSignature = `${effectiveCwd}\0${turnTools.map((tool) => tool.name).join(',')}`;
             if (promptToolSignatureRef.current !== toolSignature) {
-                const stablePrompt = await buildBaseSystemPrompt(getWorkingDir(), turnTools);
+                const stablePrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
                 const rest = historyRef.current[0]?.role === 'system'
                     ? historyRef.current.slice(1)
                     : [...historyRef.current];
@@ -467,30 +481,33 @@ export function useChat(args) {
             }
             // 每回合只刷新易变层；稳定层仅在实际能力目录变化时重建。
             const turnTransient = await buildTransientPromptBundle({
-                cwd: getWorkingDir(),
+                cwd: effectiveCwd,
                 tools: turnTools,
                 runtime: {
                     surface: 'tui',
-                    cwd: getWorkingDir(),
+                    cwd: effectiveCwd,
                     currentUserInput: trimmed,
                     workspaceId: workspace?.id,
+                    sessionId: activeSessionIdRef.current,
                     interactiveAsk: true,
                     supervisedBrowser: false,
                     memoryAccess: 'read-write',
                 },
             }).catch(() => undefined);
+            // 会话原文记账（与 session/runTurn.ts 共用同一份实现）。
+            // TUI 不经过 runTurn，此前整条路径都不入库，SearchConversations 对 TUI 用户静默失效。
+            turnJournalStart = historyRef.current.length;
+            turnJournal = await startTurnJournal({
+                memoryContext: memoryContextFromRuntime(runtimeContext),
+                userInput: trimmed,
+            }).catch(() => null);
             for await (const ev of runWithPlugins(trimmed, {
                 provider: providerRef.current,
                 history: historyRef.current,
                 signal: ac.signal,
                 runtimeContext,
                 allowedTools: turnTools.map((tool) => tool.name),
-                sessionState: getOrCreateSessionState(sessionStateKey({
-                    surface: 'tui',
-                    workspaceId: workspace?.id,
-                    cwd: workspace?.id ? undefined : getWorkingDir(),
-                    sessionId: activeSessionIdRef.current,
-                })),
+                sessionState: turnSessionState,
                 parseInlineImages: true,
                 ...(turnTransient ? { transientBundle: turnTransient } : {}),
                 promptCache: createPromptCacheContext(`workspace:${workspace?.id ?? getWorkingDir()}:session:${activeSessionIdRef.current}`),
@@ -558,6 +575,9 @@ export function useChat(args) {
             }
             activeComputerRunRef.current = null;
             runningToolsRef.current.clear();
+            // 记账失败不影响落盘与解锁（它是附加能力，不是功能）。
+            await turnJournal?.finish(historyRef.current, turnJournalStart).catch(() => undefined);
+            turnJournal = null;
             // v2 multi-session：持久化到当前 active session 文件。
             try {
                 await saveContext(historyRef.current, sessionFileFor(getWorkingDir(), activeSessionIdRef.current));

package/src/ui/hooks/useChat.ts

@@ -45,6 +45,7 @@ import {
   filterToolsForRuntime,
   memoryContextFromRuntime,
 } from '../../runtime/agentRuntimeContext.js';
+import { startTurnJournal, type TurnJournal } from '../../memory/turnJournal.js';
 import { ALL_TOOLS, getToolByName } from '../../tools/index.js';
 import { createInputQueue } from '../../messageQueue.js';
 import {
@@ -58,6 +59,7 @@ import { createAskSlot } from './askSlot.js';
 import { figures } from '../figures.js';
 import { clearFileState } from '../../tools/shared/fileState.js';
 import { getOrCreateSessionState, sessionStateKey } from '../../session/sessionState.js';
+import { hydrateSessionWorktree } from '../../tools/worktree/sessionWorktree.js';
 import type {
   LoopEvent,
   Message,
@@ -627,6 +629,8 @@ export function useChat(args: {
       const ac = new AbortController();
       abortRef.current = ac;
       let releaseContextLock: (() => Promise<void>) | null = null;
+      let turnJournal: TurnJournal | null = null;
+      let turnJournalStart = 0;
       dlog('ui', 'turn START', { input: trimmed.slice(0, 80) });
 
       // 长时间运行时（如工作流 agent 步骤）的定时 token 刷新：
@@ -681,10 +685,20 @@ export function useChat(args: {
             })
           : undefined;
         const toolGate = computerRun ? createComputerUseHostGate(computerRun) : undefined;
+        const turnSessionState = getOrCreateSessionState(sessionStateKey({
+          surface: 'tui', workspaceId: workspace?.id,
+          cwd: workspace?.id ? undefined : getWorkingDir(),
+          sessionId: activeSessionIdRef.current,
+        }));
+        await hydrateSessionWorktree({
+          sessionState: turnSessionState, workspaceId: workspace?.id,
+          sessionId: activeSessionIdRef.current, cwd: getWorkingDir(),
+        });
+        const effectiveCwd = turnSessionState.activeWorktree?.path ?? getWorkingDir();
         const runtimeContext = createAgentRuntimeContext({
           surface: 'tui',
           profile: 'main',
-          cwd: getWorkingDir(),
+          cwd: effectiveCwd,
           workspaceId: workspace?.id,
           sessionId: activeSessionIdRef.current,
           owner: 'local-owner',
@@ -695,9 +709,9 @@ export function useChat(args: {
           toolGate,
         });
         const turnTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
-        const toolSignature = turnTools.map((tool) => tool.name).join(',');
+        const toolSignature = `${effectiveCwd}\0${turnTools.map((tool) => tool.name).join(',')}`;
         if (promptToolSignatureRef.current !== toolSignature) {
-          const stablePrompt = await buildBaseSystemPrompt(getWorkingDir(), turnTools);
+          const stablePrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
           const rest = historyRef.current[0]?.role === 'system'
             ? historyRef.current.slice(1)
             : [...historyRef.current];
@@ -707,32 +721,33 @@ export function useChat(args: {
         }
         // 每回合只刷新易变层；稳定层仅在实际能力目录变化时重建。
         const turnTransient = await buildTransientPromptBundle({
-          cwd: getWorkingDir(),
+          cwd: effectiveCwd,
           tools: turnTools,
           runtime: {
             surface: 'tui',
-            cwd: getWorkingDir(),
+            cwd: effectiveCwd,
             currentUserInput: trimmed,
             workspaceId: workspace?.id,
+            sessionId: activeSessionIdRef.current,
             interactiveAsk: true,
             supervisedBrowser: false,
             memoryAccess: 'read-write',
           },
         }).catch(() => undefined);
+        // 会话原文记账（与 session/runTurn.ts 共用同一份实现）。
+        // TUI 不经过 runTurn，此前整条路径都不入库，SearchConversations 对 TUI 用户静默失效。
+        turnJournalStart = historyRef.current.length;
+        turnJournal = await startTurnJournal({
+          memoryContext: memoryContextFromRuntime(runtimeContext),
+          userInput: trimmed,
+        }).catch(() => null);
         for await (const ev of runWithPlugins(trimmed, {
           provider: providerRef.current,
           history: historyRef.current,
           signal: ac.signal,
           runtimeContext,
           allowedTools: turnTools.map((tool) => tool.name),
-          sessionState: getOrCreateSessionState(
-            sessionStateKey({
-              surface: 'tui',
-              workspaceId: workspace?.id,
-              cwd: workspace?.id ? undefined : getWorkingDir(),
-              sessionId: activeSessionIdRef.current,
-            }),
-          ),
+          sessionState: turnSessionState,
           parseInlineImages: true,
           ...(turnTransient ? { transientBundle: turnTransient } : {}),
           promptCache: createPromptCacheContext(
@@ -800,6 +815,9 @@ export function useChat(args: {
         }
         activeComputerRunRef.current = null;
         runningToolsRef.current.clear();
+        // 记账失败不影响落盘与解锁（它是附加能力，不是功能）。
+        await turnJournal?.finish(historyRef.current, turnJournalStart).catch(() => undefined);
+        turnJournal = null;
         // v2 multi-session：持久化到当前 active session 文件。
         try {
           await saveContext(historyRef.current, sessionFileFor(getWorkingDir(), activeSessionIdRef.current));

package/src/web/protocol.ts

@@ -19,7 +19,7 @@
 
 import type { AskAnswer, AskOption, AskQuestionSpec, AskSource } from '../askBridge.js';
 import type { PluginEvent } from '../plugins/pluginApi.js';
-import type { AgentResultMetadata, ConversationFilePurpose, FileActivityMetadata, LoopEvent, Message, MessageAttachmentRef, MessageBrowserReference, ProgressStage, SubagentProgress, ToolCall, ToolProgressDetail, ToolResultMetadata } from '../types.js';
+import type { AgentResultMetadata, ConversationFilePurpose, DeliverableManifest, FileActivityMetadata, LoopEvent, Message, MessageAttachmentRef, MessageBrowserReference, ProgressStage, SubagentProgress, ToolCall, ToolProgressDetail, ToolResultMetadata } from '../types.js';
 import type { ConversationSearchResult, MemoryCategory, MemoryDiagnostic, MemoryEditablePatch, MemoryRecord, MemorySettings, MemoryUpdate, PersonaDocument } from '../memory/memoryService.js';
 import type { HumanInterventionReason } from '../humanIntervention.js';
 
@@ -1067,7 +1067,7 @@ export interface GroupMessageAttachment {
   size: number;
 }
 
-export type ConversationFileKind = 'workspace-file' | 'group-attachment' | 'agent-file';
+export type ConversationFileKind = 'workspace-file' | 'user-attachment' | 'group-attachment' | 'agent-file';
 export type ConversationFileActivity = 'referenced' | 'read' | 'created' | 'modified' | 'generated' | 'deleted';
 
 /** Safe metadata an Agent Node may publish to a group. Absolute paths and file bytes are forbidden. */
@@ -1105,6 +1105,65 @@ export interface ConversationFileRef {
   sha256?: string;
   modifiedAt?: number;
   contentChanged?: boolean;
+  originalAvailable?: boolean;
+  archivedAvailable?: boolean;
+  previewSource?: 'original' | 'archive' | 'upload';
+}
+
+/** A durable, turn-scoped formal delivery. File refs are resolved at read time. */
+export interface ConversationDelivery {
+  id: string;
+  turnId: string;
+  toolCallId?: string;
+  createdAt: number;
+  manifest: DeliverableManifest;
+  resolvedFiles: ConversationFileRef[];
+}
+
+/** Durable user-supplied and formally delivered artifacts for one user turn. */
+export interface ConversationArtifactGroup {
+  turnId: string;
+  createdAt: number;
+  compacted: boolean;
+  userAttachments: MessageAttachmentRef[];
+  deliveries: ConversationDelivery[];
+}
+
+export type ConversationAssetCategory = 'document' | 'code' | 'image' | 'link' | 'other';
+export type ConversationAssetOrigin = 'user-upload' | 'user-reference' | 'ai-delivery';
+export type ConversationAssetKind = 'workspace-file' | 'user-attachment' | 'web-link';
+
+/** A durable, session-scoped item explicitly supplied by the user or formally delivered by the Agent. */
+export interface ConversationAsset {
+  id: string;
+  conversationKey: string;
+  kind: ConversationAssetKind;
+  category: ConversationAssetCategory;
+  name: string;
+  origins: ConversationAssetOrigin[];
+  firstTurnId: string;
+  lastTurnId: string;
+  firstSeenAt: number;
+  lastSeenAt: number;
+  pinned: boolean;
+  available: boolean;
+  previewable: boolean;
+  relativePath?: string;
+  url?: string;
+  domain?: string;
+  mime?: string;
+  size?: number;
+  previewUrl?: string;
+  verification?: import('../types.js').FileVerification;
+  sha256?: string;
+  modifiedAt?: number;
+  contentChanged?: boolean;
+  /** The original workspace file still exists at its submitted path. */
+  originalAvailable?: boolean;
+  /** An immutable, content-addressed copy of the submitted file is available. */
+  archivedAvailable?: boolean;
+  /** Which bytes are opened by the default preview action. */
+  previewSource?: 'original' | 'archive' | 'upload';
 }
 
 export interface GroupChatMessage {
@@ -1244,8 +1303,13 @@ export type ClientFrame =
   | { t: 'plain/rename'; sessionId: string; title: string }
   | { t: 'plain/delete'; sessionId: string }
   | { t: 'resource/files/list'; dir: string; sessionId: string }
+  | { t: 'resource/assets/list'; requestId: string; target: ConversationTarget & { sessionId: string } }
+  | { t: 'resource/assets/pin'; requestId: string; target: ConversationTarget & { sessionId: string }; assetId: string; pinned: boolean }
+  | { t: 'resource/assets/open'; requestId: string; target: ConversationTarget & { sessionId: string }; assetId: string; source?: 'default' | 'original' | 'archive' }
+  | { t: 'resource/assets/reveal'; requestId: string; target: ConversationTarget & { sessionId: string }; assetId: string; source?: 'original' | 'archive' }
+  | { t: 'resource/files/open'; requestId: string; target: ConversationTarget & { sessionId: string }; relativePath: string }
   | { t: 'resource/files/pin'; dir: string; sessionId: string; relativePath: string; pinned: boolean }
-  | { t: 'resource/files/reveal'; dir: string; relativePath: string }
+  | { t: 'resource/files/reveal'; requestId?: string; dir?: string; target?: ConversationTarget & { sessionId: string }; relativePath: string }
   | { t: 'resource/memories/list'; workspaceId?: string; query?: string }
   | { t: 'resource/memories/settings/update'; autoRemember: boolean; workspaceId?: string }
   | { t: 'resource/memories/update'; id: string; scope: 'personal' | 'workspace'; expectedVersion: string; patch: MemoryUpdate; workspaceId?: string }
@@ -1519,10 +1583,21 @@ export type ServerFrame =
       conversationKey: string;
       historyRevision: string;
       messages: Message[];
+      deliveries?: ConversationDelivery[];
+      assets?: ConversationAsset[];
+      artifactGroups?: ConversationArtifactGroup[];
       runSnapshot?: ConversationRunSnapshot;
       contextUsage?: Extract<LoopEvent, { type: 'context_usage' }>;
     }
+  | { t: 'conversation/delivery/changed'; conversationKey: string; delivery: ConversationDelivery }
+  | { t: 'conversation/assets/changed'; conversationKey: string; assets: ConversationAsset[] }
   | { t: 'resource/files/list'; dir: string; sessionId: string; files: ConversationFileRef[] }
+  | { t: 'resource/assets/list'; requestId: string; conversationKey: string; assets?: ConversationAsset[]; error?: string }
+  | { t: 'resource/assets/pinned'; requestId: string; ok: boolean; error?: string }
+  | { t: 'resource/assets/opened'; requestId: string; ref?: ConversationFileRef; error?: string }
+  | { t: 'resource/assets/revealed'; requestId: string; ok: boolean; error?: string }
+  | { t: 'resource/files/opened'; requestId: string; ref?: ConversationFileRef; error?: string }
+  | { t: 'resource/files/revealed'; requestId: string; ok: boolean; error?: string }
   | { t: 'resource/memories'; records: MemoryRecord[]; settings: MemorySettings; workspaceId?: string; reviewRecords?: MemoryRecord[]; persona?: PersonaDocument | null }
   | { t: 'resource/memories/conversations'; requestId: string; results: ConversationSearchResult[]; error?: string }
   | { t: 'resource/memories/manage/state'; requestId: string; state: MemoryManagementState }