Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(session): fork conversations from a historical user message (#3304)
nullptr-error42e61639819d
diff --git a/docker/Dockerfile.sandbox b/docker/Dockerfile.sandboxindex a0c7dba3c..6b66c4628 100644--- a/docker/Dockerfile.sandbox+++ b/docker/Dockerfile.sandbox@@ -56,7 +56,8 @@ RUN npm install -g pnpm# image). `file` is not in slim; models reach for it after a script-type error.# curl is not optional: the sandbox connectivity check probes egress with it,# and skills that fetch a URL expect it to be there. The compression tools are-# here because skill bundles and their assets arrive archived.+# here because skill bundles and their assets arrive archived. git backs the+# per-turn /workspace checkpoints that session fork rolls back to.RUN apt-get update && apt-get install -y --no-install-recommends \jq \curl \@@ -67,6 +68,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \bzip2 \xz-utils \zstd \+ git \&& rm -rf /var/lib/apt/lists/* /var/cache/apt/*# Add packages here when installed skills actually need them:diff --git a/frontend/src/api/chat/index.ts b/frontend/src/api/chat/index.tsindex 0fb4b5f8d..31322c43c 100644--- a/frontend/src/api/chat/index.ts+++ b/frontend/src/api/chat/index.ts@@ -30,6 +30,13 @@ export async function updateSession(session_id: string, data: { title: string; dreturn put(`/api/v1/sessions/${session_id}`, data);}+export async function forkSession(+ session_id: string,+ data: { message_id: string; title?: string },+) {+ return post(`/api/v1/sessions/${session_id}/fork`, data, { timeout: 180000 });+}+export async function knowledgeChat(data: { session_id: string; query: string; }) {return postChat(`/api/v1/knowledge-chat/${data.session_id}`, { query: data.query, channel: "web" });}diff --git a/frontend/src/components/Input-field.vue b/frontend/src/components/Input-field.vueindex 32e8ff2e0..8464b8a26 100644--- a/frontend/src/components/Input-field.vue+++ b/frontend/src/components/Input-field.vue@@ -2614,6 +2614,14 @@ defineExpose({if (!text.trim()) return;query.value = text;nextTick(() => createSession(text));+ },+ /**+ * Puts text in the composer WITHOUT sending it. Session fork uses this so+ * the user lands on the branch with the original question ready to edit —+ * the whole point of branching at a user message.+ */+ prefill(text: string) {+ query.value = text;}});diff --git a/frontend/src/components/SessionSidebarRow.vue b/frontend/src/components/SessionSidebarRow.vueindex 451c5cdbd..dd93b8257 100644--- a/frontend/src/components/SessionSidebarRow.vue+++ b/frontend/src/components/SessionSidebarRow.vue@@ -14,6 +14,9 @@</form><span v-else class="submenu_title" :class="batchMode ? 'submenu_title--batch' : ''" :title="item.title"><t-icon v-if="item.is_pinned" name="pin" class="submenu_pin_icon" />+ <t-tooltip v-if="item.parent_session_id" content="由其他会话分叉而来">+ <t-icon name="git-branch" class="submenu_fork_icon" />+ </t-tooltip><span class="submenu_title-text">{{ item.title }}</span><span v-if="apiOwnerTag" class="session-owner-tag" :class="`session-owner-tag--${apiOwnerTag.kind}`":title="apiOwnerTag.full">{{ apiOwnerTag.label }}</span>@@ -77,7 +80,7 @@ interface SessionMenuOption {type MenuMode = 'menu' | 'clear' | 'delete'const props = defineProps<{- item: { id: string; path: string; title: string; is_pinned?: boolean; user_id?: string }+ item: { id: string; path: string; title: string; is_pinned?: boolean; user_id?: string; parent_session_id?: string }batchMode: booleanactivePath: stringselectedIds: string[]diff --git a/frontend/src/components/menu.vue b/frontend/src/components/menu.vueindex 5e4ab884d..40b966612 100644--- a/frontend/src/components/menu.vue+++ b/frontend/src/components/menu.vue@@ -699,6 +699,7 @@ const mapSessionRow = (item: any) => ({im_platform: item.im_platform || '',description: item.description || '',user_id: item.user_id || '',+ parent_session_id: item.parent_session_id || '',});const syncMenuStoreFromBuckets = () => {@@ -720,6 +721,7 @@ const menuChildToSessionRow = (item: Record<string, unknown>): SessionForGroupinim_platform: typeof item.im_platform === 'string' ? item.im_platform : '',description: typeof item.description === 'string' ? item.description : '',user_id: typeof item.user_id === 'string' ? item.user_id : '',+ parent_session_id: typeof item.parent_session_id === 'string' ? item.parent_session_id : '',};};@@ -1501,6 +1503,14 @@ const onDragHandleMouseDown = (e: MouseEvent) => {flex-shrink: 0;}+ :deep(.submenu_fork_icon) {+ color: inherit;+ font-size: 12px;+ margin-right: 4px;+ vertical-align: middle;+ flex-shrink: 0;+ }+.submenu_source_icon {width: 14px;height: 14px;diff --git a/frontend/src/components/sessionGrouping.ts b/frontend/src/components/sessionGrouping.tsindex 0053b78c2..bd934988c 100644--- a/frontend/src/components/sessionGrouping.ts+++ b/frontend/src/components/sessionGrouping.ts@@ -23,6 +23,7 @@ export interface SessionForGrouping {im_platform?: stringdescription?: stringuser_id?: string+ parent_session_id?: stringoriginalIndex?: number}diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vueindex 561a489e5..26615746e 100644--- a/frontend/src/views/chat/components/AgentStreamDisplay.vue+++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue@@ -384,6 +384,11 @@</div><div v-if="answerFullyRendered && event.done && event.content && event.content.trim() && !embeddedMode"class="answer-toolbar">+ <t-tooltip v-if="canFork" :content="forkTooltip">+ <t-button size="small" variant="outline" shape="round" @click.stop="emitFork">+ <t-icon name="git-branch" />+ </t-button>+ </t-tooltip><t-button size="small" variant="outline" shape="round" @click.stop="handleCopyAnswer(event)":title="$t('agent.copy')"><t-icon name="copy" />@@ -961,12 +966,21 @@ const props = defineProps<{embedVisitorId?: string;ragMode?: boolean;followUpLoading?: boolean;+ canFork?: boolean;}>();const emit = defineEmits<{(event: 'render-complete-change', ready: boolean): void;+ (event: 'fork', messageId: string): void;}>();+const canFork = computed(() => props.canFork === true && !props.embeddedMode)+const forkTooltip = '从这条回答继续分叉'+const emitFork = () => {+ const messageId = persistedAssistantId(props.session) || String(props.session?.id || '')+ if (messageId) emit('fork', messageId)+}+const embedAuthProps = computed(() => ({embeddedMode: props.embeddedMode,embedChannelId: props.embedChannelId,diff --git a/frontend/src/views/chat/components/botmsg.vue b/frontend/src/views/chat/components/botmsg.vueindex 0c6b8458a..74a730ad4 100644--- a/frontend/src/views/chat/components/botmsg.vue+++ b/frontend/src/views/chat/components/botmsg.vue@@ -18,6 +18,9 @@<RagPipelineProgress :session="session" :embedded-mode="embeddedMode" /><AgentStreamDisplay v-if="session.isAgentMode" :session="session" :session-id="sessionId":user-query="userQuery" :rag-mode="true" :follow-up-loading="followUpLoading"+ :embedded-mode="embeddedMode"+ :can-fork="canFork"+ @fork="emit('fork', $event)"@render-complete-change="emit('render-complete-change', $event)" /></div><template v-else>@@ -30,6 +33,9 @@<docInfo v-if="session.knowledge_references?.length" :session="session"></docInfo><AgentStreamDisplay :session="session" :session-id="sessionId" :user-query="userQuery"v-if="session.isAgentMode" :follow-up-loading="followUpLoading"+ :embedded-mode="embeddedMode"+ :can-fork="canFork"+ @fork="emit('fork', $event)"@render-complete-change="emit('render-complete-change', $event)" /></template><deepThink :deepSession="session" v-if="session.showThink && !session.isAgentMode"></deepThink>@@ -44,6 +50,11 @@</div><!-- 复制和添加到知识库按钮 - 非 Agent 模式下显示 --><div v-if="answerFullyRendered && (content || session.content)" class="answer-toolbar">+ <t-tooltip v-if="canFork" :content="forkTooltip">+ <t-button size="small" variant="outline" shape="round" @click.stop="emitFork">+ <t-icon name="git-branch" />+ </t-button>+ </t-tooltip><t-button size="small" variant="outline" shape="round" @click.stop="handleCopyAnswer":title="$t('agent.copy')"><t-icon name="copy" />@@ -161,7 +172,7 @@ const mentionTagIcon = (item) => {return 'file';};-const emit = defineEmits(['scroll-bottom', 'render-complete-change'])+const emit = defineEmits(['scroll-bottom', 'render-complete-change', 'fork'])const { t } = useI18n()const uiStore = useUIStore();let parentMd = ref()@@ -202,9 +213,20 @@ const props = defineProps({followUpLoading: {type: Boolean,default: false+ },+ canFork: {+ type: Boolean,+ default: false}});+const canFork = computed(() => props.canFork === true && !props.embeddedMode)+const forkTooltip = '从这条回答继续分叉'+const emitFork = () => {+ const messageId = persistedAssistantId(props.session) || props.session?.id+ if (messageId) emit('fork', messageId)+}+const showRequestInfo = computed(() => !!(props.session?.request_id || props.session?.id));// -----------------------------------------------------------------------------diff --git a/frontend/src/views/chat/components/usermsg.vue b/frontend/src/views/chat/components/usermsg.vueindex 93801de80..4357bde34 100644--- a/frontend/src/views/chat/components/usermsg.vue+++ b/frontend/src/views/chat/components/usermsg.vue@@ -43,6 +43,18 @@<div class="user_msg">{{ content }}</div>+ <div v-if="canFork" class="user_msg_actions">+ <t-tooltip :content="forkTooltip">+ <t-button+ variant="text"+ size="small"+ class="user_msg_action"+ @click="emit('fork', messageId)"+ >+ <t-icon name="git-branch" />+ </t-button>+ </t-tooltip>+ </div><div v-if="steerFailed" class="steer-failure" role="status"><span>{{ t('input.messages.steerFailed') }}</span><t-tooltip :content="t('input.steerRetry')"><button type="button" :aria-label="t('input.steerRetry')" @click="emit('retry-steer')"><t-icon name="refresh" /></button></t-tooltip>@@ -59,7 +71,7 @@ import { useI18n } from 'vue-i18n';import { useChatAttachmentPreviewDrawer } from '@/composables/useChatAttachmentPreviewDrawer';import { isPreviewableAttachment, resolveAttachmentFileType } from '@/utils/attachmentPreview';import { SKILL_ICON } from '@/types/mention';-const emit = defineEmits(['retry-steer', 'remove-steer']);+const emit = defineEmits(['retry-steer', 'remove-steer', 'fork']);const { t } = useI18n();@@ -108,9 +120,20 @@ const props = defineProps({sessionId: {type: String,default: ''+ },+ messageId: {+ type: String,+ default: ''+ },+ canFork: {+ type: Boolean,+ default: false}});+const canFork = computed(() => props.canFork === true && !props.embeddedMode);+const forkTooltip = '从这里分叉出新会话';+const attachmentPreviewDrawer = useChatAttachmentPreviewDrawer();const channelLabelMap = {@@ -195,6 +218,7 @@ const closePreImg = () => {@import '../../../components/css/chat-resource-chips.less';.user_msg_container {+ position: relative;display: flex;flex-direction: column;align-items: flex-end;@@ -370,4 +394,10 @@ html[theme-mode="dark"] {.steer-failure { margin-top: 6px; color: var(--td-error-color); }.steer-failure button { display: inline-flex; align-items: center; justify-content: center; width: 26px; height: 26px; border: 0; border-radius: 6px; background: transparent; color: inherit; cursor: pointer; }.steer-failure button:hover { background: var(--td-bg-color-secondarycontainer); }++.user_msg_actions {+ display: flex;+ justify-content: flex-end;+ padding-top: 2px;+}</style>diff --git a/frontend/src/views/chat/forkPoint.test.ts b/frontend/src/views/chat/forkPoint.test.tsnew file mode 100644index 000000000..8a8206c20--- /dev/null+++ b/frontend/src/views/chat/forkPoint.test.ts@@ -0,0 +1,51 @@+import assert from 'node:assert/strict'+import test from 'node:test'+import { resolveForkAffordance } from './forkPoint'++test('第一条 user 消息可以分叉', () => {+ const messages = [+ { id: 'u1', role: 'user' },+ { id: 'a1', role: 'assistant' },+ ]+ assert.deepEqual(resolveForkAffordance(messages, 'u1'), { canFork: true })+})++test('前置 assistant 无论有没有 checkpoint 都可以分叉', () => {+ const messages = [+ { id: 'u1', role: 'user' },+ { id: 'a1', role: 'assistant' },+ { id: 'u2', role: 'user' },+ ]+ assert.deepEqual(resolveForkAffordance(messages, 'u2'), { canFork: true })+})++test('assistant 消息可以分叉', () => {+ const messages = [+ { id: 'u1', role: 'user' },+ { id: 'a1', role: 'assistant', is_completed: true },+ ]+ assert.deepEqual(resolveForkAffordance(messages, 'a1'), { canFork: true })+})++test('未知角色不能作为分叉点', () => {+ const messages = [+ { id: 'u1', role: 'user' },+ { id: 's1', role: 'system' },+ ]+ assert.deepEqual(resolveForkAffordance(messages, 's1'), { canFork: false })+})++test('未知消息 ID 不能分叉', () => {+ assert.deepEqual(+ resolveForkAffordance([{ id: 'u1', role: 'user' }], 'nope'),+ { canFork: false },+ )+})++test('未完成的 assistant 消息意味着本轮还在跑,不给分叉', () => {+ const messages = [+ { id: 'u1', role: 'user' },+ { id: 'a1', role: 'assistant', is_completed: false },+ ]+ assert.deepEqual(resolveForkAffordance(messages, 'u1'), { canFork: false })+})diff --git a/frontend/src/views/chat/forkPoint.ts b/frontend/src/views/chat/forkPoint.tsnew file mode 100644index 000000000..148384ef0--- /dev/null+++ b/frontend/src/views/chat/forkPoint.ts@@ -0,0 +1,45 @@+/**+ * Fork affordance rules, kept as a pure function so they can be tested without+ * mounting the chat view.+ *+ * The backend re-derives all of this; this is purely so the UI can show the+ * right button state without an extra round trip.+ *+ * User messages fork *at* the question (history excludes it, composer prefills+ * it). Assistant messages fork *after* the answer (history includes it).+ */++export interface ForkCandidateMessage {+ id?: unknown+ role?: unknown+ is_completed?: unknown+}++export interface ForkAffordance {+ /** Whether the fork button should be offered on this message at all. */+ canFork: boolean+}++const REFUSED: ForkAffordance = { canFork: false }++export function resolveForkAffordance(+ messages: ForkCandidateMessage[],+ messageId: string,+): ForkAffordance {+ const index = messages.findIndex((m) => m.id === messageId)+ if (index < 0) {+ return REFUSED+ }++ // A turn still streaming means the source session holds an active sandbox+ // lease. The backend would answer 409, so do not offer the button.+ if (messages.some((m) => m.role === 'assistant' && m.is_completed === false)) {+ return REFUSED+ }++ const target = messages[index]+ if (target.role === 'assistant' || target.role === 'user') {+ return { canFork: true }+ }+ return REFUSED+}diff --git a/frontend/src/views/chat/index.vue b/frontend/src/views/chat/index.vueindex 7ce222f12..7721bf3ff 100644--- a/frontend/src/views/chat/index.vue+++ b/frontend/src/views/chat/index.vue@@ -109,9 +109,12 @@<usermsg :content="session.content" :mentioned_items="session.mentioned_items":images="session.images" :attachments="session.attachments" :embeddedMode="embeddedMode":session-id="session_id"+ :message-id="session.id"+ :can-fork="!embeddedMode && forkAffordanceOf(session.id).canFork":steer-failed="Boolean(session._steerFailed)"@retry-steer="handleRetrySteer(session.steer_id)"- @remove-steer="handleRemoveSteer(session.steer_id)">+ @remove-steer="handleRemoveSteer(session.steer_id)"+ @fork="handleFork"></usermsg></div><div v-if="session.role == 'assistant' && shouldRenderAssistantMessage(session)"@@ -120,6 +123,8 @@:user-query="getUserQuery(index)" @scroll-bottom="scrollToBottom":isFirstEnter="isFirstEnter" :embeddedMode="embeddedMode":follow-up-loading="Boolean(session.suggestionLoading && !session.suggestionSet?.questions?.length)"+ :can-fork="!embeddedMode && forkAffordanceOf(session.id).canFork"+ @fork="handleFork"@render-complete-change="(ready) => handleAnswerRenderComplete(session, ready)"></botmsg><FollowUpSuggestions v-if="session.answerFullyRendered && !session.steerForked && !session.suggestionsDismissed"@@ -176,11 +181,12 @@import { makeSteerClientId } from '@/utils/steerId';import { storeToRefs } from 'pinia';import { ref, onMounted, onBeforeMount, onUnmounted, nextTick, watch, reactive, computed } from 'vue';-import { useRoute, onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router';+import { useRoute, useRouter, onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router';import InputField from '../../components/Input-field.vue';import botmsg from './components/botmsg.vue';import usermsg from './components/usermsg.vue';-import { getMessageList, getSession } from "@/api/chat/index";+import { getMessageList, getSession, forkSession } from "@/api/chat/index";+import { resolveForkAffordance } from './forkPoint';import { getSuggestedQuestions } from "@/api/agent/index";import { deleteTemporaryAttachment, uploadTemporaryAttachment } from '@/api/chat/temporary-attachments';import { useStream } from '../../api/chat/streame'@@ -277,6 +283,7 @@ const attachStreamDebugToMessage = (message) => {message.debugRequest = payload;};const route = useRoute();+const router = useRouter();const session_id = ref(props.session_id || route.params.chatid);const currentSession = ref(null);@@ -303,6 +310,102 @@ const inputFieldRef = ref();const created_at = ref('');const limit = ref(20);const messagesList = reactive([]);++function forkAffordanceOf(messageId) {+ if (!messageId) return { canFork: false }+ return resolveForkAffordance(messagesList, messageId)+}++const FORK_PREFILL_KEY = 'weknora:fork-prefill'+let forkInFlight = false++function stashForkLanding(sessionId, text) {+ const payload = JSON.stringify({ sessionId, text })+ try {+ sessionStorage.setItem(FORK_PREFILL_KEY, payload)+ } catch {+ // sessionStorage can throw in private mode; landing still navigates.+ }+}++function readForkLanding() {+ try {+ const raw = sessionStorage.getItem(FORK_PREFILL_KEY)+ if (!raw) return null+ const parsed = JSON.parse(raw)+ if (!parsed || typeof parsed !== 'object') return null+ return {+ sessionId: String(parsed.sessionId || ''),+ text: String(parsed.text || ''),+ }+ } catch {+ return null+ }+}++function clearForkLanding() {+ try {+ sessionStorage.removeItem(FORK_PREFILL_KEY)+ } catch {+ // ignore+ }+}++function applyForkLanding() {+ const landed = readForkLanding()+ if (!landed || landed.sessionId !== String(session_id.value || '')) {+ return false+ }+ clearForkLanding()+ inputFieldRef.value?.prefill(landed.text)+ return true+}++async function handleFork(messageId) {+ if (props.embeddedMode) return+ if (forkInFlight) return+ if (!messageId || !session_id.value) return+ const source = messagesList.find((m) => m.id === messageId)+ if (!source) return+ const sourceSessionId = session_id.value++ forkInFlight = true+ try {+ const res = await forkSession(sourceSessionId, { message_id: messageId })+ const data = res?.data+ if (!data?.session_id) return++ // Carry the question across navigation in sessionStorage: the chat view+ // is reused across chat/:chatid, and history reload / composer reset+ // would clobber an in-memory prefill if we applied it too early.+ const prefill = source.role === 'user' ? String(source.content ?? '') : ''+ stashForkLanding(data.session_id, prefill)++ const now = new Date().toISOString()+ const sourceTitle = currentSession.value?.title || t('menu.newSession')+ usemenuStore.updataMenuChildren({+ id: data.session_id,+ path: `chat/${data.session_id}`,+ title: `${sourceTitle}(分支)`,+ parent_session_id: sourceSessionId,+ isMore: false,+ isNoTitle: false,+ created_at: now,+ updated_at: now,+ })++ await router.push(`/platform/chat/${data.session_id}`)+ } catch (err) {+ if (err?.status === 409 || err?.$httpStatus === 409) {+ MessagePlugin.warning('请等本轮回答结束后再分叉')+ return+ }+ MessagePlugin.error('分叉失败,请重试')+ } finally {+ forkInFlight = false+ }+}+const sessionArtifacts = computed(() => collectSessionArtifacts(messagesList));const sessionArtifactsCollecting = computed(() =>messagesList.some((message) => isCollectingSkillArtifacts(message)),@@ -332,6 +435,14 @@ watch([activitySessionId, isReplying, isStreaming, isImRecovering, currentAssistconst historyLoading = ref(true);const historyLoadingMore = ref(false);const hasMoreHistory = ref(true);++// Prefill after THIS session's history load settles. A messagesList watch+// would fire on the splice-to-empty that starts a session switch and then+// get clobbered by composer reset / history mount.+watch(historyLoading, (loading) => {+ if (loading) return+ applyForkLanding()+}, { flush: 'post' })let fullContent = ref('')const scrollContainer = ref(null)const userHasScrolledUp = ref(false)diff --git a/frontend/vite.config.ts b/frontend/vite.config.tsindex 5c39b94d3..f7a90799b 100644--- a/frontend/vite.config.ts+++ b/frontend/vite.config.ts@@ -139,6 +139,10 @@ export default defineConfig({// 沙箱终端等 WebSocket 升级请求也走 /api,必须开启 WS 转发,// 否则浏览器侧握手失败、前端表现为"一直正在连接"。ws: true,+ // Cube fork snapshots pause a live MicroVM; 30s axios/proxy defaults+ // abort the POST and the backend then 500s on a canceled persist.+ timeout: 180_000,+ proxyTimeout: 180_000,},'/files': {target: DEV_PROXY_TARGET,@@ -159,6 +163,8 @@ export default defineConfig({changeOrigin: true,secure: false,ws: true,+ timeout: 180_000,+ proxyTimeout: 180_000,},'/files': {target: DEV_PROXY_TARGET,diff --git a/internal/application/repository/message.go b/internal/application/repository/message.goindex 28befe836..c5299b7fe 100644--- a/internal/application/repository/message.go+++ b/internal/application/repository/message.go@@ -46,12 +46,18 @@ func (r *messageRepository) GetMessage(return &message, nil}-// GetMessagesBySession retrieves all messages for a session with pagination+// GetMessagesBySession retrieves all messages for a session with pagination.+//+// The secondary sort on id is not cosmetic: messages created in the same+// millisecond would otherwise come back in an order the database is free to+// vary between calls, which makes a fork boundary drawn at one of them+// irreproducible.func (r *messageRepository) GetMessagesBySession(ctx context.Context, sessionID string, page int, pageSize int,) ([]*types.Message, error) {var messages []*types.Message- if err := r.db.WithContext(ctx).Where("session_id = ?", sessionID).Order("created_at ASC").+ if err := r.db.WithContext(ctx).Where("session_id = ?", sessionID).+ Order("created_at ASC, id ASC").Offset((page - 1) * pageSize).Limit(pageSize).Find(&messages).Error; err != nil {return nil, err}@@ -135,6 +141,27 @@ func (r *messageRepository) ListMessagesBySessionAfterCursor(ctx context.Contextreturn messages, err}+// ListMessagesBySessionUpTo returns every message of a session that sorts+// strictly before the (boundary, boundaryID) cursor, oldest first.+//+// The cursor is composite rather than a bare timestamp because a fork boundary+// must be reproducible: two messages written in the same millisecond are+// ordered by ID, and the caller's boundary message must be excluded regardless+// of how many peers share its timestamp.+func (r *messageRepository) ListMessagesBySessionUpTo(+ ctx context.Context, sessionID string, boundary time.Time, boundaryID string,+) ([]*types.Message, error) {+ var messages []*types.Message+ if err := r.db.WithContext(ctx).+ Where("session_id = ?", sessionID).+ Where("created_at < ? OR (created_at = ? AND id < ?)", boundary, boundary, boundaryID).+ Order("created_at ASC, id ASC").+ Find(&messages).Error; err != nil {+ return nil, err+ }+ return messages, nil+}+// UpdateMessage updates an existing message.func (r *messageRepository) UpdateMessage(ctx context.Context, message *types.Message) error {return r.db.WithContext(ctx).Model(&types.Message{}).Where(@@ -275,11 +302,12 @@ func (r *messageRepository) GetMessagesByKnowledgeIDs(return results, nil}-// GetMessagesByRequestIDs retrieves messages by their request IDs (used to fetch Q&A pair partners)+// GetMessagesByRequestIDs retrieves messages by request ID inside one session+// (used to fetch Q&A pair partners). Empty sessionID is treated as no match.func (r *messageRepository) GetMessagesByRequestIDs(- ctx context.Context, requestIDs []string,+ ctx context.Context, sessionID string, requestIDs []string,) ([]*types.MessageWithSession, error) {- if len(requestIDs) == 0 {+ if sessionID == "" || len(requestIDs) == 0 {return nil, nil}var results []*types.MessageWithSession@@ -288,6 +316,7 @@ func (r *messageRepository) GetMessagesByRequestIDs(Select("messages.*, sessions.title as session_title").Joins("INNER JOIN sessions ON sessions.id = messages.session_id AND sessions.deleted_at IS NULL").Where("messages.deleted_at IS NULL").+ Where("messages.session_id = ?", sessionID).Where("messages.request_id IN ?", requestIDs).Find(&results).Error; err != nil {return nil, err@@ -379,6 +408,73 @@ func (r *messageRepository) GetSessionArtifacts(return result, nil}+// RewriteSandboxCheckpoints retargets copied checkpoints onto the forked+// session's live sandbox. CommitSHA / CommittedAt are left untouched: the git+// objects are in the snapshot, only the sandbox identity changed.+func (r *messageRepository) RewriteSandboxCheckpoints(+ ctx context.Context, sessionID, oldSandboxID, newSandboxID string,+) error {+ if sessionID == "" || oldSandboxID == "" || newSandboxID == "" || oldSandboxID == newSandboxID {+ return nil+ }+ var messages []*types.Message+ if err := r.db.WithContext(ctx).+ Where("session_id = ?", sessionID).+ Find(&messages).Error; err != nil {+ return err+ }+ for _, message := range messages {+ if message == nil || message.SandboxCheckpoint == nil {+ continue+ }+ if message.SandboxCheckpoint.SandboxID != oldSandboxID {+ continue+ }+ updated := *message.SandboxCheckpoint+ updated.SandboxID = newSandboxID+ if err := r.db.WithContext(ctx).+ Model(&types.Message{}).+ Where("id = ? AND session_id = ?", message.ID, sessionID).+ Update("sandbox_checkpoint", updated).Error; err != nil {+ return err+ }+ }+ return nil+}++// RecordRestoredArtifactMtime updates ModTime (and ContentHash) on artifacts+// in this session whose source path matches a same-content sandbox restore.+func (r *messageRepository) RecordRestoredArtifactMtime(+ ctx context.Context, sessionID, sourcePath string, mod time.Time, hash string,+) error {+ if sessionID == "" || sourcePath == "" {+ return nil+ }+ var messages []*types.Message+ if err := r.db.WithContext(ctx).+ Select("id", "session_id", "artifacts").+ Where("session_id = ?", sessionID).+ Find(&messages).Error; err != nil {+ return err+ }+ for _, message := range messages {+ if message == nil {+ continue+ }+ updated, changed := message.Artifacts.WithRestoredMtime(sourcePath, mod, hash)+ if !changed {+ continue+ }+ if err := r.db.WithContext(ctx).+ Model(&types.Message{}).+ Where("id = ? AND session_id = ?", message.ID, sessionID).+ Update("artifacts", updated).Error; err != nil {+ return err+ }+ }+ return nil+}+// GetSessionAttachments returns every user-uploaded attachment in creation// order while projecting only the attachments JSON column.func (r *messageRepository) GetSessionAttachments(diff --git a/internal/application/repository/message_fork_boundary_test.go b/internal/application/repository/message_fork_boundary_test.gonew file mode 100644index 000000000..f96e6c8c5--- /dev/null+++ b/internal/application/repository/message_fork_boundary_test.go@@ -0,0 +1,133 @@+package repository++import (+ "context"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+ "gorm.io/driver/sqlite"+ "gorm.io/gorm"+)++func newMessageRepositoryForForkTest(t *testing.T) (*messageRepository, *gorm.DB) {+ t.Helper()++ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})+ require.NoError(t, err)+ require.NoError(t, db.AutoMigrate(&types.Message{}))++ return &messageRepository{db: db}, db+}++func seedMessage(t *testing.T, db *gorm.DB, id, sessionID, role string, at time.Time) {+ t.Helper()+ // Message.BeforeCreate always assigns a fresh UUID, which would discard+ // the IDs these tests use as both expected results and the composite+ // cursor. Skip hooks so the seeded identity is the one the queries see.+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Message{+ ID: id,+ SessionID: sessionID,+ Role: role,+ CreatedAt: at,+ }).Error)+}++// Same-millisecond messages must come back in a deterministic order, otherwise+// a fork boundary drawn at one of them is not reproducible.+func TestGetMessagesBySessionBreaksTimestampTiesById(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ at := time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)++ seedMessage(t, db, "m-c", "s1", "assistant", at)+ seedMessage(t, db, "m-a", "s1", "user", at)+ seedMessage(t, db, "m-b", "s1", "assistant", at)++ got, err := repo.GetMessagesBySession(ctx, "s1", 1, 10)+ require.NoError(t, err)+ require.Equal(t, []string{"m-a", "m-b", "m-c"}, messageIDs(got))+}++func TestListMessagesBySessionUpToExcludesBoundaryAndLater(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ base := time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)++ seedMessage(t, db, "m1", "s1", "user", base)+ seedMessage(t, db, "m2", "s1", "assistant", base.Add(time.Second))+ seedMessage(t, db, "m3", "s1", "user", base.Add(2*time.Second))+ seedMessage(t, db, "m4", "s1", "assistant", base.Add(3*time.Second))+ seedMessage(t, db, "other", "s2", "user", base)++ got, err := repo.ListMessagesBySessionUpTo(ctx, "s1", base.Add(2*time.Second), "m3")+ require.NoError(t, err)+ require.Equal(t, []string{"m1", "m2"}, messageIDs(got))+}++// The boundary is a composite (created_at, id) cursor, so a message sharing the+// boundary's timestamp is included only when its ID sorts before the boundary's.+func TestListMessagesBySessionUpToUsesCompositeCursor(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ at := time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)++ seedMessage(t, db, "m-a", "s1", "user", at)+ seedMessage(t, db, "m-b", "s1", "assistant", at)+ seedMessage(t, db, "m-c", "s1", "user", at)++ got, err := repo.ListMessagesBySessionUpTo(ctx, "s1", at, "m-c")+ require.NoError(t, err)+ require.Equal(t, []string{"m-a", "m-b"}, messageIDs(got))+}++func TestListMessagesBySessionUpToSkipsSoftDeleted(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ base := time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)++ seedMessage(t, db, "m1", "s1", "user", base)+ seedMessage(t, db, "m2", "s1", "assistant", base.Add(time.Second))+ seedMessage(t, db, "boundary", "s1", "user", base.Add(2*time.Second))+ require.NoError(t, db.Delete(&types.Message{}, "id = ?", "m2").Error)++ got, err := repo.ListMessagesBySessionUpTo(ctx, "s1", base.Add(2*time.Second), "boundary")+ require.NoError(t, err)+ require.Equal(t, []string{"m1"}, messageIDs(got))+}++func TestRecordRestoredArtifactMtimeOnlyTouchesThisSession(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ ctx := context.Background()+ at := time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)+ oldMod := at+ newMod := at.Add(time.Minute)+ hash := "abc"+ art := types.MessageArtifacts{{+ SourcePath: "/workspace/output/report.pptx", FileName: "report.pptx",+ ModTime: oldMod, FileSize: 4, ContentHash: hash,+ }}+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Message{+ ID: "parent-msg", SessionID: "parent", Role: "assistant", CreatedAt: at, Artifacts: art,+ }).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Message{+ ID: "fork-msg", SessionID: "fork-1", Role: "assistant", CreatedAt: at, Artifacts: art,+ }).Error)++ require.NoError(t, repo.RecordRestoredArtifactMtime(ctx, "fork-1", "/workspace/output/report.pptx", newMod, hash))++ var parent, child types.Message+ require.NoError(t, db.Where("id = ?", "parent-msg").First(&parent).Error)+ require.NoError(t, db.Where("id = ?", "fork-msg").First(&child).Error)+ require.True(t, parent.Artifacts[0].ModTime.Equal(oldMod), "parent artifact mtime must stay put")+ require.True(t, child.Artifacts[0].ModTime.Equal(newMod), "fork artifact mtime should follow the restored sandbox")+}++func messageIDs(messages []*types.Message) []string {+ ids := make([]string, 0, len(messages))+ for _, m := range messages {+ ids = append(ids, m.ID)+ }+ return ids+}diff --git a/internal/application/repository/message_request_id_test.go b/internal/application/repository/message_request_id_test.gonew file mode 100644index 000000000..996cad089--- /dev/null+++ b/internal/application/repository/message_request_id_test.go@@ -0,0 +1,52 @@+package repository++import (+ "context"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+ "gorm.io/gorm"+)++func TestGetMessagesByRequestIDsStaysInsideSession(t *testing.T) {+ repo, db := newMessageRepositoryForForkTest(t)+ require.NoError(t, db.AutoMigrate(&types.Session{}))+ ctx := context.Background()+ at := time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)++ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).+ Create(&types.Session{ID: "parent", TenantID: 1}).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Session{ID: "fork", TenantID: 1}).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Message{+ ID: "p-u", SessionID: "parent", RequestID: "req", Role: "user", CreatedAt: at,+ }).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Message{+ ID: "p-a", SessionID: "parent", RequestID: "req", Role: "assistant", CreatedAt: at.Add(time.Second),+ }).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Message{+ ID: "f-u", SessionID: "fork", RequestID: "req", Role: "user", CreatedAt: at,+ }).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Message{+ ID: "f-a", SessionID: "fork", RequestID: "req", Role: "assistant", CreatedAt: at.Add(time.Second),+ }).Error)++ got, err := repo.GetMessagesByRequestIDs(ctx, "fork", []string{"req"})+ require.NoError(t, err)+ require.Equal(t, []string{"f-u", "f-a"}, messageIDsFromWithSession(got))++ empty, err := repo.GetMessagesByRequestIDs(ctx, "", []string{"req"})+ require.NoError(t, err)+ require.Empty(t, empty)+}++func messageIDsFromWithSession(messages []*types.MessageWithSession) []string {+ ids := make([]string, 0, len(messages))+ for _, m := range messages {+ if m != nil {+ ids = append(ids, m.ID)+ }+ }+ return ids+}diff --git a/internal/application/repository/session.go b/internal/application/repository/session.goindex 67c8f0720..5384a9e92 100644--- a/internal/application/repository/session.go+++ b/internal/application/repository/session.go@@ -391,3 +391,175 @@ func (r *sessionRepository) DeleteAllByTenantID(ctx context.Context, tenantID ui).Delete(&types.Session{})return res.RowsAffected, res.Error}++// CreateForked persists a forked session and its copied history atomically.+// A partially written fork would show up in the sidebar with a truncated or+// empty conversation, so both halves must land together.+func (r *sessionRepository) CreateForked(+ ctx context.Context, session *types.Session, messages []*types.Message,+) error {+ return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {+ now := time.Now()+ session.CreatedAt = now+ session.UpdatedAt = now+ // Session.BeforeCreate would overwrite the ID the fork service already+ // assigned (the copied messages point at it), so write the row with+ // the hook skipped.+ if err := tx.Session(&gorm.Session{SkipHooks: true}).Create(session).Error; err != nil {+ return err+ }+ if len(messages) == 0 {+ return nil+ }+ return tx.Session(&gorm.Session{SkipHooks: true}).+ CreateInBatches(messages, 100).Error+ })+}++// UpdateForkBootstrap overwrites a session's fork bootstrap. Passing nil clears+// it, which is how a failed or abandoned bootstrap is retired.+func (r *sessionRepository) UpdateForkBootstrap(+ ctx context.Context, sessionID string, b *types.ForkBootstrap,+) error {+ return r.db.WithContext(ctx).Unscoped().Model(&types.Session{}).+ Where("id = ?", sessionID).+ Update("fork_bootstrap", b).Error+}++// ListUnconsumedForks returns fork bootstraps the snapshot reaper should+// try to retire: unopened forks older than olderThan, plus consumed forks+// that still name a snapshot (Cube keeps runtime refs until both sandboxes+// exit, so AfterCreate often cannot delete immediately).+//+// Soft-deleted sessions are included: deleting an unopened fork hides the+// row from the default GORM scope, and this listing is the reaper's fallback+// when delete-path snapshot cleanup did not run.+func (r *sessionRepository) ListUnconsumedForks(+ ctx context.Context, olderThan time.Time,+) ([]*types.Session, error) {+ var sessions []*types.Session+ // Only the columns the reaper needs. The full session row includes large+ // JSONB (last_request_state) that this listing never reads.+ if err := r.db.WithContext(ctx).Unscoped().+ Model(&types.Session{}).+ Select("id", "tenant_id", "sandbox_config_id", "fork_bootstrap", "deleted_at").+ Where("fork_bootstrap IS NOT NULL").+ Find(&sessions).Error; err != nil {+ return nil, err+ }+ pending := make([]*types.Session, 0, len(sessions))+ for _, s := range sessions {+ if s == nil || s.ForkBootstrap == nil {+ continue+ }+ if strings.TrimSpace(s.ForkBootstrap.SnapshotID) == "" {+ continue+ }+ if s.ForkBootstrap.Consumed() {+ pending = append(pending, s)+ continue+ }+ if s.ForkBootstrap.CreatedAt.After(olderThan) {+ continue+ }+ pending = append(pending, s)+ }+ return pending, nil+}++func forkBootstrapJSONText(db *gorm.DB, key string) string {+ if db.Name() == "postgres" {+ return "fork_bootstrap ->> '" + key + "'"+ }+ return "json_extract(fork_bootstrap, '$." + key + "')"+}++func (r *sessionRepository) unconsumedForkSnapshotQuery(ctx context.Context, snapshotID string) *gorm.DB {+ snapExpr := forkBootstrapJSONText(r.db, "snapshot_id")+ consumedExpr := forkBootstrapJSONText(r.db, "consumed_at")+ // Matches idx_sessions_unconsumed_fork on Postgres: snapshot_id equality+ // under (fork_bootstrap IS NOT NULL AND consumed_at IS NULL).+ return r.db.WithContext(ctx).+ Model(&types.Session{}).+ Where("fork_bootstrap IS NOT NULL").+ Where(snapExpr+" = ?", snapshotID).+ Where(consumedExpr + " IS NULL")+}++func (r *sessionRepository) unconsumedForkSnapshotHolders(+ ctx context.Context, snapshotID string,+) ([]string, error) {+ snapshotID = strings.TrimSpace(snapshotID)+ if snapshotID == "" {+ return nil, nil+ }+ var ids []string+ if err := r.unconsumedForkSnapshotQuery(ctx, snapshotID).+ Pluck("id", &ids).Error; err != nil {+ return nil, err+ }+ return ids, nil+}++// HasOtherUnconsumedForkSnapshot reports whether another session still needs+// snapshotID to provision. Nested unused forks share one snapshot; deleting it+// when the first sibling boots would strand the rest.+func (r *sessionRepository) HasOtherUnconsumedForkSnapshot(+ ctx context.Context, snapshotID, excludeSessionID string,+) (bool, error) {+ snapshotID = strings.TrimSpace(snapshotID)+ if snapshotID == "" {+ return false, nil+ }+ q := r.unconsumedForkSnapshotQuery(ctx, snapshotID)+ if excludeSessionID != "" {+ q = q.Where("id <> ?", excludeSessionID)+ }+ var ids []string+ if err := q.Limit(1).Pluck("id", &ids).Error; err != nil {+ return false, err+ }+ return len(ids) > 0, nil+}++// UnconsumedForkSnapshotHolders returns session IDs that still need snapshotID+// to boot.+func (r *sessionRepository) UnconsumedForkSnapshotHolders(+ ctx context.Context, snapshotID string,+) ([]string, error) {+ return r.unconsumedForkSnapshotHolders(ctx, snapshotID)+}++func (r *sessionRepository) CreateForkSnapshotLease(+ ctx context.Context, lease *types.ForkSnapshotLease,+) error {+ if lease == nil || strings.TrimSpace(lease.SnapshotID) == "" {+ return nil+ }+ if lease.CreatedAt.IsZero() {+ lease.CreatedAt = time.Now().UTC()+ }+ return r.db.WithContext(ctx).Create(lease).Error+}++func (r *sessionRepository) DeleteForkSnapshotLease(ctx context.Context, snapshotID string) error {+ snapshotID = strings.TrimSpace(snapshotID)+ if snapshotID == "" {+ return nil+ }+ return r.db.WithContext(ctx).+ Where("snapshot_id = ?", snapshotID).+ Delete(&types.ForkSnapshotLease{}).Error+}++func (r *sessionRepository) ListStaleForkSnapshotLeases(+ ctx context.Context, olderThan time.Time,+) ([]*types.ForkSnapshotLease, error) {+ var leases []*types.ForkSnapshotLease+ if err := r.db.WithContext(ctx).+ Where("created_at <= ?", olderThan).+ Find(&leases).Error; err != nil {+ return nil, err+ }+ return leases, nil+}diff --git a/internal/application/repository/session_fork_test.go b/internal/application/repository/session_fork_test.gonew file mode 100644index 000000000..77632bad4--- /dev/null+++ b/internal/application/repository/session_fork_test.go@@ -0,0 +1,295 @@+package repository++import (+ "context"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/stretchr/testify/require"+ "gorm.io/driver/sqlite"+ "gorm.io/gorm"+)++func newSessionRepositoryForForkTest(t *testing.T) (interfaces.SessionRepository, *gorm.DB) {+ t.Helper()++ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})+ require.NoError(t, err)+ require.NoError(t, db.AutoMigrate(&types.Session{}, &types.Message{}, &types.ForkSnapshotLease{}))++ return NewSessionRepository(db), db+}++func TestCreateForkedPersistsSessionAndCopiedMessages(t *testing.T) {+ repo, db := newSessionRepositoryForForkTest(t)+ ctx := context.Background()+ createdAt := time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)++ session := &types.Session{+ ID: "fork-1",+ TenantID: 1,+ UserID: "u1",+ Title: "原会话(分支)",+ SandboxConfigID: "cfg-1",+ ParentSessionID: "src",+ ForkedFromMessageID: "u-msg-2",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-1",+ CommitSHA: "sha1",+ SourceSandboxID: "sbx-1",+ CreatedAt: createdAt,+ },+ }+ messages := []*types.Message{+ {ID: "copy-1", SessionID: "fork-1", Role: "user", CreatedAt: createdAt, KnowledgeID: ""},+ {ID: "copy-2", SessionID: "fork-1", Role: "assistant", CreatedAt: createdAt.Add(time.Second)},+ }++ require.NoError(t, repo.CreateForked(ctx, session, messages))++ got, err := repo.GetByID(ctx, 1, "fork-1")+ require.NoError(t, err)+ require.Equal(t, "fork-1", got.ID, "SkipHooks must keep the ID the service already assigned")+ require.Equal(t, "src", got.ParentSessionID)+ require.Equal(t, "u-msg-2", got.ForkedFromMessageID)+ require.Equal(t, "cfg-1", got.SandboxConfigID)+ require.NotNil(t, got.ForkBootstrap)+ require.Equal(t, "snap-1", got.ForkBootstrap.SnapshotID)+ require.Equal(t, "sha1", got.ForkBootstrap.CommitSHA)+ require.False(t, got.ForkBootstrap.Consumed())++ var stored []*types.Message+ require.NoError(t, db.Where("session_id = ?", "fork-1").Order("created_at ASC, id ASC").Find(&stored).Error)+ require.Equal(t, []string{"copy-1", "copy-2"}, messageIDs(stored))+}++func TestCreateForkedAllowsEmptyHistory(t *testing.T) {+ repo, _ := newSessionRepositoryForForkTest(t)+ ctx := context.Background()++ session := &types.Session{ID: "fork-empty", TenantID: 1, UserID: "u1", Title: "first"}+ require.NoError(t, repo.CreateForked(ctx, session, nil))++ got, err := repo.GetByID(ctx, 1, "fork-empty")+ require.NoError(t, err)+ require.Equal(t, "fork-empty", got.ID)+}++func TestUpdateForkBootstrapSetsAndClears(t *testing.T) {+ repo, _ := newSessionRepositoryForForkTest(t)+ ctx := context.Background()+ session := &types.Session{ID: "s1", TenantID: 1, UserID: "u1", Title: "s"}+ require.NoError(t, repo.CreateForked(ctx, session, nil))++ bootstrap := &types.ForkBootstrap{+ SnapshotID: "snap-1",+ CommitSHA: "sha1",+ SourceSandboxID: "sbx-1",+ CreatedAt: time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC),+ }+ require.NoError(t, repo.UpdateForkBootstrap(ctx, "s1", bootstrap))++ got, err := repo.GetByID(ctx, 1, "s1")+ require.NoError(t, err)+ require.NotNil(t, got.ForkBootstrap)+ require.Equal(t, "snap-1", got.ForkBootstrap.SnapshotID)++ require.NoError(t, repo.UpdateForkBootstrap(ctx, "s1", nil))++ got, err = repo.GetByID(ctx, 1, "s1")+ require.NoError(t, err)+ require.Nil(t, got.ForkBootstrap)+}++func TestListUnconsumedForksFiltersConsumedAndTooNew(t *testing.T) {+ repo, _ := newSessionRepositoryForForkTest(t)+ ctx := context.Background()+ cutoff := time.Date(2026, 9, 10, 10, 0, 0, 0, time.UTC)+ consumedAt := cutoff.Add(-time.Hour)++ stale := &types.Session{+ ID: "stale", TenantID: 1, UserID: "u1", Title: "stale",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-stale", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: cutoff.Add(-time.Hour),+ },+ }+ fresh := &types.Session{+ ID: "fresh", TenantID: 1, UserID: "u1", Title: "fresh",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-fresh", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: cutoff.Add(time.Minute),+ },+ }+ consumed := &types.Session{+ ID: "consumed", TenantID: 1, UserID: "u1", Title: "consumed",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-consumed", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: cutoff.Add(-2 * time.Hour),+ ConsumedAt: &consumedAt,+ },+ }+ plain := &types.Session{ID: "plain", TenantID: 1, UserID: "u1", Title: "plain"}++ require.NoError(t, repo.CreateForked(ctx, stale, nil))+ require.NoError(t, repo.CreateForked(ctx, fresh, nil))+ require.NoError(t, repo.CreateForked(ctx, consumed, nil))+ require.NoError(t, repo.CreateForked(ctx, plain, nil))++ got, err := repo.ListUnconsumedForks(ctx, cutoff)+ require.NoError(t, err)++ ids := make([]string, 0, len(got))+ for _, s := range got {+ ids = append(ids, s.ID)+ }+ require.ElementsMatch(t, []string{"stale", "consumed"}, ids)+}++func TestListUnconsumedForksIncludesSoftDeletedUnopenedFork(t *testing.T) {+ repo, _ := newSessionRepositoryForForkTest(t)+ ctx := context.Background()+ cutoff := time.Date(2026, 9, 10, 10, 0, 0, 0, time.UTC)+ stale := &types.Session{+ ID: "deleted-fork", TenantID: 1, UserID: "u1", Title: "gone",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-deleted", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: cutoff.Add(-time.Hour),+ },+ }+ require.NoError(t, repo.CreateForked(ctx, stale, nil))+ n, err := repo.Delete(ctx, 1, "u1", "deleted-fork")+ require.NoError(t, err)+ require.Equal(t, int64(1), n)++ got, err := repo.ListUnconsumedForks(ctx, cutoff)+ require.NoError(t, err)+ require.Len(t, got, 1)+ require.Equal(t, "deleted-fork", got[0].ID)+ require.Equal(t, "snap-deleted", got[0].ForkBootstrap.SnapshotID)+}++func TestHasOtherUnconsumedForkSnapshotIgnoresSelfAndConsumed(t *testing.T) {+ repo, _ := newSessionRepositoryForForkTest(t)+ ctx := context.Background()+ consumedAt := time.Now().UTC()++ self := &types.Session{+ ID: "self", TenantID: 1, UserID: "u1", Title: "self",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-shared", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ },+ }+ sibling := &types.Session{+ ID: "sibling", TenantID: 1, UserID: "u1", Title: "sibling",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-shared", CommitSHA: "sha-early", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ },+ }+ otherSnap := &types.Session{+ ID: "other-snap", TenantID: 1, UserID: "u1", Title: "other",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-other", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ },+ }+ consumed := &types.Session{+ ID: "consumed", TenantID: 1, UserID: "u1", Title: "consumed",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-shared", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC().Add(-time.Hour),+ ConsumedAt: &consumedAt,+ },+ }++ require.NoError(t, repo.CreateForked(ctx, self, nil))+ require.NoError(t, repo.CreateForked(ctx, sibling, nil))+ require.NoError(t, repo.CreateForked(ctx, otherSnap, nil))+ require.NoError(t, repo.CreateForked(ctx, consumed, nil))++ got, err := repo.HasOtherUnconsumedForkSnapshot(ctx, "snap-shared", "self")+ require.NoError(t, err)+ require.True(t, got)++ got, err = repo.HasOtherUnconsumedForkSnapshot(ctx, "snap-shared", "sibling")+ require.NoError(t, err)+ require.True(t, got, "self is still unconsumed")++ got, err = repo.HasOtherUnconsumedForkSnapshot(ctx, "snap-other", "other-snap")+ require.NoError(t, err)+ require.False(t, got, "only this session names snap-other")++ got, err = repo.HasOtherUnconsumedForkSnapshot(ctx, "snap-shared", "missing")+ require.NoError(t, err)+ require.True(t, got)++ got, err = repo.HasOtherUnconsumedForkSnapshot(ctx, "", "self")+ require.NoError(t, err)+ require.False(t, got)++ holders, err := repo.UnconsumedForkSnapshotHolders(ctx, "snap-shared")+ require.NoError(t, err)+ require.ElementsMatch(t, []string{"self", "sibling"}, holders)+}++func TestHasOtherUnconsumedForkSnapshotIgnoresSoftDeletedSibling(t *testing.T) {+ repo, _ := newSessionRepositoryForForkTest(t)+ ctx := context.Background()+ self := &types.Session{+ ID: "self", TenantID: 1, UserID: "u1", Title: "self",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-shared", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ },+ }+ sibling := &types.Session{+ ID: "sibling", TenantID: 1, UserID: "u1", Title: "sibling",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-shared", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ },+ }+ require.NoError(t, repo.CreateForked(ctx, self, nil))+ require.NoError(t, repo.CreateForked(ctx, sibling, nil))+ n, err := repo.Delete(ctx, 1, "u1", "sibling")+ require.NoError(t, err)+ require.Equal(t, int64(1), n)++ got, err := repo.HasOtherUnconsumedForkSnapshot(ctx, "snap-shared", "self")+ require.NoError(t, err)+ require.False(t, got, "a soft-deleted sibling no longer needs the snapshot")+}++func TestForkSnapshotLeaseRoundTripAndStaleListing(t *testing.T) {+ repo, _ := newSessionRepositoryForForkTest(t)+ ctx := context.Background()+ stale := time.Now().UTC().Add(-20 * time.Minute)+ fresh := time.Now().UTC()++ require.NoError(t, repo.CreateForkSnapshotLease(ctx, &types.ForkSnapshotLease{+ SnapshotID: "snap-stale",+ TenantID: 9,+ SandboxConfigID: "cfg-1",+ CreatedAt: stale,+ }))+ require.NoError(t, repo.CreateForkSnapshotLease(ctx, &types.ForkSnapshotLease{+ SnapshotID: "snap-fresh",+ CreatedAt: fresh,+ }))++ got, err := repo.ListStaleForkSnapshotLeases(ctx, time.Now().UTC().Add(-15*time.Minute))+ require.NoError(t, err)+ require.Len(t, got, 1)+ require.Equal(t, "snap-stale", got[0].SnapshotID)+ require.Equal(t, uint64(9), got[0].TenantID)+ require.Equal(t, "cfg-1", got[0].SandboxConfigID)++ require.NoError(t, repo.DeleteForkSnapshotLease(ctx, "snap-stale"))+ got, err = repo.ListStaleForkSnapshotLeases(ctx, time.Now().UTC().Add(-15*time.Minute))+ require.NoError(t, err)+ require.Empty(t, got)+}diff --git a/internal/application/service/artifact_collector.go b/internal/application/service/artifact_collector.goindex be7a55976..59cb0a455 100644--- a/internal/application/service/artifact_collector.go+++ b/internal/application/service/artifact_collector.go@@ -14,12 +14,16 @@// sandbox and returns an empty slice when none exists.// - Best-effort: individual errors are logged and skipped, never returned,// so a stray unreadable file cannot block the assistant reply.-// - De-duplication by (SourcePath, ModTime): if a prior message in the-// same session already recorded the same (path, mtime), skip it.+// - De-duplication by (SourcePath, ModTime), with a content-hash check+// when mtime changed: git checkout refreshes mtime on unchanged bytes+// and must not re-attach; a same-size in-place rewrite must.package serviceimport ("context"+ "crypto/sha256"+ "encoding/hex"+ "io""path/filepath""strings""time"@@ -45,10 +49,14 @@ type SandboxArtifactSource interface {// backed by the message repository; in tests it is stubbed with an in-memory// map so the collector can be exercised without a database.type SessionArtifactStore interface {- // KnownArtifacts returns every (SourcePath, ModTime) pair already- // attached to any prior message of the session. The returned set is- // unordered and safe to mutate by the caller.+ // KnownArtifacts returns every artifact already attached to any prior+ // message of the session. The collector uses SourcePath + ModTime as the+ // cheap identity and ContentHash (or the stored blob) when mtime moved.KnownArtifacts(ctx context.Context, sessionID string) ([]types.MessageArtifact, error)+ // RecordRestoredMtime writes the sandbox mtime observed after a same-content+ // restore onto this session's copied artifacts so the next collect can skip+ // by path+mtime. It must not touch any other session. Best-effort.+ RecordRestoredMtime(ctx context.Context, sessionID, sourcePath string, mod time.Time, hash string) error}// ArtifactCollectorConfig bounds the collector's I/O and storage footprint.@@ -233,11 +241,11 @@ func (c *ArtifactCollector) Collect(return c.collect(ctx, sessionID, messageID, tenantID, outputDir, nil)}-// CollectWithNotify is Collect plus a progress hook fired after the sandbox-// listing is filtered, before any file is read or uploaded. The frontend uses-// this to show a toolbar placeholder while object-storage uploads (often a-// few seconds for HTML charts) finish. notify is skipped when nothing will-// be persisted, so ordinary sandbox turns without new files stay quiet.+// CollectWithNotify is Collect plus a progress hook fired after files have+// been hashed and we know they will be uploaded. The frontend uses this to+// show a toolbar placeholder while object-storage uploads (often a few+// seconds for HTML charts) finish. notify is skipped when nothing will be+// persisted, so a fork restore that only refreshes mtime stays quiet.func (c *ArtifactCollector) CollectWithNotify(ctx context.Context,sessionID string,@@ -319,42 +327,46 @@ func (c *ArtifactCollector) collect(// file when several turns share the sandbox. Errors here degrade to an// empty set: attaching duplicates is a soft failure, aborting is not.known := c.loadKnownSet(ctx, sessionID)- if len(known) > 0 {- logger.Infof(ctx, "[ArtifactCollector] known set size=%d (session=%s)", len(known), sessionID)+ if known.len() > 0 {+ logger.Infof(ctx, "[ArtifactCollector] known set size=%d (session=%s)", known.len(), sessionID)}- pending := 0+ // pending uploads are files that passed the hash check. Counting+ // acceptEntry (mtime miss) before the read would treat a git restore as+ // "about to persist" and spin the toolbar on an empty attach.+ var uploads []pendingArtifactUploadfor _, entry := range entries {- if c.acceptEntry(entry, known) {- pending+++ data, hash, ok := c.readNewContent(ctx, source, sessionID, entry, known)+ if !ok {+ continue}+ uploads = append(uploads, pendingArtifactUpload{entry: entry, data: data, hash: hash})+ known.remember(types.MessageArtifact{+ SourcePath: entry.Path, ModTime: entry.ModTime, ContentHash: hash, FileSize: int64(len(data)),+ })}- if pending > 0 && notify != nil {- notify(pending)+ if len(uploads) > 0 && notify != nil {+ notify(len(uploads))}- artifacts = make(types.MessageArtifacts, 0, pending)- for _, entry := range entries {- art, ok := c.maybePersist(ctx, source, sessionID, messageID, tenantID, entry, known)+ artifacts = make(types.MessageArtifacts, 0, len(uploads))+ for _, item := range uploads {+ art, ok := c.persistBytes(ctx, sessionID, messageID, tenantID, item.entry, item.data, item.hash)if !ok {continue}artifacts = append(artifacts, art)- // Adding to the known set inside the loop protects us against the- // pathological case where ListSessionFiles returns the same path- // twice (envd hasn't been observed to do so, but future-proofing- // the loop is cheap).- known[artifactKey(art.SourcePath, art.ModTime)] = struct{}{}+ known.remember(art)}logger.Infof(ctx, "[ArtifactCollector] done session=%s listed=%d attached=%d",sessionID, len(entries), len(artifacts))return artifacts, nil}-// loadKnownSet returns the (source_path, mod_time) tuples already recorded-// against the session. Empty on error so the caller can proceed.-func (c *ArtifactCollector) loadKnownSet(ctx context.Context, sessionID string) map[string]struct{} {- set := map[string]struct{}{}+// loadKnownSet returns the artifacts already recorded against the session.+// Empty on error so the caller can proceed.+func (c *ArtifactCollector) loadKnownSet(ctx context.Context, sessionID string) *artifactKnownSet {+ set := newArtifactKnownSet()if c.store == nil {return set}@@ -365,12 +377,12 @@ func (c *ArtifactCollector) loadKnownSet(ctx context.Context, sessionID string)return set}for _, p := range prev {- set[artifactKey(p.SourcePath, p.ModTime)] = struct{}{}+ set.remember(p)}return set}-func (c *ArtifactCollector) acceptEntry(entry sandbox.RemoteDirEntry, known map[string]struct{}) bool {+func (c *ArtifactCollector) acceptEntry(entry sandbox.RemoteDirEntry, known *artifactKnownSet) bool {if entry.Type != sandbox.RemoteEntryFile {return false}@@ -380,51 +392,69 @@ func (c *ArtifactCollector) acceptEntry(entry sandbox.RemoteDirEntry, known map[if entry.Size > c.config.MaxFileBytes {return false}- if _, seen := known[artifactKey(entry.Path, entry.ModTime)]; seen {- return false- }- return true+ return !known.seenMtime(entry.Path, entry.ModTime)}-// maybePersist runs the per-file pipeline (filter → download → upload →-// build metadata). Returns ok=false when the entry was skipped for any-// reason (already known, too large, upload failed). All skip reasons are-// logged so operators can diagnose empty artifact panels.-func (c *ArtifactCollector) maybePersist(+type pendingArtifactUpload struct {+ entry sandbox.RemoteDirEntry+ data []byte+ hash string+}++// readNewContent downloads an accepted file and returns its bytes when the+// content is new. Same-content restores update this session's mtime and+// return ok=false so they are not counted as pending uploads.+func (c *ArtifactCollector) readNewContent(ctx context.Context,source SandboxArtifactSource,sessionID string,- messageID string,- tenantID uint64,entry sandbox.RemoteDirEntry,- known map[string]struct{},-) (types.MessageArtifact, bool) {+ known *artifactKnownSet,+) ([]byte, string, bool) {if !c.acceptEntry(entry, known) {if entry.Type == sandbox.RemoteEntryFile && entry.Size > c.config.MaxFileBytes {logger.Warnf(ctx, "[ArtifactCollector] skip oversize artifact: session=%s path=%s size=%d limit=%d",sessionID, entry.Path, entry.Size, c.config.MaxFileBytes)}- return types.MessageArtifact{}, false+ return nil, "", false}data, err := source.ReadSessionFile(ctx, sessionID, entry.Path)if err != nil {logger.Warnf(ctx, "[ArtifactCollector] read artifact failed: session=%s path=%s err=%v",sessionID, entry.Path, err)- return types.MessageArtifact{}, false+ return nil, "", false+ }+ hash := artifactContentHash(data)+ if c.knownSameContent(ctx, known, entry.Path, hash) {+ known.remember(types.MessageArtifact{+ SourcePath: entry.Path, ModTime: entry.ModTime, ContentHash: hash, FileSize: int64(len(data)),+ })+ if c.store != nil {+ if err := c.store.RecordRestoredMtime(ctx, sessionID, entry.Path, entry.ModTime, hash); err != nil {+ logger.Warnf(ctx, "[ArtifactCollector] persist restored mtime failed: session=%s path=%s err=%v",+ sessionID, entry.Path, err)+ }+ }+ return nil, "", false}- // A second guard: envd may report a stale size while the file is being- // re-written; enforce the cap against the actual byte count too.if int64(len(data)) > c.config.MaxFileBytes {logger.Warnf(ctx, "[ArtifactCollector] skip oversize artifact after read: session=%s path=%s size=%d limit=%d",sessionID, entry.Path, len(data), c.config.MaxFileBytes)- return types.MessageArtifact{}, false+ return nil, "", false}+ return data, hash, true+}- // Give each blob a UUID-namespaced storage name so concurrent turns- // cannot collide, and so the storage key itself is unguessable from- // the outside (defence-in-depth on top of the /artifacts/:index- // endpoint's ownership check).+func (c *ArtifactCollector) persistBytes(+ ctx context.Context,+ sessionID string,+ messageID string,+ tenantID uint64,+ entry sandbox.RemoteDirEntry,+ data []byte,+ hash string,+) (types.MessageArtifact, bool) {storageName := "artifact_" + uuid.NewString() + "_" + safeFileName(entry.Name)storagePath, err := c.fileService.SaveBytes(ctx, data, tenantID, storageName, false)if err != nil {@@ -436,16 +466,58 @@ func (c *ArtifactCollector) maybePersist(c.bindArtifactResource(ctx, storagePath, messageID)return types.MessageArtifact{- URL: storagePath,- FileName: entry.Name,- FileType: strings.ToLower(filepath.Ext(entry.Name)),- FileSize: int64(len(data)),- SourcePath: entry.Path,- ModTime: entry.ModTime,- CreatedAt: time.Now().UTC(),+ URL: storagePath,+ FileName: entry.Name,+ FileType: strings.ToLower(filepath.Ext(entry.Name)),+ FileSize: int64(len(data)),+ ContentHash: hash,+ SourcePath: entry.Path,+ ModTime: entry.ModTime,+ CreatedAt: time.Now().UTC(),}, true}+func (c *ArtifactCollector) knownSameContent(ctx context.Context, known *artifactKnownSet, path, hash string) bool {+ if known == nil || hash == "" {+ return false+ }+ if known.seenHash(path, hash) {+ return true+ }+ for _, art := range known.byPath[path] {+ if art.ContentHash == hash {+ return true+ }+ if art.ContentHash != "" {+ continue+ }+ stored := c.hashStoredArtifact(ctx, art)+ if stored != "" {+ known.keys[artifactHashKey(path, stored)] = struct{}{}+ if stored == hash {+ return true+ }+ }+ }+ return false+}++func (c *ArtifactCollector) hashStoredArtifact(ctx context.Context, art types.MessageArtifact) string {+ if c == nil || c.fileService == nil || strings.TrimSpace(art.URL) == "" {+ return ""+ }+ file, err := c.fileService.GetFile(ctx, art.URL)+ if err != nil || file == nil {+ return ""+ }+ defer file.Close()+ data, err := io.ReadAll(file)+ if err != nil {+ return ""+ }+ return artifactContentHash(data)+}+// bindArtifactResource records that the freshly-persisted artifact resource// is owned by its assistant message. Best-effort: a binding failure never// discards the artifact, because the file is already stored and remains@@ -469,34 +541,41 @@ func (c *ArtifactCollector) bindArtifactResource(ctx context.Context, ref, messa}}-// ReferencedHistory returns only artifacts from this session explicitly named-// in the answer. Bind these immutable versions to the new message as well, so-// deleting their original message cannot invalidate a later reference.-func (c *ArtifactCollector) ReferencedHistory(ctx context.Context, sessionID, messageID, content string) types.MessageArtifacts {- if c == nil || c.store == nil {- return nil- }- refs := make(map[string]bool)- for _, ref := range types.ScanResourceReferences(content) {- refs[ref] = true- }- if len(refs) == 0 {+// SessionArtifacts returns every artifact already recorded against the session.+// Empty on error, so the caller degrades to "nothing to resolve" rather than+// dropping the turn.+//+// Callers need this to resolve an answer's file references: a turn can name a+// file it did not (re)generate — the first turn after a session fork points the+// sandbox back at an earlier commit, so every unchanged file is de-duplicated+// out of that turn's own artifact list — and the reference still has to be bound+// to that file's stable handle.+func (c *ArtifactCollector) SessionArtifacts(ctx context.Context, sessionID string) types.MessageArtifacts {+ if c == nil || c.store == nil || sessionID == "" {return nil}previous, err := c.store.KnownArtifacts(ctx, sessionID)if err != nil {- logger.Warnf(ctx, "Read referenced artifact history failed: %v", err)+ logger.Warnf(ctx, "Read session artifacts failed: %v", err)return nil}- var result types.MessageArtifacts- for _, artifact := range previous {- if refs[artifact.URL] {- result = append(result, artifact)- c.bindArtifactResource(ctx, artifact.URL, messageID)- delete(refs, artifact.URL)- }+ return previous+}++// BindArtifactsToMessage makes messageID an owner of each artifact's resource+// handle as well. Deleting the message that originally produced the file then+// cannot invalidate a reference made from a later one. Best-effort: a binding+// failure never discards the artifact, which is already stored and downloadable+// through the /artifacts endpoint.+func (c *ArtifactCollector) BindArtifactsToMessage(+ ctx context.Context, messageID string, artifacts types.MessageArtifacts,+) {+ if c == nil || c.catalog == nil || messageID == "" {+ return+ }+ for _, artifact := range artifacts {+ c.bindArtifactResource(ctx, artifact.URL, messageID)}- return result}// artifactKey is the string form of the (source_path, mtime) tuple used to@@ -510,6 +589,72 @@ func artifactKey(path string, mod time.Time) string {return path + "\x00" + mod.UTC().Format(time.RFC3339Nano)}+func artifactHashKey(path, hash string) string {+ return path + "\x00h" + hash+}++func artifactContentHash(data []byte) string {+ sum := sha256.Sum256(data)+ return hex.EncodeToString(sum[:])+}++// artifactKnownSet is the per-collect de-dupe index. path+mtime is the cheap+// skip for an untouched file; path+hash catches a restore that only changed+// mtime. Size is never an identity key.+type artifactKnownSet struct {+ keys map[string]struct{}+ byPath map[string][]types.MessageArtifact+}++func newArtifactKnownSet() *artifactKnownSet {+ return &artifactKnownSet{+ keys: map[string]struct{}{},+ byPath: map[string][]types.MessageArtifact{},+ }+}++func (k *artifactKnownSet) len() int {+ if k == nil {+ return 0+ }+ return len(k.keys)+}++func (k *artifactKnownSet) remember(art types.MessageArtifact) {+ if k == nil {+ return+ }+ if k.keys == nil {+ k.keys = map[string]struct{}{}+ }+ if k.byPath == nil {+ k.byPath = map[string][]types.MessageArtifact{}+ }+ k.keys[artifactKey(art.SourcePath, art.ModTime)] = struct{}{}+ if art.ContentHash != "" {+ k.keys[artifactHashKey(art.SourcePath, art.ContentHash)] = struct{}{}+ }+ if art.SourcePath != "" {+ k.byPath[art.SourcePath] = append(k.byPath[art.SourcePath], art)+ }+}++func (k *artifactKnownSet) seenMtime(path string, mod time.Time) bool {+ if k == nil {+ return false+ }+ _, ok := k.keys[artifactKey(path, mod)]+ return ok+}++func (k *artifactKnownSet) seenHash(path, hash string) bool {+ if k == nil || hash == "" {+ return false+ }+ _, ok := k.keys[artifactHashKey(path, hash)]+ return ok+}+// safeFileName strips slashes and backslashes from the original name before// concatenating it into the storage key. The FileService may or may not// sanitise on its own; belt-and-suspenders here avoids provider-specificdiff --git a/internal/application/service/artifact_collector_store.go b/internal/application/service/artifact_collector_store.goindex 6617c0508..077e7bb2a 100644--- a/internal/application/service/artifact_collector_store.go+++ b/internal/application/service/artifact_collector_store.go@@ -2,6 +2,7 @@ package serviceimport ("context"+ "time""github.com/Tencent/WeKnora/internal/types""github.com/Tencent/WeKnora/internal/types/interfaces"@@ -34,3 +35,53 @@ func (s *messageRepoArtifactStore) KnownArtifacts(}return arts, nil}++// RecordRestoredMtime stamps checkout mtimes onto this session's copied+// artifacts only. The parent session is a different session_id and is not+// loaded here.+func (s *messageRepoArtifactStore) RecordRestoredMtime(+ ctx context.Context, sessionID, sourcePath string, mod time.Time, hash string,+) error {+ if s == nil || s.repo == nil || sessionID == "" || sourcePath == "" {+ return nil+ }+ if rewriter, ok := s.repo.(restoredArtifactMtimeRewriter); ok {+ return rewriter.RecordRestoredArtifactMtime(ctx, sessionID, sourcePath, mod, hash)+ }+ return s.recordRestoredMtimeViaMessages(ctx, sessionID, sourcePath, mod, hash)+}++type restoredArtifactMtimeRewriter interface {+ RecordRestoredArtifactMtime(ctx context.Context, sessionID, sourcePath string, mod time.Time, hash string) error+}++func (s *messageRepoArtifactStore) recordRestoredMtimeViaMessages(+ ctx context.Context, sessionID, sourcePath string, mod time.Time, hash string,+) error {+ const pageSize = 200+ for page := 1; ; page++ {+ messages, err := s.repo.GetMessagesBySession(ctx, sessionID, page, pageSize)+ if err != nil {+ return err+ }+ if len(messages) == 0 {+ return nil+ }+ for _, message := range messages {+ if message == nil {+ continue+ }+ updated, changed := message.Artifacts.WithRestoredMtime(sourcePath, mod, hash)+ if !changed {+ continue+ }+ message.Artifacts = updated+ if err := s.repo.UpdateMessage(ctx, message); err != nil {+ return err+ }+ }+ if len(messages) < pageSize {+ return nil+ }+ }+}diff --git a/internal/application/service/artifact_collector_test.go b/internal/application/service/artifact_collector_test.goindex d37b513ef..5e44cf5d6 100644--- a/internal/application/service/artifact_collector_test.go+++ b/internal/application/service/artifact_collector_test.go@@ -63,6 +63,14 @@ func (s *fakeStore) KnownArtifacts(_ context.Context, _ string) ([]types.Messagereturn s.prev, s.err}+func (s *fakeStore) RecordRestoredMtime(_ context.Context, _, sourcePath string, mod time.Time, hash string) error {+ updated, changed := types.MessageArtifacts(s.prev).WithRestoredMtime(sourcePath, mod, hash)+ if changed {+ s.prev = updated+ }+ return nil+}+// fakeFileService captures uploads and returns a deterministic provider URL.// Only SaveBytes is exercised by the collector; the other methods are// implemented to satisfy interfaces.FileService but panic on use so a@@ -94,8 +102,11 @@ func (f *fakeFileService) SaveBytes(_ context.Context, data []byte, tenantID uinreturn key, nil}-func (f *fakeFileService) GetFile(_ context.Context, _ string) (io.ReadCloser, error) {- panic("GetFile should not be called by ArtifactCollector")+func (f *fakeFileService) GetFile(_ context.Context, filePath string) (io.ReadCloser, error) {+ if data, ok := f.saved[filePath]; ok {+ return io.NopCloser(strings.NewReader(string(data))), nil+ }+ return nil, stderrors.New("fake file service: not found: " + filePath)}func (f *fakeFileService) GetFileURL(_ context.Context, _ string) (string, error) {@@ -150,12 +161,15 @@ type fakeCatalog struct {func (c *fakeCatalog) Register(context.Context, uint64, string, interfaces.ResourceRegistration) (string, error) {return "", nil}+func (c *fakeCatalog) Resolve(context.Context, string) (*types.StoredResource, error) {return nil, nil}+func (c *fakeCatalog) ResolvePath(_ context.Context, v string) (string, *types.StoredResource, error) {return v, nil, nil}+func (c *fakeCatalog) Bind(_ context.Context, ref, ownerType, ownerID, relation string) error {c.binds = append(c.binds, bindCall{ref, ownerType, ownerID, relation})return c.bindErr@@ -172,9 +186,11 @@ func (c *fakeCatalog) Release(_ context.Context, ref, ownerType, ownerID string)}return -1, nil}+func (c *fakeCatalog) CreateAccessGrant(context.Context, string, time.Duration) (string, error) {return "", nil}+func (c *fakeCatalog) ResolveAccessGrant(context.Context, string) (*types.StoredResource, error) {return nil, nil}@@ -257,12 +273,16 @@ func TestArtifactCollector_NotifyFiresBeforeUpload(t *testing.T) {"/workspace/output/b.csv": []byte("x,"),},}- c := newTestCollector(src, &fakeStore{}, &fakeFileService{}, 1<<20)+ fs := &fakeFileService{}+ c := newTestCollector(src, &fakeStore{}, fs, 1<<20)var notified intgot, err := c.CollectWithNotify(ctx, "sess-1", "msg-1", 42, "/workspace/output", func(n int) {- if src.readCalls != nil {- t.Fatalf("notify ran after ReadSessionFile: %v", src.readCalls)+ if len(fs.saved) != 0 {+ t.Fatalf("notify ran after SaveBytes: saved=%v", fs.saved)+ }+ if len(src.readCalls) == 0 {+ t.Fatalf("notify should run after hash reads")}notified = n})@@ -277,6 +297,44 @@ func TestArtifactCollector_NotifyFiresBeforeUpload(t *testing.T) {}}+func TestArtifactCollector_NotifySkipsHashMatchedRestores(t *testing.T) {+ ctx := context.Background()+ oldMod, _ := time.Parse(time.RFC3339, "2026-07-10T10:20:33Z")+ src := &fakeSandboxSource{+ entries: map[string][]sandbox.RemoteDirEntry{+ "sess-1": {+ {Name: "report.pptx", Path: "/workspace/output/report.pptx", Type: sandbox.RemoteEntryFile, Size: 4, ModTime: mustParseTime("2026-07-10T10:21:00Z")},+ },+ },+ contents: map[string][]byte{+ "/workspace/output/report.pptx": []byte("PPTX"),+ },+ }+ store := &fakeStore{prev: []types.MessageArtifact{+ {+ SourcePath: "/workspace/output/report.pptx",+ ModTime: oldMod,+ FileSize: 4,+ ContentHash: artifactContentHash([]byte("PPTX")),+ },+ }}+ c := newTestCollector(src, store, &fakeFileService{}, 1<<20)++ notified := 0+ got, err := c.CollectWithNotify(ctx, "sess-1", "msg-1", 42, "/workspace/output", func(n int) {+ notified = n+ })+ if err != nil {+ t.Fatalf("CollectWithNotify() error = %v", err)+ }+ if notified != 0 {+ t.Fatalf("notify count = %d, want 0 (restored files must not look pending)", notified)+ }+ if len(got) != 0 {+ t.Fatalf("CollectWithNotify() len = %d, want 0", len(got))+ }+}+func TestArtifactCollector_SkipsAlreadyKnown(t *testing.T) {ctx := context.Background()mod, _ := time.Parse(time.RFC3339, "2026-07-10T10:20:33Z")@@ -311,13 +369,51 @@ func TestArtifactCollector_SkipsAlreadyKnown(t *testing.T) {}}-func TestArtifactCollector_ReattachesOnMtimeChange(t *testing.T) {+func TestArtifactCollector_SkipsRestoredFileSamePathSameSize(t *testing.T) {+ ctx := context.Background()+ oldMod, _ := time.Parse(time.RFC3339, "2026-07-10T10:20:33Z")+ src := &fakeSandboxSource{+ entries: map[string][]sandbox.RemoteDirEntry{+ "sess-1": {+ // git checkout rewrites the file with a fresh mtime but the+ // same bytes. That must not attach a duplicate to the next+ // assistant message.+ {Name: "report.pptx", Path: "/workspace/output/report.pptx", Type: sandbox.RemoteEntryFile, Size: 4, ModTime: mustParseTime("2026-07-10T10:21:00Z")},+ },+ },+ contents: map[string][]byte{+ "/workspace/output/report.pptx": []byte("PPTX"),+ },+ }+ store := &fakeStore{prev: []types.MessageArtifact{+ {+ SourcePath: "/workspace/output/report.pptx",+ ModTime: oldMod,+ FileSize: 4,+ ContentHash: artifactContentHash([]byte("PPTX")),+ },+ }}+ fs := &fakeFileService{}+ c := newTestCollector(src, store, fs, 1<<20)++ got, err := c.Collect(ctx, "sess-1", "msg-1", 42, "/workspace/output")+ if err != nil {+ t.Fatalf("Collect() error = %v", err)+ }+ if len(got) != 0 {+ t.Fatalf("Collect() len = %d, want 0 (same bytes after restore must not re-attach)", len(got))+ }+ if len(fs.saved) != 0 {+ t.Fatalf("SaveBytes should not have been called; saved=%v", fs.saved)+ }+}++func TestArtifactCollector_SkipsRestoredFileUsingStoredBlob(t *testing.T) {ctx := context.Background()oldMod, _ := time.Parse(time.RFC3339, "2026-07-10T10:20:33Z")src := &fakeSandboxSource{entries: map[string][]sandbox.RemoteDirEntry{"sess-1": {- // Same path as the known set, but a *newer* mtime — must be re-attached.{Name: "report.pptx", Path: "/workspace/output/report.pptx", Type: sandbox.RemoteEntryFile, Size: 4, ModTime: mustParseTime("2026-07-10T10:21:00Z")},},},@@ -325,8 +421,131 @@ func TestArtifactCollector_ReattachesOnMtimeChange(t *testing.T) {"/workspace/output/report.pptx": []byte("PPTX"),},}+ fs := &fakeFileService{saved: map[string][]byte{"fake://prev": []byte("PPTX")}}+ store := &fakeStore{prev: []types.MessageArtifact{+ {SourcePath: "/workspace/output/report.pptx", ModTime: oldMod, FileSize: 4, URL: "fake://prev"},+ }}+ c := newTestCollector(src, store, fs, 1<<20)++ got, err := c.Collect(ctx, "sess-1", "msg-1", 42, "/workspace/output")+ if err != nil {+ t.Fatalf("Collect() error = %v", err)+ }+ if len(got) != 0 {+ t.Fatalf("Collect() len = %d, want 0 (same stored blob after restore must not re-attach)", len(got))+ }+}++func TestArtifactCollector_PersistsRestoredMtimeSoNextTurnDoesNotReread(t *testing.T) {+ ctx := context.Background()+ oldMod, _ := time.Parse(time.RFC3339, "2026-07-10T10:20:33Z")+ newMod := mustParseTime("2026-07-10T10:21:00Z")+ src := &fakeSandboxSource{+ entries: map[string][]sandbox.RemoteDirEntry{+ "fork-1": {+ {Name: "report.pptx", Path: "/workspace/output/report.pptx", Type: sandbox.RemoteEntryFile, Size: 4, ModTime: newMod},+ },+ },+ contents: map[string][]byte{+ "/workspace/output/report.pptx": []byte("PPTX"),+ },+ }+ store := &fakeStore{prev: []types.MessageArtifact{+ {+ SourcePath: "/workspace/output/report.pptx",+ ModTime: oldMod,+ FileSize: 4,+ ContentHash: artifactContentHash([]byte("PPTX")),+ },+ }}+ c := newTestCollector(src, store, &fakeFileService{}, 1<<20)++ got, err := c.Collect(ctx, "fork-1", "msg-1", 42, "/workspace/output")+ if err != nil {+ t.Fatalf("first Collect() error = %v", err)+ }+ if len(got) != 0 {+ t.Fatalf("first Collect() len = %d, want 0", len(got))+ }+ if len(src.readCalls) != 1 {+ t.Fatalf("first Collect() reads = %d, want 1 (hash restore)", len(src.readCalls))+ }+ if !store.prev[0].ModTime.Equal(newMod) {+ t.Fatalf("restored mtime not written back: got %v want %v", store.prev[0].ModTime, newMod)+ }++ src.readCalls = nil+ got, err = c.Collect(ctx, "fork-1", "msg-2", 42, "/workspace/output")+ if err != nil {+ t.Fatalf("second Collect() error = %v", err)+ }+ if len(got) != 0 {+ t.Fatalf("second Collect() len = %d, want 0", len(got))+ }+ if len(src.readCalls) != 0 {+ t.Fatalf("second Collect() should hit path+mtime and skip the read; readCalls=%v", src.readCalls)+ }+}++func TestArtifactCollector_ReattachesOnMtimeChange(t *testing.T) {+ ctx := context.Background()+ oldMod, _ := time.Parse(time.RFC3339, "2026-07-10T10:20:33Z")+ src := &fakeSandboxSource{+ entries: map[string][]sandbox.RemoteDirEntry{+ "sess-1": {+ // Same path, newer mtime *and* a different size — the skill+ // actually rewrote the file this turn.+ {+ Name: "report.pptx",+ Path: "/workspace/output/report.pptx",+ Type: sandbox.RemoteEntryFile,+ Size: 8,+ ModTime: mustParseTime("2026-07-10T10:21:00Z"),+ },+ },+ },+ contents: map[string][]byte{+ "/workspace/output/report.pptx": []byte("PPTX-NEW"),+ },+ }+ store := &fakeStore{prev: []types.MessageArtifact{+ {SourcePath: "/workspace/output/report.pptx", ModTime: oldMod, FileSize: 4},+ }}+ fs := &fakeFileService{}+ c := newTestCollector(src, store, fs, 1<<20)++ got, err := c.Collect(ctx, "sess-1", "msg-1", 42, "/workspace/output")+ if err != nil {+ t.Fatalf("Collect() error = %v", err)+ }+ if len(got) != 1 {+ t.Fatalf("Collect() len = %d, want 1 (rewritten file should re-attach)", len(got))+ }+ if len(fs.saved) != 1 {+ t.Fatalf("SaveBytes calls = %d, want 1", len(fs.saved))+ }+}++func TestArtifactCollector_ReattachesSameSizeDifferentContent(t *testing.T) {+ ctx := context.Background()+ oldMod, _ := time.Parse(time.RFC3339, "2026-07-10T10:20:33Z")+ oldBytes := []byte("PPTX")+ newBytes := []byte("PPT!")+ if len(oldBytes) != len(newBytes) {+ t.Fatal("fixture must keep size identical so a size-key skip would hide the rewrite")+ }+ src := &fakeSandboxSource{+ entries: map[string][]sandbox.RemoteDirEntry{+ "sess-1": {+ {Name: "report.pptx", Path: "/workspace/output/report.pptx", Type: sandbox.RemoteEntryFile, Size: int64(len(newBytes)), ModTime: mustParseTime("2026-07-10T10:21:00Z")},+ },+ },+ contents: map[string][]byte{+ "/workspace/output/report.pptx": newBytes,+ },+ }store := &fakeStore{prev: []types.MessageArtifact{- {SourcePath: "/workspace/output/report.pptx", ModTime: oldMod},+ {SourcePath: "/workspace/output/report.pptx", ModTime: oldMod, FileSize: int64(len(oldBytes)), ContentHash: artifactContentHash(oldBytes)},}}fs := &fakeFileService{}c := newTestCollector(src, store, fs, 1<<20)@@ -336,7 +555,7 @@ func TestArtifactCollector_ReattachesOnMtimeChange(t *testing.T) {t.Fatalf("Collect() error = %v", err)}if len(got) != 1 {- t.Fatalf("Collect() len = %d, want 1 (mtime-change should re-attach)", len(got))+ t.Fatalf("Collect() len = %d, want 1 (same-size rewrite must still attach)", len(got))}if len(fs.saved) != 1 {t.Fatalf("SaveBytes calls = %d, want 1", len(fs.saved))diff --git a/internal/application/service/fork_bootstrapper.go b/internal/application/service/fork_bootstrapper.gonew file mode 100644index 000000000..29b90a308--- /dev/null+++ b/internal/application/service/fork_bootstrapper.go@@ -0,0 +1,372 @@+// Package service - forked-session sandbox bootstrap.+//+// ForkBootstrapper implements sandbox.SessionBootstrapper for forked sessions:+// it points the first create at the fork snapshot, then rolls /workspace back+// to the fork point with git. Git tracks the full tree, including input/ and+// output/; object storage is not rewritten into the sandbox.+//+// The provider snapshot is the live sandbox at fork *time*, so reset must+// also drop later-turn git objects. Otherwise `git checkout` of a post-fork+// commit would restore files the working tree just rolled back. Packages and+// other paths outside /workspace stay at the fork moment; that is intentional.+//+// It is all-or-nothing for the filesystem: handing back a sandbox that sits+// at the fork MOMENT rather than the fork POINT would look normal while+// silently working from the wrong baseline. Snapshot deletion is not part of+// that contract — Cube refuses to delete a snapshot while the source and+// child sandboxes still hold runtime refs, and failing the bootstrap for that+// would destroy a correctly rolled-back sandbox.+package service++import (+ "context"+ "errors"+ "fmt"+ "strings"+ "time"++ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+)++// ForkSnapshotDeleter retires a consumed or abandoned fork snapshot.+type ForkSnapshotDeleter interface {+ DeleteSnapshot(ctx context.Context, snapshotID string) error+}++type forkBootstrapSessionStore interface {+ GetByID(ctx context.Context, tenantID uint64, id string) (*types.Session, error)+ UpdateForkBootstrap(ctx context.Context, sessionID string, b *types.ForkBootstrap) error+ HasOtherUnconsumedForkSnapshot(ctx context.Context, snapshotID, excludeSessionID string) (bool, error)+}++type forkBootstrapMessageStore interface {+ RewriteSandboxCheckpoints(ctx context.Context, sessionID, oldSandboxID, newSandboxID string) error+}++// forkResetTimeout bounds the git rollback. clean -fdx may delete a large+// untracked tree, and gc --prune=now walks leftover objects from later turns,+// so this is more generous than the per-turn checkpoint.+const forkResetTimeout = 90 * time.Second++// ForkBootstrapper provisions forked sessions' first sandbox.+type ForkBootstrapper struct {+ sessions forkBootstrapSessionStore+ messages forkBootstrapMessageStore+ runner SandboxShellRunner+ snapshots ForkSnapshotDeleter+ client sandbox.RemoteSandboxClient+}++// NewForkBootstrapper wires the bootstrapper.+func NewForkBootstrapper(+ sessions forkBootstrapSessionStore,+ messages forkBootstrapMessageStore,+ runner SandboxShellRunner,+ snapshots ForkSnapshotDeleter,+) *ForkBootstrapper {+ return &ForkBootstrapper{+ sessions: sessions,+ messages: messages,+ runner: runner,+ snapshots: snapshots,+ }+}++// NewForkBootstrapperFromRepos is the exported DI constructor. The sandbox+// client is bound later via WithClient.+func NewForkBootstrapperFromRepos(+ sessions interfaces.SessionRepository,+ messages interfaces.MessageRepository,+) *ForkBootstrapper {+ return NewForkBootstrapper(sessions, messages, nil, nil)+}++// WithClient returns a copy that executes AfterCreate against the client+// that created the handle. AfterCreate runs under the session lifecycle+// lock and must not call Resolve.+func (b *ForkBootstrapper) WithClient(client sandbox.RemoteSandboxClient) sandbox.SessionBootstrapper {+ if b == nil {+ return nil+ }+ cp := *b+ cp.client = client+ return &cp+}++// TemplateOverride returns the fork snapshot for a session whose bootstrap is+// still pending.+func (b *ForkBootstrapper) TemplateOverride(+ ctx context.Context, key sandbox.SessionSandboxKey,+) (string, error) {+ pending, err := b.pendingBootstrap(ctx, key)+ if err != nil {+ return "", err+ }+ if pending == nil {+ return "", nil+ }+ return pending.SnapshotID, nil+}++// OnCreateFailed retires a fork snapshot that Create could not boot.+//+// AfterCreate never runs on this path, so git-reset abandon cannot fire.+// NotFound / invalid template mean the snapshot will not start next time+// either; leave transient errors (timeout, capacity, outage) on the row so+// a later Resolve can retry the same snapshot.+func (b *ForkBootstrapper) OnCreateFailed(+ ctx context.Context, key sandbox.SessionSandboxKey, createErr error,+) {+ if b == nil || !forkSnapshotUnusable(createErr) {+ return+ }+ pending, err := b.pendingBootstrap(ctx, key)+ if err != nil {+ logger.Warnf(ctx, "[ForkBootstrap] load bootstrap after create failure: %v", err)+ return+ }+ if pending == nil {+ return+ }+ logger.Warnf(ctx, "[ForkBootstrap] create from snapshot %s failed; abandoning bootstrap: %v",+ pending.SnapshotID, createErr)+ b.abandon(ctx, key.SessionID, pending)+}++func forkSnapshotUnusable(err error) bool {+ return sandbox.IsRemoteNotFound(err) || sandbox.IsRemoteInvalidRequest(err)+}++// AfterCreate rolls the new sandbox back to the fork point.+func (b *ForkBootstrapper) AfterCreate(+ ctx context.Context, key sandbox.SessionSandboxKey, handle sandbox.RemoteSandboxHandle,+) error {+ pending, err := b.pendingBootstrap(ctx, key)+ if err != nil {+ return err+ }+ if pending == nil {+ return nil+ }++ if err := b.resetWorkspace(ctx, key.SessionID, pending.CommitSHA, handle); err != nil {+ // Retire the bootstrap so the next resolve provisions an ordinary+ // sandbox instead of retrying a rollback that just failed.+ b.abandon(ctx, key.SessionID, pending)+ return err+ }++ if err := b.rewriteCopiedCheckpoints(ctx, key.SessionID, pending.SourceSandboxID, handle); err != nil {+ // Git reset succeeded, so the snapshot is still the right disk.+ // Leave bootstrap unconsumed: lifecycle destroys this sandbox and+ // the next Resolve retries from the same snapshot instead of+ // marking consumed with the parent's sandbox ID (SANDBOX_REPLACED+ // on a nested fork).+ return err+ }++ now := time.Now().UTC()+ consumed := *pending+ consumed.ConsumedAt = &now+ if err := b.sessions.UpdateForkBootstrap(ctx, key.SessionID, &consumed); err != nil {+ return fmt.Errorf("mark fork bootstrap consumed: %w", err)+ }++ // Cube (and sometimes Docker/E2B) refuses to delete a snapshot while the+ // source sandbox and the sandbox just created from it still hold runtime+ // refs. Failing here would make lifecycle destroy a correctly rolled-back+ // sandbox, then the next Resolve would boot from the same snapshot and+ // hit the same delete — a create/destroy loop. Snapshot GC is best-effort;+ // the reaper retries leftover IDs after the refs drop.+ if keep, err := b.snapshotStillShared(ctx, key.SessionID, pending.SnapshotID); err != nil {+ logger.Warnf(ctx, "[ForkBootstrap] lookup shared snapshot %s failed; leaving it: %v",+ pending.SnapshotID, err)+ } else if keep {+ logger.Infof(ctx, "[ForkBootstrap] snapshot %s still referenced by another unopened fork; deferring delete",+ pending.SnapshotID)+ } else if err := b.deleteSnapshot(ctx, pending.SnapshotID); err != nil {+ logger.Warnf(ctx, "[ForkBootstrap] delete snapshot %s failed after reset; sandbox kept: %v",+ pending.SnapshotID, err)+ }+ return nil+}++func (b *ForkBootstrapper) pendingBootstrap(+ ctx context.Context, key sandbox.SessionSandboxKey,+) (*types.ForkBootstrap, error) {+ if b == nil || b.sessions == nil {+ return nil, nil+ }+ session, err := b.sessions.GetByID(ctx, key.TenantID, key.SessionID)+ if err != nil {+ return nil, fmt.Errorf("load session for fork bootstrap: %w", err)+ }+ if session == nil || session.ForkBootstrap == nil {+ return nil, nil+ }+ if session.ForkBootstrap.Consumed() {+ return nil, nil+ }+ if strings.TrimSpace(session.ForkBootstrap.SnapshotID) == "" {+ return nil, nil+ }+ return session.ForkBootstrap, nil+}++func (b *ForkBootstrapper) snapshotStillShared(ctx context.Context, sessionID, snapshotID string) (bool, error) {+ if b == nil || b.sessions == nil {+ return false, nil+ }+ return b.sessions.HasOtherUnconsumedForkSnapshot(ctx, snapshotID, sessionID)+}++func forkResetScript(workspace, sha string) (string, error) {+ if !gitSHAPattern.MatchString(sha) {+ return "", fmt.Errorf("fork bootstrap: invalid commit sha %q", truncateForLog(sha))+ }+ ws := shellSingleQuote(workspace)+ return fmt.Sprintf(`set -e+git config --global safe.directory %[1]s+git -C %[1]s reset --hard %[2]s+current=$(git -C %[1]s symbolic-ref -q HEAD || true)+for ref in $(git -C %[1]s for-each-ref --format='%%(refname)'); do+ [ -z "$ref" ] && continue+ [ "$ref" = "$current" ] && continue+ git -C %[1]s update-ref -d "$ref"+done+rm -f %[1]s/.git/ORIG_HEAD %[1]s/.git/FETCH_HEAD+git -C %[1]s reflog expire --expire=now --all+git -C %[1]s gc --prune=now+git -C %[1]s clean -fdx`, ws, sha), nil+}++func shellSingleQuote(s string) string {+ return "'" + strings.ReplaceAll(s, `'`, `'"'"'`) + "'"+}++func gitResetFailure(sha, stderr string) error {+ return fmt.Errorf("fork bootstrap: git reset to %s failed: %s", sha, stderr)+}++// resetWorkspace rolls /workspace back to sha.+//+// reset --hard restores tracked files (including input/ and output/). Other+// refs, ORIG_HEAD, and reflogs still name later-turn commits from the live+// snapshot, so those are deleted and gc'd before clean -fdx; otherwise the+// working tree would look right while `git checkout` could resurrect later+// files. -x then drops leftover untracked files that are not in that commit.+func (b *ForkBootstrapper) resetWorkspace(+ ctx context.Context, sessionID, sha string, handle sandbox.RemoteSandboxHandle,+) error {+ script, err := forkResetScript(sandbox.SessionWorkspaceRoot, strings.TrimSpace(sha))+ if err != nil {+ return err+ }++ if b.client != nil && handle != nil {+ result, err := b.client.Exec(ctx, handle, sandbox.RemoteExecRequest{+ Command: script,+ Shell: true,+ WorkDir: sandbox.SessionWorkspaceRoot,+ Timeout: forkResetTimeout,+ User: sandbox.DefaultSandboxExecUser,+ })+ if err != nil {+ return fmt.Errorf("fork bootstrap: git reset exec: %w", err)+ }+ if result == nil || result.ExitCode != 0 {+ stderr := ""+ if result != nil {+ stderr = result.Stderr+ }+ return gitResetFailure(sha, stderr)+ }+ return nil+ }++ if b.runner == nil {+ return errors.New("fork bootstrap: no shell runner wired")+ }+ result, err := b.runner.ExecShellCommand(+ ctx, sessionID, script, sandbox.SessionWorkspaceRoot, forkResetTimeout, nil,+ )+ if err != nil {+ return fmt.Errorf("fork bootstrap: git reset exec: %w", err)+ }+ if result == nil || result.ExitCode != 0 {+ stderr := ""+ if result != nil {+ stderr = result.Stderr+ }+ return gitResetFailure(sha, stderr)+ }+ return nil+}++func (b *ForkBootstrapper) rewriteCopiedCheckpoints(+ ctx context.Context, sessionID, oldSandboxID string, handle sandbox.RemoteSandboxHandle,+) error {+ if b.messages == nil || handle == nil {+ return nil+ }+ newID := strings.TrimSpace(handle.ID())+ oldID := strings.TrimSpace(oldSandboxID)+ if newID == "" || oldID == "" || newID == oldID {+ return nil+ }+ if err := b.messages.RewriteSandboxCheckpoints(ctx, sessionID, oldID, newID); err != nil {+ return fmt.Errorf("fork bootstrap: rewrite sandbox checkpoints: %w", err)+ }+ return nil+}++// abandon retires a bootstrap that could not be applied.+//+// Clear the bootstrap pointer first. Deleting the snapshot while the row still+// names it is the leak-safe order the reaper uses in reverse: if clear fails,+// the snapshot ID remains so a later pass can retry.+func (b *ForkBootstrapper) abandon(ctx context.Context, sessionID string, pending *types.ForkBootstrap) {+ cleanupCtx := context.WithoutCancel(ctx)+ if err := b.sessions.UpdateForkBootstrap(cleanupCtx, sessionID, nil); err != nil {+ logger.Warnf(cleanupCtx, "[ForkBootstrap] clear bootstrap of %s failed: %v", sessionID, err)+ return+ }+ if pending != nil {+ if keep, err := b.snapshotStillShared(cleanupCtx, sessionID, pending.SnapshotID); err != nil {+ logger.Warnf(cleanupCtx, "[ForkBootstrap] lookup shared snapshot %s failed; leaving it: %v",+ pending.SnapshotID, err)+ } else if keep {+ logger.Infof(cleanupCtx,+ "[ForkBootstrap] snapshot %s still referenced by another unopened fork; deferring delete",+ pending.SnapshotID)+ } else if err := b.deleteSnapshot(cleanupCtx, pending.SnapshotID); err != nil {+ logger.Warnf(cleanupCtx, "[ForkBootstrap] delete snapshot %s failed: %v", pending.SnapshotID, err)+ }+ }+}++func (b *ForkBootstrapper) deleteSnapshot(ctx context.Context, snapshotID string) error {+ if strings.TrimSpace(snapshotID) == "" {+ return nil+ }+ var err error+ if b.snapshots != nil {+ err = b.snapshots.DeleteSnapshot(ctx, snapshotID)+ } else if b.client != nil {+ if mgr, ok := sandbox.SnapshotManagerFrom(b.client); ok {+ err = mgr.DeleteSnapshot(ctx, snapshotID)+ }+ }+ if err == nil || sandbox.IsRemoteNotFound(err) {+ return nil+ }+ return err+}++var _ sandbox.SessionBootstrapper = (*ForkBootstrapper)(nil)++var _ sandbox.SessionBootstrapperWithClient = (*ForkBootstrapper)(nil)+var _ sandbox.SessionCreateFailureHandler = (*ForkBootstrapper)(nil)diff --git a/internal/application/service/fork_bootstrapper_test.go b/internal/application/service/fork_bootstrapper_test.gonew file mode 100644index 000000000..47bb016cb--- /dev/null+++ b/internal/application/service/fork_bootstrapper_test.go@@ -0,0 +1,504 @@+package service++import (+ "context"+ "errors"+ "os"+ "os/exec"+ "path/filepath"+ "strings"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+)++func forkTestCommitSHA() string {+ return strings.Repeat("a", 40)+}++type fakeSnapshotDeleter struct {+ deleted []string+ err error+}++func (f *fakeSnapshotDeleter) DeleteSnapshot(_ context.Context, id string) error {+ f.deleted = append(f.deleted, id)+ return f.err+}++type fakeHandle struct {+ id string+}++func (h fakeHandle) ID() string { return h.id }+func (h fakeHandle) Provider() sandbox.RemoteProvider { return sandbox.SandboxTypeCube }+func (h fakeHandle) Metadata() map[string]string { return nil }++func pendingForkSession() *types.Session {+ return &types.Session{+ ID: "fork-1", TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-1", CommitSHA: forkTestCommitSHA(),+ SourceSandboxID: "sbx-1", CreatedAt: time.Now().UTC(),+ },+ }+}++func forkKey() sandbox.SessionSandboxKey {+ return sandbox.SessionSandboxKey{TenantID: 1, SessionID: "fork-1"}+}++func TestTemplateOverrideReturnsSnapshotForPendingFork(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ b := NewForkBootstrapper(sessions, nil, nil, nil)++ got, err := b.TemplateOverride(context.Background(), forkKey())++ require.NoError(t, err)+ require.Equal(t, "snap-1", got)+}++func TestTemplateOverrideIsEmptyForOrdinarySession(t *testing.T) {+ sessions := newFakeSessionStore(&types.Session{ID: "fork-1", TenantID: 1})+ b := NewForkBootstrapper(sessions, nil, nil, nil)++ got, err := b.TemplateOverride(context.Background(), forkKey())++ require.NoError(t, err)+ require.Empty(t, got)+}++func TestTemplateOverrideIsEmptyForConsumedFork(t *testing.T) {+ s := pendingForkSession()+ at := time.Now().UTC()+ s.ForkBootstrap.ConsumedAt = &at+ sessions := newFakeSessionStore(s)+ b := NewForkBootstrapper(sessions, nil, nil, nil)++ got, err := b.TemplateOverride(context.Background(), forkKey())++ require.NoError(t, err)+ require.Empty(t, got)+}++func TestTemplateOverridePropagatesLookupError(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.getErr = errors.New("db down")+ b := NewForkBootstrapper(sessions, nil, nil, nil)++ _, err := b.TemplateOverride(context.Background(), forkKey())++ require.Error(t, err)+}++func TestAfterCreateResetsWorkspaceThenConsumesAndDeletesSnapshot(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, snapshots)++ require.NoError(t, b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"}))++ require.Len(t, runner.calls, 1)+ script := runner.calls[0]+ require.Contains(t, script, "reset --hard "+forkTestCommitSHA())+ require.Contains(t, script, "reflog expire --expire=now --all")+ require.Contains(t, script, "gc --prune=now")+ require.Contains(t, script, "clean -fdx")+ require.Contains(t, script, "ORIG_HEAD")++ require.Equal(t, []string{"snap-1"}, snapshots.deleted)+ require.NotNil(t, sessions.updatedBootstrap)+ require.True(t, sessions.updatedBootstrap.Consumed())+}++func TestAfterCreateConsumesWhenSnapshotDeleteFailsAfterReset(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ snapshots := &fakeSnapshotDeleter{err: sandbox.NewRemoteError(+ sandbox.SandboxTypeCube, "DeleteSnapshot", sandbox.RemoteErrorKindConflict,+ "CubeMaster returned error code 130409: template attempt is already in progress: "++ "snapshot snap-1 still has 2 active runtime ref(s): src@host, fork@host (HTTP 500)",+ nil,+ )}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, snapshots)++ err := b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"})++ require.NoError(t, err, "git reset succeeded; an in-use Cube snapshot must not destroy the sandbox")+ require.Equal(t, []string{"snap-1"}, snapshots.deleted)+ require.False(t, sessions.bootstrapCleared)+ require.True(t, sessions.updatedBootstrap.Consumed())+ require.Equal(t, "snap-1", sessions.updatedBootstrap.SnapshotID)++ got, overrideErr := b.TemplateOverride(context.Background(), forkKey())+ require.NoError(t, overrideErr)+ require.Empty(t, got, "retry must not boot another sandbox from the same snapshot")+}++func TestAfterCreateSkipsDeleteWhenSiblingStillNeedsSnapshot(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ sessions.unconsumed = []*types.Session{{+ ID: "fork-2", TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-1", CreatedAt: time.Now().UTC(),+ },+ }}+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, snapshots)++ require.NoError(t, b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"}))++ require.Empty(t, snapshots.deleted, "a sibling still boots from this snapshot")+ require.True(t, sessions.updatedBootstrap.Consumed())+ require.Equal(t, "snap-1", sessions.updatedBootstrap.SnapshotID)+}++func TestAfterCreateResetFailKeepsSnapshotWhenClearFails(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ sessions.clearErr = errors.New("db down")+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{+ ExitCode: 128, Stderr: "fatal: bad object " + forkTestCommitSHA(),+ }}+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, snapshots)++ err := b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"})++ require.Error(t, err)+ require.False(t, sessions.bootstrapCleared)+ require.Empty(t, snapshots.deleted)+ require.NotNil(t, sessions.source.ForkBootstrap)+}++func TestAfterCreateRewritesCopiedCheckpointsToNewSandboxID(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ committedAt := time.Date(2026, 9, 10, 9, 0, 1, 0, time.UTC)+ messages := newFakeMessageStore([]*types.Message{{+ ID: "a1", SessionID: "fork-1", Role: "assistant",+ SandboxCheckpoint: &types.SandboxCheckpoint{+ SandboxID: "sbx-1", CommitSHA: forkTestCommitSHA(), CommittedAt: committedAt,+ },+ }})+ b := NewForkBootstrapper(sessions, messages, runner, &fakeSnapshotDeleter{})++ require.NoError(t, b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"}))++ require.Equal(t, "sbx-2", messages.messages[0].SandboxCheckpoint.SandboxID)+ require.Equal(t, forkTestCommitSHA(), messages.messages[0].SandboxCheckpoint.CommitSHA)+ require.Equal(t, committedAt, messages.messages[0].SandboxCheckpoint.CommittedAt)+ require.True(t, sessions.updatedBootstrap.Consumed())+}++func TestAfterCreateRewriteFailureDoesNotConsumeBootstrap(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ snapshots := &fakeSnapshotDeleter{}+ messages := newFakeMessageStore([]*types.Message{{+ ID: "a1", SessionID: "fork-1", Role: "assistant",+ SandboxCheckpoint: &types.SandboxCheckpoint{+ SandboxID: "sbx-1", CommitSHA: "abc123",+ },+ }})+ messages.rewriteErr = errors.New("db down")+ b := NewForkBootstrapper(sessions, messages, runner, snapshots)++ err := b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"})++ require.Error(t, err)+ require.False(t, sessions.bootstrapCleared)+ require.Nil(t, sessions.updatedBootstrap)+ require.False(t, sessions.source.ForkBootstrap.Consumed())+ require.Empty(t, snapshots.deleted)+ require.Equal(t, "sbx-1", messages.messages[0].SandboxCheckpoint.SandboxID)++ got, overrideErr := b.TemplateOverride(context.Background(), forkKey())+ require.NoError(t, overrideErr)+ require.Equal(t, "snap-1", got, "retry must boot from the same snapshot")+}++func TestAfterCreateIsNoOpForOrdinarySession(t *testing.T) {+ sessions := newFakeSessionStore(&types.Session{ID: "fork-1", TenantID: 1})+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, &fakeSnapshotDeleter{})++ require.NoError(t, b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"}))+ require.Empty(t, runner.calls)+}++// 全有或全无:reset 失败必须返回 error,让 lifecycle 销毁这个沙箱。+func TestAfterCreateFailsWhenResetFails(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{+ ExitCode: 128, Stderr: "fatal: bad object " + forkTestCommitSHA(),+ }}+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, snapshots)++ err := b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"})++ require.Error(t, err)+ // 引导失败时清空 bootstrap 并回收快照:下次 resolve 走全新沙箱路径。+ require.Equal(t, []string{"snap-1"}, snapshots.deleted)+ require.True(t, sessions.bootstrapCleared)+}++func TestAfterCreateRejectsInvalidCommitSHAWithoutExec(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ sessions.source.ForkBootstrap.CommitSHA = "HEAD; echo pwned"+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, snapshots)++ err := b.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"})++ require.Error(t, err)+ require.Empty(t, runner.calls)+ require.Contains(t, err.Error(), "invalid commit sha")+}++func TestForkResetScriptRejectsNonHexSHA(t *testing.T) {+ _, err := forkResetScript(sandbox.SessionWorkspaceRoot, "abc123")+ require.Error(t, err)+ _, err = forkResetScript(sandbox.SessionWorkspaceRoot, "")+ require.Error(t, err)+ _, err = forkResetScript(sandbox.SessionWorkspaceRoot, forkTestCommitSHA()+";rm")+ require.Error(t, err)+}++func TestForkResetScriptPrunesLaterCommits(t *testing.T) {+ if _, err := exec.LookPath("git"); err != nil {+ t.Skip("git not available")+ }+ dir := t.TempDir()+ env := isolatedGitEnv(t)+ runGit := func(args ...string) string {+ t.Helper()+ cmd := exec.Command("git", append([]string{"-C", dir}, args...)...)+ cmd.Env = env+ out, err := cmd.CombinedOutput()+ require.NoError(t, err, string(out))+ return strings.TrimSpace(string(out))+ }++ runGit("init")+ runGit("config", "user.email", "[email protected]")+ runGit("config", "user.name", "WeKnora Agent")+ require.NoError(t, os.WriteFile(filepath.Join(dir, "keep.txt"), []byte("early"), 0o644))+ runGit("add", "-A")+ runGit("commit", "-m", "early")+ early := runGit("rev-parse", "HEAD")+ if !gitSHAPattern.MatchString(early) {+ t.Skip("host git is not using SHA-1 object names")+ }++ require.NoError(t, os.WriteFile(filepath.Join(dir, "secret.txt"), []byte("later-secret"), 0o644))+ runGit("add", "-A")+ runGit("commit", "-m", "later")+ later := runGit("rev-parse", "HEAD")+ require.NotEqual(t, early, later)++ script, err := forkResetScript(dir, early)+ require.NoError(t, err)+ cmd := exec.Command("bash", "-c", script)+ cmd.Env = env+ out, err := cmd.CombinedOutput()+ require.NoError(t, err, string(out))++ cat := exec.Command("git", "-C", dir, "cat-file", "-t", later)+ cat.Env = env+ require.Error(t, cat.Run(), "later-turn commit must be unreachable after prune")+ _, err = os.Stat(filepath.Join(dir, "secret.txt"))+ require.True(t, os.IsNotExist(err))+ body, err := os.ReadFile(filepath.Join(dir, "keep.txt"))+ require.NoError(t, err)+ require.Equal(t, "early", string(body))+}++func isolatedGitEnv(t *testing.T) []string {+ t.Helper()+ return append(os.Environ(),+ "GIT_CONFIG_GLOBAL="+filepath.Join(t.TempDir(), "gitconfig"),+ "GIT_CONFIG_NOSYSTEM=1",+ "GIT_AUTHOR_NAME=WeKnora Agent",+ "[email protected]",+ "GIT_COMMITTER_NAME=WeKnora Agent",+ "[email protected]",+ )+}++func TestWithClientNilReceiver(t *testing.T) {+ var b *ForkBootstrapper+ require.Nil(t, b.WithClient(&recordingRemoteClient{}))+}++func TestOnCreateFailedAbandonsWhenSnapshotIsGone(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, nil, nil, snapshots)++ b.OnCreateFailed(context.Background(), forkKey(), sandbox.NewRemoteError(+ sandbox.SandboxTypeCube, "Create", sandbox.RemoteErrorKindNotFound, "template gone", nil,+ ))++ require.True(t, sessions.bootstrapCleared)+ require.Equal(t, []string{"snap-1"}, snapshots.deleted)++ got, err := b.TemplateOverride(context.Background(), forkKey())+ require.NoError(t, err)+ require.Empty(t, got, "retry must boot an ordinary sandbox, not the dead snapshot")+}++func TestOnCreateFailedAbandonsWhenTemplateIsInvalid(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, nil, nil, snapshots)++ // Create HTTP 404 is classified as invalid_request, not not_found.+ b.OnCreateFailed(context.Background(), forkKey(), sandbox.NewRemoteError(+ sandbox.SandboxTypeCube, "Create", sandbox.RemoteErrorKindInvalidRequest, "unknown template", nil,+ ))++ require.True(t, sessions.bootstrapCleared)+ require.Equal(t, []string{"snap-1"}, snapshots.deleted)+}++func TestOnCreateFailedKeepsBootstrapOnTransientError(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, nil, nil, snapshots)++ b.OnCreateFailed(context.Background(), forkKey(), sandbox.NewRemoteError(+ sandbox.SandboxTypeCube, "Create", sandbox.RemoteErrorKindUnavailable, "provider down", nil,+ ))++ require.False(t, sessions.bootstrapCleared)+ require.Empty(t, snapshots.deleted)++ got, err := b.TemplateOverride(context.Background(), forkKey())+ require.NoError(t, err)+ require.Equal(t, "snap-1", got)+}++func TestOnCreateFailedIsNoOpWithoutPendingBootstrap(t *testing.T) {+ sessions := newFakeSessionStore(&types.Session{ID: "fork-1", TenantID: 1})+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, nil, nil, snapshots)++ b.OnCreateFailed(context.Background(), forkKey(), sandbox.NewRemoteError(+ sandbox.SandboxTypeCube, "Create", sandbox.RemoteErrorKindNotFound, "template gone", nil,+ ))++ require.False(t, sessions.bootstrapCleared)+ require.Empty(t, snapshots.deleted)+}++func TestAfterCreateWithClientUsesHandleNotRunner(t *testing.T) {+ sessions := newFakeSessionStore(pendingForkSession())+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{ExitCode: 0}}+ client := &recordingRemoteClient{execResult: &sandbox.RemoteExecResult{ExitCode: 0}}+ snapshots := &fakeSnapshotDeleter{}+ b := NewForkBootstrapper(sessions, newFakeMessageStore(nil), runner, snapshots)++ bound, ok := b.WithClient(client).(*ForkBootstrapper)+ require.True(t, ok)+ require.Same(t, client, bound.client)++ require.NoError(t, bound.AfterCreate(context.Background(), forkKey(), fakeHandle{id: "sbx-2"}))++ require.Empty(t, runner.calls, "AfterCreate must not Resolve via the session runner")+ require.Len(t, client.execs, 1)+ require.True(t, client.execs[0].Shell)+ require.Equal(t, sandbox.SessionWorkspaceRoot, client.execs[0].WorkDir)+ require.Equal(t, sandbox.DefaultSandboxExecUser, client.execs[0].User)+ require.Equal(t, forkResetTimeout, client.execs[0].Timeout)+ require.Contains(t, client.execs[0].Command, "reset --hard "+forkTestCommitSHA())+ require.Contains(t, client.execs[0].Command, "gc --prune=now")+ require.Equal(t, []string{"snap-1"}, snapshots.deleted)+ require.True(t, sessions.updatedBootstrap.Consumed())+}++type recordingRemoteClient struct {+ execs []sandbox.RemoteExecRequest+ execResult *sandbox.RemoteExecResult+ execErr error+}++func (c *recordingRemoteClient) Provider() sandbox.RemoteProvider { return sandbox.SandboxTypeCube }+func (c *recordingRemoteClient) Capabilities() sandbox.RemoteSandboxCapabilities {+ return sandbox.RemoteSandboxCapabilities{}+}+func (c *recordingRemoteClient) Health(context.Context) error { return nil }+func (c *recordingRemoteClient) Create(+ context.Context, sandbox.RemoteCreateRequest,+) (sandbox.RemoteSandboxHandle, error) {+ panic("Create should not be called from AfterCreate")+}++func (c *recordingRemoteClient) Connect(+ context.Context, sandbox.RemoteConnectRequest,+) (sandbox.RemoteSandboxHandle, error) {+ panic("Connect should not be called from AfterCreate")+}++func (c *recordingRemoteClient) Get(context.Context, string) (*sandbox.RemoteSandboxSummary, error) {+ panic("Get should not be called from AfterCreate")+}++func (c *recordingRemoteClient) List(+ context.Context, sandbox.RemoteListFilter,+) ([]sandbox.RemoteSandboxSummary, error) {+ panic("List should not be called from AfterCreate")+}++func (c *recordingRemoteClient) Delete(context.Context, string) error {+ panic("Delete should not be called from AfterCreate")+}++func (c *recordingRemoteClient) Exec(+ _ context.Context, _ sandbox.RemoteSandboxHandle, req sandbox.RemoteExecRequest,+) (*sandbox.RemoteExecResult, error) {+ c.execs = append(c.execs, req)+ if c.execErr != nil {+ return nil, c.execErr+ }+ if c.execResult != nil {+ return c.execResult, nil+ }+ return &sandbox.RemoteExecResult{ExitCode: 0}, nil+}++func (c *recordingRemoteClient) WriteFile(context.Context, sandbox.RemoteSandboxHandle, string, []byte) error {+ panic("WriteFile should not be called from AfterCreate")+}++func (c *recordingRemoteClient) ReadFile(context.Context, sandbox.RemoteSandboxHandle, string) ([]byte, error) {+ panic("ReadFile should not be called from AfterCreate")+}++func (c *recordingRemoteClient) ListDir(+ context.Context, sandbox.RemoteSandboxHandle, string,+) ([]sandbox.RemoteDirEntry, error) {+ panic("ListDir should not be called from AfterCreate")+}++func (c *recordingRemoteClient) MakeDir(context.Context, sandbox.RemoteSandboxHandle, string) error {+ panic("MakeDir should not be called from AfterCreate")+}++func (c *recordingRemoteClient) Remove(context.Context, sandbox.RemoteSandboxHandle, string) error {+ panic("Remove should not be called from AfterCreate")+}++func (c *recordingRemoteClient) Stat(+ context.Context, sandbox.RemoteSandboxHandle, string,+) (*sandbox.RemoteStatEntry, error) {+ panic("Stat should not be called from AfterCreate")+}++var _ sandbox.RemoteSandboxClient = (*recordingRemoteClient)(nil)diff --git a/internal/application/service/fork_snapshot_reaper.go b/internal/application/service/fork_snapshot_reaper.gonew file mode 100644index 000000000..fed988b07--- /dev/null+++ b/internal/application/service/fork_snapshot_reaper.go@@ -0,0 +1,356 @@+// Package service - orphan fork snapshot collection.+//+// A fork takes a provider snapshot immediately but provisions the sandbox+// lazily. A branch the user never opens therefore leaves a snapshot behind+// forever. Persist can also fail after the snapshot already exists, or the+// process can crash before the session row is committed; those IDs live in+// fork_snapshot_leases so this reaper can still find them.+//+// The happy path tries to delete at consume time. Cube often refuses while+// the source and child sandboxes still hold runtime refs, so this reaper+// retries leftover snapshot IDs after those refs drop, and still collects+// forks that were never opened.+package service++import (+ "context"+ "errors"+ "strings"+ "time"++ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+)++// DefaultForkSnapshotRetention is how long an unopened fork keeps its+// snapshot. A week is long enough that "I'll get back to that branch on+// Monday" works, and short enough that abandoned forks do not accumulate.+const DefaultForkSnapshotRetention = 7 * 24 * time.Hour++// DefaultForkSnapshotLeaseGrace is how long a snapshot lease lives before the+// reaper treats it as abandoned. It must outlast CreateForked (milliseconds)+// and a brief process restart, but not a week — there is no session for the+// user to come back to.+const DefaultForkSnapshotLeaseGrace = 15 * time.Minute++type reaperSessionStore interface {+ ListUnconsumedForks(ctx context.Context, olderThan time.Time) ([]*types.Session, error)+ UpdateForkBootstrap(ctx context.Context, sessionID string, b *types.ForkBootstrap) error+ UnconsumedForkSnapshotHolders(ctx context.Context, snapshotID string) ([]string, error)+ ListStaleForkSnapshotLeases(ctx context.Context, olderThan time.Time) ([]*types.ForkSnapshotLease, error)+ DeleteForkSnapshotLease(ctx context.Context, snapshotID string) error+}++type forkSnapshotReleaseStore interface {+ HasOtherUnconsumedForkSnapshot(ctx context.Context, snapshotID, excludeSessionID string) (bool, error)+ CreateForkSnapshotLease(ctx context.Context, lease *types.ForkSnapshotLease) error+}++// ForkSnapshotReaper deletes snapshots of forks that were never opened.+type ForkSnapshotReaper struct {+ sessions reaperSessionStore+ snapshots ForkSnapshotDeleter+ retention time.Duration+}++// NewForkSnapshotReaper wires the reaper.+func NewForkSnapshotReaper(+ sessions reaperSessionStore, snapshots ForkSnapshotDeleter, retention time.Duration,+) *ForkSnapshotReaper {+ if retention <= 0 {+ retention = DefaultForkSnapshotRetention+ }+ return &ForkSnapshotReaper{sessions: sessions, snapshots: snapshots, retention: retention}+}++// NewForkSnapshotReaperFromRepos is the exported DI constructor. It uses the+// default retention; tests inject a shorter window through NewForkSnapshotReaper.+func NewForkSnapshotReaperFromRepos(+ sessions interfaces.SessionRepository, snapshots ForkSnapshotDeleter,+) *ForkSnapshotReaper {+ return NewForkSnapshotReaper(sessions, snapshots, DefaultForkSnapshotRetention)+}++type forkSessionSnapshotDeleter interface {+ DeleteForkSnapshot(ctx context.Context, tenantID uint64, sandboxConfigID, snapshotID string) error+}++// ReapOnce runs a single collection pass and reports how many snapshots it+// retired.+//+// A per-snapshot delete failure is logged and skipped rather than returned:+// one unreachable snapshot must not stop the pass, and the next run retries it.+func (r *ForkSnapshotReaper) ReapOnce(ctx context.Context) (int, error) {+ if r == nil || r.sessions == nil || r.snapshots == nil {+ return 0, nil+ }+ cutoff := time.Now().UTC().Add(-r.retention)+ stale, err := r.sessions.ListUnconsumedForks(ctx, cutoff)+ if err != nil {+ return 0, err+ }++ staleIDs := make(map[string]struct{}, len(stale))+ for _, session := range stale {+ if session != nil {+ staleIDs[session.ID] = struct{}{}+ }+ }++ deleted := make(map[string]bool)+ skipped := make(map[string]bool)+ reaped := 0+ for _, session := range stale {+ if session == nil || session.ForkBootstrap == nil {+ continue+ }+ snapshotID := session.ForkBootstrap.SnapshotID+ if strings.TrimSpace(snapshotID) == "" {+ continue+ }+ if skipped[snapshotID] {+ continue+ }+ if deleted[snapshotID] {+ if err := r.sessions.UpdateForkBootstrap(ctx, session.ID, nil); err != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] clear bootstrap of %s failed: %v",+ session.ID, err)+ continue+ }+ reaped+++ continue+ }++ holders, shareErr := r.sessions.UnconsumedForkSnapshotHolders(ctx, snapshotID)+ if shareErr != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] lookup snapshot holders %s failed; leaving it: %v",+ snapshotID, shareErr)+ continue+ }+ if snapshotHeldOutsideBatch(holders, staleIDs) {+ skipped[snapshotID] = true+ continue+ }++ if err := r.deleteSnapshot(ctx, session, snapshotID); err != nil {+ // Clearing the bootstrap now would drop the only record of this+ // snapshot's ID and leak it permanently. Leave it for next time.+ logger.Warnf(ctx, "[ForkSnapshotReaper] delete %s (session=%s) failed: %v",+ snapshotID, session.ID, err)+ continue+ }+ if err := r.sessions.UpdateForkBootstrap(ctx, session.ID, nil); err != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] clear bootstrap of %s failed: %v",+ session.ID, err)+ continue+ }+ deleted[snapshotID] = true+ reaped+++ }+ leased, err := r.reapSnapshotLeases(ctx, deleted, skipped)+ if err != nil {+ return reaped, err+ }+ reaped += leased+ if reaped > 0 {+ logger.Infof(ctx, "[ForkSnapshotReaper] reaped %d orphan fork snapshot(s)", reaped)+ }+ return reaped, nil+}++// releaseForkSnapshotOnDelete retires a fork snapshot that no remaining live+// session needs. Call it after the session row is gone so a sibling that still+// lists the same snapshot is not stranded. Delete failure writes a lease so+// the reaper can retry; lookup failure does the same rather than risk deleting+// a snapshot another fork still needs.+func releaseForkSnapshotOnDelete(+ ctx context.Context,+ sessions forkSnapshotReleaseStore,+ snapshots ForkSnapshotDeleter,+ session *types.Session,+) {+ if session == nil || session.ForkBootstrap == nil {+ return+ }+ snapshotID := strings.TrimSpace(session.ForkBootstrap.SnapshotID)+ if snapshotID == "" {+ return+ }+ if sessions != nil {+ keep, err := sessions.HasOtherUnconsumedForkSnapshot(ctx, snapshotID, session.ID)+ if err != nil {+ logger.Warnf(ctx, "[SessionFork] lookup snapshot holders %s failed; leasing it: %v",+ snapshotID, err)+ leaseForkSnapshotOnDelete(ctx, sessions, session, snapshotID)+ return+ }+ if keep {+ return+ }+ }+ if err := deleteForkSnapshot(ctx, snapshots, session, snapshotID); err != nil {+ logger.Warnf(ctx, "[SessionFork] delete snapshot %s on session delete failed: %v",+ snapshotID, err)+ leaseForkSnapshotOnDelete(ctx, sessions, session, snapshotID)+ }+}++func leaseForkSnapshotOnDelete(+ ctx context.Context,+ sessions forkSnapshotReleaseStore,+ session *types.Session,+ snapshotID string,+) {+ if sessions == nil || session == nil || strings.TrimSpace(snapshotID) == "" {+ return+ }+ lease := &types.ForkSnapshotLease{+ SnapshotID: snapshotID,+ TenantID: session.TenantID,+ SandboxConfigID: session.SandboxConfigID,+ CreatedAt: time.Now().UTC(),+ }+ if err := sessions.CreateForkSnapshotLease(ctx, lease); err != nil {+ logger.Warnf(ctx, "[SessionFork] record snapshot lease %s failed: %v", snapshotID, err)+ }+}++func (r *ForkSnapshotReaper) reapSnapshotLeases(+ ctx context.Context, deleted, skipped map[string]bool,+) (int, error) {+ cutoff := time.Now().UTC().Add(-DefaultForkSnapshotLeaseGrace)+ leases, err := r.sessions.ListStaleForkSnapshotLeases(ctx, cutoff)+ if err != nil {+ return 0, err+ }+ reaped := 0+ for _, lease := range leases {+ if lease == nil || strings.TrimSpace(lease.SnapshotID) == "" {+ continue+ }+ snapshotID := lease.SnapshotID+ if skipped[snapshotID] {+ continue+ }+ holders, shareErr := r.sessions.UnconsumedForkSnapshotHolders(ctx, snapshotID)+ if shareErr != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] lookup snapshot holders %s failed; leaving lease: %v",+ snapshotID, shareErr)+ continue+ }+ if len(holders) > 0 {+ if err := r.sessions.DeleteForkSnapshotLease(ctx, snapshotID); err != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] clear lease %s failed: %v", snapshotID, err)+ }+ continue+ }+ if deleted[snapshotID] {+ if err := r.sessions.DeleteForkSnapshotLease(ctx, snapshotID); err != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] clear lease %s failed: %v", snapshotID, err)+ continue+ }+ reaped+++ continue+ }+ placeholder := &types.Session{+ TenantID: lease.TenantID,+ SandboxConfigID: lease.SandboxConfigID,+ }+ if err := r.deleteSnapshot(ctx, placeholder, snapshotID); err != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] delete leased snapshot %s failed: %v",+ snapshotID, err)+ continue+ }+ if err := r.sessions.DeleteForkSnapshotLease(ctx, snapshotID); err != nil {+ logger.Warnf(ctx, "[ForkSnapshotReaper] clear lease %s failed: %v", snapshotID, err)+ continue+ }+ deleted[snapshotID] = true+ reaped+++ }+ return reaped, nil+}++func snapshotHeldOutsideBatch(holders []string, staleIDs map[string]struct{}) bool {+ for _, id := range holders {+ if _, inBatch := staleIDs[id]; !inBatch {+ return true+ }+ }+ return false+}++func (r *ForkSnapshotReaper) deleteSnapshot(+ ctx context.Context, session *types.Session, snapshotID string,+) error {+ return deleteForkSnapshot(ctx, r.snapshots, session, snapshotID)+}++func deleteForkSnapshot(+ ctx context.Context, snapshots ForkSnapshotDeleter, session *types.Session, snapshotID string,+) error {+ if snapshots == nil {+ return errors.New("fork snapshot deleter is nil")+ }+ var err error+ if session != nil {+ if scoped, ok := snapshots.(forkSessionSnapshotDeleter); ok {+ err = scoped.DeleteForkSnapshot(ctx, session.TenantID, session.SandboxConfigID, snapshotID)+ } else {+ err = snapshots.DeleteSnapshot(ctx, snapshotID)+ }+ } else {+ err = snapshots.DeleteSnapshot(ctx, snapshotID)+ }+ if err == nil || sandbox.IsRemoteNotFound(err) {+ return nil+ }+ return err+}++type resolverForkSnapshotDeleter struct {+ resolver sandbox.TenantSandboxResolver+ fallback sandbox.Manager+}++// NewResolverForkSnapshotDeleter deletes fork snapshots through the tenant's+// sandbox manager. Cube and E2B credentials are per-tenant, so an ID-only+// delete cannot reach them.+func NewResolverForkSnapshotDeleter(+ resolver sandbox.TenantSandboxResolver, fallback sandbox.Manager,+) ForkSnapshotDeleter {+ return &resolverForkSnapshotDeleter{resolver: resolver, fallback: fallback}+}++func (d *resolverForkSnapshotDeleter) DeleteSnapshot(context.Context, string) error {+ return errors.New("fork snapshot delete requires tenant and sandbox config")+}++type managerSnapshotDeleter interface {+ DeleteSnapshot(ctx context.Context, snapshotID string) error+}++func (d *resolverForkSnapshotDeleter) DeleteForkSnapshot(+ ctx context.Context, tenantID uint64, sandboxConfigID, snapshotID string,+) error {+ if d == nil {+ return errors.New("fork snapshot deleter is nil")+ }+ ctx = context.WithValue(ctx, types.TenantIDContextKey, tenantID)+ mgr, err := resolveTenantSandboxForConfig(ctx, d.resolver, d.fallback, tenantID, sandboxConfigID, nil)+ if err != nil {+ return err+ }+ deleter, ok := mgr.(managerSnapshotDeleter)+ if !ok || deleter == nil {+ return errors.New("sandbox: resolved manager does not support snapshot delete")+ }+ return deleter.DeleteSnapshot(ctx, snapshotID)+}++var (+ _ ForkSnapshotDeleter = (*resolverForkSnapshotDeleter)(nil)+ _ forkSessionSnapshotDeleter = (*resolverForkSnapshotDeleter)(nil)+)diff --git a/internal/application/service/fork_snapshot_reaper_test.go b/internal/application/service/fork_snapshot_reaper_test.gonew file mode 100644index 000000000..a9c46c847--- /dev/null+++ b/internal/application/service/fork_snapshot_reaper_test.go@@ -0,0 +1,343 @@+package service++import (+ "context"+ "errors"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+)++func agedFork(id string, age time.Duration) *types.Session {+ return &types.Session{+ ID: id, TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-" + id,+ CreatedAt: time.Now().UTC().Add(-age),+ },+ }+}++func TestReapDeletesSnapshotAndClearsBootstrap(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.unconsumed = []*types.Session{agedFork("f1", 8*24*time.Hour)}+ snapshots := &fakeSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Equal(t, 1, n)+ require.Equal(t, []string{"snap-f1"}, snapshots.deleted)+ require.True(t, sessions.bootstrapCleared)+}++func TestReapReportsZeroWhenNothingIsOldEnough(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.unconsumed = nil // 仓储层已按 retention 过滤+ reaper := NewForkSnapshotReaper(sessions, &fakeSnapshotDeleter{}, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Zero(t, n)+}++// 一个删不掉的快照不该挡住后面的。+func TestReapContinuesAfterOneDeleteFails(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.unconsumed = []*types.Session{+ agedFork("f1", 8*24*time.Hour),+ agedFork("f2", 9*24*time.Hour),+ }+ snapshots := &fakeSnapshotDeleter{err: errors.New("provider timeout")}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ _, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err, "单个删除失败不该让整轮回收报错")+ require.Len(t, snapshots.deleted, 2, "两个都要尝试")+}++// 删不掉时绝不能清空 bootstrap,否则快照 ID 丢失,快照永久泄漏。+func TestReapKeepsBootstrapWhenDeleteFails(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.unconsumed = []*types.Session{agedFork("f1", 8*24*time.Hour)}+ snapshots := &fakeSnapshotDeleter{err: errors.New("provider timeout")}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ _, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.False(t, sessions.bootstrapCleared)+}++func TestReapDeletesStaleLeaseWithNoSessionHolder(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.leases = []*types.ForkSnapshotLease{{+ SnapshotID: "snap-orphan",+ TenantID: 9,+ SandboxConfigID: "cfg-1",+ CreatedAt: time.Now().UTC().Add(-20 * time.Minute),+ }}+ snapshots := &fakeForkSessionSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Equal(t, 1, n)+ require.Equal(t, []string{"snap-orphan"}, snapshots.forkDeleted)+ require.Empty(t, sessions.leases)+}++func TestReapSkipsFreshLease(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.leases = []*types.ForkSnapshotLease{{+ SnapshotID: "snap-fresh",+ CreatedAt: time.Now().UTC(),+ }}+ snapshots := &fakeSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Zero(t, n)+ require.Empty(t, snapshots.deleted)+ require.Len(t, sessions.leases, 1)+}++func TestReapDropsLeaseWhenSessionHoldsSnapshot(t *testing.T) {+ holder := agedFork("f1", time.Hour)+ holder.ForkBootstrap.SnapshotID = "snap-held"+ sessions := newFakeSessionStore(holder)+ sessions.leases = []*types.ForkSnapshotLease{{+ SnapshotID: "snap-held",+ CreatedAt: time.Now().UTC().Add(-20 * time.Minute),+ }}+ snapshots := &fakeSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Zero(t, n)+ require.Empty(t, snapshots.deleted, "session still needs this snapshot")+ require.Empty(t, sessions.leases, "redundant lease is just bookkeeping")+}++type fakeForkSessionSnapshotDeleter struct {+ fakeSnapshotDeleter+ forkDeleted []string+ forkErr error+ lastTenant uint64+ lastConfig string+}++func (f *fakeForkSessionSnapshotDeleter) DeleteForkSnapshot(+ _ context.Context, tenantID uint64, sandboxConfigID, snapshotID string,+) error {+ f.lastTenant = tenantID+ f.lastConfig = sandboxConfigID+ f.forkDeleted = append(f.forkDeleted, snapshotID)+ return f.forkErr+}++func TestReapPrefersTenantScopedForkDelete(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sess := agedFork("f1", 8*24*time.Hour)+ sess.SandboxConfigID = "cfg-1"+ sessions.unconsumed = []*types.Session{sess}+ snapshots := &fakeForkSessionSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Equal(t, 1, n)+ require.Equal(t, []string{"snap-f1"}, snapshots.forkDeleted)+ require.Equal(t, uint64(1), snapshots.lastTenant)+ require.Equal(t, "cfg-1", snapshots.lastConfig)+ require.Empty(t, snapshots.deleted, "ID-only DeleteSnapshot must not run when tenant-scoped delete exists")+ require.True(t, sessions.bootstrapCleared)+}++func TestReapSkipsSnapshotStillNeededByUnopenedSibling(t *testing.T) {+ sessions := newFakeSessionStore(&types.Session{+ ID: "unopened", TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-shared",+ CreatedAt: time.Now().UTC(),+ },+ })+ consumedAt := time.Now().UTC()+ sessions.unconsumed = []*types.Session{{+ ID: "opened", TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-shared",+ CreatedAt: consumedAt.Add(-time.Minute),+ ConsumedAt: &consumedAt,+ },+ }}+ snapshots := &fakeSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Zero(t, n)+ require.Empty(t, snapshots.deleted)+ require.False(t, sessions.bootstrapCleared)+}++func TestReapDeletesSharedSnapshotOnceBothHoldersAreStale(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.unconsumed = []*types.Session{+ agedFork("f1", 8*24*time.Hour),+ {+ ID: "f2", TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-f1",+ CreatedAt: time.Now().UTC().Add(-9 * 24 * time.Hour),+ },+ },+ }+ snapshots := &fakeSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Equal(t, 2, n)+ require.Equal(t, []string{"snap-f1"}, snapshots.deleted)+}++func TestReapRetriesConsumedLeftoverSnapshot(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ consumedAt := time.Now().UTC()+ sessions.unconsumed = []*types.Session{{+ ID: "fork-1", TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-fork-1",+ CreatedAt: consumedAt.Add(-time.Minute),+ ConsumedAt: &consumedAt,+ },+ }}+ snapshots := &fakeSnapshotDeleter{}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ n, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.Equal(t, 1, n)+ require.Equal(t, []string{"snap-fork-1"}, snapshots.deleted)+ require.True(t, sessions.bootstrapCleared)+}++func TestReapKeepsBootstrapWhenForkDeleteFails(t *testing.T) {+ sessions := newFakeSessionStore(nil)+ sessions.unconsumed = []*types.Session{agedFork("f1", 8*24*time.Hour)}+ snapshots := &fakeForkSessionSnapshotDeleter{forkErr: errors.New("cube timeout")}+ reaper := NewForkSnapshotReaper(sessions, snapshots, 7*24*time.Hour)++ _, err := reaper.ReapOnce(context.Background())++ require.NoError(t, err)+ require.False(t, sessions.bootstrapCleared)+}++type stubSnapshotDeletingManager struct {+ stubPinnedManager+ deleted []string+ err error+}++func (m *stubSnapshotDeletingManager) DeleteSnapshot(_ context.Context, snapshotID string) error {+ m.deleted = append(m.deleted, snapshotID)+ return m.err+}++func TestResolverForkSnapshotDeleterDeletesViaResolvedManager(t *testing.T) {+ mgr := &stubSnapshotDeletingManager{}+ resolver := &stubTenantSandboxResolver{mgr: mgr}+ deleter := NewResolverForkSnapshotDeleter(resolver, nil)+ scoped, ok := deleter.(forkSessionSnapshotDeleter)+ require.True(t, ok)++ err := scoped.DeleteForkSnapshot(context.Background(), 9, "cfg-1", "snap-1")++ require.NoError(t, err)+ require.Equal(t, []string{"snap-1"}, mgr.deleted)+ require.Equal(t, 1, resolver.calls)+ require.Equal(t, "cfg-1", resolver.lastCfg)+}++func TestResolverForkSnapshotDeleterKeepsIDOnlyDeleteUnsupported(t *testing.T) {+ err := NewResolverForkSnapshotDeleter(nil, nil).DeleteSnapshot(context.Background(), "snap-1")+ require.Error(t, err)+}++func TestReleaseForkSnapshotOnDeleteRemovesUnusedSnapshot(t *testing.T) {+ session := &types.Session{+ ID: "fork-1", TenantID: 9, UserID: "u1", SandboxConfigID: "cfg-1",+ ForkBootstrap: &types.ForkBootstrap{SnapshotID: "snap-1", CreatedAt: time.Now().UTC()},+ }+ sessions := newFakeSessionStore(session)+ snapshots := &fakeForkSessionSnapshotDeleter{}++ releaseForkSnapshotOnDelete(context.Background(), sessions, snapshots, session)++ require.Equal(t, []string{"snap-1"}, snapshots.forkDeleted)+ require.Equal(t, uint64(9), snapshots.lastTenant)+ require.Equal(t, "cfg-1", snapshots.lastConfig)+ require.Empty(t, sessions.leases)+}++func TestReleaseForkSnapshotOnDeleteKeepsSharedSnapshot(t *testing.T) {+ session := &types.Session{+ ID: "fork-1", TenantID: 1, UserID: "u1",+ ForkBootstrap: &types.ForkBootstrap{SnapshotID: "snap-shared", CreatedAt: time.Now().UTC()},+ }+ sessions := newFakeSessionStore(session)+ sessions.unconsumed = []*types.Session{{+ ID: "sibling", TenantID: 1,+ ForkBootstrap: &types.ForkBootstrap{SnapshotID: "snap-shared", CreatedAt: time.Now().UTC()},+ }}+ snapshots := &fakeForkSessionSnapshotDeleter{}++ releaseForkSnapshotOnDelete(context.Background(), sessions, snapshots, session)++ require.Empty(t, snapshots.forkDeleted)+ require.Empty(t, sessions.leases)+}++func TestReleaseForkSnapshotOnDeleteLeasesWhenDeleteFails(t *testing.T) {+ session := &types.Session{+ ID: "fork-1", TenantID: 9, UserID: "u1", SandboxConfigID: "cfg-1",+ ForkBootstrap: &types.ForkBootstrap{SnapshotID: "snap-1", CreatedAt: time.Now().UTC()},+ }+ sessions := newFakeSessionStore(session)+ snapshots := &fakeForkSessionSnapshotDeleter{forkErr: errors.New("cube timeout")}++ releaseForkSnapshotOnDelete(context.Background(), sessions, snapshots, session)++ require.Equal(t, []string{"snap-1"}, snapshots.forkDeleted)+ require.Len(t, sessions.leases, 1)+ require.Equal(t, "snap-1", sessions.leases[0].SnapshotID)+ require.Equal(t, uint64(9), sessions.leases[0].TenantID)+ require.Equal(t, "cfg-1", sessions.leases[0].SandboxConfigID)+}++func TestReleaseForkSnapshotOnDeleteSkipsSessionsWithoutBootstrap(t *testing.T) {+ session := &types.Session{ID: "plain", TenantID: 1, UserID: "u1"}+ sessions := newFakeSessionStore(session)+ snapshots := &fakeForkSessionSnapshotDeleter{}++ releaseForkSnapshotOnDelete(context.Background(), sessions, snapshots, session)++ require.Empty(t, snapshots.forkDeleted)+ require.Empty(t, sessions.leases)+}diff --git a/internal/application/service/message.go b/internal/application/service/message.goindex d8eb0b880..4957ef811 100644--- a/internal/application/service/message.go+++ b/internal/application/service/message.go@@ -855,14 +855,14 @@ func (s *messageService) fetchPartnerMessages(ctx context.Context, items []*typeexistingIDs := make(map[string]bool)for _, item := range items {existingIDs[item.ID] = true- rid := item.RequestID- if rid == "" {+ if item.RequestID == "" || item.SessionID == "" {continue}- rs, ok := seen[rid]+ key := searchPairKey(item.SessionID, item.RequestID)+ rs, ok := seen[key]if !ok {rs = &roleSet{}- seen[rid] = rs+ seen[key] = rs}if item.Role == "user" {rs.hasUser = true@@ -871,35 +871,38 @@ func (s *messageService) fetchPartnerMessages(ctx context.Context, items []*type}}- // Find request_ids that need partner lookup- var needFetch []string- for rid, rs := range seen {- if !rs.hasUser || !rs.hasAssistant {- needFetch = append(needFetch, rid)+ needBySession := make(map[string][]string)+ for key, rs := range seen {+ if rs.hasUser && rs.hasAssistant {+ continue}+ sessionID, rid, ok := strings.Cut(key, "\x00")+ if !ok || sessionID == "" || rid == "" {+ continue+ }+ needBySession[sessionID] = append(needBySession[sessionID], rid)}- if len(needFetch) == 0 {- return items- }-- // Fetch partner messages- partners, err := s.messageRepo.GetMessagesByRequestIDs(ctx, needFetch)- if err != nil {- logger.Warnf(ctx, "Failed to fetch partner messages: %v", err)+ if len(needBySession) == 0 {return items}- // Append only messages not already in results- for _, p := range partners {- if existingIDs[p.ID] {- continue+ for sessionID, rids := range needBySession {+ partners, err := s.messageRepo.GetMessagesByRequestIDs(ctx, sessionID, rids)+ if err != nil {+ logger.Warnf(ctx, "Failed to fetch partner messages: %v", err)+ return items+ }+ for _, p := range partners {+ if existingIDs[p.ID] {+ continue+ }+ existingIDs[p.ID] = true+ items = append(items, &types.MessageSearchResultItem{+ MessageWithSession: *p,+ Score: 0, // partner is not directly matched+ MatchType: "",+ })}- existingIDs[p.ID] = true- items = append(items, &types.MessageSearchResultItem{- MessageWithSession: *p,- Score: 0, // partner is not directly matched- MatchType: "",- })}return items@@ -916,10 +919,9 @@ func groupByRequestID(items []*types.MessageSearchResultItem) []*types.MessageSenextOrder := 0for _, item := range items {- key := item.RequestID- if key == "" {- // No request_id — treat as standalone- key = item.ID+ key := item.ID+ if item.RequestID != "" {+ key = searchPairKey(item.SessionID, item.RequestID)}g, exists := groups[key]@@ -976,3 +978,7 @@ func groupByRequestID(items []*types.MessageSearchResultItem) []*types.MessageSereturn result}++func searchPairKey(sessionID, requestID string) string {+ return sessionID + "\x00" + requestID+}diff --git a/internal/application/service/message_artifact_versions_test.go b/internal/application/service/message_artifact_versions_test.goindex 8a68a42d6..14aef3d3e 100644--- a/internal/application/service/message_artifact_versions_test.go+++ b/internal/application/service/message_artifact_versions_test.go@@ -2,6 +2,7 @@ package serviceimport ("context"+ stderrors "errors""testing""github.com/Tencent/WeKnora/internal/types"@@ -37,10 +38,16 @@ func TestHistoricalVersionClarificationAcrossPagination(t *testing.T) {require.Equal(t, 1, repo.calls, "matching current references need no session-wide lookup")}-func TestReferencedArtifactHistoryDoesNotGuessByName(t *testing.T) {+func TestSessionArtifactsReadsEveryRecordedArtifact(t *testing.T) {old := types.MessageArtifact{URL: "resource://dHZ_fFslfs0GgJGaJZGjGA", FileName: "deck.pptx"}- c := &ArtifactCollector{store: &fakeStore{prev: []types.MessageArtifact{old, old}}}- got := c.ReferencedHistory(context.Background(), "session", "message", "")- require.Equal(t, types.MessageArtifacts{old}, got)- require.Empty(t, c.ReferencedHistory(context.Background(), "session", "message", ""))+ c := &ArtifactCollector{store: &fakeStore{prev: []types.MessageArtifact{old}}}+ require.Equal(t, types.MessageArtifacts{old}, c.SessionArtifacts(context.Background(), "session"))++ // A missing store, an empty session, and a lookup failure all degrade to+ // "nothing to resolve" rather than failing the turn.+ require.Nil(t, (&ArtifactCollector{}).SessionArtifacts(context.Background(), "session"))+ require.Nil(t, c.SessionArtifacts(context.Background(), ""))+ require.Nil(t, (&ArtifactCollector{+ store: &fakeStore{err: stderrors.New("boom")},+ }).SessionArtifacts(context.Background(), "session"))}diff --git a/internal/application/service/message_search_group_test.go b/internal/application/service/message_search_group_test.gonew file mode 100644index 000000000..1ea7f76f6--- /dev/null+++ b/internal/application/service/message_search_group_test.go@@ -0,0 +1,73 @@+package service++import (+ "context"+ "testing"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/stretchr/testify/require"+)++func TestGroupByRequestIDKeepsSessionsApart(t *testing.T) {+ items := []*types.MessageSearchResultItem{+ {MessageWithSession: types.MessageWithSession{Message: types.Message{+ ID: "p-u", SessionID: "parent", RequestID: "req", Role: "user", Content: "q-parent",+ }}},+ {MessageWithSession: types.MessageWithSession{Message: types.Message{+ ID: "f-u", SessionID: "fork", RequestID: "req", Role: "user", Content: "q-fork",+ }}},+ }++ got := groupByRequestID(items)++ require.Len(t, got, 2)+ bySession := map[string]string{}+ for _, g := range got {+ bySession[g.SessionID] = g.QueryContent+ }+ require.Equal(t, "q-parent", bySession["parent"])+ require.Equal(t, "q-fork", bySession["fork"])+}++type partnerLookupRepo struct {+ interfaces.MessageRepository+ calls []partnerLookupCall+}++type partnerLookupCall struct {+ sessionID string+ requestIDs []string+}++func (r *partnerLookupRepo) GetMessagesByRequestIDs(+ _ context.Context, sessionID string, requestIDs []string,+) ([]*types.MessageWithSession, error) {+ copied := append([]string(nil), requestIDs...)+ r.calls = append(r.calls, partnerLookupCall{sessionID: sessionID, requestIDs: copied})+ return nil, nil+}++func TestFetchPartnerMessagesQueriesEachSessionSeparately(t *testing.T) {+ repo := &partnerLookupRepo{}+ svc := &messageService{messageRepo: repo}+ items := []*types.MessageSearchResultItem{+ {MessageWithSession: types.MessageWithSession{Message: types.Message{+ ID: "p-u", SessionID: "parent", RequestID: "req", Role: "user",+ }}},+ {MessageWithSession: types.MessageWithSession{Message: types.Message{+ ID: "f-u", SessionID: "fork", RequestID: "req", Role: "user",+ }}},+ }++ got := svc.fetchPartnerMessages(context.Background(), items)++ require.Equal(t, items, got)+ require.Len(t, repo.calls, 2)+ bySession := map[string][]string{}+ for _, call := range repo.calls {+ bySession[call.sessionID] = call.requestIDs+ }+ require.Equal(t, []string{"req"}, bySession["parent"])+ require.Equal(t, []string{"req"}, bySession["fork"])+}diff --git a/internal/application/service/pinned_session_sandbox.go b/internal/application/service/pinned_session_sandbox.gonew file mode 100644index 000000000..48f6916f1--- /dev/null+++ b/internal/application/service/pinned_session_sandbox.go@@ -0,0 +1,150 @@+package service++import (+ "context"+ "errors"+ "strings"+ "time"++ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+)++// sessionSandboxPinReader is the pin lookup used to choose the manager that+// owns a session's binding. *SessionSandboxPinner is the production+// implementation; tests use a stub so this does not need a database.+type sessionSandboxPinReader interface {+ Read(ctx context.Context, sessionID string) (string, error)+}++// PinnedSessionSandbox resolves the session's pinned sandbox manager at+// request time. The process-wide sandbox.Manager is DisabledManager, so+// checkpoint and BoundSandboxID must go through the same pin + tenant+// resolver path ArtifactCollector and SandboxTerminalService already use.+type PinnedSessionSandbox struct {+ pinner sessionSandboxPinReader+ resolver sandbox.TenantSandboxResolver+ fallback sandbox.Manager+}++// NewPinnedSessionSandbox wires request-time sandbox access. Any dependency+// may be nil; BoundSandboxID then reports ok=false and ExecShellCommand+// fails, which WorkspaceCheckpointer treats as "no checkpoint".+func NewPinnedSessionSandbox(+ pinner sessionSandboxPinReader,+ resolver sandbox.TenantSandboxResolver,+ fallback sandbox.Manager,+) *PinnedSessionSandbox {+ return &PinnedSessionSandbox{+ pinner: pinner,+ resolver: resolver,+ fallback: fallback,+ }+}++func (a *PinnedSessionSandbox) manager(ctx context.Context, sessionID string) sandbox.Manager {+ if a == nil || strings.TrimSpace(sessionID) == "" {+ return nil+ }+ if a.pinner == nil {+ return nil+ }+ configID, err := a.pinner.Read(ctx, sessionID)+ if err != nil || strings.TrimSpace(configID) == "" {+ return nil+ }+ tenantID, _ := types.TenantIDFromContext(ctx)+ mgr, err := resolveTenantSandboxForConfig(+ ctx, a.resolver, a.fallback, tenantID, configID, nil,+ )+ if err != nil {+ return nil+ }+ return mgr+}++// BoundSandboxID reports the sandbox currently bound to sessionID without+// provisioning one. A session with no pin or no live binding reports+// ok=false.+func (a *PinnedSessionSandbox) BoundSandboxID(ctx context.Context, sessionID string) (string, bool) {+ mgr := a.manager(ctx, sessionID)+ type lookup interface {+ BoundSandboxID(context.Context, string) (string, bool)+ }+ if l, ok := mgr.(lookup); ok {+ return l.BoundSandboxID(ctx, sessionID)+ }+ return "", false+}++// ExecShellCommand runs a command on the session's pinned sandbox manager.+func (a *PinnedSessionSandbox) ExecShellCommand(+ ctx context.Context,+ sessionID, command, workDir string,+ timeout time.Duration,+ env map[string]string,+) (*sandbox.ExecuteResult, error) {+ mgr := a.manager(ctx, sessionID)+ runner, ok := mgr.(SandboxShellRunner)+ if !ok || runner == nil {+ return nil, errors.New("sandbox: no shell runner for session")+ }+ return runner.ExecShellCommand(ctx, sessionID, command, workDir, timeout, env)+}++// HasActiveTurn reports whether the session's pinned manager currently holds a+// turn lease. Managers that do not expose the method are treated as not busy.+func (a *PinnedSessionSandbox) HasActiveTurn(ctx context.Context, sessionID string) (bool, error) {+ mgr := a.manager(ctx, sessionID)+ type turnChecker interface {+ HasActiveTurn(context.Context, string) (bool, error)+ }+ if checker, ok := mgr.(turnChecker); ok {+ return checker.HasActiveTurn(ctx, sessionID)+ }+ return false, nil+}++// CreateForkSnapshot snapshots the session's already-bound sandbox through the+// pinned manager. Managers that do not expose the method return an error so+// fork can degrade to SNAPSHOT_UNSUPPORTED.+func (a *PinnedSessionSandbox) CreateForkSnapshot(+ ctx context.Context, sessionID, name string,+) (string, error) {+ mgr := a.manager(ctx, sessionID)+ type snapshotter interface {+ CreateForkSnapshot(context.Context, string, string) (string, error)+ }+ if s, ok := mgr.(snapshotter); ok {+ return s.CreateForkSnapshot(ctx, sessionID, name)+ }+ return "", errors.New("sandbox: fork snapshot is not supported")+}++// DeleteForkSnapshot removes a fork snapshot through the session's pinned+// manager. Managers that do not expose the method return an error so the+// caller can keep the lease for the reaper.+func (a *PinnedSessionSandbox) DeleteForkSnapshot(+ ctx context.Context, sessionID, snapshotID string,+) error {+ mgr := a.manager(ctx, sessionID)+ type deleter interface {+ DeleteForkSnapshot(context.Context, string, string) error+ }+ if d, ok := mgr.(deleter); ok {+ return d.DeleteForkSnapshot(ctx, sessionID, snapshotID)+ }+ type snapshotDeleter interface {+ DeleteSnapshot(context.Context, string) error+ }+ if d, ok := mgr.(snapshotDeleter); ok {+ return d.DeleteSnapshot(ctx, snapshotID)+ }+ return errors.New("sandbox: fork snapshot delete is not supported")+}++var _ SandboxShellRunner = (*PinnedSessionSandbox)(nil)++var _ SessionForkSandboxPort = (*PinnedSessionSandbox)(nil)++var _ SessionForkSandboxPort = (*sandbox.SessionBoundManager)(nil)diff --git a/internal/application/service/pinned_session_sandbox_test.go b/internal/application/service/pinned_session_sandbox_test.gonew file mode 100644index 000000000..1ba622a58--- /dev/null+++ b/internal/application/service/pinned_session_sandbox_test.go@@ -0,0 +1,163 @@+package service++import (+ "context"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+)++type stubPinReader struct {+ configID string+ err error+}++func (s stubPinReader) Read(context.Context, string) (string, error) {+ return s.configID, s.err+}++type stubTenantSandboxResolver struct {+ mgr sandbox.Manager+ err error+ calls int+ lastCfg string+}++func (s *stubTenantSandboxResolver) Resolve(_ context.Context, _ uint64, configID string) (sandbox.Manager, error) {+ s.calls+++ s.lastCfg = configID+ return s.mgr, s.err+}++type stubPinnedManager struct {+ id string+ ok bool+ execs int+ execErr error+ execOut *sandbox.ExecuteResult+}++func (m *stubPinnedManager) Execute(context.Context, *sandbox.ExecuteConfig) (*sandbox.ExecuteResult, error) {+ return nil, nil+}+func (m *stubPinnedManager) Cleanup(context.Context) error { return nil }+func (m *stubPinnedManager) GetSandbox() sandbox.Sandbox { return nil }+func (m *stubPinnedManager) GetType() sandbox.SandboxType { return sandbox.SandboxTypeCube }++func (m *stubPinnedManager) BoundSandboxID(context.Context, string) (string, bool) {+ return m.id, m.ok+}++func (m *stubPinnedManager) ExecShellCommand(+ _ context.Context, _ string, _, _ string, _ time.Duration, _ map[string]string,+) (*sandbox.ExecuteResult, error) {+ m.execs+++ if m.execErr != nil {+ return nil, m.execErr+ }+ return m.execOut, nil+}++func TestPinnedSessionSandboxBoundSandboxIDUsesPinnedManager(t *testing.T) {+ mgr := &stubPinnedManager{id: "sbx-1", ok: true}+ resolver := &stubTenantSandboxResolver{mgr: mgr}+ access := NewPinnedSessionSandbox(stubPinReader{configID: "cfg-1"}, resolver, nil)++ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(9))+ id, ok := access.BoundSandboxID(ctx, "sess-1")++ require.True(t, ok)+ require.Equal(t, "sbx-1", id)+ require.Equal(t, 1, resolver.calls)+ require.Equal(t, "cfg-1", resolver.lastCfg)+ require.Zero(t, mgr.execs)+}++func TestPinnedSessionSandboxBoundSandboxIDSkipsWhenUnpinned(t *testing.T) {+ resolver := &stubTenantSandboxResolver{mgr: &stubPinnedManager{id: "sbx-1", ok: true}}+ access := NewPinnedSessionSandbox(stubPinReader{}, resolver, nil)++ id, ok := access.BoundSandboxID(context.Background(), "sess-1")++ require.False(t, ok)+ require.Empty(t, id)+ require.Zero(t, resolver.calls)+}++type stubForkPinnedManager struct {+ stubPinnedManager+ busy bool+ busyErr error+ snapshotID string+ snapErr error+ snapCalls int+ snapName string+}++func (m *stubForkPinnedManager) HasActiveTurn(context.Context, string) (bool, error) {+ return m.busy, m.busyErr+}++func (m *stubForkPinnedManager) CreateForkSnapshot(_ context.Context, _, name string) (string, error) {+ m.snapCalls+++ m.snapName = name+ return m.snapshotID, m.snapErr+}++func TestPinnedSessionSandboxHasActiveTurnDelegates(t *testing.T) {+ mgr := &stubForkPinnedManager{busy: true}+ access := NewPinnedSessionSandbox(+ stubPinReader{configID: "cfg-1"},+ &stubTenantSandboxResolver{mgr: mgr},+ nil,+ )+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(9))++ busy, err := access.HasActiveTurn(ctx, "sess-1")+ require.NoError(t, err)+ require.True(t, busy)+}++func TestPinnedSessionSandboxHasActiveTurnWhenManagerLacksMethod(t *testing.T) {+ access := NewPinnedSessionSandbox(+ stubPinReader{configID: "cfg-1"},+ &stubTenantSandboxResolver{mgr: &stubPinnedManager{id: "sbx-1", ok: true}},+ nil,+ )+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(9))++ busy, err := access.HasActiveTurn(ctx, "sess-1")+ require.NoError(t, err)+ require.False(t, busy)+}++func TestPinnedSessionSandboxCreateForkSnapshotDelegates(t *testing.T) {+ mgr := &stubForkPinnedManager{snapshotID: "snap-9"}+ access := NewPinnedSessionSandbox(+ stubPinReader{configID: "cfg-1"},+ &stubTenantSandboxResolver{mgr: mgr},+ nil,+ )+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(9))++ id, err := access.CreateForkSnapshot(ctx, "sess-1", "fork-name")+ require.NoError(t, err)+ require.Equal(t, "snap-9", id)+ require.Equal(t, 1, mgr.snapCalls)+ require.Equal(t, "fork-name", mgr.snapName)+}++func TestPinnedSessionSandboxCreateForkSnapshotErrorsWhenUnsupported(t *testing.T) {+ access := NewPinnedSessionSandbox(+ stubPinReader{configID: "cfg-1"},+ &stubTenantSandboxResolver{mgr: &stubPinnedManager{id: "sbx-1", ok: true}},+ nil,+ )+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(9))++ _, err := access.CreateForkSnapshot(ctx, "sess-1", "fork-name")+ require.Error(t, err)+}diff --git a/internal/application/service/session.go b/internal/application/service/session.goindex a1e026c27..4c5583ca2 100644--- a/internal/application/service/session.go+++ b/internal/application/service/session.go@@ -134,6 +134,10 @@ type sessionService struct {// TenantSkillService because that service depends on this one.sandboxConfigRepo repository.TenantSandboxConfigRepositorytenantSkillRepo repository.TenantSkillRepository+ // forkSnapshots retires provider snapshots when a forked session is deleted+ // before its sandbox is provisioned. Nil uses NewResolverForkSnapshotDeleter+ // from sandboxResolver/sandboxMgr.+ forkSnapshots ForkSnapshotDeleter}// NewSessionService creates a new session service instance with all required dependencies@@ -480,7 +484,8 @@ func (s *sessionService) DeleteSession(ctx context.Context, id string) error {tenantID := types.MustTenantIDFromContext(ctx)userID := sessionUserIDFromContext(ctx)- if _, err := s.sessionRepo.Get(ctx, tenantID, userID, id); err != nil {+ session, err := s.sessionRepo.Get(ctx, tenantID, userID, id)+ if err != nil {return err}@@ -534,6 +539,7 @@ func (s *sessionService) DeleteSession(ctx context.Context, id string) error {return apperrors.ErrSessionNotFound}+ s.releaseForkSnapshot(ctx, session)return nil}@@ -548,9 +554,12 @@ func (s *sessionService) BatchDeleteSessions(ctx context.Context, ids []string)tenantID := types.MustTenantIDFromContext(ctx)userID := sessionUserIDFromContext(ctx)+ visible := make([]*types.Session, 0, len(ids))visibleIDs := make([]string, 0, len(ids))for _, id := range ids {- if _, err := s.sessionRepo.Get(ctx, tenantID, userID, id); err == nil {+ session, err := s.sessionRepo.Get(ctx, tenantID, userID, id)+ if err == nil {+ visible = append(visible, session)visibleIDs = append(visibleIDs, id)} else if !stderrors.Is(err, apperrors.ErrSessionNotFound) {return err@@ -605,6 +614,7 @@ func (s *sessionService) BatchDeleteSessions(ctx context.Context, ids []string)}}+ s.releaseForkSnapshots(ctx, visible)return nil}@@ -663,6 +673,7 @@ func (s *sessionService) DeleteAllSessions(ctx context.Context) error {}}+ s.releaseForkSnapshots(ctx, sessions)logger.Infof(ctx, "All sessions deleted for tenant %d", tenantID)return nil}@@ -724,6 +735,35 @@ func (s *sessionService) destroyBoundSandbox(ctx context.Context, sessionID stri}}+func (s *sessionService) releaseForkSnapshot(ctx context.Context, session *types.Session) {+ if s == nil || session == nil {+ return+ }+ snapshots := s.forkSnapshots+ if snapshots == nil {+ snapshots = NewResolverForkSnapshotDeleter(s.sandboxResolver, s.sandboxMgr)+ }+ releaseForkSnapshotOnDelete(ctx, s.sessionRepo, snapshots, session)+}++func (s *sessionService) releaseForkSnapshots(ctx context.Context, sessions []*types.Session) {+ seen := make(map[string]struct{}, len(sessions))+ for _, session := range sessions {+ if session == nil || session.ForkBootstrap == nil {+ continue+ }+ snapshotID := strings.TrimSpace(session.ForkBootstrap.SnapshotID)+ if snapshotID == "" {+ continue+ }+ if _, ok := seen[snapshotID]; ok {+ continue+ }+ seen[snapshotID] = struct{}{}+ s.releaseForkSnapshot(ctx, session)+ }+}+// maxSessionTitleRunes bounds the auto-generated session title. sessions.title// is VARCHAR(255) in every shipped migration, so an over-long model response// would be rejected by the database; 100 runes stays well clear of that limitdiff --git a/internal/application/service/session_attachment_staging.go b/internal/application/service/session_attachment_staging.goindex fc9368862..ae8d391fa 100644--- a/internal/application/service/session_attachment_staging.go+++ b/internal/application/service/session_attachment_staging.go@@ -192,12 +192,14 @@ func (s *agentService) stageSessionAttachments(// deliberately excluded from DB serialization (json:"-") so a cross-session// downloadable reference cannot leak; the temporary-document row keyed by// attachment.ID is the authoritative source of the storage reference.+// Lookup is tenant+id (not session-scoped) so a forked session can still+// stage attachments whose temporary_documents row remains on the parent.// Attachments that already carry a URL, or that have no temporary-document ID,// pass through unchanged so callers with other attachment sources keep working.func (s *agentService) resolveSessionAttachmentURLs(ctx context.Context,tenantID uint64,- sessionID string,+ _ string,attachments types.MessageAttachments,) (types.MessageAttachments, error) {if len(attachments) == 0 || s == nil || s.db == nil {@@ -210,7 +212,7 @@ func (s *agentService) resolveSessionAttachmentURLs(out = append(out, attachment)continue}- document, err := repo.GetScoped(ctx, tenantID, sessionID, attachment.ID)+ document, err := repo.GetByID(ctx, tenantID, attachment.ID)if err != nil {return nil, fmt.Errorf("resolve attachment %q storage reference: %w", attachment.FileName, err)}diff --git a/internal/application/service/session_attachment_staging_test.go b/internal/application/service/session_attachment_staging_test.goindex 7cd0cede0..14d673816 100644--- a/internal/application/service/session_attachment_staging_test.go+++ b/internal/application/service/session_attachment_staging_test.go@@ -257,6 +257,59 @@ func TestStageSessionAttachmentsResolvesURLFromTemporaryDocument(t *testing.T) {assert.Equal(t, 1, fileService.getCalls[resourceRef])}+func TestStageSessionAttachmentsResolvesURLFromParentSessionDocument(t *testing.T) {+ db := stagingTempDocDB(t)+ docID := "doc-1"+ resourceRef := "local://tenant/attachment-1"+ require.NoError(t, db.Create(&types.TemporaryDocument{+ ID: docID,+ TenantID: 7,+ SessionID: "parent-session",+ ResourceRef: resourceRef,+ FileName: "report.pdf",+ FileType: ".pdf",+ FileSize: 7,+ Status: types.TemporaryDocumentStatusReady,+ ExpiresAt: time.Now().Add(time.Hour),+ }).Error)++ attachment := types.MessageAttachment{+ ID: docID,+ FileName: "report.pdf",+ FileType: ".pdf",+ FileSize: 7,+ }+ remotePath, err := sandboxAttachmentPath(types.MessageAttachment{+ URL: resourceRef, FileName: "report.pdf",+ })+ require.NoError(t, err)++ manager := &stagingSandboxManager{sandboxType: sandbox.SandboxTypeCube}+ fileService := &stagingFileService{+ files: map[string][]byte{resourceRef: []byte("content")},+ }+ service := &agentService{+ db: db,+ sandboxMgr: manager,+ fileService: fileService,+ sandboxResolver: stubSandboxResolver{mgr: manager},+ }+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(7))++ staged, err := service.stageSessionAttachments(+ ctx,+ "forked-session",+ "cfg-remote",+ 7,+ types.MessageAttachments{attachment},+ )++ require.NoError(t, err)+ require.Len(t, staged, 1)+ assert.Equal(t, remotePath, staged[0].Path)+ assert.Equal(t, []string{remotePath}, manager.writes)+}+func TestStageSessionAttachmentsSkipsMissingTemporaryDocument(t *testing.T) {db := stagingTempDocDB(t)manager := &stagingSandboxManager{sandboxType: sandbox.SandboxTypeCube}diff --git a/internal/application/service/session_fork.go b/internal/application/service/session_fork.gonew file mode 100644index 000000000..67d9a139a--- /dev/null+++ b/internal/application/service/session_fork.go@@ -0,0 +1,509 @@+// Package service - session fork.+//+// Fork copies a session's history through a chosen user or assistant message+// into a brand new session, and arranges for that new session's first sandbox+// to boot from a snapshot of the source sandbox rolled back to the fork point.+//+// The whole operation is cheap and synchronous: it writes the database and+// takes one provider snapshot. No sandbox is created here — provisioning stays+// lazy, exactly as it is for ordinary sessions.+package service++import (+ "context"+ "errors"+ "fmt"+ "strings"+ "time"++ apperrors "github.com/Tencent/WeKnora/internal/errors"+ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/google/uuid"+ "gorm.io/gorm"+)++// ForkDegradeReason explains why a fork could not carry the source sandbox's+// state over. A degraded fork still succeeds — it just starts from a brand new+// sandbox — because the alternative (refusing) would block the common cases:+// Docker kills idle containers outright, and plain chat sessions never had a+// sandbox to begin with.+type ForkDegradeReason string++const (+ // ForkDegradeNoCheckpoint means the turn preceding the fork point never+ // produced a git checkpoint (commit failed, or it ran without a sandbox).+ ForkDegradeNoCheckpoint ForkDegradeReason = "NO_CHECKPOINT"++ // ForkDegradeSandboxReplaced means the checkpoint belongs to a sandbox the+ // session no longer uses. In-sandbox git history restarts from zero on+ // every rebuild, so that SHA is unreachable from the current sandbox.+ ForkDegradeSandboxReplaced ForkDegradeReason = "SANDBOX_REPLACED"++ // ForkDegradeSandboxGone means the source session has no live sandbox to+ // snapshot.+ ForkDegradeSandboxGone ForkDegradeReason = "SANDBOX_GONE"++ // ForkDegradeSnapshotUnsupported means snapshotting failed or the backend+ // does not support it.+ ForkDegradeSnapshotUnsupported ForkDegradeReason = "SNAPSHOT_UNSUPPORTED"+)++var (+ // ErrForkSourceBusy reports that the source session has an agent turn in+ // flight. Snapshotting pauses the source sandbox on every backend, which+ // would interrupt a tool mid-execution, so the fork is refused rather than+ // queued. HTTP 409.+ ErrForkSourceBusy = errors.New("session fork: source session has an active turn")++ // ErrForkSessionNotFound covers a missing session and a session the caller+ // does not own. Both map to HTTP 404 so ownership is not enumerable.+ ErrForkSessionNotFound = errors.New("session fork: source session not found")++ // ErrForkMessageNotFound covers a missing message and a message that+ // belongs to a different session. HTTP 404.+ ErrForkMessageNotFound = errors.New("session fork: fork point message not found")++ // ErrForkMessageNotUser is returned when the fork point exists but is+ // neither a user nor an assistant message. HTTP 400.+ ErrForkMessageNotUser = errors.New("session fork: fork point must be a user or assistant message")+)++// forkSnapshotTimeout bounds the provider snapshot plus the persist that+// follows it. Cube pauses a live MicroVM and copies its disk; that routinely+// exceeds the 30s HTTP-client timeout and the browser's default axios budget.+// The work is detached from the incoming request cancel so a client abort+// mid-snapshot cannot leave a 500 after the snapshot already ran.+const forkSnapshotTimeout = 2 * time.Minute++func isForkNotFound(err error) bool {+ return errors.Is(err, apperrors.ErrSessionNotFound) || errors.Is(err, gorm.ErrRecordNotFound)+}++// ForkResult is what the HTTP layer renders.+type ForkResult struct {+ SessionID string `json:"session_id"`+ Degraded bool `json:"degraded"`+ Reason ForkDegradeReason `json:"reason,omitempty"`+}++// SessionForkSandboxPort is the narrow sandbox surface fork needs. It is an+// interface so the fork logic is testable without a provider.+type SessionForkSandboxPort interface {+ // BoundSandboxID returns the session's currently bound sandbox without+ // provisioning one.+ BoundSandboxID(ctx context.Context, sessionID string) (string, bool)++ // HasActiveTurn reports whether an agent turn currently holds the+ // session's sandbox lease.+ HasActiveTurn(ctx context.Context, sessionID string) (bool, error)++ // CreateForkSnapshot snapshots the session's live sandbox and returns a+ // snapshot ID usable as a create-time template.+ CreateForkSnapshot(ctx context.Context, sessionID, name string) (string, error)++ // DeleteForkSnapshot removes a snapshot created for sessionID. Used when+ // fork persist fails after the snapshot already exists.+ DeleteForkSnapshot(ctx context.Context, sessionID, snapshotID string) error+}++type forkSessionStore interface {+ GetByID(ctx context.Context, tenantID uint64, id string) (*types.Session, error)+ // CreateForked persists the new session and the copied messages in one+ // transaction. Copied messages arrive with fresh IDs already assigned and+ // SessionID pointing at the new session.+ CreateForked(ctx context.Context, session *types.Session, messages []*types.Message) error+ CreateForkSnapshotLease(ctx context.Context, lease *types.ForkSnapshotLease) error+ DeleteForkSnapshotLease(ctx context.Context, snapshotID string) error+}++type forkMessageStore interface {+ GetMessage(ctx context.Context, sessionID, messageID string) (*types.Message, error)+ ListMessagesBySessionUpTo(+ ctx context.Context, sessionID string, boundary time.Time, boundaryID string,+ ) ([]*types.Message, error)+}++// SessionForkService implements the fork decision chain.+type SessionForkService struct {+ sessions forkSessionStore+ messages forkMessageStore+ sandbox SessionForkSandboxPort+}++// NewSessionForkService wires the service. A nil sandbox port makes every fork+// degrade, which is the correct behaviour for a deployment without sandboxes.+func NewSessionForkService(+ sessions forkSessionStore,+ messages forkMessageStore,+ sandboxPort SessionForkSandboxPort,+) *SessionForkService {+ return &SessionForkService{sessions: sessions, messages: messages, sandbox: sandboxPort}+}++// NewSessionForkServiceFromRepos is the DI-friendly constructor. The+// repository interfaces satisfy the narrow ports structurally.+func NewSessionForkServiceFromRepos(+ sessions interfaces.SessionRepository,+ messages interfaces.MessageRepository,+ sandboxPort SessionForkSandboxPort,+) *SessionForkService {+ return NewSessionForkService(sessions, messages, sandboxPort)+}++// Fork branches sourceSessionID at messageID.+//+// Errors are reserved for conditions the user must act on: a bad request, a+// session they do not own, or a source that is busy. Everything about the+// sandbox degrades instead, and is reported through ForkResult.+func (s *SessionForkService) Fork(+ ctx context.Context,+ tenantID uint64,+ userID string,+ sourceSessionID string,+ messageID string,+ title string,+) (*ForkResult, error) {+ source, err := s.sessions.GetByID(ctx, tenantID, sourceSessionID)+ if err != nil {+ if isForkNotFound(err) {+ return nil, ErrForkSessionNotFound+ }+ return nil, fmt.Errorf("session fork: load source session: %w", err)+ }+ if source == nil {+ return nil, ErrForkSessionNotFound+ }+ // Fork is a write. Empty user_id rows are tenant-level channel/legacy+ // sessions: list/read scope still surfaces them, but copying history into+ // a new session requires an exact owner match. Skipping that when UserID+ // is empty would let any same-tenant caller fork the row.+ if userID == "" || source.UserID != userID {+ return nil, ErrForkSessionNotFound+ }++ forkPoint, err := s.messages.GetMessage(ctx, sourceSessionID, messageID)+ if err != nil {+ if isForkNotFound(err) {+ return nil, ErrForkMessageNotFound+ }+ return nil, fmt.Errorf("session fork: load fork point: %w", err)+ }+ if forkPoint == nil {+ return nil, ErrForkMessageNotFound+ }+ if forkPoint.Role != "user" && forkPoint.Role != "assistant" {+ return nil, ErrForkMessageNotUser+ }+ // An unfinished assistant answer is still the live turn. Snapshotting+ // would pause the sandbox under it; treat it like a busy source.+ if forkPoint.Role == "assistant" && !forkPoint.IsCompleted {+ return nil, ErrForkSourceBusy+ }++ // Refuse before doing anything observable: snapshotting pauses the source+ // sandbox, and interrupting a running tool is worse than making the user+ // wait for the turn to finish.+ if s.sandbox != nil {+ busy, turnErr := s.sandbox.HasActiveTurn(ctx, sourceSessionID)+ if turnErr != nil {+ return nil, fmt.Errorf("session fork: check source turn state: %w", turnErr)+ }+ if busy {+ return nil, ErrForkSourceBusy+ }+ }++ history, err := s.messages.ListMessagesBySessionUpTo(+ ctx, sourceSessionID, forkPoint.CreatedAt, forkPoint.ID,+ )+ if err != nil {+ return nil, fmt.Errorf("session fork: load history: %w", err)+ }+ history = historyThroughForkPoint(history, forkPoint)++ workCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), forkSnapshotTimeout)+ defer cancel()++ bootstrap, reason, createdSnapshot, prepErr := s.prepareBootstrap(workCtx, source, history)+ if prepErr != nil {+ return nil, prepErr+ }++ if createdSnapshot {+ if err := s.recordSnapshotLease(workCtx, source, bootstrap); err != nil {+ s.abandonCreatedSnapshot(workCtx, source.ID, bootstrap.SnapshotID)+ return nil, err+ }+ }++ newSession := &types.Session{+ ID: uuid.New().String(),+ TenantID: source.TenantID,+ UserID: source.UserID,+ Title: forkTitle(title, source.Title),+ Description: source.Description,+ LastRequestState: source.LastRequestState,+ SandboxConfigID: source.SandboxConfigID,+ ParentSessionID: source.ID,+ ForkedFromMessageID: forkPoint.ID,+ ForkBootstrap: bootstrap,+ }++ copied := copyMessagesInto(newSession.ID, history)+ if err := s.sessions.CreateForked(workCtx, newSession, copied); err != nil {+ if createdSnapshot {+ s.abandonCreatedSnapshot(workCtx, source.ID, bootstrap.SnapshotID)+ }+ return nil, fmt.Errorf("session fork: persist forked session: %w", err)+ }+ if createdSnapshot {+ s.clearSnapshotLease(workCtx, bootstrap.SnapshotID)+ }++ logger.Infof(ctx,+ "[SessionFork] source=%s fork_point=%s new=%s messages=%d degraded=%v reason=%s",+ sourceSessionID, forkPoint.ID, newSession.ID, len(copied), reason != "", reason)++ return &ForkResult{+ SessionID: newSession.ID,+ Degraded: reason != "",+ Reason: reason,+ }, nil+}++// prepareBootstrap runs the decision chain from the design doc §4.2 and, when+// every condition holds, takes the snapshot.+//+// A nil bootstrap with an empty reason means "no sandbox state was needed":+// forking at the very first user message has no prior output to carry, so a+// brand new sandbox is the correct result rather than a degradation.+func (s *SessionForkService) prepareBootstrap(+ ctx context.Context, source *types.Session, history []*types.Message,+) (*types.ForkBootstrap, ForkDegradeReason, bool, error) {+ checkpoint := latestCheckpoint(history)+ if checkpoint == nil {+ if !hasAssistantMessage(history) {+ // Forking at the first user message.+ return nil, "", false, nil+ }+ return nil, ForkDegradeNoCheckpoint, false, nil+ }+ if inherited := inheritUnconsumedForkSnapshot(source, checkpoint); inherited != nil {+ if currentID, ok := s.boundSandboxID(ctx, source.ID); !ok || currentID == "" {+ logger.Infof(ctx, "[SessionFork] inherit unused snapshot %s from source=%s sha=%s",+ inherited.SnapshotID, source.ID, inherited.CommitSHA)+ return inherited, "", false, nil+ }+ }+ if s.sandbox == nil {+ return nil, ForkDegradeSandboxGone, false, nil+ }++ currentID, ok := s.sandbox.BoundSandboxID(ctx, source.ID)+ if !ok || currentID == "" {+ return nil, ForkDegradeSandboxGone, false, nil+ }+ if currentID != checkpoint.SandboxID {+ // The session swapped sandboxes after this checkpoint was written, so+ // the SHA does not exist in the current sandbox's repository.+ return nil, ForkDegradeSandboxReplaced, false, nil+ }++ // Re-check immediately before pausing the sandbox. The earlier check in+ // Fork is a cheap reject; this closes the window after checkpoint lookup.+ busy, turnErr := s.sandbox.HasActiveTurn(ctx, source.ID)+ if turnErr != nil {+ return nil, "", false, fmt.Errorf("session fork: check source turn state: %w", turnErr)+ }+ if busy {+ return nil, "", false, ErrForkSourceBusy+ }++ snapshotID, err := s.sandbox.CreateForkSnapshot(+ ctx, source.ID, forkSnapshotName(source.ID),+ )+ if err != nil {+ if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {+ return nil, "", false, fmt.Errorf("session fork: snapshot source sandbox: %w", err)+ }+ logger.Warnf(ctx, "[SessionFork] snapshot failed source=%s: %v", source.ID, err)+ return nil, ForkDegradeSnapshotUnsupported, false, nil+ }+ if snapshotID == "" {+ logger.Warnf(ctx, "[SessionFork] snapshot failed source=%s: empty snapshot id", source.ID)+ return nil, ForkDegradeSnapshotUnsupported, false, nil+ }++ return &types.ForkBootstrap{+ SnapshotID: snapshotID,+ CommitSHA: checkpoint.CommitSHA,+ SourceSandboxID: checkpoint.SandboxID,+ CreatedAt: time.Now().UTC(),+ }, "", true, nil+}++func (s *SessionForkService) recordSnapshotLease(+ ctx context.Context, source *types.Session, bootstrap *types.ForkBootstrap,+) error {+ if s.sessions == nil || source == nil || bootstrap == nil || strings.TrimSpace(bootstrap.SnapshotID) == "" {+ return nil+ }+ lease := &types.ForkSnapshotLease{+ SnapshotID: bootstrap.SnapshotID,+ TenantID: source.TenantID,+ SandboxConfigID: source.SandboxConfigID,+ CreatedAt: time.Now().UTC(),+ }+ if err := s.sessions.CreateForkSnapshotLease(ctx, lease); err != nil {+ return fmt.Errorf("session fork: record snapshot lease: %w", err)+ }+ return nil+}++func (s *SessionForkService) clearSnapshotLease(ctx context.Context, snapshotID string) {+ if s.sessions == nil || strings.TrimSpace(snapshotID) == "" {+ return+ }+ if err := s.sessions.DeleteForkSnapshotLease(ctx, snapshotID); err != nil {+ logger.Warnf(ctx, "[SessionFork] clear snapshot lease %s failed: %v", snapshotID, err)+ }+}++// abandonCreatedSnapshot deletes a snapshot this fork just created. On success+// it also drops the lease. On delete failure the lease stays so the reaper+// can retry — there is no session row to hang the ID on.+func (s *SessionForkService) abandonCreatedSnapshot(ctx context.Context, sourceSessionID, snapshotID string) {+ snapshotID = strings.TrimSpace(snapshotID)+ if snapshotID == "" || s.sandbox == nil {+ return+ }+ cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)+ defer cancel()+ if err := s.sandbox.DeleteForkSnapshot(cleanupCtx, sourceSessionID, snapshotID); err != nil {+ if !sandbox.IsRemoteNotFound(err) {+ logger.Warnf(cleanupCtx, "[SessionFork] delete orphan snapshot %s failed; lease kept for reaper: %v",+ snapshotID, err)+ return+ }+ }+ s.clearSnapshotLease(cleanupCtx, snapshotID)+}++func (s *SessionForkService) boundSandboxID(ctx context.Context, sessionID string) (string, bool) {+ if s == nil || s.sandbox == nil {+ return "", false+ }+ return s.sandbox.BoundSandboxID(ctx, sessionID)+}++// inheritUnconsumedForkSnapshot reuses a parent branch's unused snapshot when+// that branch has never provisioned a sandbox. Treating "no binding" as+// SANDBOX_GONE would drop state that still exists on the provider.+func inheritUnconsumedForkSnapshot(source *types.Session, checkpoint *types.SandboxCheckpoint) *types.ForkBootstrap {+ if source == nil || source.ForkBootstrap == nil || source.ForkBootstrap.Consumed() || checkpoint == nil {+ return nil+ }+ snapshotID := strings.TrimSpace(source.ForkBootstrap.SnapshotID)+ sha := strings.TrimSpace(checkpoint.CommitSHA)+ if snapshotID == "" || sha == "" {+ return nil+ }+ parentSandbox := strings.TrimSpace(source.ForkBootstrap.SourceSandboxID)+ checkpointSandbox := strings.TrimSpace(checkpoint.SandboxID)+ if parentSandbox != "" && checkpointSandbox != "" && parentSandbox != checkpointSandbox {+ return nil+ }+ sourceSandbox := checkpointSandbox+ if sourceSandbox == "" {+ sourceSandbox = parentSandbox+ }+ return &types.ForkBootstrap{+ SnapshotID: snapshotID,+ CommitSHA: sha,+ SourceSandboxID: sourceSandbox,+ CreatedAt: time.Now().UTC(),+ }+}++// latestCheckpoint returns the checkpoint of the last assistant message in+// history, or nil when that message has none.+func latestCheckpoint(history []*types.Message) *types.SandboxCheckpoint {+ for i := len(history) - 1; i >= 0; i-- {+ if history[i].Role != "assistant" {+ continue+ }+ return history[i].SandboxCheckpoint+ }+ return nil+}++func hasAssistantMessage(history []*types.Message) bool {+ for _, m := range history {+ if m.Role == "assistant" {+ return true+ }+ }+ return false+}++// historyThroughForkPoint is exclusive of a user fork point (the client+// prefills that question) and inclusive of an assistant fork point (the+// branch continues after that answer).+func historyThroughForkPoint(listed []*types.Message, forkPoint *types.Message) []*types.Message {+ if forkPoint == nil || forkPoint.Role != "assistant" {+ return listed+ }+ out := make([]*types.Message, 0, len(listed)+1)+ out = append(out, listed...)+ return append(out, forkPoint)+}++// copyMessagesInto clones history into the new session.+//+// Every copy gets a fresh primary key but keeps its original CreatedAt so the+// branch reads with the same timeline as its parent. RequestIDs are remapped+// per original value so a user/assistant pair stays paired inside the fork+// without colliding with the parent in search partner lookups.+//+// Copies deliberately keep their Artifacts and Attachments. Artifact URLs are+// persisted on the message row, so the forked session's 产物 tab can list and+// download the same files. Attachment storage handles live in+// temporary_documents (still scoped to the parent session) and are resolved+// by ID at preview and staging time when the copied messages reference them.+func copyMessagesInto(newSessionID string, history []*types.Message) []*types.Message {+ copies := make([]*types.Message, 0, len(history))+ requestIDs := make(map[string]string, len(history))+ for _, src := range history {+ clone := *src+ clone.ID = uuid.New().String()+ clone.SessionID = newSessionID+ // The parent already indexed these into the chat-history knowledge+ // base. Clearing the link stops the copy from being re-indexed, which+ // would both duplicate retrieval hits and burn embedding quota.+ clone.KnowledgeID = ""+ if src.RequestID != "" {+ mapped, ok := requestIDs[src.RequestID]+ if !ok {+ mapped = uuid.New().String()+ requestIDs[src.RequestID] = mapped+ }+ clone.RequestID = mapped+ }+ copies = append(copies, &clone)+ }+ return copies+}++func forkTitle(requested, sourceTitle string) string {+ if requested != "" {+ return requested+ }+ return sourceTitle + "(分支)"+}++func forkSnapshotName(sourceSessionID string) string {+ return fmt.Sprintf("fork-%s-%d", sourceSessionID, time.Now().UnixMilli())+}diff --git a/internal/application/service/session_fork_delete_test.go b/internal/application/service/session_fork_delete_test.gonew file mode 100644index 000000000..cae182608--- /dev/null+++ b/internal/application/service/session_fork_delete_test.go@@ -0,0 +1,106 @@+package service++import (+ "context"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/application/repository"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/stretchr/testify/require"+ "gorm.io/driver/sqlite"+ "gorm.io/gorm"+)++type deleteForkMessageRepo struct {+ interfaces.MessageRepository+}++func (deleteForkMessageRepo) GetKnowledgeIDsBySessionID(context.Context, string) ([]string, error) {+ return nil, nil+}++type deleteForkWebSearchState struct {+ interfaces.WebSearchStateService+}++func (deleteForkWebSearchState) DeleteWebSearchTempKBState(context.Context, string) error {+ return nil+}++func newSessionServiceForForkDeleteTest(t *testing.T) (*sessionService, *gorm.DB, *fakeForkSessionSnapshotDeleter) {+ t.Helper()+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})+ require.NoError(t, err)+ require.NoError(t, db.AutoMigrate(&types.Session{}, &types.ForkSnapshotLease{}))+ snapshots := &fakeForkSessionSnapshotDeleter{}+ svc := &sessionService{+ sessionRepo: repository.NewSessionRepository(db),+ messageRepo: deleteForkMessageRepo{},+ webSearchStateRepo: deleteForkWebSearchState{},+ forkSnapshots: snapshots,+ }+ return svc, db, snapshots+}++func TestDeleteSessionReleasesUnopenedForkSnapshot(t *testing.T) {+ svc, db, snapshots := newSessionServiceForForkDeleteTest(t)+ ctx := testSessionScopeContext(1, "u1")+ row := &types.Session{+ ID: "fork-1", TenantID: 1, UserID: "u1", Title: "branch", SandboxConfigID: "cfg-1",+ ForkBootstrap: &types.ForkBootstrap{+ SnapshotID: "snap-1", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ },+ }+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(row).Error)++ require.NoError(t, svc.DeleteSession(ctx, "fork-1"))++ require.Equal(t, []string{"snap-1"}, snapshots.forkDeleted)+ var n int64+ require.NoError(t, db.Model(&types.Session{}).Count(&n).Error)+ require.Zero(t, n)+}++func TestDeleteSessionKeepsSnapshotStillNeededBySibling(t *testing.T) {+ svc, db, snapshots := newSessionServiceForForkDeleteTest(t)+ ctx := testSessionScopeContext(1, "u1")+ bootstrap := &types.ForkBootstrap{+ SnapshotID: "snap-shared", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ }+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Session{+ ID: "fork-1", TenantID: 1, UserID: "u1", Title: "branch",+ ForkBootstrap: bootstrap,+ }).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Session{+ ID: "fork-2", TenantID: 1, UserID: "u1", Title: "sibling",+ ForkBootstrap: bootstrap,+ }).Error)++ require.NoError(t, svc.DeleteSession(ctx, "fork-1"))++ require.Empty(t, snapshots.forkDeleted)+}++func TestBatchDeleteSessionsReleasesUnopenedForkSnapshotsAfterAllRowsAreGone(t *testing.T) {+ svc, db, snapshots := newSessionServiceForForkDeleteTest(t)+ ctx := testSessionScopeContext(1, "u1")+ bootstrap := &types.ForkBootstrap{+ SnapshotID: "snap-shared", CommitSHA: "sha", SourceSandboxID: "sbx",+ CreatedAt: time.Now().UTC(),+ }+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Session{+ ID: "fork-1", TenantID: 1, UserID: "u1", Title: "a", ForkBootstrap: bootstrap,+ }).Error)+ require.NoError(t, db.Session(&gorm.Session{SkipHooks: true}).Create(&types.Session{+ ID: "fork-2", TenantID: 1, UserID: "u1", Title: "b", ForkBootstrap: bootstrap,+ }).Error)++ require.NoError(t, svc.BatchDeleteSessions(ctx, []string{"fork-1", "fork-2"}))++ require.Equal(t, []string{"snap-shared"}, snapshots.forkDeleted,+ "shared snapshot must be deleted once, after both rows are gone")+}diff --git a/internal/application/service/session_fork_test.go b/internal/application/service/session_fork_test.gonew file mode 100644index 000000000..ad5cc6c9a--- /dev/null+++ b/internal/application/service/session_fork_test.go@@ -0,0 +1,897 @@+package service++import (+ "context"+ "errors"+ "sort"+ "strings"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+)++type fakeForkSandboxPort struct {+ boundID string+ bound bool+ activeTurn bool+ activeTurnErr error+ forceBusyAfter int+ hasActiveCalls int+ snapshotID string+ snapshotErr error+ snapshotCalls int+ snapshotNameIn string+ cancelParent context.CancelFunc+ snapshotCtxErr error+ deleted []string+ deleteErr error+}++func (f *fakeForkSandboxPort) BoundSandboxID(context.Context, string) (string, bool) {+ return f.boundID, f.bound+}++func (f *fakeForkSandboxPort) HasActiveTurn(context.Context, string) (bool, error) {+ f.hasActiveCalls+++ if f.activeTurnErr != nil {+ return false, f.activeTurnErr+ }+ if f.forceBusyAfter > 0 && f.hasActiveCalls >= f.forceBusyAfter {+ return true, nil+ }+ return f.activeTurn, nil+}++func (f *fakeForkSandboxPort) CreateForkSnapshot(ctx context.Context, _, name string) (string, error) {+ f.snapshotCalls+++ f.snapshotNameIn = name+ if f.cancelParent != nil {+ f.cancelParent()+ }+ f.snapshotCtxErr = ctx.Err()+ if f.snapshotErr != nil {+ return "", f.snapshotErr+ }+ if err := ctx.Err(); err != nil {+ return "", err+ }+ return f.snapshotID, nil+}++func (f *fakeForkSandboxPort) DeleteForkSnapshot(_ context.Context, _, snapshotID string) error {+ f.deleted = append(f.deleted, snapshotID)+ return f.deleteErr+}++// fakeSessionStore is the narrow session port SessionForkService needs.+type fakeSessionStore struct {+ source *types.Session+ created *types.Session+ copiedMessages []*types.Message+ copiedOrigIDs []string+ origIDsFrom *fakeMessageStore+ getErr error+ updatedBootstrap *types.ForkBootstrap+ bootstrapCleared bool+ clearErr error+ unconsumed []*types.Session+ createErr error+ leases []*types.ForkSnapshotLease+}++func newFakeSessionStore(src *types.Session) *fakeSessionStore {+ return &fakeSessionStore{source: src}+}++func (f *fakeSessionStore) GetByID(_ context.Context, tenantID uint64, id string) (*types.Session, error) {+ if f.getErr != nil {+ return nil, f.getErr+ }+ if f.source == nil || f.source.ID != id || f.source.TenantID != tenantID {+ return nil, nil+ }+ return f.source, nil+}++func (f *fakeSessionStore) UpdateForkBootstrap(_ context.Context, _ string, b *types.ForkBootstrap) error {+ if b == nil {+ if f.clearErr != nil {+ return f.clearErr+ }+ f.bootstrapCleared = true+ f.updatedBootstrap = nil+ if f.source != nil {+ f.source.ForkBootstrap = nil+ }+ return nil+ }+ copied := *b+ f.updatedBootstrap = &copied+ if f.source != nil {+ f.source.ForkBootstrap = &copied+ }+ return nil+}++func (f *fakeSessionStore) ListUnconsumedForks(_ context.Context, _ time.Time) ([]*types.Session, error) {+ return f.unconsumed, nil+}++func (f *fakeSessionStore) UnconsumedForkSnapshotHolders(_ context.Context, snapshotID string) ([]string, error) {+ snapshotID = strings.TrimSpace(snapshotID)+ if snapshotID == "" {+ return nil, nil+ }+ seen := map[string]struct{}{}+ var ids []string+ candidates := []*types.Session{f.source, f.created}+ candidates = append(candidates, f.unconsumed...)+ for _, s := range candidates {+ if s == nil || s.ForkBootstrap == nil || s.ForkBootstrap.Consumed() {+ continue+ }+ if s.ForkBootstrap.SnapshotID != snapshotID {+ continue+ }+ if _, ok := seen[s.ID]; ok {+ continue+ }+ seen[s.ID] = struct{}{}+ ids = append(ids, s.ID)+ }+ return ids, nil+}++func (f *fakeSessionStore) HasOtherUnconsumedForkSnapshot(+ ctx context.Context, snapshotID, excludeSessionID string,+) (bool, error) {+ holders, err := f.UnconsumedForkSnapshotHolders(ctx, snapshotID)+ if err != nil {+ return false, err+ }+ for _, id := range holders {+ if id != excludeSessionID {+ return true, nil+ }+ }+ return false, nil+}++func (f *fakeSessionStore) CreateForkSnapshotLease(_ context.Context, lease *types.ForkSnapshotLease) error {+ if lease == nil {+ return nil+ }+ copied := *lease+ f.leases = append(f.leases, &copied)+ return nil+}++func (f *fakeSessionStore) DeleteForkSnapshotLease(_ context.Context, snapshotID string) error {+ out := f.leases[:0]+ for _, lease := range f.leases {+ if lease != nil && lease.SnapshotID != snapshotID {+ out = append(out, lease)+ }+ }+ f.leases = out+ return nil+}++func (f *fakeSessionStore) ListStaleForkSnapshotLeases(+ _ context.Context, olderThan time.Time,+) ([]*types.ForkSnapshotLease, error) {+ var out []*types.ForkSnapshotLease+ for _, lease := range f.leases {+ if lease == nil || lease.CreatedAt.After(olderThan) {+ continue+ }+ out = append(out, lease)+ }+ return out, nil+}++func (f *fakeSessionStore) CreateForked(ctx context.Context, session *types.Session, messages []*types.Message) error {+ if err := ctx.Err(); err != nil {+ return err+ }+ if f.createErr != nil {+ return f.createErr+ }+ f.created = session+ f.copiedMessages = append([]*types.Message(nil), messages...)+ // Copies already have fresh IDs; original IDs come from the listing the+ // service used as the copy source.+ if f.origIDsFrom != nil {+ f.copiedOrigIDs = append([]string(nil), f.origIDsFrom.lastListedIDs...)+ }+ return nil+}++func (f *fakeSessionStore) copiedFromIDs() []string {+ return f.copiedOrigIDs+}++// fakeMessageStore is the narrow message port SessionForkService needs.+type fakeMessageStore struct {+ messages []*types.Message+ lastListedIDs []string+ rewriteErr error+}++func newFakeMessageStore(messages []*types.Message) *fakeMessageStore {+ return &fakeMessageStore{messages: messages}+}++func (f *fakeMessageStore) GetMessage(_ context.Context, sessionID, messageID string) (*types.Message, error) {+ for _, m := range f.messages {+ if m != nil && m.SessionID == sessionID && m.ID == messageID {+ return m, nil+ }+ }+ return nil, nil+}++func (f *fakeMessageStore) GetMessagesBySession(+ _ context.Context, sessionID string, page, pageSize int,+) ([]*types.Message, error) {+ var out []*types.Message+ for _, m := range f.messages {+ if m != nil && m.SessionID == sessionID {+ out = append(out, m)+ }+ }+ sort.Slice(out, func(i, j int) bool {+ if !out[i].CreatedAt.Equal(out[j].CreatedAt) {+ return out[i].CreatedAt.Before(out[j].CreatedAt)+ }+ return out[i].ID < out[j].ID+ })+ if page < 1 {+ page = 1+ }+ if pageSize <= 0 {+ return out, nil+ }+ start := (page - 1) * pageSize+ if start >= len(out) {+ return []*types.Message{}, nil+ }+ end := start + pageSize+ if end > len(out) {+ end = len(out)+ }+ return out[start:end], nil+}++func (f *fakeMessageStore) ListMessagesBySessionUpTo(+ _ context.Context, sessionID string, boundary time.Time, boundaryID string,+) ([]*types.Message, error) {+ var out []*types.Message+ for _, m := range f.messages {+ if m == nil || m.SessionID != sessionID {+ continue+ }+ if m.CreatedAt.Before(boundary) || (m.CreatedAt.Equal(boundary) && m.ID < boundaryID) {+ out = append(out, m)+ }+ }+ sort.Slice(out, func(i, j int) bool {+ if !out[i].CreatedAt.Equal(out[j].CreatedAt) {+ return out[i].CreatedAt.Before(out[j].CreatedAt)+ }+ return out[i].ID < out[j].ID+ })+ f.lastListedIDs = make([]string, 0, len(out))+ for _, m := range out {+ f.lastListedIDs = append(f.lastListedIDs, m.ID)+ }+ return out, nil+}++func (f *fakeMessageStore) GetSessionArtifacts(ctx context.Context, sessionID string) (types.MessageArtifacts, error) {+ messages, err := f.GetMessagesBySession(ctx, sessionID, 1, 0)+ if err != nil {+ return nil, err+ }+ var out types.MessageArtifacts+ for _, m := range messages {+ if m == nil || len(m.Artifacts) == 0 {+ continue+ }+ out = append(out, m.Artifacts...)+ }+ if out == nil {+ out = types.MessageArtifacts{}+ }+ return out, nil+}++func (f *fakeMessageStore) RewriteSandboxCheckpoints(_ context.Context, sessionID, oldID, newID string) error {+ if f.rewriteErr != nil {+ return f.rewriteErr+ }+ if sessionID == "" || oldID == "" || newID == "" || oldID == newID {+ return nil+ }+ for _, m := range f.messages {+ if m == nil || m.SessionID != sessionID || m.SandboxCheckpoint == nil {+ continue+ }+ if m.SandboxCheckpoint.SandboxID != oldID {+ continue+ }+ cp := *m.SandboxCheckpoint+ cp.SandboxID = newID+ m.SandboxCheckpoint = &cp+ }+ return nil+}++var (+ _ forkSessionStore = (*fakeSessionStore)(nil)+ _ forkBootstrapSessionStore = (*fakeSessionStore)(nil)+ _ reaperSessionStore = (*fakeSessionStore)(nil)+ _ forkMessageStore = (*fakeMessageStore)(nil)+ _ forkBootstrapMessageStore = (*fakeMessageStore)(nil)+ _ SessionForkSandboxPort = (*fakeForkSandboxPort)(nil)+)++// --- fixture helpers -------------------------------------------------------++var forkBase = time.Date(2026, 9, 10, 9, 0, 0, 0, time.UTC)++func checkpointedTurn(userID, assistantID, sandboxID, sha string, offset time.Duration) []*types.Message {+ return []*types.Message{+ {ID: userID, SessionID: "src", Role: "user", CreatedAt: forkBase.Add(offset)},+ {+ ID: assistantID, SessionID: "src", Role: "assistant",+ CreatedAt: forkBase.Add(offset + time.Second),+ SandboxCheckpoint: &types.SandboxCheckpoint{+ SandboxID: sandboxID, CommitSHA: sha, CommittedAt: forkBase.Add(offset + time.Second),+ },+ },+ }+}++func newForkFixture(t *testing.T, port *fakeForkSandboxPort, messages []*types.Message) (+ *SessionForkService, *fakeSessionStore, *fakeMessageStore,+) {+ t.Helper()+ sessions := newFakeSessionStore(&types.Session{+ ID: "src", TenantID: 1, UserID: "u1", Title: "原会话", SandboxConfigID: "cfg-1",+ })+ msgs := newFakeMessageStore(messages)+ sessions.origIDsFrom = msgs+ return NewSessionForkService(sessions, msgs, port), sessions, msgs+}++// --- tests -----------------------------------------------------------------++func TestForkHappyPathTakesSnapshotAndCopiesHistory(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.False(t, got.Degraded)+ require.Empty(t, got.Reason)+ require.Equal(t, 1, port.snapshotCalls)++ created := sessions.created+ require.NotNil(t, created)+ require.Equal(t, "src", created.ParentSessionID)+ require.Equal(t, "u-msg-2", created.ForkedFromMessageID)+ require.Equal(t, "cfg-1", created.SandboxConfigID, "必须继承 sandbox_config_id,否则可能落到别的 backend")+ require.Equal(t, "原会话(分支)", created.Title)+ require.NotNil(t, created.ForkBootstrap)+ require.Equal(t, "snap-1", created.ForkBootstrap.SnapshotID)+ require.Equal(t, "sha1", created.ForkBootstrap.CommitSHA)+ require.Equal(t, "sbx-1", created.ForkBootstrap.SourceSandboxID)+ require.False(t, created.ForkBootstrap.Consumed())++ // 只复制分叉点之前的消息,且都换了新 ID+ require.Equal(t, []string{"u-msg-1", "a-msg-1"}, sessions.copiedFromIDs())+ for _, m := range sessions.copiedMessages {+ require.NotEmpty(t, m.ID)+ require.Equal(t, created.ID, m.SessionID)+ }+}++func TestCopyMessagesIntoRemapsRequestIDsPerTurn(t *testing.T) {+ history := []*types.Message{+ {ID: "u1", SessionID: "src", Role: "user", RequestID: "req-a", Content: "q1"},+ {ID: "a1", SessionID: "src", Role: "assistant", RequestID: "req-a", Content: "a1"},+ {ID: "u2", SessionID: "src", Role: "user", RequestID: "req-b", Content: "q2"},+ {ID: "a2", SessionID: "src", Role: "assistant", RequestID: "req-b", Content: "a2"},+ {ID: "u3", SessionID: "src", Role: "user", Content: "no-request-id"},+ }++ copies := copyMessagesInto("fork-1", history)++ require.Len(t, copies, 5)+ require.NotEqual(t, "req-a", copies[0].RequestID)+ require.Equal(t, copies[0].RequestID, copies[1].RequestID, "same turn must still pair")+ require.NotEqual(t, copies[0].RequestID, copies[2].RequestID, "distinct turns must not share an ID")+ require.Equal(t, copies[2].RequestID, copies[3].RequestID)+ require.Empty(t, copies[4].RequestID)+ require.Equal(t, "fork-1", copies[0].SessionID)+ require.NotEqual(t, "u1", copies[0].ID)+}++func TestForkCopiesArtifactsAndAttachmentsOntoNewSession(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ turn[0].Attachments = types.MessageAttachments{{+ ID: "doc-1", FileName: "brief.pdf", FileType: ".pdf", FileSize: 12,+ }}+ turn[1].Artifacts = types.MessageArtifacts{{+ URL: "local://tenant/deck",+ FileName: "deck.pptx",+ FileType: ".pptx",+ FileSize: 32,+ SourcePath: "/workspace/output/deck.pptx",+ }}+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ var copiedUser, copiedAssistant *types.Message+ for _, m := range sessions.copiedMessages {+ switch m.Role {+ case "user":+ copiedUser = m+ case "assistant":+ copiedAssistant = m+ }+ }+ require.NotNil(t, copiedUser)+ require.Equal(t, turn[0].Attachments, copiedUser.Attachments)+ require.NotNil(t, copiedAssistant)+ require.Equal(t, turn[1].Artifacts, copiedAssistant.Artifacts)+}++func TestForkUsesProvidedTitle(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "我的分支")++ require.NoError(t, err)+ require.Equal(t, "我的分支", sessions.created.Title)+}++// 分叉点是第一条 user 消息:前面本就无产物,全新沙箱才是正确结果,不算降级。+func TestForkAtFirstUserMessageIsNotDegraded(t *testing.T) {+ first := &types.Message{ID: "u-msg-1", SessionID: "src", Role: "user", CreatedAt: forkBase}+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, []*types.Message{first})++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-1", "")++ require.NoError(t, err)+ require.False(t, got.Degraded)+ require.Empty(t, got.Reason)+ require.Zero(t, port.snapshotCalls, "没有前置产物就不该浪费一个快照")+ require.Nil(t, sessions.created.ForkBootstrap)+ require.Empty(t, sessions.copiedFromIDs())+}++func TestForkDegradesWhenPrecedingTurnHasNoCheckpoint(t *testing.T) {+ messages := []*types.Message{+ {ID: "u-msg-1", SessionID: "src", Role: "user", CreatedAt: forkBase},+ {ID: "a-msg-1", SessionID: "src", Role: "assistant", CreatedAt: forkBase.Add(time.Second)},+ {ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second)},+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, messages)++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.True(t, got.Degraded)+ require.Equal(t, ForkDegradeNoCheckpoint, got.Reason)+ require.Zero(t, port.snapshotCalls)+ require.Nil(t, sessions.created.ForkBootstrap)+ require.Equal(t, []string{"u-msg-1", "a-msg-1"}, sessions.copiedFromIDs(), "降级也要复制消息")+}++// 会话中途换过沙箱:旧 sha 在新沙箱的仓库里根本不存在。+func TestForkDegradesWhenSandboxWasReplaced(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-OLD", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-NEW", bound: true, snapshotID: "snap-1"}+ svc, _, _ := newForkFixture(t, port, append(turn, forkPoint))++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.True(t, got.Degraded)+ require.Equal(t, ForkDegradeSandboxReplaced, got.Reason)+ require.Zero(t, port.snapshotCalls)+}++func TestForkDegradesWhenSandboxGone(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{bound: false}+ svc, _, _ := newForkFixture(t, port, append(turn, forkPoint))++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.True(t, got.Degraded)+ require.Equal(t, ForkDegradeSandboxGone, got.Reason)+}++func TestForkInheritsUnconsumedBootstrapWhenSourceHasNoSandbox(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha-early", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{bound: false, snapshotID: "must-not-create"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))+ sessions.source.ForkBootstrap = &types.ForkBootstrap{+ SnapshotID: "snap-shared",+ CommitSHA: "sha-later",+ SourceSandboxID: "sbx-1",+ CreatedAt: forkBase,+ }++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.False(t, got.Degraded)+ require.Zero(t, port.snapshotCalls, "unused fork has no live sandbox to snapshot")+ require.NotNil(t, sessions.created.ForkBootstrap)+ require.Equal(t, "snap-shared", sessions.created.ForkBootstrap.SnapshotID)+ require.Equal(t, "sha-early", sessions.created.ForkBootstrap.CommitSHA)+ require.Equal(t, "sbx-1", sessions.created.ForkBootstrap.SourceSandboxID)+ require.False(t, sessions.created.ForkBootstrap.Consumed())+}++func TestForkDoesNotInheritConsumedBootstrapWhenSandboxGone(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ consumedAt := forkBase.Add(time.Minute)+ port := &fakeForkSandboxPort{bound: false}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))+ sessions.source.ForkBootstrap = &types.ForkBootstrap{+ SnapshotID: "snap-old",+ CommitSHA: "sha1",+ SourceSandboxID: "sbx-1",+ CreatedAt: forkBase,+ ConsumedAt: &consumedAt,+ }++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.True(t, got.Degraded)+ require.Equal(t, ForkDegradeSandboxGone, got.Reason)+ require.Zero(t, port.snapshotCalls)+}++func TestForkDegradesWhenSnapshotFails(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{+ boundID: "sbx-1", bound: true, snapshotErr: errors.New("provider does not support snapshots"),+ }+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err, "快照失败是降级,不是报错")+ require.True(t, got.Degraded)+ require.Equal(t, ForkDegradeSnapshotUnsupported, got.Reason)+ require.Nil(t, sessions.created.ForkBootstrap)+}++func TestForkDoesNotDegradeWhenSnapshotIsCanceled(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{+ boundID: "sbx-1", bound: true, snapshotErr: context.Canceled,+ }+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.ErrorIs(t, err, context.Canceled)+ require.Nil(t, sessions.created, "canceled snapshot must not persist a degraded fork")+}++func TestForkFinishesSnapshotAfterCallerCancels(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ ctx, cancel := context.WithCancel(context.Background())+ port := &fakeForkSandboxPort{+ boundID: "sbx-1", bound: true, snapshotID: "snap-1", cancelParent: cancel,+ }+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ got, err := svc.Fork(ctx, 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.NoError(t, port.snapshotCtxErr, "snapshot must not inherit the canceled HTTP request")+ require.False(t, got.Degraded)+ require.Equal(t, "snap-1", sessions.created.ForkBootstrap.SnapshotID)+}++// 源沙箱正在跑 agent 时打快照会暂停它、打断执行中的工具。+func TestForkRefusesWhileSourceTurnIsActive(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, activeTurn: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.ErrorIs(t, err, ErrForkSourceBusy)+ require.Zero(t, port.snapshotCalls)+ require.Nil(t, sessions.created, "拒绝时不得留下半个会话")+}++func TestForkAtAssistantCopiesTurnAndUsesItsCheckpoint(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ turn[1].IsCompleted = true+ later := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, later))++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "a-msg-1", "")++ require.NoError(t, err)+ require.False(t, got.Degraded)+ require.Equal(t, 1, port.snapshotCalls)+ require.Equal(t, "a-msg-1", sessions.created.ForkedFromMessageID)+ require.Len(t, sessions.copiedMessages, 2, "assistant fork must include the clicked answer, not stop before it")+ require.Equal(t, "user", sessions.copiedMessages[0].Role)+ require.Equal(t, "assistant", sessions.copiedMessages[1].Role)+ require.Equal(t, "sha1", sessions.copiedMessages[1].SandboxCheckpoint.CommitSHA)+ require.Equal(t, "sbx-1", sessions.created.ForkBootstrap.SourceSandboxID)+}++func TestForkAtAssistantUsesThisTurnsCheckpointNotAnEarlierOne(t *testing.T) {+ first := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha-old", 0)+ first[1].IsCompleted = true+ second := checkpointedTurn("u-msg-2", "a-msg-2", "sbx-1", "sha-new", 10*time.Second)+ second[1].IsCompleted = true+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-2"}+ svc, sessions, _ := newForkFixture(t, port, append(first, second...))++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "a-msg-2", "")++ require.NoError(t, err)+ require.Len(t, sessions.copiedMessages, 4)+ require.Equal(t, "assistant", sessions.copiedMessages[3].Role)+ require.Equal(t, "sha-new", sessions.copiedMessages[3].SandboxCheckpoint.CommitSHA)+}++func TestForkAtAssistantWithoutCheckpointDegrades(t *testing.T) {+ turn := []*types.Message{+ {ID: "u-msg-1", SessionID: "src", Role: "user", CreatedAt: forkBase},+ {ID: "a-msg-1", SessionID: "src", Role: "assistant", CreatedAt: forkBase.Add(time.Second), IsCompleted: true},+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, turn)++ got, err := svc.Fork(context.Background(), 1, "u1", "src", "a-msg-1", "")++ require.NoError(t, err)+ require.True(t, got.Degraded)+ require.Equal(t, ForkDegradeNoCheckpoint, got.Reason)+ require.Zero(t, port.snapshotCalls)+ require.Len(t, sessions.copiedMessages, 2)+ require.Equal(t, "assistant", sessions.copiedMessages[1].Role)+ require.Nil(t, sessions.created.ForkBootstrap)+}++func TestForkRejectsIncompleteAssistantAsForkPoint(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, turn)++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "a-msg-1", "")++ require.ErrorIs(t, err, ErrForkSourceBusy)+ require.Zero(t, port.snapshotCalls)+ require.Nil(t, sessions.created)+}++func TestForkRejectsNonUserNonAssistantForkPoint(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ turn = append(turn, &types.Message{+ ID: "sys-1", SessionID: "src", Role: "system", CreatedAt: forkBase.Add(2 * time.Second),+ })+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, _, _ := newForkFixture(t, port, turn)++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "sys-1", "")++ require.ErrorIs(t, err, ErrForkMessageNotUser)+ require.Zero(t, port.snapshotCalls)+}++func TestForkRejectsForeignSession(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, _, _ := newForkFixture(t, port, turn)++ _, err := svc.Fork(context.Background(), 1, "someone-else", "src", "u-msg-1", "")++ require.ErrorIs(t, err, ErrForkSessionNotFound)+ require.Zero(t, port.snapshotCalls)+}++func TestForkRejectsEmptyOwnerSession(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, turn)+ sessions.source.UserID = ""++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-1", "")++ require.ErrorIs(t, err, ErrForkSessionNotFound)+ require.Zero(t, port.snapshotCalls)+ require.Nil(t, sessions.created)+}++func TestForkRejectsEmptyCaller(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, turn)+ sessions.source.UserID = ""++ _, err := svc.Fork(context.Background(), 1, "", "src", "u-msg-1", "")++ require.ErrorIs(t, err, ErrForkSessionNotFound)+ require.Zero(t, port.snapshotCalls)+ require.Nil(t, sessions.created)+}++func TestForkRejectsMissingSession(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, _, _ := newForkFixture(t, port, turn)++ _, err := svc.Fork(context.Background(), 1, "u1", "missing", "u-msg-1", "")++ require.ErrorIs(t, err, ErrForkSessionNotFound)+}++func TestForkRejectsMissingMessage(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, _, _ := newForkFixture(t, port, turn)++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "no-such-msg", "")++ require.ErrorIs(t, err, ErrForkMessageNotFound)+}++func TestForkRefusesWhenSourceBecomesBusyBeforeSnapshot(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{+ boundID: "sbx-1", bound: true, snapshotID: "snap-1", forceBusyAfter: 2,+ }+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.ErrorIs(t, err, ErrForkSourceBusy)+ require.GreaterOrEqual(t, port.hasActiveCalls, 2)+ require.Zero(t, port.snapshotCalls)+ require.Nil(t, sessions.created)+}++func TestForkDeletesCreatedSnapshotWhenPersistFails(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))+ sessions.createErr = errors.New("db down")++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.Error(t, err)+ require.Nil(t, sessions.created)+ require.Equal(t, 1, port.snapshotCalls)+ require.Equal(t, []string{"snap-1"}, port.deleted)+ require.Empty(t, sessions.leases, "deleted snapshot must not leave a lease behind")+}++func TestForkKeepsLeaseWhenPersistAndDeleteBothFail(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{+ boundID: "sbx-1", bound: true, snapshotID: "snap-1", deleteErr: errors.New("provider timeout"),+ }+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))+ sessions.createErr = errors.New("db down")++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.Error(t, err)+ require.Equal(t, []string{"snap-1"}, port.deleted)+ require.Len(t, sessions.leases, 1)+ require.Equal(t, "snap-1", sessions.leases[0].SnapshotID)+ require.Equal(t, uint64(1), sessions.leases[0].TenantID)+ require.Equal(t, "cfg-1", sessions.leases[0].SandboxConfigID)+}++func TestForkDoesNotDeleteInheritedSnapshotWhenPersistFails(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha-early", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{bound: false, snapshotID: "must-not-create"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))+ sessions.source.ForkBootstrap = &types.ForkBootstrap{+ SnapshotID: "snap-shared",+ CommitSHA: "sha-later",+ SourceSandboxID: "sbx-1",+ CreatedAt: forkBase,+ }+ sessions.createErr = errors.New("db down")++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.Error(t, err)+ require.Zero(t, port.snapshotCalls)+ require.Empty(t, port.deleted, "parent still needs the inherited snapshot")+ require.Empty(t, sessions.leases)+}++func TestForkClearsLeaseAfterPersistSucceeds(t *testing.T) {+ turn := checkpointedTurn("u-msg-1", "a-msg-1", "sbx-1", "sha1", 0)+ forkPoint := &types.Message{+ ID: "u-msg-2", SessionID: "src", Role: "user", CreatedAt: forkBase.Add(10 * time.Second),+ }+ port := &fakeForkSandboxPort{boundID: "sbx-1", bound: true, snapshotID: "snap-1"}+ svc, sessions, _ := newForkFixture(t, port, append(turn, forkPoint))++ _, err := svc.Fork(context.Background(), 1, "u1", "src", "u-msg-2", "")++ require.NoError(t, err)+ require.Empty(t, port.deleted)+ require.Empty(t, sessions.leases, "session.fork_bootstrap now owns the snapshot")+}diff --git a/internal/application/service/temporary_document.go b/internal/application/service/temporary_document.goindex 12786e6a9..4a0976d27 100644--- a/internal/application/service/temporary_document.go+++ b/internal/application/service/temporary_document.go@@ -93,15 +93,24 @@ var temporaryTextExtensions = map[string]struct{}{".md": {}, ".markdown": {}, ".txt": {}, ".csv": {}, ".json": {}, ".xml": {}, ".yaml": {}, ".yml": {}, ".log": {},}+// sessionAttachmentLookup is the message-store surface Get/OpenFile need to+// authorize a parent-session temporary document after a fork. Fork copies+// attachment IDs onto the new messages but leaves the temporary_documents+// row on the parent; preview still has to work from the fork session id.+type sessionAttachmentLookup interface {+ GetSessionAttachments(ctx context.Context, sessionID string) (types.MessageAttachments, error)+}+type temporaryDocumentService struct {- repo interfaces.TemporaryDocumentRepository- fileService interfaces.FileService- resourceCatalog interfaces.ResourceCatalog- documentReader interfaces.DocumentReader- imageResolver *docparser.ImageResolver- modelService interfaces.ModelService- tenantService interfaces.TenantService- taskEnqueuer interfaces.TaskEnqueuer+ repo interfaces.TemporaryDocumentRepository+ fileService interfaces.FileService+ resourceCatalog interfaces.ResourceCatalog+ documentReader interfaces.DocumentReader+ imageResolver *docparser.ImageResolver+ modelService interfaces.ModelService+ tenantService interfaces.TenantService+ taskEnqueuer interfaces.TaskEnqueuer+ sessionAttachments sessionAttachmentLookup}func NewTemporaryDocumentService(@@ -113,11 +122,13 @@ func NewTemporaryDocumentService(modelService interfaces.ModelService,tenantService interfaces.TenantService,taskEnqueuer interfaces.TaskEnqueuer,+ messages interfaces.MessageRepository,) interfaces.TemporaryDocumentService {return &temporaryDocumentService{repo: repo, fileService: fileService, resourceCatalog: resourceCatalog,documentReader: documentReader, imageResolver: imageResolver,modelService: modelService, tenantService: tenantService, taskEnqueuer: taskEnqueuer,+ sessionAttachments: messages,}}@@ -242,11 +253,11 @@ func (s *temporaryDocumentService) supportsExtension(ctx context.Context, tenant}func (s *temporaryDocumentService) Get(ctx context.Context, tenantID uint64, sessionID, documentID string) (*types.TemporaryDocument, error) {- return s.repo.GetScoped(ctx, tenantID, sessionID, documentID)+ return s.resolveInSession(ctx, tenantID, sessionID, documentID)}func (s *temporaryDocumentService) OpenFile(ctx context.Context, tenantID uint64, sessionID, documentID string) (io.ReadCloser, string, error) {- document, err := s.repo.GetScoped(ctx, tenantID, sessionID, documentID)+ document, err := s.resolveInSession(ctx, tenantID, sessionID, documentID)if err != nil {return nil, "", err}@@ -260,6 +271,52 @@ func (s *temporaryDocumentService) OpenFile(ctx context.Context, tenantID uint64return file, document.FileName, nil}+// resolveInSession finds a temporary document the caller may read from this+// session. Composer uploads live on temporary_documents.session_id; forked+// history keeps the parent's document id on copied messages, so a scoped miss+// falls back to tenant+id when that id appears on this session's messages.+func (s *temporaryDocumentService) resolveInSession(+ ctx context.Context, tenantID uint64, sessionID, documentID string,+) (*types.TemporaryDocument, error) {+ document, err := s.repo.GetScoped(ctx, tenantID, sessionID, documentID)+ if err != nil || document != nil {+ return document, err+ }+ document, err = s.repo.GetByID(ctx, tenantID, documentID)+ if err != nil || document == nil {+ return document, err+ }+ if document.SessionID == sessionID {+ return document, nil+ }+ ok, authErr := s.sessionReferencesAttachment(ctx, sessionID, documentID)+ if authErr != nil {+ return nil, authErr+ }+ if !ok {+ return nil, nil+ }+ return document, nil+}++func (s *temporaryDocumentService) sessionReferencesAttachment(+ ctx context.Context, sessionID, documentID string,+) (bool, error) {+ if s == nil || s.sessionAttachments == nil || sessionID == "" || documentID == "" {+ return false, nil+ }+ attachments, err := s.sessionAttachments.GetSessionAttachments(ctx, sessionID)+ if err != nil {+ return false, fmt.Errorf("authorize forked attachment: %w", err)+ }+ for _, attachment := range attachments {+ if attachment.ID == documentID {+ return true, nil+ }+ }+ return false, nil+}+func (s *temporaryDocumentService) List(ctx context.Context, tenantID uint64, sessionID string) ([]*types.TemporaryDocument, error) {return s.repo.ListScoped(ctx, tenantID, sessionID)}@@ -609,7 +666,7 @@ func (s *temporaryDocumentService) ResolveForPrompt(ctx context.Context, tenantIcontinue}seen[documentID] = struct{}{}- document, err := s.repo.GetScoped(ctx, tenantID, sessionID, documentID)+ document, err := s.resolveInSession(ctx, tenantID, sessionID, documentID)if err != nil {return nil, err}diff --git a/internal/application/service/temporary_document_fork_access_test.go b/internal/application/service/temporary_document_fork_access_test.gonew file mode 100644index 000000000..929ef0460--- /dev/null+++ b/internal/application/service/temporary_document_fork_access_test.go@@ -0,0 +1,186 @@+package service++import (+ "bytes"+ "context"+ "io"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require"+)++// Fork copies message attachment IDs onto the new session but leaves the+// temporary_documents row on the parent. Preview/Get are session-scoped, so+// they must still resolve a parent-owned document when this session's copied+// messages reference it — and must not leak a document that is not on the+// fork's history.++type forkAccessDocRepo struct {+ docs []*types.TemporaryDocument+}++func (r *forkAccessDocRepo) Create(context.Context, *types.TemporaryDocument) error {+ panic("unexpected Create")+}+func (r *forkAccessDocRepo) MarkProcessing(context.Context, uint64, string, time.Time) error {+ panic("unexpected MarkProcessing")+}+func (r *forkAccessDocRepo) MarkReady(context.Context, uint64, string, string, types.JSON, types.JSON, types.JSON, int, int, time.Time) error {+ panic("unexpected MarkReady")+}+func (r *forkAccessDocRepo) MarkFailed(context.Context, uint64, string, string) error {+ panic("unexpected MarkFailed")+}+func (r *forkAccessDocRepo) DeleteScoped(context.Context, uint64, string, string) error {+ panic("unexpected DeleteScoped")+}+func (r *forkAccessDocRepo) ListExpired(context.Context, time.Time, int) ([]*types.TemporaryDocument, error) {+ panic("unexpected ListExpired")+}+func (r *forkAccessDocRepo) ListScoped(context.Context, uint64, string) ([]*types.TemporaryDocument, error) {+ panic("unexpected ListScoped")+}++func (r *forkAccessDocRepo) GetByID(_ context.Context, tenantID uint64, documentID string) (*types.TemporaryDocument, error) {+ for _, doc := range r.docs {+ if doc.TenantID == tenantID && doc.ID == documentID {+ return doc, nil+ }+ }+ return nil, nil+}++func (r *forkAccessDocRepo) GetScoped(_ context.Context, tenantID uint64, sessionID, documentID string) (*types.TemporaryDocument, error) {+ for _, doc := range r.docs {+ if doc.TenantID == tenantID && doc.SessionID == sessionID && doc.ID == documentID {+ return doc, nil+ }+ }+ return nil, nil+}++type forkAccessAttachments struct {+ bySession map[string]types.MessageAttachments+}++func (s *forkAccessAttachments) GetSessionAttachments(_ context.Context, sessionID string) (types.MessageAttachments, error) {+ return s.bySession[sessionID], nil+}++func parentOwnedBrief(t *testing.T) *types.TemporaryDocument {+ t.Helper()+ return &types.TemporaryDocument{+ ID: "doc-1",+ TenantID: 7,+ SessionID: "parent",+ ResourceRef: "local://tenant/brief.pdf",+ FileName: "brief.pdf",+ FileType: ".pdf",+ FileSize: 12,+ Status: types.TemporaryDocumentStatusReady,+ ExpiresAt: time.Now().Add(time.Hour),+ }+}++func TestGetUsesOwningSessionScopeWithoutMessageLookup(t *testing.T) {+ doc := parentOwnedBrief(t)+ doc.SessionID = "session-1"+ svc := &temporaryDocumentService{+ repo: &forkAccessDocRepo{docs: []*types.TemporaryDocument{doc}},+ }++ got, err := svc.Get(context.Background(), 7, "session-1", "doc-1")++ require.NoError(t, err)+ require.NotNil(t, got)+ require.Equal(t, "session-1", got.SessionID)+}++func TestGetResolvesParentAttachmentReferencedByForkedSession(t *testing.T) {+ doc := parentOwnedBrief(t)+ svc := &temporaryDocumentService{+ repo: &forkAccessDocRepo{docs: []*types.TemporaryDocument{doc}},+ sessionAttachments: &forkAccessAttachments{bySession: map[string]types.MessageAttachments{+ "fork": {{ID: "doc-1", FileName: "brief.pdf"}},+ }},+ }++ got, err := svc.Get(context.Background(), 7, "fork", "doc-1")++ require.NoError(t, err)+ require.NotNil(t, got)+ require.Equal(t, "doc-1", got.ID)+ require.Equal(t, "parent", got.SessionID)+}++func TestGetHidesParentAttachmentNotOnForkedHistory(t *testing.T) {+ doc := parentOwnedBrief(t)+ svc := &temporaryDocumentService{+ repo: &forkAccessDocRepo{docs: []*types.TemporaryDocument{doc}},+ sessionAttachments: &forkAccessAttachments{bySession: map[string]types.MessageAttachments{+ "fork": {{ID: "other-doc", FileName: "later.pdf"}},+ }},+ }++ got, err := svc.Get(context.Background(), 7, "fork", "doc-1")++ require.NoError(t, err)+ require.Nil(t, got, "a fork must not preview attachments that were not copied into its history")+}++func TestOpenFileResolvesParentAttachmentReferencedByForkedSession(t *testing.T) {+ doc := parentOwnedBrief(t)+ files := &stagingFileService{files: map[string][]byte{doc.ResourceRef: []byte("%PDF-fake")}}+ svc := &temporaryDocumentService{+ repo: &forkAccessDocRepo{docs: []*types.TemporaryDocument{doc}},+ fileService: files,+ sessionAttachments: &forkAccessAttachments{bySession: map[string]types.MessageAttachments{+ "fork": {{ID: "doc-1", FileName: "brief.pdf"}},+ }},+ }++ reader, name, err := svc.OpenFile(context.Background(), 7, "fork", "doc-1")++ require.NoError(t, err)+ require.Equal(t, "brief.pdf", name)+ body, err := io.ReadAll(reader)+ require.NoError(t, err)+ require.NoError(t, reader.Close())+ require.True(t, bytes.Equal(body, []byte("%PDF-fake")))+}++func TestResolveForPromptUsesParentAttachmentReferencedByFork(t *testing.T) {+ doc := parentOwnedBrief(t)+ doc.Content = "parent brief body"+ svc := &temporaryDocumentService{+ repo: &forkAccessDocRepo{docs: []*types.TemporaryDocument{doc}},+ sessionAttachments: &forkAccessAttachments{bySession: map[string]types.MessageAttachments{+ "fork": {{ID: "doc-1", FileName: "brief.pdf"}},+ }},+ }++ got, err := svc.ResolveForPrompt(context.Background(), 7, "fork", []string{"doc-1"}, "summarize")++ require.NoError(t, err)+ require.Len(t, got.Attachments, 1)+ require.Equal(t, "doc-1", got.Attachments[0].ID)+ require.Equal(t, "parent brief body", got.Attachments[0].Content)+}++func TestResolveForPromptHidesParentAttachmentNotOnForkedHistory(t *testing.T) {+ doc := parentOwnedBrief(t)+ doc.Content = "secret"+ svc := &temporaryDocumentService{+ repo: &forkAccessDocRepo{docs: []*types.TemporaryDocument{doc}},+ sessionAttachments: &forkAccessAttachments{bySession: map[string]types.MessageAttachments{+ "fork": {{ID: "other-doc", FileName: "later.pdf"}},+ }},+ }++ _, err := svc.ResolveForPrompt(context.Background(), 7, "fork", []string{"doc-1"}, "summarize")++ require.Error(t, err)+ require.Contains(t, err.Error(), "not found")+}diff --git a/internal/application/service/workspace_checkpointer.go b/internal/application/service/workspace_checkpointer.gonew file mode 100644index 000000000..17a823340--- /dev/null+++ b/internal/application/service/workspace_checkpointer.go@@ -0,0 +1,166 @@+// Package service - per-turn /workspace git checkpoints.+//+// WorkspaceCheckpointer commits the session sandbox's /workspace at the end of+// every agent turn so session fork can later roll a forked sandbox back to a+// specific turn. It mirrors ArtifactCollector's shape deliberately: a narrow+// injectable interface for the sandbox side, and strict best-effort semantics+// so an auxiliary feature can never break a reply.+//+// Contract:+// - Never returns an error. A failed checkpoint yields nil, the message+// simply carries no checkpoint, and that fork point degrades.+// - Never lazy-creates a sandbox: an empty sandboxID short-circuits.+// - Idempotent inside the sandbox: the script initialises the repository+// only when absent, so pause/resume and sandbox rebuilds self-heal.+package service++import (+ "context"+ "fmt"+ "regexp"+ "strings"+ "time"++ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+)++// SandboxShellRunner is the narrow subset of sandbox behaviour the+// checkpointer needs. *sandbox.SessionBoundManager satisfies it in production;+// tests use a fake to assert on the emitted script without a real sandbox.+type SandboxShellRunner interface {+ ExecShellCommand(+ ctx context.Context,+ sessionID, command, workDir string,+ timeout time.Duration,+ env map[string]string,+ ) (*sandbox.ExecuteResult, error)+}++// workspaceCheckpointTimeout bounds the git round-trip. `git add -A` walks the+// whole working tree, so this is generous relative to a normal commit but+// still short enough that a wedged sandbox cannot stall the completion path.+const workspaceCheckpointTimeout = 30 * time.Second++// gitSHAPattern matches a full 40-character hex object name. The script's last+// stdout line must look like one; anything else means git printed a warning or+// the script diverged, and we refuse to record a checkpoint we cannot trust.+var gitSHAPattern = regexp.MustCompile(`^[0-9a-f]{40}$`)++// WorkspaceCheckpointer commits /workspace after each agent turn.+type WorkspaceCheckpointer struct {+ runner SandboxShellRunner+}++// NewWorkspaceCheckpointer wires a checkpointer. A nil runner yields a+// checkpointer that degrades to "no checkpoint", matching the graceful+// degradation contract used by ArtifactCollector.+func NewWorkspaceCheckpointer(runner SandboxShellRunner) *WorkspaceCheckpointer {+ return &WorkspaceCheckpointer{runner: runner}+}++// checkpointScript renders the idempotent init-and-commit script.+//+// Ordering matters in two places:+//+// - `safe.directory` comes first. /workspace is owned by uid 1000 while+// shell_exec runs as root by default, and git refuses to touch a+// dubiously-owned repository — including from the rev-parse probe below.+// Plain assignment rather than `--add`: safe.directory is a multi-valued+// key, so --add would append one duplicate line to ~/.gitconfig per turn.+//+// - `--allow-empty` is mandatory. A turn that only answered a question+// without touching a file would otherwise produce no commit, leaving that+// message with no checkpoint and making it unusable as a fork point. With+// it, every turn has exactly one checkpoint and fork boundaries are always+// resolvable.+func checkpointScript(workspace, messageID string) string {+ return fmt.Sprintf(`set -e+git config --global safe.directory %[1]s+git -C %[1]s rev-parse --git-dir >/dev/null 2>&1 || {+ git init -q %[1]s+ git -C %[1]s config user.email [email protected]+ git -C %[1]s config user.name 'WeKnora Agent'+}+git -C %[1]s add -A+git -C %[1]s commit -q --allow-empty -m 'turn:%[2]s'+git -C %[1]s rev-parse HEAD`, workspace, messageID)+}++// Checkpoint commits /workspace and returns the resulting checkpoint, or nil+// when anything at all went wrong. It never returns an error by design: the+// caller runs on the turn-completion path and must not be blocked here.+func (c *WorkspaceCheckpointer) Checkpoint(+ ctx context.Context, sessionID, sandboxID, messageID string,+) *types.SandboxCheckpoint {+ if c == nil || c.runner == nil {+ return nil+ }+ if strings.TrimSpace(sessionID) == "" || strings.TrimSpace(messageID) == "" {+ return nil+ }+ // No bound sandbox means there is nothing to snapshot, and a checkpoint+ // without a sandbox ID could never be validated at fork time anyway.+ if strings.TrimSpace(sandboxID) == "" {+ return nil+ }++ result, err := c.runner.ExecShellCommand(+ ctx,+ sessionID,+ checkpointScript(sandbox.SessionWorkspaceRoot, messageID),+ sandbox.SessionWorkspaceRoot,+ workspaceCheckpointTimeout,+ nil,+ )+ if err != nil {+ logger.Warnf(ctx, "[WorkspaceCheckpointer] exec failed session=%s message=%s: %v",+ sessionID, messageID, err)+ return nil+ }+ if result == nil {+ logger.Warnf(ctx, "[WorkspaceCheckpointer] nil result session=%s message=%s",+ sessionID, messageID)+ return nil+ }+ if result.ExitCode != 0 {+ logger.Warnf(ctx,+ "[WorkspaceCheckpointer] git exited %d session=%s message=%s stderr=%s",+ result.ExitCode, sessionID, messageID, truncateForLog(result.Stderr))+ return nil+ }++ sha := lastNonEmptyLine(result.Stdout)+ if !gitSHAPattern.MatchString(sha) {+ logger.Warnf(ctx,+ "[WorkspaceCheckpointer] unexpected stdout tail session=%s message=%s tail=%q",+ sessionID, messageID, truncateForLog(sha))+ return nil+ }++ return &types.SandboxCheckpoint{+ SandboxID: sandboxID,+ CommitSHA: sha,+ CommittedAt: time.Now().UTC(),+ }+}++func lastNonEmptyLine(s string) string {+ lines := strings.Split(strings.TrimRight(s, "\n"), "\n")+ for i := len(lines) - 1; i >= 0; i-- {+ if line := strings.TrimSpace(lines[i]); line != "" {+ return line+ }+ }+ return ""+}++func truncateForLog(s string) string {+ const limit = 256+ s = strings.TrimSpace(s)+ if len(s) <= limit {+ return s+ }+ return s[:limit] + "…"+}diff --git a/internal/application/service/workspace_checkpointer_test.go b/internal/application/service/workspace_checkpointer_test.gonew file mode 100644index 000000000..bb5c8e372--- /dev/null+++ b/internal/application/service/workspace_checkpointer_test.go@@ -0,0 +1,118 @@+package service++import (+ "context"+ "errors"+ "strings"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/stretchr/testify/require"+)++type fakeShellRunner struct {+ calls []string+ result *sandbox.ExecuteResult+ err error+ timeout time.Duration+ workDir string+}++func (f *fakeShellRunner) ExecShellCommand(+ _ context.Context, _ string, command, workDir string,+ timeout time.Duration, _ map[string]string,+) (*sandbox.ExecuteResult, error) {+ f.calls = append(f.calls, command)+ f.timeout = timeout+ f.workDir = workDir+ return f.result, f.err+}++func TestCheckpointReturnsShaFromLastStdoutLine(t *testing.T) {+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{+ ExitCode: 0,+ Stdout: "Initialized empty Git repository\n1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b\n",+ }}+ cp := NewWorkspaceCheckpointer(runner)++ got := cp.Checkpoint(context.Background(), "s1", "sbx-1", "msg-1")++ require.NotNil(t, got)+ require.Equal(t, "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", got.CommitSHA)+ require.Equal(t, "sbx-1", got.SandboxID)+ require.False(t, got.CommittedAt.IsZero())+}++func TestCheckpointScriptShape(t *testing.T) {+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{+ ExitCode: 0, Stdout: strings.Repeat("a", 40) + "\n",+ }}+ cp := NewWorkspaceCheckpointer(runner)++ cp.Checkpoint(context.Background(), "s1", "sbx-1", "msg-42")++ require.Len(t, runner.calls, 1)+ script := runner.calls[0]++ // safe.directory must precede the rev-parse probe: the probe itself is+ // what dubious-ownership blocks.+ require.Less(t,+ strings.Index(script, "safe.directory"),+ strings.Index(script, "rev-parse --git-dir"),+ )+ // Plain assignment, not --add: safe.directory is multi-valued and --add+ // would append a duplicate line to ~/.gitconfig on every single turn.+ require.NotContains(t, script, "--add safe.directory")+ require.Contains(t, script, "--allow-empty")+ require.Contains(t, script, "turn:msg-42")+ require.NotContains(t, script, ".gitignore")+ require.NotContains(t, script, "printf 'input/\\noutput/\\n'")+ require.Equal(t, workspaceCheckpointTimeout, runner.timeout)+ require.Equal(t, sandbox.SessionWorkspaceRoot, runner.workDir)+}++func TestCheckpointReturnsNilWhenExecFails(t *testing.T) {+ runner := &fakeShellRunner{err: errors.New("sandbox unreachable")}+ cp := NewWorkspaceCheckpointer(runner)++ require.Nil(t, cp.Checkpoint(context.Background(), "s1", "sbx-1", "msg-1"))+}++func TestCheckpointReturnsNilOnNonZeroExit(t *testing.T) {+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{+ ExitCode: 128, Stderr: "fatal: not a git repository",+ }}+ cp := NewWorkspaceCheckpointer(runner)++ require.Nil(t, cp.Checkpoint(context.Background(), "s1", "sbx-1", "msg-1"))+}++func TestCheckpointReturnsNilWhenStdoutIsNotASha(t *testing.T) {+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{+ ExitCode: 0, Stdout: "warning: something odd\n",+ }}+ cp := NewWorkspaceCheckpointer(runner)++ require.Nil(t, cp.Checkpoint(context.Background(), "s1", "sbx-1", "msg-1"))+}++func TestCheckpointReturnsNilWhenRunnerMissing(t *testing.T) {+ require.Nil(t, NewWorkspaceCheckpointer(nil).Checkpoint(+ context.Background(), "s1", "sbx-1", "msg-1"))++ var nilCheckpointer *WorkspaceCheckpointer+ require.Nil(t, nilCheckpointer.Checkpoint(context.Background(), "s1", "sbx-1", "msg-1"))+}++func TestCheckpointReturnsNilWithoutSandboxID(t *testing.T) {+ runner := &fakeShellRunner{result: &sandbox.ExecuteResult{+ ExitCode: 0, Stdout: strings.Repeat("a", 40) + "\n",+ }}+ cp := NewWorkspaceCheckpointer(runner)++ // No bound sandbox means there is nothing to check point, and a checkpoint+ // without a sandbox ID could never be validated at fork time.+ require.Nil(t, cp.Checkpoint(context.Background(), "s1", "", "msg-1"))+ require.Empty(t, runner.calls)+}diff --git a/internal/container/container.go b/internal/container/container.goindex 14352e59a..876bc7170 100644--- a/internal/container/container.go+++ b/internal/container/container.go@@ -88,6 +88,7 @@ import ("github.com/Tencent/WeKnora/internal/models/limiter""github.com/Tencent/WeKnora/internal/models/utils/ollama""github.com/Tencent/WeKnora/internal/router"+ "github.com/Tencent/WeKnora/internal/sandbox""github.com/Tencent/WeKnora/internal/storageallowlist""github.com/Tencent/WeKnora/internal/stream""github.com/Tencent/WeKnora/internal/tracing/langfuse"@@ -197,6 +198,13 @@ func BuildContainer(container *dig.Container) *dig.Container {// from the tenant's own configuration, falling back to the singleton above// for tenants that configured nothing.must(container.Provide(service.NewTenantSandboxConfigLoader))+ must(container.Provide(service.NewForkBootstrapperFromRepos))+ must(container.Provide(func(b *service.ForkBootstrapper) sandbox.SessionBootstrapper {+ if b == nil {+ return nil+ }+ return b+ }))must(container.Provide(newTenantSandboxResolver))// Business service layer@@ -322,6 +330,54 @@ func BuildContainer(container *dig.Container) *dig.Container {// per-session file inspection; downstream code guards on nil.must(container.Provide(service.NewArtifactCollectorFromSandboxManager))+ // WorkspaceCheckpointer commits the sandbox /workspace after each agent+ // turn so session fork can roll a forked sandbox back to a given message.+ // The process-wide Manager is DisabledManager, so the runner and ID lookup+ // go through the session pin + per-tenant resolver — the same path+ // ArtifactCollector already uses. Direct Manager type-asserts still win+ // when a deployment injects a SessionBoundManager as the process default.+ must(container.Provide(func(+ mgr sandbox.Manager,+ resolver sandbox.TenantSandboxResolver,+ pinner *service.SessionSandboxPinner,+ ) *service.PinnedSessionSandbox {+ return service.NewPinnedSessionSandbox(pinner, resolver, mgr)+ }))+ must(container.Provide(func(+ mgr sandbox.Manager,+ pinned *service.PinnedSessionSandbox,+ ) *service.WorkspaceCheckpointer {+ if runner, ok := mgr.(service.SandboxShellRunner); ok {+ return service.NewWorkspaceCheckpointer(runner)+ }+ return service.NewWorkspaceCheckpointer(pinned)+ }))+ must(container.Provide(func(+ mgr sandbox.Manager,+ pinned *service.PinnedSessionSandbox,+ ) session.SandboxIDLookup {+ if lookup, ok := mgr.(session.SandboxIDLookup); ok {+ return lookup+ }+ if pinned == nil {+ return nil+ }+ return pinned+ }))+ must(container.Provide(func(+ mgr sandbox.Manager,+ pinned *service.PinnedSessionSandbox,+ ) service.SessionForkSandboxPort {+ if port, ok := mgr.(service.SessionForkSandboxPort); ok {+ return port+ }+ if pinned == nil {+ return nil+ }+ return pinned+ }))+ must(container.Provide(service.NewSessionForkServiceFromRepos))+// SandboxTerminalService opens interactive PTYs on session sandboxes for// the frontend terminal panel. First-use provisioning takes a sandbox// config ID already resolved by the WebSocket handler (own or shared agent).@@ -411,6 +467,17 @@ func BuildContainer(container *dig.Container) *dig.Container {// block above — starting the reaper any earlier panics.must(container.Invoke(startTenantSkillReaper))logger.Debugf(ctx, "[Container] Tenant skill reaper registered")+ must(container.Provide(func(+ sessions interfaces.SessionRepository,+ resolver sandbox.TenantSandboxResolver,+ mgr sandbox.Manager,+ ) *service.ForkSnapshotReaper {+ return service.NewForkSnapshotReaperFromRepos(+ sessions, service.NewResolverForkSnapshotDeleter(resolver, mgr),+ )+ }))+ must(container.Invoke(startForkSnapshotReaper))+ logger.Debugf(ctx, "[Container] Fork snapshot reaper registered")// HTTP handlers layerlogger.Debugf(ctx, "[Container] Registering HTTP handlers...")@@ -1782,6 +1849,38 @@ func startTenantSkillReaper(svc *service.TenantSkillService, cleaner interfaces.})}+// startForkSnapshotReaper collects snapshots of forks that were never opened.+// Best-effort: a wiring gap is logged but does NOT abort the container.+func startForkSnapshotReaper(reaper *service.ForkSnapshotReaper, cleaner interfaces.ResourceCleaner) {+ if reaper == nil {+ logger.Warnf(context.Background(), "[Container] fork snapshot reaper unavailable")+ return+ }+ if cleaner == nil {+ logger.Warnf(context.Background(), "[Container] fork snapshot reaper start failed: resource cleaner missing")+ return+ }+ stop := make(chan struct{})+ go func() {+ ticker := time.NewTicker(6 * time.Hour)+ defer ticker.Stop()+ for {+ select {+ case <-ticker.C:+ if _, err := reaper.ReapOnce(context.Background()); err != nil {+ logger.Warnf(context.Background(), "[ForkSnapshotReaper] reap failed: %v", err)+ }+ case <-stop:+ return+ }+ }+ }()+ cleaner.RegisterWithName("ForkSnapshotReaper", func() error {+ close(stop)+ return nil+ })+}+// startTemporaryDocumentCleanup removes expired session attachments and their// extracted images. The durable expiry timestamp is the source of truth; the// ticker only controls how quickly storage is reclaimed.diff --git a/internal/container/sandbox.go b/internal/container/sandbox.goindex d1e203d10..abc4a50e3 100644--- a/internal/container/sandbox.go+++ b/internal/container/sandbox.go@@ -112,6 +112,7 @@ func newTenantSandboxResolver(loader sandbox.TenantSandboxConfigLoader,redisClient *redis.Client,sessionRepo interfaces.SessionRepository,+ bootstrapper sandbox.SessionBootstrapper,) sandbox.TenantSandboxResolver {ctx := context.Background()@@ -129,6 +130,7 @@ func newTenantSandboxResolver(Loader: loader,Store: store,Checker: sessionExistenceCheckerFor(sessionRepo),+ Bootstrapper: bootstrapper,SharedTransport: sandbox.NewGuardedTransport(),})if err != nil {diff --git a/internal/database/migration_sqlite_versioned_schema_test.go b/internal/database/migration_sqlite_versioned_schema_test.goindex 1dd374eb8..ae3e68eb1 100644--- a/internal/database/migration_sqlite_versioned_schema_test.go+++ b/internal/database/migration_sqlite_versioned_schema_test.go@@ -2,8 +2,10 @@ package databaseimport ("database/sql"+ "fmt""os""path/filepath"+ "strings""testing""github.com/stretchr/testify/require"@@ -23,24 +25,26 @@ var versionedSQLiteTables = []string{"browser_devices","browser_pairings","browser_task_interruptions",+ "fork_snapshot_leases",}// versionedSQLiteColumns maps each existing table to the columns that the// versioned migrations add and the SQLite baseline was missing.var versionedSQLiteColumns = map[string][]string{- "memory_subjects": {"extraction_state"}, // 000094- "memory_items": {"replaces_id"}, // 000094- "tenants": {"api_principal_config"}, // 000064- "users": {"is_system_admin"}, // 000053- "knowledges": {"pending_subtasks_count"}, // 000056- "messages": {"attachments", "usage"}, // 000034, 000085- "tenant_invitations": {"token", "accepted_count"}, // 000054- "embed_channels": {"allow_memory"}, // 000060- "mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064- "mcp_tool_approvals": {"enabled"}, // 000091+ "memory_subjects": {"extraction_state"}, // 000094+ "memory_items": {"replaces_id"}, // 000094+ "tenants": {"api_principal_config"}, // 000064+ "users": {"is_system_admin"}, // 000053+ "knowledges": {"pending_subtasks_count"}, // 000056+ "messages": {"attachments", "usage", "sandbox_checkpoint"}, // 000034, 000085, 000097+ "sessions": {"parent_session_id", "forked_from_message_id", "fork_bootstrap"}, // 000097+ "tenant_invitations": {"token", "accepted_count"}, // 000054+ "embed_channels": {"allow_memory"}, // 000060+ "mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064+ "mcp_tool_approvals": {"enabled"}, // 000091}-const expectedSQLiteMigrationVersion = 17+const expectedSQLiteMigrationVersion = 19func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {repoRoot := sqliteRepoRoot(t)@@ -137,6 +141,42 @@ func TestSQLiteMigrationsUpgradeV4PreservesData(t *testing.T) {require.False(t, sqliteColumnExists(t, db, "knowledges", "tag_id"))}+func TestSQLiteMigrationsUpgradeV16AddsSessionForkColumns(t *testing.T) {+ repoRoot := sqliteRepoRoot(t)++ legacyRoot := copySQLiteMigrationsThrough(t, repoRoot, 16)+ chdirAndRestore(t, legacyRoot)++ dbPath := filepath.Join(t.TempDir(), "upgrade-v16.db")+ require.NoError(t, RunMigrationsWithOptions("sqlite3://unused", MigrationOptions{SQLiteDBPath: dbPath}))++ db := openSQLiteDB(t, dbPath)+ versionBefore, dirtyBefore := sqliteMigrationState(t, db)+ require.Equal(t, 16, versionBefore)+ require.False(t, dirtyBefore)+ require.False(t, sqliteColumnExists(t, db, "sessions", "parent_session_id"))+ require.False(t, sqliteColumnExists(t, db, "sessions", "forked_from_message_id"))+ require.False(t, sqliteColumnExists(t, db, "sessions", "fork_bootstrap"))+ require.False(t, sqliteColumnExists(t, db, "messages", "sandbox_checkpoint"))++ chdirAndRestore(t, repoRoot)+ require.NoError(t, RunMigrationsWithOptions("sqlite3://unused", MigrationOptions{SQLiteDBPath: dbPath}))++ db = openSQLiteDB(t, dbPath)+ versionAfter, dirtyAfter := sqliteMigrationState(t, db)+ require.Equal(t, expectedSQLiteMigrationVersion, versionAfter)+ require.False(t, dirtyAfter)+ for _, column := range versionedSQLiteColumns["sessions"] {+ require.Truef(+ t,+ sqliteColumnExists(t, db, "sessions", column),+ "upgraded SQLite DB must have column sessions.%s",+ column,+ )+ }+ require.True(t, sqliteColumnExists(t, db, "messages", "sandbox_checkpoint"))+}+func sqliteRepoRoot(t *testing.T) string {t.Helper()repoRoot, err := filepath.Abs(filepath.Join("..", ".."))@@ -248,23 +288,36 @@ func assertSQLiteMCPOAuthPrincipalUpsertWorks(t *testing.T, db *sql.DB) {}func copySQLiteMigrationsV4(t *testing.T, repoRoot string) string {+ t.Helper()+ return copySQLiteMigrationsThrough(t, repoRoot, 4)+}++func copySQLiteMigrationsThrough(t *testing.T, repoRoot string, maxVersion int) string {t.Helper()dest := t.TempDir()srcDir := filepath.Join(repoRoot, "migrations", "sqlite")destDir := filepath.Join(dest, "migrations", "sqlite")require.NoError(t, os.MkdirAll(destDir, 0o755))- legacy := []string{- "000000_init.up.sql",- "000001_remove_wiki_log.up.sql",- "000002_knowledge_folder_path.up.sql",- "000003_knowledge_base_auto_tag_config.up.sql",- "000004_memory.up.sql",- }- for _, name := range legacy {- data, err := os.ReadFile(filepath.Join(srcDir, name))- require.NoError(t, err)+ entries, err := os.ReadDir(srcDir)+ require.NoError(t, err)+ copied := 0+ for _, entry := range entries {+ name := entry.Name()+ if entry.IsDir() || !strings.HasSuffix(name, ".up.sql") {+ continue+ }+ var version int+ _, scanErr := fmt.Sscanf(name, "%d_", &version)+ require.NoError(t, scanErr, "sqlite migration filename %s", name)+ if version > maxVersion {+ continue+ }+ data, readErr := os.ReadFile(filepath.Join(srcDir, name))+ require.NoError(t, readErr)require.NoError(t, os.WriteFile(filepath.Join(destDir, name), data, 0o600))+ copied++}+ require.Greater(t, copied, 0)return dest}diff --git a/internal/handler/session/agent_stream_handler.go b/internal/handler/session/agent_stream_handler.goindex 6ef0a2e20..c616a82da 100644--- a/internal/handler/session/agent_stream_handler.go+++ b/internal/handler/session/agent_stream_handler.go@@ -13,10 +13,22 @@ import ("github.com/Tencent/WeKnora/internal/application/service""github.com/Tencent/WeKnora/internal/event""github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/sandbox""github.com/Tencent/WeKnora/internal/types""github.com/Tencent/WeKnora/internal/types/interfaces")+// SandboxIDLookup reports the sandbox currently bound to a session without+// provisioning one. A session with no live sandbox reports ok=false, which the+// completion path treats as "nothing to check point".+type SandboxIDLookup interface {+ BoundSandboxID(ctx context.Context, sessionID string) (string, bool)+}++var _ SandboxIDLookup = (*sandbox.SessionBoundManager)(nil)++var _ SandboxIDLookup = (*service.PinnedSessionSandbox)(nil)+// AgentStreamHandler handles agent events for SSE streaming// It uses a dedicated EventBus per request to avoid SessionID filtering// Events are appended to StreamManager without accumulation@@ -38,6 +50,16 @@ type AgentStreamHandler struct {// doesn't support artifact collection or WeKnora was built without it.artifactCollector *service.ArtifactCollector+ // checkpointer commits the sandbox's /workspace at the end of the turn so+ // session fork can roll a forked sandbox back to this exact message. Nil+ // when the deployment has no sandbox backend; handleComplete checks.+ checkpointer *service.WorkspaceCheckpointer++ // sandboxIDLookup resolves the session's currently bound sandbox ID. The+ // ID is stored next to the commit SHA because a SHA is only meaningful+ // within one sandbox's git repository.+ sandboxIDLookup SandboxIDLookup+// State trackingknowledgeRefs []*types.SearchResultfinalAnswer string@@ -90,6 +112,8 @@ func NewAgentStreamHandler(streamManager interfaces.StreamManager,eventBus *event.EventBus,artifactCollector *service.ArtifactCollector,+ checkpointer *service.WorkspaceCheckpointer,+ sandboxIDLookup SandboxIDLookup,) *AgentStreamHandler {return &AgentStreamHandler{ctx: ctx,@@ -102,6 +126,8 @@ func NewAgentStreamHandler(streamManager: streamManager,eventBus: eventBus,artifactCollector: artifactCollector,+ checkpointer: checkpointer,+ sandboxIDLookup: sandboxIDLookup,knowledgeRefs: make([]*types.SearchResult, 0),eventStartTimes: make(map[string]time.Time),}@@ -717,6 +743,26 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Eventh.assistantMessage.Usage = usage}+ // Check point /workspace before draining artifacts. Every tool has+ // finished, and the turn's sandbox lease is still held, so the sandbox+ // is guaranteed to still be here.+ //+ // This runs on every exit path, including cancelled and errored turns.+ // Skipping unsuccessful turns would fold their file changes into the+ // NEXT turn's commit, so forking at that next turn would silently pick+ // up the cancelled turn's edits.+ //+ // Best-effort throughout: a nil checkpoint just means this message+ // cannot serve as a fork point.+ if h.checkpointer != nil && h.sandboxIDLookup != nil {+ checkpointCtx := context.WithoutCancel(h.ctx)+ if sandboxID, ok := h.sandboxIDLookup.BoundSandboxID(checkpointCtx, h.sessionID); ok {+ h.assistantMessage.SandboxCheckpoint = h.checkpointer.Checkpoint(+ checkpointCtx, h.sessionID, sandboxID, h.assistantMessageID,+ )+ }+ }+// Drain skill-generated files from the sandbox into persistent// storage. Best-effort: any failure is logged and the turn is// persisted without artifacts. Collect is a no-op when either the@@ -738,22 +784,46 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event"artifact collect failed session=%s message=%s: %v",h.sessionID, h.assistantMessageID, err,)- } else if len(artifacts) > 0 {- h.assistantMessage.Artifacts = artifacts+ }++ // Resolve the files the answer names against this turn's artifacts+ // AND the ones already recorded for the session.+ //+ // A turn can legitimately reference a file it did not regenerate.+ // The first turn after a session fork is restored to the fork point,+ // so every unchanged file is de-duplicated out of `artifacts` — yet+ // the model still writes `sandbox:<name>` for it. Gating the+ // rewrite on `artifacts` alone would leave those references+ // unnormalized, and the client resolves names only against the+ // message's own artifact list, so they would render as missing+ // files.+ // KnownArtifacts is oldest-first. Name matching is first-wins, so+ // this turn shadows a regenerated file, then the latest known+ // version (the fork-point file) beats earlier ones of the same name.+ known := h.artifactCollector.SessionArtifacts(collectCtx, h.sessionID)+ referenced := referencedArtifacts(+ h.assistantMessage.Content,+ mergeArtifactLists(artifacts, artifactsNewestFirst(known)),+ )+ previous = historyOnlyArtifacts(referenced, artifacts)++ if attached := mergeArtifactLists(h.assistantMessage.Artifacts, artifacts, referenced); len(attached) > 0 {+ h.assistantMessage.Artifacts = attached// The answer text names generated files the way the model saw// them in the sandbox. Bind those names to artifact indices now// that the index space is final, so a reloaded conversation// renders them instead of showing a broken link.h.assistantMessage.Content = rewriteArtifactReferences(- h.assistantMessage.Content, artifacts,+ h.assistantMessage.Content, attached,)logger.GetLogger(h.ctx).Infof("artifact collect attached %d file(s) to message=%s session=%s",- len(artifacts), h.assistantMessageID, h.sessionID,+ len(attached), h.assistantMessageID, h.sessionID,)}- previous = h.artifactCollector.ReferencedHistory(collectCtx, h.sessionID,- h.assistantMessageID, h.assistantMessage.Content)+ // A reused reference is owned by this message too, so deleting the+ // message that first produced the file cannot invalidate it.+ h.artifactCollector.BindArtifactsToMessage(collectCtx, h.assistantMessageID, previous)}h.assistantMessage.Content = types.ClarifyArtifactVersions(h.assistantMessage.Content,h.assistantMessage.Artifacts, previous, types.LanguageFromContextOrDefault(h.ctx))diff --git a/internal/handler/session/artifact_completion_test.go b/internal/handler/session/artifact_completion_test.goindex 633e6bf5e..ddb5efa25 100644--- a/internal/handler/session/artifact_completion_test.go+++ b/internal/handler/session/artifact_completion_test.go@@ -2,7 +2,9 @@ package sessionimport ("context"+ "strings""testing"+ "time""github.com/Tencent/WeKnora/internal/application/service""github.com/Tencent/WeKnora/internal/event"@@ -27,14 +29,24 @@ func (s completionHistory) KnownArtifacts(context.Context, string) ([]types.Messreturn s.previous, nil}+func (s completionHistory) RecordRestoredMtime(context.Context, string, string, time.Time, string) error {+ return nil+}+func TestCompletionPublishesReconciledArtifactContent(t *testing.T) {old := types.MessageArtifact{URL: "resource://dHZ_fFslfs0GgJGaJZGjGA", FileName: "deck.pptx", SourcePath: "/workspace/output/deck.pptx"}next := oldnext.URL = "resource://4N1nAo-FZZoDEExDQz2yoA"stream := &completionEventRecorder{}message := &types.Message{ID: "m", Content: "", Artifacts: types.MessageArtifacts{next}}- handler := NewAgentStreamHandler(context.Background(), "s", "m", "req", 1, next.CreatedAt,- message, stream, nil, service.NewArtifactCollector(nil, nil, completionHistory{[]types.MessageArtifact{old}}, nil, service.ArtifactCollectorConfig{}))+ handler := NewAgentStreamHandler(+ context.Background(), "s", "m", "req", 1, next.CreatedAt,+ message, stream, nil,+ service.NewArtifactCollector(+ nil, nil, completionHistory{[]types.MessageArtifact{old}}, nil, service.ArtifactCollectorConfig{},+ ),+ nil, nil,+ )err := handler.handleComplete(context.Background(), event.Event{Data: event.AgentCompleteData{MessageID: "m"}})require.NoError(t, err)last := stream.events[len(stream.events)-1]@@ -45,3 +57,68 @@ func TestCompletionPublishesReconciledArtifactContent(t *testing.T) {response := buildStreamResponse(last, "req")require.Equal(t, message.Content, response.Data["final_content"])}++// A turn that re-references a file it did not regenerate must still resolve the+// name. ArtifactCollector de-duplicates identical content, so this turn's+// `artifacts` is empty — and the rewrite used to be gated on it, leaving the+// body's `sandbox:<name>` unnormalized and rendering as a missing file.+//+// The first turn after a session fork is exactly this: the sandbox is rolled+// back to the fork point, so every file carried over from before the fork is+// skipped as unchanged.+func TestCompletionResolvesReferencesWhenNothingWasPersisted(t *testing.T) {+ existing := types.MessageArtifact{+ URL: types.BuildResourcePath(strings.Repeat("a", types.ResourceHandleLength)),+ FileName: "report.pptx",+ SourcePath: "/workspace/output/report.pptx",+ }+ stream := &completionEventRecorder{}+ message := &types.Message{ID: "m", Content: "已生成 "}+ handler := NewAgentStreamHandler(context.Background(), "s", "m", "req", 1, time.Time{},+ message, stream, nil,+ service.NewArtifactCollector(nil, nil, completionHistory{[]types.MessageArtifact{existing}}, nil, service.ArtifactCollectorConfig{}),+ nil, nil)++ err := handler.handleComplete(context.Background(), event.Event{Data: event.AgentCompleteData{MessageID: "m"}})+ require.NoError(t, err)++ require.Len(t, message.Artifacts, 1, "the referenced file must be attached to this message")+ require.Equal(t, existing.URL, message.Artifacts[0].URL)+ require.Contains(t, message.Content, existing.URL)+ require.NotContains(t, message.Content, "sandbox:")++ last := stream.events[len(stream.events)-1]+ require.Equal(t, types.ResponseTypeComplete, last.Type)+ require.Equal(t, message.Content, last.Data["final_content"])+}++// KnownArtifacts is creation order (oldest first). A name with several+// versions must resolve to the latest recorded file — the one sitting in+// the sandbox at the fork point — not the first time that name appeared.+func TestCompletionResolvesNameToLatestKnownVersion(t *testing.T) {+ old := types.MessageArtifact{+ URL: types.BuildResourcePath(strings.Repeat("a", types.ResourceHandleLength)),+ FileName: "report.pptx",+ SourcePath: "/workspace/output/report.pptx",+ }+ latest := types.MessageArtifact{+ URL: types.BuildResourcePath(strings.Repeat("b", types.ResourceHandleLength)),+ FileName: "report.pptx",+ SourcePath: "/workspace/output/report.pptx",+ }+ stream := &completionEventRecorder{}+ message := &types.Message{ID: "m", Content: "已生成 "}+ handler := NewAgentStreamHandler(context.Background(), "s", "m", "req", 1, time.Time{},+ message, stream, nil,+ service.NewArtifactCollector(nil, nil, completionHistory{[]types.MessageArtifact{old, latest}}, nil, service.ArtifactCollectorConfig{}),+ nil, nil)++ err := handler.handleComplete(context.Background(), event.Event{Data: event.AgentCompleteData{MessageID: "m"}})+ require.NoError(t, err)++ require.Len(t, message.Artifacts, 1)+ require.Equal(t, latest.URL, message.Artifacts[0].URL)+ require.Contains(t, message.Content, latest.URL)+ require.NotContains(t, message.Content, old.URL)+ require.NotContains(t, message.Content, "sandbox:")+}diff --git a/internal/handler/session/artifact_reference.go b/internal/handler/session/artifact_reference.goindex 1152b10bb..8df134710 100644--- a/internal/handler/session/artifact_reference.go+++ b/internal/handler/session/artifact_reference.go@@ -190,6 +190,19 @@ func looksLikeSandboxOutputPath(candidate string) bool {// lookupArtifactRef resolves one Markdown destination to an artifact reference.func lookupArtifactRef(destination string, byName map[string]string, image bool) (string, bool) {+ name, ok := artifactDestinationName(destination, image)+ if !ok {+ return "", false+ }+ ref, ok := byName[name]+ return ref, ok+}++// artifactDestinationName normalizes one Markdown link/image destination down to+// the sandbox-output file name it names. ok is false when the destination is not+// a sandbox-local file name at all — a real URL, a resource:// handle, a bare+// name in an ordinary link, or incidental prose punctuation.+func artifactDestinationName(destination string, image bool) (string, bool) {candidate := strings.TrimSpace(destination)if candidate == "" {return "", false@@ -231,9 +244,101 @@ func lookupArtifactRef(destination string, byName map[string]string, image bool)if candidate == "" || candidate == "." || candidate == "/" {return "", false}+ return candidate, true+}- ref, ok := byName[candidate]- return ref, ok+// forEachArtifactDestination calls fn with the normalized file name of every+// link/image destination in content. Destinations inside code spans or fences+// are skipped, mirroring rewriteArtifactReferences.+func forEachArtifactDestination(content string, fn func(name string)) {+ if content == "" || !strings.Contains(content, "](") {+ return+ }+ // Split returns only the non-code segments (Go does not interleave the+ // matched fences the way a capturing-group Python split would). Walk+ // every part; skipping odd indexes would drop citations after the first+ // fence, which rewriteArtifactReferences still rewrites.+ for _, part := range fencedOrInlineCodeRE.Split(content, -1) {+ walkSegmentDestinations(part, fn)+ }+}++func walkSegmentDestinations(segment string, fn func(name string)) {+ cursor := 0+ for cursor < len(segment) {+ relative := strings.Index(segment[cursor:], "](")+ if relative < 0 {+ return+ }+ closeBracket := cursor + relative+ open := closeBracket + 1++ inner, end, ok := scanLinkDestination(segment, open)+ if !ok || !hasLinkLabelBefore(segment, closeBracket) {+ cursor = open + 1+ continue+ }+ destination, _ := splitDestinationTitle(inner)+ if name, ok := artifactDestinationName(destination, markdownImageBefore(segment, closeBracket)); ok {+ fn(name)+ }+ cursor = end + 1+ }+}++// referencedArtifacts returns the candidates the answer body names, in+// candidate order.+//+// A candidate is named when the body carries its resource:// handle, or when a+// link/image destination resolves to its file name — the same spellings+// rewriteArtifactReferences accepts. Matching goes through the Markdown+// destination rules rather than a substring search, so a file that merely+// appears in prose is not treated as a reference.+//+// Candidates are matched in the order given: listing this turn's artifacts+// first lets a regenerated file shadow the older version of itself, so only an+// explicit handle reference still pulls the old version in.+func referencedArtifacts(content string, candidates types.MessageArtifacts) types.MessageArtifacts {+ if content == "" || len(candidates) == 0 {+ return nil+ }++ matched := make([]bool, len(candidates))+ for _, handle := range types.ScanResourceReferences(content) {+ for i := range candidates {+ if candidates[i].URL == handle {+ matched[i] = true+ break+ }+ }+ }++ nameToIndex := make(map[string]int, len(candidates))+ for i := range candidates {+ name := strings.TrimSpace(candidates[i].FileName)+ if name == "" {+ continue+ }+ if _, exists := nameToIndex[name]; exists {+ continue+ }+ nameToIndex[name] = i+ }+ if len(nameToIndex) > 0 {+ forEachArtifactDestination(content, func(name string) {+ if i, ok := nameToIndex[name]; ok {+ matched[i] = true+ }+ })+ }++ var out types.MessageArtifacts+ for i := range candidates {+ if matched[i] {+ out = append(out, candidates[i])+ }+ }+ return out}// artifactRefByName maps each artifact's file name to the reference that@@ -268,3 +373,67 @@ func artifactReference(artifact types.MessageArtifact) string {}return "sandbox:" + strings.TrimSpace(artifact.FileName)}++// artifactsNewestFirst returns a copy of artifacts in reverse order so the+// latest recorded version of a name is first. KnownArtifacts is creation+// order (oldest first); a hash-skipped citation must bind the fork-point+// file, not the first time that name appeared. A copy is required: reversing+// in place would mutate the store's backing slice.+func artifactsNewestFirst(artifacts types.MessageArtifacts) types.MessageArtifacts {+ n := len(artifacts)+ if n < 2 {+ return artifacts+ }+ out := make(types.MessageArtifacts, n)+ for i, artifact := range artifacts {+ out[n-1-i] = artifact+ }+ return out+}++// mergeArtifactLists concatenates artifact lists in order, keeping the first+// occurrence of each storage URL. Order is preserved because a reference+// resolves to an index into the resulting list, so the caller's ordering+// decides which version a name points at: putting this turn's artifacts first+// makes a regenerated file shadow the older one.+func mergeArtifactLists(lists ...types.MessageArtifacts) types.MessageArtifacts {+ var out types.MessageArtifacts+ var seen map[string]struct{}+ for _, list := range lists {+ for _, artifact := range list {+ key := strings.TrimSpace(artifact.URL)+ if key != "" {+ if _, exists := seen[key]; exists {+ continue+ }+ if seen == nil {+ seen = make(map[string]struct{})+ }+ seen[key] = struct{}{}+ }+ out = append(out, artifact)+ }+ }+ return out+}++// historyOnlyArtifacts returns the entries of referenced that this turn did not+// produce. Those are the ones whose ownership has to be extended to the new+// message; the collector already bound the ones it persisted itself.+func historyOnlyArtifacts(referenced, current types.MessageArtifacts) types.MessageArtifacts {+ if len(referenced) == 0 {+ return nil+ }+ produced := make(map[string]struct{}, len(current))+ for _, artifact := range current {+ produced[strings.TrimSpace(artifact.URL)] = struct{}{}+ }+ var out types.MessageArtifacts+ for _, artifact := range referenced {+ if _, isCurrent := produced[strings.TrimSpace(artifact.URL)]; isCurrent {+ continue+ }+ out = append(out, artifact)+ }+ return out+}diff --git a/internal/handler/session/artifact_reference_test.go b/internal/handler/session/artifact_reference_test.goindex c17f27697..791f28d5a 100644--- a/internal/handler/session/artifact_reference_test.go+++ b/internal/handler/session/artifact_reference_test.go@@ -6,6 +6,7 @@ import ("testing""github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/require")// handleFor builds a syntactically valid 22-character resource handle for@@ -206,3 +207,110 @@ func TestArtifactRefByNameKeepsFirstDuplicate(t *testing.T) {t.Fatalf("b.html resolved to %q, want %q", byName["b.html"], refFor(2))}}++func TestReferencedArtifactsMatchesNamesAndHandles(t *testing.T) {+ artifacts := artifactsFixture("report.pptx", "chart.html", "data.csv")++ cases := []struct {+ name string+ content string+ want types.MessageArtifacts+ }{+ {+ name: "sandbox-prefixed name",+ content: "已生成 ",+ want: types.MessageArtifacts{artifacts[0]},+ },+ {+ name: "bare name in an image",+ content: "",+ want: types.MessageArtifacts{artifacts[1]},+ },+ {+ name: "output path in an ordinary link",+ content: "[数据](./output/data.csv)",+ want: types.MessageArtifacts{artifacts[2]},+ },+ {+ name: "canonical handle",+ content: " + ")",+ want: types.MessageArtifacts{artifacts[0]},+ },+ {+ name: "prose mention is not a reference",+ content: "生成了 report.pptx 和 chart.html 两个文件。",+ want: nil,+ },+ {+ name: "bare name in an ordinary link is not a reference",+ content: "见 [说明](report.pptx)",+ want: nil,+ },+ {+ name: "unknown name",+ content: "",+ want: nil,+ },+ {+ name: "code sample is not a reference",+ content: "```\n\n```",+ want: nil,+ },+ {+ // Go regexp.Split does not interleave the matched fences, so+ // walking parts with i+=2 would skip the segment after the first+ // fence and miss a real citation that rewrite still rewrites.+ name: "reference after a code fence",+ content: "\n\n```\n\n```\n\n",+ want: types.MessageArtifacts{artifacts[0], artifacts[1]},+ },+ {+ name: "multiple references keep candidate order",+ content: "\n\n",+ want: types.MessageArtifacts{artifacts[0], artifacts[2]},+ },+ }++ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ require.Equal(t, tc.want, referencedArtifacts(tc.content, artifacts))+ })+ }+}++// A regenerated file shadows the older version of itself: the name resolves to+// the first candidate, while an explicit handle still reaches the old one.+func TestReferencedArtifactsPrefersTheFirstCandidate(t *testing.T) {+ old := types.MessageArtifact{FileName: "deck.pptx", URL: refFor(0)}+ fresh := types.MessageArtifact{FileName: "deck.pptx", URL: refFor(1)}+ candidates := types.MessageArtifacts{fresh, old}++ require.Equal(t, types.MessageArtifacts{fresh},+ referencedArtifacts("", candidates))+ require.Equal(t, types.MessageArtifacts{old},+ referencedArtifacts("", candidates))+}++// KnownArtifacts is oldest-first. Reverse it before merging so a hash-skipped+// name binds the latest file; this turn still shadows that latest file.+func TestMergeArtifactListsPrefersThisTurnThenLatestKnown(t *testing.T) {+ old := types.MessageArtifact{FileName: "deck.pptx", URL: refFor(0)}+ latest := types.MessageArtifact{FileName: "deck.pptx", URL: refFor(1)}+ fresh := types.MessageArtifact{FileName: "deck.pptx", URL: refFor(2)}+ known := types.MessageArtifacts{old, latest}++ require.Equal(t, types.MessageArtifacts{latest},+ referencedArtifacts("",+ mergeArtifactLists(nil, artifactsNewestFirst(known))))+ require.Equal(t, types.MessageArtifacts{fresh},+ referencedArtifacts("",+ mergeArtifactLists(types.MessageArtifacts{fresh}, artifactsNewestFirst(known))))+}++func TestArtifactsNewestFirstDoesNotMutateInput(t *testing.T) {+ in := artifactsFixture("a.html", "b.html")+ got := artifactsNewestFirst(in)+ require.Equal(t, "b.html", got[0].FileName)+ require.Equal(t, "a.html", got[1].FileName)+ require.Equal(t, "a.html", in[0].FileName)+}diff --git a/internal/handler/session/command_output_test.go b/internal/handler/session/command_output_test.goindex 4d8ce2975..3b57a070d 100644--- a/internal/handler/session/command_output_test.go+++ b/internal/handler/session/command_output_test.go@@ -15,7 +15,9 @@ func TestCommandOutputReachesChatStreamWithoutCompletingTool(t *testing.T) {bus := event.NewEventBus()streams := &completionEventRecorder{}message := &types.Message{ID: "message"}- h := NewAgentStreamHandler(ctx, "session", "message", "request", 1, time.Now(), message, streams, bus, nil)+ h := NewAgentStreamHandler(+ ctx, "session", "message", "request", 1, time.Now(), message, streams, bus, nil, nil, nil,+ )h.Subscribe()for _, done := range []bool{false, true} {require.NoError(t, bus.Emit(ctx, event.Event{diff --git a/internal/handler/session/fork.go b/internal/handler/session/fork.gonew file mode 100644index 000000000..be95db435--- /dev/null+++ b/internal/handler/session/fork.go@@ -0,0 +1,115 @@+package session++import (+ "context"+ stderrors "errors"+ "net/http"+ "strings"++ "github.com/Tencent/WeKnora/internal/application/service"+ "github.com/Tencent/WeKnora/internal/errors"+ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/gin-gonic/gin"+)++// sessionForker is the fork surface the handler needs. Declaring it here+// rather than depending on *service.SessionForkService keeps the handler+// testable with a stub.+type sessionForker interface {+ Fork(+ ctx context.Context,+ tenantID uint64,+ userID, sourceSessionID, messageID, title string,+ ) (*service.ForkResult, error)+}++// ForkSessionRequest is the fork endpoint's body.+type ForkSessionRequest struct {+ // MessageID is the message to branch at. A user message copies history+ // strictly before it (the client prefills that question). An assistant+ // message copies history through that answer so the branch continues after it.+ MessageID string `json:"message_id" binding:"required"`+ // Title is optional. Empty falls back to the source title plus a suffix.+ Title string `json:"title"`+}++// ForkSession godoc+// @Summary 分叉会话+// @Description 从指定的用户或助手消息处分叉出一个新会话。用户消息:复制其之前的历史并预填该问题;助手消息:复制含该回答在内的历史,从该轮沙箱状态继续。+// @Tags 会话+// @Accept json+// @Produce json+// @Param session_id path string true "源会话 ID"+// @Param request body ForkSessionRequest true "分叉请求"+// @Success 200 {object} map[string]interface{} "新会话"+// @Failure 400 {object} errors.AppError "请求参数错误 / 分叉点角色不支持"+// @Failure 404 {object} errors.AppError "会话或消息不存在"+// @Failure 409 {object} errors.AppError "源会话正在生成中"+// @Security Bearer+// @Security ApiKeyAuth+// @Router /sessions/{session_id}/fork [post]+func (h *Handler) ForkSession(c *gin.Context) {+ ctx := c.Request.Context()++ sessionID := strings.TrimSpace(c.Param("session_id"))+ if sessionID == "" {+ sessionID = strings.TrimSpace(c.Param("id"))+ }+ if sessionID == "" {+ _ = c.Error(errors.NewBadRequestError("session ID is required"))+ return+ }++ var req ForkSessionRequest+ if err := c.ShouldBindJSON(&req); err != nil {+ _ = c.Error(errors.NewBadRequestError("message_id is required"))+ return+ }+ if strings.TrimSpace(req.MessageID) == "" {+ _ = c.Error(errors.NewBadRequestError("message_id is required"))+ return+ }++ if h.forkService == nil {+ _ = c.Error(errors.NewBadRequestError("session fork is not available"))+ return+ }++ tenantID, _ := types.TenantIDFromContext(ctx)+ userID := types.SessionOwnerIDFromContext(ctx)++ result, err := h.forkService.Fork(+ ctx, tenantID, userID, sessionID,+ strings.TrimSpace(req.MessageID), strings.TrimSpace(req.Title),+ )+ if err != nil {+ // A busy source is a retryable, user-actionable state, not a fault:+ // snapshotting would pause the sandbox and interrupt the running turn.+ if stderrors.Is(err, service.ErrForkSourceBusy) {+ c.JSON(http.StatusConflict, gin.H{+ "success": false,+ "error": "source session has an active turn",+ "code": "FORK_SOURCE_BUSY",+ })+ return+ }+ if stderrors.Is(err, service.ErrForkSessionNotFound) {+ _ = c.Error(errors.NewNotFoundError("session not found"))+ return+ }+ if stderrors.Is(err, service.ErrForkMessageNotFound) {+ _ = c.Error(errors.NewNotFoundError("message not found"))+ return+ }+ if stderrors.Is(err, service.ErrForkMessageNotUser) {+ _ = c.Error(errors.NewBadRequestError("fork point must be a user or assistant message"))+ return+ }+ logger.Errorf(ctx, "fork session %s failed: %v", sessionID, err)+ _ = c.Error(errors.NewInternalServerError("fork session failed"))+ return+ }++ c.JSON(http.StatusOK, gin.H{"success": true, "data": result})+}diff --git a/internal/handler/session/fork_test.go b/internal/handler/session/fork_test.gonew file mode 100644index 000000000..c1cdecd94--- /dev/null+++ b/internal/handler/session/fork_test.go@@ -0,0 +1,135 @@+package session++import (+ "bytes"+ "context"+ "encoding/json"+ "errors"+ "net/http"+ "net/http/httptest"+ "testing"++ "github.com/Tencent/WeKnora/internal/application/service"+ "github.com/Tencent/WeKnora/internal/middleware"+ "github.com/gin-gonic/gin"+ "github.com/stretchr/testify/require"+)++type stubForker struct {+ result *service.ForkResult+ err error+ gotMsg string+ gotTit string+}++func (s *stubForker) Fork(+ _ context.Context, _ uint64, _, _, messageID, title string,+) (*service.ForkResult, error) {+ s.gotMsg = messageID+ s.gotTit = title+ return s.result, s.err+}++func performFork(t *testing.T, forker sessionForker, body string) *httptest.ResponseRecorder {+ t.Helper()+ gin.SetMode(gin.TestMode)+ h := &Handler{forkService: forker}++ w := httptest.NewRecorder()+ r := gin.New()+ r.Use(middleware.ErrorHandler())+ r.POST("/sessions/:session_id/fork", h.ForkSession)+ req := httptest.NewRequest(http.MethodPost, "/sessions/src/fork", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")+ r.ServeHTTP(w, req)+ return w+}++func TestForkSessionReturnsNewSessionID(t *testing.T) {+ forker := &stubForker{result: &service.ForkResult{SessionID: "new-1"}}++ w := performFork(t, forker, `{"message_id":"u-2"}`)++ require.Equal(t, http.StatusOK, w.Code)+ require.Equal(t, "u-2", forker.gotMsg)++ var body map[string]any+ require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))+ data := body["data"].(map[string]any)+ require.Equal(t, "new-1", data["session_id"])+ require.Equal(t, false, data["degraded"])+}++func TestForkSessionSurfacesDegradeReason(t *testing.T) {+ forker := &stubForker{result: &service.ForkResult{+ SessionID: "new-1", Degraded: true, Reason: service.ForkDegradeSandboxGone,+ }}++ w := performFork(t, forker, `{"message_id":"u-2"}`)++ require.Equal(t, http.StatusOK, w.Code)+ var body map[string]any+ require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))+ data := body["data"].(map[string]any)+ require.Equal(t, true, data["degraded"])+ require.Equal(t, "SANDBOX_GONE", data["reason"])+}++func TestForkSessionMapsBusySourceTo409(t *testing.T) {+ forker := &stubForker{err: service.ErrForkSourceBusy}++ w := performFork(t, forker, `{"message_id":"u-2"}`)++ require.Equal(t, http.StatusConflict, w.Code)+ var body map[string]any+ require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))+ require.Equal(t, "FORK_SOURCE_BUSY", body["code"])+}++func TestForkSessionMapsMissingSessionTo404(t *testing.T) {+ forker := &stubForker{err: service.ErrForkSessionNotFound}++ w := performFork(t, forker, `{"message_id":"u-2"}`)++ require.Equal(t, http.StatusNotFound, w.Code)+}++func TestForkSessionMapsMissingMessageTo404(t *testing.T) {+ forker := &stubForker{err: service.ErrForkMessageNotFound}++ w := performFork(t, forker, `{"message_id":"u-2"}`)++ require.Equal(t, http.StatusNotFound, w.Code)+}++func TestForkSessionMapsNonUserForkPointTo400(t *testing.T) {+ forker := &stubForker{err: service.ErrForkMessageNotUser}++ w := performFork(t, forker, `{"message_id":"a-1"}`)++ require.Equal(t, http.StatusBadRequest, w.Code)+}++func TestForkSessionRejectsMissingMessageID(t *testing.T) {+ forker := &stubForker{result: &service.ForkResult{SessionID: "new-1"}}++ w := performFork(t, forker, `{}`)++ require.Equal(t, http.StatusBadRequest, w.Code)+}++func TestForkSessionMapsUnknownErrorTo500(t *testing.T) {+ forker := &stubForker{err: errors.New("boom")}++ w := performFork(t, forker, `{"message_id":"u-2"}`)++ require.Equal(t, http.StatusInternalServerError, w.Code)+}++func TestForkSessionPassesTitleThrough(t *testing.T) {+ forker := &stubForker{result: &service.ForkResult{SessionID: "new-1"}}++ performFork(t, forker, `{"message_id":"u-2","title":"我的分支"}`)++ require.Equal(t, "我的分支", forker.gotTit)+}diff --git a/internal/handler/session/handler.go b/internal/handler/session/handler.goindex fb1c82cf3..806ca04ea 100644--- a/internal/handler/session/handler.go+++ b/internal/handler/session/handler.go@@ -40,7 +40,13 @@ type Handler struct {// after an agent turn completes. May be nil when the sandbox backend does// not support artifact collection; handlers must check before using.artifactCollector *service.ArtifactCollector- memoryService interfaces.MemoryService // Service for cross-session long-term memory+ // workspaceCheckpointer commits the sandbox /workspace at the end of each+ // agent turn so session fork can roll back to a specific message. May be+ // nil when the deployment has no sandbox backend.+ workspaceCheckpointer *service.WorkspaceCheckpointer+ // sandboxIDLookup resolves a session's bound sandbox without provisioning.+ sandboxIDLookup SandboxIDLookup+ memoryService interfaces.MemoryService // Service for cross-session long-term memory// userService / memberService back the sandbox terminal's self-contained// handshake (browser WebSocket upgrades cannot send Authorization).userService interfaces.UserService@@ -56,6 +62,9 @@ type Handler struct {// redis backs the distributed desktop slot. Nil in Lite mode, where the// in-process limiter is the correct degradation.redis *redis.Client+ // forkService branches a session at a chosen user message. May be nil in+ // deployments where fork is not wired; ForkSession checks.+ forkService sessionForker}// NewHandler creates a new instance of Handler with all necessary dependencies@@ -78,6 +87,8 @@ func NewHandler(imageResolver *docparser.ImageResolver,temporaryDocuments interfaces.TemporaryDocumentService,artifactCollector *service.ArtifactCollector,+ workspaceCheckpointer *service.WorkspaceCheckpointer,+ sandboxIDLookup SandboxIDLookup,memoryService interfaces.MemoryService,userService interfaces.UserService,memberService interfaces.TenantMemberService,@@ -87,33 +98,36 @@ func NewHandler(desktopTickets service.SandboxDesktopTicketStore,desktopLast service.SandboxDesktopLastStore,rdb *redis.Client,+ forkService *service.SessionForkService,) *Handler {- return &Handler{- browserSkill: browserSkill,- sessionService: sessionService,- messageService: messageService,- suggestionService: suggestionService,- streamManager: streamManager,- config: config,- knowledgebaseService: knowledgebaseService,- customAgentService: customAgentService,- tenantService: tenantService,- agentShareService: agentShareService,- kbShareService: kbShareService,- fileService: fileService,- resourceCatalog: resourceCatalog,- storageResolver: storageResolver,- modelService: modelService,- temporaryDocuments: temporaryDocuments,- artifactCollector: artifactCollector,- memoryService: memoryService,- userService: userService,- memberService: memberService,- terminalService: terminalService,- desktopService: desktopService,- desktopTickets: desktopTickets,- desktopLast: desktopLast,- redis: rdb,+ h := &Handler{+ browserSkill: browserSkill,+ sessionService: sessionService,+ messageService: messageService,+ suggestionService: suggestionService,+ streamManager: streamManager,+ config: config,+ knowledgebaseService: knowledgebaseService,+ customAgentService: customAgentService,+ tenantService: tenantService,+ agentShareService: agentShareService,+ kbShareService: kbShareService,+ fileService: fileService,+ resourceCatalog: resourceCatalog,+ storageResolver: storageResolver,+ modelService: modelService,+ temporaryDocuments: temporaryDocuments,+ artifactCollector: artifactCollector,+ workspaceCheckpointer: workspaceCheckpointer,+ sandboxIDLookup: sandboxIDLookup,+ memoryService: memoryService,+ userService: userService,+ memberService: memberService,+ terminalService: terminalService,+ desktopService: desktopService,+ desktopTickets: desktopTickets,+ desktopLast: desktopLast,+ redis: rdb,attachmentProcessor: NewAttachmentProcessor(fileService,documentReader,@@ -121,6 +135,10 @@ func NewHandler(modelService,),}+ if forkService != nil {+ h.forkService = forkService+ }+ return h}// CreateSession godocdiff --git a/internal/handler/session/helpers.go b/internal/handler/session/helpers.goindex 2f05ee139..4cb04a7bb 100644--- a/internal/handler/session/helpers.go+++ b/internal/handler/session/helpers.go@@ -309,6 +309,7 @@ func (h *Handler) setupStreamHandler(streamHandler := NewAgentStreamHandler(ctx, sessionID, assistantMessageID, requestID, tenantID, receivedAt,assistantMessage, h.streamManager, eventBus, h.artifactCollector,+ h.workspaceCheckpointer, h.sandboxIDLookup,)streamHandler.Subscribe()return streamHandlerdiff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.goindex 8c708152c..d50476d63 100644--- a/internal/handler/session/qa.go+++ b/internal/handler/session/qa.go@@ -1194,12 +1194,7 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitlelogger.Infof(streamCtx.asyncCtx, "Knowledge QA service completed for session: %s", sessionID)updateCtx := context.WithValue(streamCtx.asyncCtx, types.TenantIDContextKey, reqCtx.session.TenantID)- h.completeAssistantMessage(updateCtx, streamCtx.assistantMessage, reqCtx.query, reqCtx.userMessageID)- streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{- Type: event.EventAgentComplete,- SessionID: sessionID,- Data: event.AgentCompleteData{FinalAnswer: streamCtx.assistantMessage.Content},- })+ h.completeQuickAnswerTurn(updateCtx, streamCtx, reqCtx.query, reqCtx.userMessageID)}return nil})@@ -1674,6 +1669,31 @@ func appendQuickAnswerReasoning(msg *types.Message, content string) {ensureQuickAnswerStep(msg).ReasoningContent += content}+// completeQuickAnswerTurn finishes a KnowledgeQA (fast-answer) turn.+// EventAgentComplete must run before the GORM write: handleComplete attaches+// SandboxCheckpoint (and artifacts) to the in-memory message, and+// completeAssistantMessage is the only persist on this path.+func (h *Handler) completeQuickAnswerTurn(+ ctx context.Context, streamCtx *sseStreamContext, query, userMessageID string,+) {+ if streamCtx == nil || streamCtx.assistantMessage == nil {+ return+ }+ if streamCtx.eventBus != nil {+ // MessageID is what handleComplete keys on. Leave FinalAnswer empty:+ // KnowledgeQA already accumulated the answer on the message, and+ // handleComplete would append FinalAnswer a second time.+ _ = streamCtx.eventBus.Emit(ctx, event.Event{+ Type: event.EventAgentComplete,+ SessionID: streamCtx.assistantMessage.SessionID,+ Data: event.AgentCompleteData{+ MessageID: streamCtx.assistantMessage.ID,+ },+ })+ }+ h.completeAssistantMessage(ctx, streamCtx.assistantMessage, query, userMessageID)+}+// completeAssistantMessage marks an assistant message as complete, updates it,// and asynchronously indexes the Q&A pair into the chat history knowledge base.func (h *Handler) completeAssistantMessage(diff --git a/internal/handler/session/workspace_checkpoint_completion_test.go b/internal/handler/session/workspace_checkpoint_completion_test.gonew file mode 100644index 000000000..c6759ec7e--- /dev/null+++ b/internal/handler/session/workspace_checkpoint_completion_test.go@@ -0,0 +1,151 @@+package session++import (+ "context"+ "errors"+ "strings"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/application/service"+ "github.com/Tencent/WeKnora/internal/event"+ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/stretchr/testify/require"+)++type stubShellRunner struct {+ stdout string+ exitCode int+ err error+ calls int+}++func (s *stubShellRunner) ExecShellCommand(+ _ context.Context, _ string, _, _ string, _ time.Duration, _ map[string]string,+) (*sandbox.ExecuteResult, error) {+ s.calls+++ if s.err != nil {+ return nil, s.err+ }+ return &sandbox.ExecuteResult{ExitCode: s.exitCode, Stdout: s.stdout}, nil+}++type stubSandboxIDLookup struct {+ id string+ ok bool+}++func (s stubSandboxIDLookup) BoundSandboxID(context.Context, string) (string, bool) {+ return s.id, s.ok+}++func newCheckpointHandler(+ t *testing.T, runner service.SandboxShellRunner, lookup SandboxIDLookup,+) (*AgentStreamHandler, *types.Message) {+ t.Helper()+ message := &types.Message{ID: "m1", SessionID: "s1", Role: "assistant"}+ h := NewAgentStreamHandler(+ context.Background(), "s1", "m1", "req1", 1, time.Now(),+ message, &completionEventRecorder{}, event.NewEventBus(), nil,+ service.NewWorkspaceCheckpointer(runner), lookup,+ )+ return h, message+}++func completeEvent() event.Event {+ return event.Event{Data: event.AgentCompleteData{MessageID: "m1", FinalAnswer: "done"}}+}++func TestHandleCompleteRecordsCheckpoint(t *testing.T) {+ runner := &stubShellRunner{stdout: strings.Repeat("a", 40) + "\n"}+ h, message := newCheckpointHandler(t, runner, stubSandboxIDLookup{id: "sbx-1", ok: true})++ require.NoError(t, h.handleComplete(context.Background(), completeEvent()))++ require.Equal(t, 1, runner.calls)+ require.NotNil(t, message.SandboxCheckpoint)+ require.Equal(t, "sbx-1", message.SandboxCheckpoint.SandboxID)+ require.Equal(t, strings.Repeat("a", 40), message.SandboxCheckpoint.CommitSHA)+}++// A failed checkpoint must never disturb the reply: the message still+// completes, it just carries no checkpoint and cannot serve as a fork point.+func TestHandleCompleteSurvivesCheckpointFailure(t *testing.T) {+ runner := &stubShellRunner{err: errors.New("sandbox unreachable")}+ h, message := newCheckpointHandler(t, runner, stubSandboxIDLookup{id: "sbx-1", ok: true})++ require.NoError(t, h.handleComplete(context.Background(), completeEvent()))++ require.Nil(t, message.SandboxCheckpoint)+ require.True(t, message.IsCompleted)+}++func TestHandleCompleteSkipsCheckpointWithoutBoundSandbox(t *testing.T) {+ runner := &stubShellRunner{stdout: strings.Repeat("a", 40) + "\n"}+ h, message := newCheckpointHandler(t, runner, stubSandboxIDLookup{ok: false})++ require.NoError(t, h.handleComplete(context.Background(), completeEvent()))++ require.Zero(t, runner.calls)+ require.Nil(t, message.SandboxCheckpoint)+}++func TestHandleCompleteWorksWithoutCheckpointerWired(t *testing.T) {+ message := &types.Message{ID: "m1", SessionID: "s1", Role: "assistant"}+ h := NewAgentStreamHandler(+ context.Background(), "s1", "m1", "req1", 1, time.Now(),+ message, &completionEventRecorder{}, event.NewEventBus(), nil, nil, nil,+ )++ require.NoError(t, h.handleComplete(context.Background(), completeEvent()))+ require.Nil(t, message.SandboxCheckpoint)+}++type capturingMessageService struct {+ interfaces.MessageService+ content string+ checkpoint *types.SandboxCheckpoint+}++func (s *capturingMessageService) UpdateMessage(_ context.Context, message *types.Message) error {+ if message == nil {+ return nil+ }+ s.content = message.Content+ if message.SandboxCheckpoint != nil {+ cp := *message.SandboxCheckpoint+ s.checkpoint = &cp+ }+ return nil+}++func (s *capturingMessageService) IndexMessageToKB(context.Context, string, string, string, string) {}++func TestQuickAnswerCompletionPersistsSandboxCheckpoint(t *testing.T) {+ runner := &stubShellRunner{stdout: strings.Repeat("a", 40) + "\n"}+ bus := event.NewEventBus()+ message := &types.Message{+ ID: "m1", SessionID: "s1", Role: "assistant", Content: "hello from quick answer",+ }+ streamHandler := NewAgentStreamHandler(+ context.Background(), "s1", "m1", "req1", 1, time.Now(),+ message, &completionEventRecorder{}, bus,+ nil, service.NewWorkspaceCheckpointer(runner), stubSandboxIDLookup{id: "sbx-1", ok: true},+ )+ streamHandler.Subscribe()++ stub := &capturingMessageService{}+ h := &Handler{messageService: stub}+ h.completeQuickAnswerTurn(context.Background(), &sseStreamContext{+ eventBus: bus,+ assistantMessage: message,+ }, "", "")++ require.Equal(t, 1, runner.calls, "quick-answer complete must checkpoint before persist")+ require.NotNil(t, stub.checkpoint, "UpdateMessage must see SandboxCheckpoint")+ require.Equal(t, "sbx-1", stub.checkpoint.SandboxID)+ require.Equal(t, strings.Repeat("a", 40), stub.checkpoint.CommitSHA)+ require.Equal(t, "hello from quick answer", stub.content, "complete event must not re-append the answer")+}diff --git a/internal/router/routes_chat.go b/internal/router/routes_chat.goindex 5f543b7c6..5a9606ce2 100644--- a/internal/router/routes_chat.go+++ b/internal/router/routes_chat.go@@ -64,6 +64,7 @@ func RegisterSessionRoutes(sessions.GET("/:id/attachments/:attachment_id/preview", handler.PreviewTemporaryDocument)sessions.DELETE("/:id/attachments/:attachment_id", handler.DeleteTemporaryDocument)sessions.POST("/:session_id/stop", handler.StopSession)+ sessions.POST("/:session_id/fork", handler.ForkSession)sessions.POST("/:session_id/sandbox/terminal-ticket", handler.IssueSandboxTerminalTicket)sessions.POST("/:session_id/sandbox/desktop-ticket", handler.IssueSandboxDesktopTicket)sessions.POST("/:session_id/sandbox/desktop/activity", handler.ReportSandboxDesktopActivity)diff --git a/internal/sandbox/cube_remote_client_test.go b/internal/sandbox/cube_remote_client_test.goindex fa5510690..2f25af607 100644--- a/internal/sandbox/cube_remote_client_test.go+++ b/internal/sandbox/cube_remote_client_test.go@@ -652,6 +652,11 @@ func TestNormalizeCubeError(t *testing.T) {StatusCode: http.StatusBadRequest,Message: "cannot delete template x because there are paused sandboxes using it",}, RemoteErrorKindConflict},+ {"delete snapshot runtime refs", "DeleteSnapshot", &cubesandbox.APIError{+ StatusCode: http.StatusInternalServerError,+ Message: "CubeMaster returned error code 130409: template attempt is already in progress: " ++ "snapshot snap-x still has 2 active runtime ref(s): a@host, b@host",+ }, RemoteErrorKindConflict},{"delete snapshot bad id", "DeleteSnapshot", &cubesandbox.APIError{StatusCode: http.StatusBadRequest,Message: "invalid snapshot id",diff --git a/internal/sandbox/docker_remote_client.go b/internal/sandbox/docker_remote_client.goindex d56296508..1213bf0bf 100644--- a/internal/sandbox/docker_remote_client.go+++ b/internal/sandbox/docker_remote_client.go@@ -14,7 +14,7 @@// Get/List → GET /containers/json?filters=label=…// Delete → DELETE /containers/{id}?force=1// Exec → POST /containers/{id}/exec → /exec/{id}/start (hijack)-// Snapshot → POST /commit (skill images under weknora-skill/)+// Snapshot → POST /commit (skill images under weknora-skill/, fork images under weknora-fork/)//// Every file operation uses exec with an explicit account (root by default),// timeout and activity tracking. Archive endpoints bypass those exec settings.@@ -1183,8 +1183,12 @@ func (c *DockerRemoteClient) ensureImage(ctx context.Context, image string) erro// Skill snapshots are daemon-local commits, not registry tags. Pulling// one would hit Docker Hub for a name we minted and never pushed, and a// miss here means "this daemon does not have the image", not "fetch it".- if dockerIsSkillSnapshotRef(image) {- return dockerInvalidRequest("Create", "skill snapshot image "+image+" is not on this daemon")+ if dockerIsLocalSnapshotRef(image) {+ kind := "skill"+ if dockerIsForkSnapshotRef(image) {+ kind = "fork"+ }+ return dockerInvalidRequest("Create", kind+" snapshot image "+image+" is not on this daemon")}pullCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), dockerImagePullBudget)defer cancel()diff --git a/internal/sandbox/docker_snapshot.go b/internal/sandbox/docker_snapshot.goindex bd2f70fbd..283b35554 100644--- a/internal/sandbox/docker_snapshot.go+++ b/internal/sandbox/docker_snapshot.go@@ -18,6 +18,16 @@ const (dockerSkillSnapshotLabel = "com.weknora.sandbox.skill-snapshot"dockerSkillSnapshotSourceLabel = "com.weknora.sandbox.skill-snapshot-source"++ // DockerForkSnapshotRepo is the local image namespace for session-fork+ // snapshots. It is deliberately separate from dockerSkillSnapshotRepo: the+ // skill reaper prunes by the skill namespace and labels, and letting fork+ // snapshots share them would have each reaper collecting the other's+ // images.+ DockerForkSnapshotRepo = "weknora-fork"++ dockerForkSnapshotLabel = "com.weknora.sandbox.fork-snapshot"+ dockerForkSnapshotSourceLabel = "com.weknora.sandbox.fork-snapshot-source")// CreateSnapshot commits the container's filesystem into a tagged local image.@@ -34,25 +44,58 @@ func (c *DockerRemoteClient) CreateSnapshot(if id == "" {return RemoteSnapshotRef{}, dockerInvalidRequest("CreateSnapshot", "sandbox ID is required")}- reference, err := dockerSkillSnapshotReference(name, id)+ return c.commitSnapshot(+ ctx, id, name,+ dockerSkillSnapshotRepo,+ "weknora skill snapshot",+ dockerSkillSnapshotLabel,+ dockerSkillSnapshotSourceLabel,+ "CreateSnapshot",+ )+}++// CreateForkSnapshot commits the container into the fork image namespace.+// Same shape as CreateSnapshot; a different repo and labels keep the skill+// reaper from collecting (or being collected by) session-fork images.+func (c *DockerRemoteClient) CreateForkSnapshot(+ ctx context.Context, sandboxID string, name string,+) (RemoteSnapshotRef, error) {+ id := strings.TrimSpace(sandboxID)+ if id == "" {+ return RemoteSnapshotRef{}, dockerInvalidRequest("CreateForkSnapshot", "sandbox ID is required")+ }+ return c.commitSnapshot(+ ctx, id, name,+ DockerForkSnapshotRepo,+ "weknora fork snapshot",+ dockerForkSnapshotLabel,+ dockerForkSnapshotSourceLabel,+ "CreateForkSnapshot",+ )+}++func (c *DockerRemoteClient) commitSnapshot(+ ctx context.Context,+ sandboxID, name, repo, comment, label, sourceLabel, op string,+) (RemoteSnapshotRef, error) {+ reference, err := dockerSnapshotReference(repo, name, sandboxID, op)if err != nil {return RemoteSnapshotRef{}, err}- committed, err := c.api.ContainerCommit(ctx, id, client.ContainerCommitOptions{+ committed, err := c.api.ContainerCommit(ctx, sandboxID, client.ContainerCommitOptions{Reference: reference,- Comment: "weknora skill snapshot",+ Comment: comment,Changes: []string{- "LABEL " + dockerSkillSnapshotLabel + "=true",- "LABEL " + dockerSkillSnapshotSourceLabel + "=" + id,+ "LABEL " + label + "=true",+ "LABEL " + sourceLabel + "=" + sandboxID,},})if err != nil {- return RemoteSnapshotRef{}, dockerError("CreateSnapshot", err)+ return RemoteSnapshotRef{}, dockerError(op, err)}if strings.TrimSpace(committed.ID) == "" {- return RemoteSnapshotRef{}, dockerInvalidRequest(- "CreateSnapshot", "provider returned an empty snapshot ID")+ return RemoteSnapshotRef{}, dockerInvalidRequest(op, "provider returned an empty snapshot ID")}return RemoteSnapshotRef{ID: dockerCanonicalSnapshotID(reference),@@ -86,7 +129,11 @@ func (c *DockerRemoteClient) DeleteSnapshot(ctx context.Context, snapshotID stri}return normalized}- c.pruneDanglingSkillImages(ctx)+ if dockerIsForkSnapshotRef(id) {+ c.pruneDanglingForkImages(ctx)+ } else {+ c.pruneDanglingSkillImages(ctx)+ }return nil}@@ -119,6 +166,29 @@ func (c *DockerRemoteClient) pruneDanglingSkillImages(ctx context.Context) {}}+// pruneDanglingForkImages drops untagged fork-snapshot images. Same rationale+// as pruneDanglingSkillImages; the filter is the fork label so a skill delete+// cannot sweep a live fork image and vice versa.+func (c *DockerRemoteClient) pruneDanglingForkImages(ctx context.Context) {+ listed, err := c.api.ImageList(ctx, client.ImageListOptions{+ All: true,+ Filters: client.Filters{}.Add("label", dockerForkSnapshotLabel+"=true"),+ })+ if err != nil {+ return+ }+ for _, item := range listed.Items {+ if !dockerImageIsForkSnapshot(item) || dockerImageHasTag(item) {+ continue+ }+ id := strings.TrimSpace(item.ID)+ if id == "" {+ continue+ }+ _, _ = c.api.ImageRemove(ctx, id, client.ImageRemoveOptions{PruneChildren: true})+ }+}+func dockerImageHasTag(item image.Summary) bool {for _, tag := range item.RepoTags {if strings.TrimSpace(tag) != "" && tag != "<none>:<none>" {@@ -169,9 +239,33 @@ func dockerImageIsSkillSnapshot(item image.Summary) bool {return false}+func dockerImageIsForkSnapshot(item image.Summary) bool {+ if item.Labels[dockerForkSnapshotLabel] == "true" {+ return true+ }+ for _, tag := range item.RepoTags {+ if dockerIsForkSnapshotRef(tag) {+ return true+ }+ }+ return false+}+func dockerIsSkillSnapshotRef(ref string) bool {+ return dockerIsRepoSnapshotRef(ref, dockerSkillSnapshotRepo)+}++func dockerIsForkSnapshotRef(ref string) bool {+ return dockerIsRepoSnapshotRef(ref, DockerForkSnapshotRepo)+}++func dockerIsLocalSnapshotRef(ref string) bool {+ return dockerIsSkillSnapshotRef(ref) || dockerIsForkSnapshotRef(ref)+}++func dockerIsRepoSnapshotRef(ref, repo string) bool {trimmed := strings.TrimSpace(ref)- prefix := dockerSkillSnapshotRepo + "/"+ prefix := repo + "/"if strings.HasPrefix(trimmed, prefix) {return true}@@ -204,15 +298,15 @@ func dockerCanonicalSnapshotID(ref string) string {return strings.TrimSuffix(trimmed, ":latest")}-func dockerSkillSnapshotReference(name, sandboxID string) (string, error) {+func dockerSnapshotReference(repo, name, sandboxID, op string) (string, error) {base := dockerSanitizeImageName(name)if base == "" {base = dockerSanitizeImageName(sandboxID)}if base == "" {- return "", dockerInvalidRequest("CreateSnapshot", "snapshot name is required")+ return "", dockerInvalidRequest(op, "snapshot name is required")}- return dockerSkillSnapshotRepo + "/" + base, nil+ return repo + "/" + base, nil}// dockerSanitizeImageName maps an install-generated snapshot name onto a@@ -240,3 +334,5 @@ func dockerSanitizeImageName(raw string) string {}return out}++var _ forkSnapshotCreator = (*DockerRemoteClient)(nil)diff --git a/internal/sandbox/docker_snapshot_test.go b/internal/sandbox/docker_snapshot_test.goindex 8f731d0fa..25f08f06d 100644--- a/internal/sandbox/docker_snapshot_test.go+++ b/internal/sandbox/docker_snapshot_test.go@@ -129,6 +129,41 @@ func TestDockerDeleteSnapshotSweepsUntaggedSkillImages(t *testing.T) {"the sweep must take the untagged snapshot and nothing that is still named")}+func TestDockerDeleteSnapshotSweepsUntaggedForkImages(t *testing.T) {+ engine := newFakeDockerEngine()+ engine.images = []image.Summary{+ {+ ID: "sha256:retired-fork",+ RepoTags: []string{DockerForkSnapshotRepo + "/fork-a:latest"},+ Labels: map[string]string{dockerForkSnapshotLabel: "true"},+ },+ {+ ID: "sha256:orphan-fork",+ RepoTags: []string{"<none>:<none>"},+ Labels: map[string]string{dockerForkSnapshotLabel: "true"},+ },+ {+ ID: "sha256:orphan-skill",+ RepoTags: []string{"<none>:<none>"},+ Labels: map[string]string{dockerSkillSnapshotLabel: "true"},+ },+ {+ ID: "sha256:live-fork",+ RepoTags: []string{DockerForkSnapshotRepo + "/fork-b:latest"},+ Labels: map[string]string{dockerForkSnapshotLabel: "true"},+ },+ }+ docker := newTestDockerClient(t, engine)++ require.NoError(t, docker.DeleteSnapshot(+ context.Background(), DockerForkSnapshotRepo+"/fork-a"))++ require.Equal(t,+ []string{DockerForkSnapshotRepo + "/fork-a", "sha256:orphan-fork"},+ engine.removedImages,+ "a fork delete must not sweep skill images")+}+func TestDockerDeleteSnapshotSweepFailureIsNotAnError(t *testing.T) {engine := newFakeDockerEngine()engine.images = []image.Summary{@@ -181,6 +216,77 @@ func TestDockerCreateDoesNotPullAMissingSkillSnapshot(t *testing.T) {"a local commit must not be fetched from a registry")}+func TestDockerCreateForkSnapshotTagsAForkImage(t *testing.T) {+ engine := newFakeDockerEngine()+ docker := newTestDockerClient(t, engine)++ ref, err := docker.CreateForkSnapshot(context.Background(), "container-1", "fork-session-a-1")+ require.NoError(t, err)+ require.Equal(t, DockerForkSnapshotRepo+"/fork-session-a-1", ref.ID)+ require.Len(t, engine.committed, 1)+ require.Equal(t, DockerForkSnapshotRepo+"/fork-session-a-1", engine.committed[0].Reference)+ require.Equal(t, "weknora fork snapshot", engine.committed[0].Comment)+ require.False(t, engine.committed[0].NoPause,+ "the Engine must pause the container for the duration of the commit")+ require.Contains(t, engine.committed[0].Changes, "LABEL "+dockerForkSnapshotLabel+"=true")+ require.Contains(t, engine.committed[0].Changes,+ "LABEL "+dockerForkSnapshotSourceLabel+"=container-1")+}++func TestDockerListTemplatesHidesForkSnapshots(t *testing.T) {+ engine := newFakeDockerEngine()+ engine.images = []image.Summary{+ {+ ID: "sha256:base",+ RepoTags: []string{"weknora/sandbox:test"},+ Labels: map[string]string{dockerTemplateLabel: "true"},+ },+ {+ ID: "sha256:fork",+ RepoTags: []string{DockerForkSnapshotRepo + "/fork-session-a-1:latest"},+ Labels: map[string]string{dockerForkSnapshotLabel: "true"},+ },+ {+ ID: "sha256:fork-tag-only",+ RepoTags: []string{DockerForkSnapshotRepo + "/untagged-label:latest"},+ },+ }+ docker := newTestDockerClient(t, engine)++ templates, err := docker.ListTemplates(context.Background())+ require.NoError(t, err)+ require.Len(t, templates, 1)+ require.Equal(t, "weknora/sandbox:test", templates[0].ID)+}++func TestDockerListSnapshotsExcludesForkImages(t *testing.T) {+ engine := newFakeDockerEngine()+ docker := newTestDockerClient(t, engine)+ ctx := context.Background()++ _, err := docker.CreateSnapshot(ctx, "container-1", "weknora-sk-cfg1-g1")+ require.NoError(t, err)+ _, err = docker.CreateForkSnapshot(ctx, "container-1", "fork-session-a-1")+ require.NoError(t, err)++ listed, err := docker.ListSnapshots(ctx, "")+ require.NoError(t, err)+ require.Len(t, listed, 1)+ require.Equal(t, "weknora-skill/weknora-sk-cfg1-g1", listed[0].ID)+}++func TestDockerCreateDoesNotPullAMissingForkSnapshot(t *testing.T) {+ engine := newFakeDockerEngine()+ docker := newTestDockerClient(t, engine)++ _, err := docker.Create(context.Background(), RemoteCreateRequest{+ TemplateID: DockerForkSnapshotRepo + "/fork-session-a-1",+ })+ require.True(t, IsRemoteInvalidRequest(err), err)+ require.Empty(t, engine.pulled,+ "a local fork commit must not be fetched from a registry")+}+func TestDockerSanitizeImageName(t *testing.T) {require.Equal(t, "weknora-sk-cfg1-g1", dockerSanitizeImageName("weknora-sk-cfg1-g1"))require.Equal(t, "abc-def", dockerSanitizeImageName("ABC_DEF"))diff --git a/internal/sandbox/docker_template_catalog.go b/internal/sandbox/docker_template_catalog.goindex b17a89bdf..4b46b393c 100644--- a/internal/sandbox/docker_template_catalog.go+++ b/internal/sandbox/docker_template_catalog.go@@ -11,8 +11,9 @@// nothing to do with sandboxes. Listing all of them would bury the one the// admin needs, so the catalog only reports images that are recognisably// sandbox templates.-// - Skill snapshots live in the same image store (weknora-skill/…), so they-// are subtracted the way Cube hides snap- IDs from GET /templates.+// - Skill and fork snapshots live in the same image store (weknora-skill/…+// and weknora-fork/…), so they are subtracted the way Cube hides snap- IDs+// from GET /templates.// - Making the standard template exist means pulling, which can take minutes// on a cold host. The pull therefore runs in the background and the// template reports "building" until it lands, mirroring how the other@@ -58,14 +59,15 @@ func (c *DockerRemoteClient) ListTemplates(ctx context.Context) ([]RemoteTemplatconfigured := strings.TrimSpace(c.settings.Image)configuredPresent := falsefor _, image := range listed.Items {- snapshot := dockerImageIsSkillSnapshot(image)+ snapshot := dockerImageIsSkillSnapshot(image) || dockerImageIsForkSnapshot(image)for _, tag := range image.RepoTags {if tag == "" || tag == "<none>:<none>" {continue}- // Skill snapshots are images, so they would otherwise appear in- // the "pick a base template" list the way Cube's snap- IDs used- // to. Hide them unless this config's stored image is that tag.+ // Skill and fork snapshots are images, so they would otherwise+ // appear in the "pick a base template" list the way Cube's snap-+ // IDs used to. Hide them unless this config's stored image is+ // that tag.if snapshot && tag != configured {continue}diff --git a/internal/sandbox/e2b_integration_test.go b/internal/sandbox/e2b_integration_test.goindex 6c575529d..c4646edf1 100644--- a/internal/sandbox/e2b_integration_test.go+++ b/internal/sandbox/e2b_integration_test.go@@ -251,6 +251,7 @@ func newE2BIntegrationLifecycle(createRequest,time.Minute,"",+ nil,)if err != nil {t.Fatalf("newRemoteSessionLifecycle: %v", err)diff --git a/internal/sandbox/filesystem_identity.go b/internal/sandbox/filesystem_identity.goindex 138008b9f..f65bcc3e3 100644--- a/internal/sandbox/filesystem_identity.go+++ b/internal/sandbox/filesystem_identity.go@@ -67,7 +67,22 @@ func rpcUsesCallerDeadline(path string) bool {if strings.HasPrefix(path, "/process.Process/") {return true}- return isFilesystemContentRPC(path)+ if isFilesystemContentRPC(path) {+ return true+ }+ return isCubeSandboxSnapshotRPC(path)+}++// isCubeSandboxSnapshotRPC reports POST /sandboxes/{id}/snapshots. Cube pauses+// the live MicroVM and copies its disk; that exceeds CubeHTTPTimeout (30s).+func isCubeSandboxSnapshotRPC(path string) bool {+ const prefix = "/sandboxes/"+ const suffix = "/snapshots"+ if !strings.HasPrefix(path, prefix) || !strings.HasSuffix(path, suffix) {+ return false+ }+ id := strings.TrimSuffix(strings.TrimPrefix(path, prefix), suffix)+ return id != "" && !strings.Contains(id, "/")}func isFilesystemContentRPC(path string) bool {diff --git a/internal/sandbox/filesystem_identity_test.go b/internal/sandbox/filesystem_identity_test.goindex a58d39375..d94dd2ea3 100644--- a/internal/sandbox/filesystem_identity_test.go+++ b/internal/sandbox/filesystem_identity_test.go@@ -106,6 +106,7 @@ func TestFileTransferSkipsShortHTTPTimeout(t *testing.T) {assertBudget(t, cube, "/filesystem.Filesystem/WriteFile", false)assertBudget(t, cube, "/filesystem.Filesystem/MakeDir", true)assertBudget(t, cube, "/process.Process/Start", false)+ assertBudget(t, cube, "/sandboxes/sbx-1/snapshots", false)assertBudget(t, e2b, "/files", false)assertBudget(t, e2b, "/filesystem.Filesystem/Read", false)assertBudget(t, e2b, "/filesystem.Filesystem/MakeDir", true)diff --git a/internal/sandbox/langfuse.go b/internal/sandbox/langfuse.goindex 3ce592c2d..afdea8d1d 100644--- a/internal/sandbox/langfuse.go+++ b/internal/sandbox/langfuse.go@@ -17,7 +17,8 @@ const sandboxSpanPreviewRunes = 256// the caller has no parent trace.//// Snapshot capability is forwarded: wrapping must not hide RemoteSnapshotManager-// from SnapshotManagerFrom.+// from SnapshotManagerFrom, and CreateForkSnapshot must still reach Docker's+// fork namespace.func wrapLangfuseRemoteClient(inner RemoteSandboxClient) RemoteSandboxClient {if inner == nil {return nil@@ -208,6 +209,29 @@ func (c *langfuseSnapshotClient) CreateSnapshot(return ref, err}+func (c *langfuseSnapshotClient) CreateForkSnapshot(+ ctx context.Context, sandboxID string, name string,+) (RemoteSnapshotRef, error) {+ if creator, ok := c.inner.(forkSnapshotCreator); ok {+ ctx, span := startSandboxSpan(ctx, "sandbox.create_fork_snapshot", map[string]interface{}{+ "sandbox_id": sandboxID,+ "name": name,+ }, nil)+ ref, err := creator.CreateForkSnapshot(ctx, sandboxID, name)+ span.Finish(map[string]interface{}{"snapshot_id": ref.ID}, nil, err)+ return ref, err+ }+ inner, ok := c.inner.(RemoteSnapshotManager)+ if !ok {+ return RemoteSnapshotRef{}, &RemoteError{+ Kind: RemoteErrorKindUnsupported,+ Op: "CreateForkSnapshot",+ Message: "inner client has no snapshot manager",+ }+ }+ return inner.CreateSnapshot(ctx, sandboxID, name)+}+func (c *langfuseSnapshotClient) DeleteSnapshot(ctx context.Context, snapshotID string) error {inner, ok := c.inner.(RemoteSnapshotManager)if !ok {@@ -347,6 +371,7 @@ func (c *langfuseRemoteClient) StartDesktopTTLRefresh(ctx context.Context, handlvar (_ RemoteSandboxClient = (*langfuseRemoteClient)(nil)_ RemoteSnapshotManager = (*langfuseSnapshotClient)(nil)+ _ forkSnapshotCreator = (*langfuseSnapshotClient)(nil)_ RemoteTerminalManager = (*langfuseRemoteClient)(nil)_ RemoteDesktopManager = (*langfuseRemoteClient)(nil)_ RemoteDesktopTTLRefresher = (*langfuseRemoteClient)(nil)diff --git a/internal/sandbox/langfuse_test.go b/internal/sandbox/langfuse_test.goindex 23af8ce3f..4711f182c 100644--- a/internal/sandbox/langfuse_test.go+++ b/internal/sandbox/langfuse_test.go@@ -23,6 +23,21 @@ func TestWrapLangfuseRemoteClientPreservesSnapshotCapability(t *testing.T) {require.NotEmpty(t, ref.ID)}+func TestWrapLangfuseRemoteClientPreservesForkSnapshotCapability(t *testing.T) {+ inner := newFakeRemoteClient(SandboxTypeCube)+ inner.capabilities.SupportsSnapshots = true+ client := &recordingForkSnapshotClient{fakeRemoteClient: inner}++ wrapped := wrapLangfuseRemoteClient(client)+ creator, ok := wrapped.(forkSnapshotCreator)+ require.True(t, ok, "wrapping must not hide CreateForkSnapshot")++ ref, err := creator.CreateForkSnapshot(context.Background(), "sb-1", "fork-1")+ require.NoError(t, err)+ require.Equal(t, "fork-sb-1", ref.ID)+ require.Equal(t, 1, client.forkCalls)+}+func TestWrapLangfuseRemoteClientDoesNotInventSnapshotSupport(t *testing.T) {inner := &noSnapshotClient{}wrapped := wrapLangfuseRemoteClient(inner)diff --git a/internal/sandbox/remote_errors.go b/internal/sandbox/remote_errors.goindex b89eec0d8..a3ee10d2f 100644--- a/internal/sandbox/remote_errors.go+++ b/internal/sandbox/remote_errors.go@@ -212,7 +212,14 @@ func snapshotInUseBySandboxes(message string) bool {if strings.Contains(msg, "sandboxes using") {return true}- return strings.Contains(msg, "cannot delete template") && strings.Contains(msg, "using it")+ if strings.Contains(msg, "cannot delete template") && strings.Contains(msg, "using it") {+ return true+ }+ // Cube CoW: HTTP 500 / 130409 while source + child sandboxes still reference the snapshot.+ if strings.Contains(msg, "runtime ref") {+ return true+ }+ return strings.Contains(msg, "130409")}// IsRemoteDirAlreadyExists reports whether MakeDir failed because thediff --git a/internal/sandbox/remote_errors_test.go b/internal/sandbox/remote_errors_test.goindex 0ad3dee98..95242343a 100644--- a/internal/sandbox/remote_errors_test.go+++ b/internal/sandbox/remote_errors_test.go@@ -230,6 +230,14 @@ func TestSnapshotDeleteKindPromotesInUseToConflict(t *testing.T) {msg: "cannot delete template x because there are sandboxes using it",want: RemoteErrorKindConflict,},+ {+ name: "cube 130409 runtime refs as 500",+ op: "DeleteSnapshot",+ kind: RemoteErrorKindInternal,+ msg: "unavailable: CubeMaster returned error code 130409: template attempt is already in progress: " ++ "snapshot snap-6a6707d7b51246c68ad643ee still has 2 active runtime ref(s): a@host, b@host (HTTP 500)",+ want: RemoteErrorKindConflict,+ },{name: "already conflict stays conflict",op: "DeleteSnapshot",diff --git a/internal/sandbox/remote_fake_test.go b/internal/sandbox/remote_fake_test.goindex 37dfd641a..de7be862a 100644--- a/internal/sandbox/remote_fake_test.go+++ b/internal/sandbox/remote_fake_test.go@@ -61,12 +61,14 @@ type fakeRemoteClient struct {nextID intsandboxes map[string]*fakeRemoteRecord- createCount int- connectIDs []string- connects []RemoteConnectRequest- getIDs []string- deleteIDs []string- listCount int+ createCount int+ connectIDs []string+ connects []RemoteConnectRequest+ getIDs []string+ deleteIDs []string+ listCount int+ lastCreateRequest RemoteCreateRequest+ lastCreatedID stringtrafficAccessToken string@@ -181,6 +183,8 @@ func (c *fakeRemoteClient) Create(c.mu.Lock()c.nextID++id := fmt.Sprintf("%s-%d", c.provider, c.nextID)+ c.lastCreateRequest = req+ c.lastCreatedID = idrecord := &fakeRemoteRecord{id: id,templateID: req.TemplateID,diff --git a/internal/sandbox/session_bootstrapper.go b/internal/sandbox/session_bootstrapper.gonew file mode 100644index 000000000..e44d6a7bd--- /dev/null+++ b/internal/sandbox/session_bootstrapper.go@@ -0,0 +1,53 @@+package sandbox++import "context"++// SessionBootstrapper customises how ONE session's first sandbox is created.+// It exists for session fork: a forked session boots from a snapshot of its+// parent's sandbox and then rolls /workspace back to the fork point.+//+// It is optional. A nil bootstrapper leaves the lifecycle's behaviour+// unchanged, which is what every ordinary session gets.+//+// The lifecycle calls both methods inside the per-session lifecycle lock, so+// implementations need no locking of their own and cannot race with a+// concurrent resolve of the same session.+type SessionBootstrapper interface {+ // TemplateOverride returns a template ID to create this session's sandbox+ // from instead of the config's. An empty string means "no override".+ //+ // An error aborts the create: an implementation that cannot tell whether+ // an override applies must not be silently treated as "no override",+ // because that would boot a plain sandbox for a session the user expects+ // to carry forked state.+ TemplateOverride(ctx context.Context, key SessionSandboxKey) (string, error)++ // AfterCreate runs once, immediately after the binding is written.+ //+ // Returning an error makes the lifecycle destroy the sandbox and delete+ // the binding. That severity is deliberate: a half-bootstrapped fork looks+ // completely normal but has the wrong baseline, and that silent wrongness+ // is far worse than an honest failure the next resolve can retry from a+ // clean slate.+ AfterCreate(ctx context.Context, key SessionSandboxKey, handle RemoteSandboxHandle) error+}++// SessionCreateFailureHandler is an optional SessionBootstrapper extension.+//+// AfterCreate only runs when Create succeeded. A fork snapshot that the+// provider will never boot (deleted, unknown template) would otherwise stay+// on the session forever: every Resolve retries the same dead ID. The+// lifecycle calls this when Create used a TemplateOverride and still failed,+// so the bootstrapper can retire that snapshot and let the next Resolve use+// the ordinary template.+type SessionCreateFailureHandler interface {+ OnCreateFailed(ctx context.Context, key SessionSandboxKey, createErr error)+}++// SessionBootstrapperWithClient rebinds a bootstrapper to the client that+// created the sandbox handle. AfterCreate runs under the session lifecycle+// lock, which is not reentrant, so implementations must talk to `client`+// (and the handle) directly instead of calling Resolve.+type SessionBootstrapperWithClient interface {+ WithClient(client RemoteSandboxClient) SessionBootstrapper+}diff --git a/internal/sandbox/session_bootstrapper_test.go b/internal/sandbox/session_bootstrapper_test.gonew file mode 100644index 000000000..365fcd911--- /dev/null+++ b/internal/sandbox/session_bootstrapper_test.go@@ -0,0 +1,188 @@+package sandbox++import (+ "context"+ "errors"+ "testing"++ "github.com/stretchr/testify/require"+)++var testSessionKey = SessionSandboxKey{TenantID: 1, SessionID: "session-bootstrap"}++type recordingBootstrapper struct {+ override string+ overrideErr error+ afterErr error+ afterCalls int+ afterHandleID string+}++func (b *recordingBootstrapper) TemplateOverride(+ context.Context, SessionSandboxKey,+) (string, error) {+ return b.override, b.overrideErr+}++func (b *recordingBootstrapper) AfterCreate(+ _ context.Context, _ SessionSandboxKey, handle RemoteSandboxHandle,+) error {+ b.afterCalls+++ if handle != nil {+ b.afterHandleID = handle.ID()+ }+ return b.afterErr+}++func newLifecycleForTest(t *testing.T) (*remoteSessionLifecycle, *fakeRemoteClient, SessionSandboxBindingStore) {+ t.Helper()+ client := newFakeRemoteClient(SandboxTypeCube)+ store := NewMemorySessionSandboxBindingStore()+ lc := newTestRemoteSessionLifecycle(+ t, client, store, &fakeSessionExistenceChecker{exists: true},+ )+ return lc, client, store+}++func TestCreateAndBindUsesTemplateOverride(t *testing.T) {+ lc, client, _ := newLifecycleForTest(t)+ lc.bootstrapper = &recordingBootstrapper{override: "snap-1"}++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.NoError(t, err)+ require.Equal(t, "snap-1", client.lastCreateRequest.TemplateID)+}++func TestCreateAndBindKeepsConfigTemplateWithoutOverride(t *testing.T) {+ lc, client, _ := newLifecycleForTest(t)+ lc.bootstrapper = &recordingBootstrapper{override: ""}++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.NoError(t, err)+ require.Equal(t, lc.createRequest.TemplateID, client.lastCreateRequest.TemplateID)+}++// 最重要的一条:override 绝不能污染跨 session 复用的 l.createRequest。+func TestTemplateOverrideDoesNotMutateSharedCreateRequest(t *testing.T) {+ lc, _, _ := newLifecycleForTest(t)+ baseTemplate := lc.createRequest.TemplateID+ lc.bootstrapper = &recordingBootstrapper{override: "snap-1"}++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.NoError(t, err)+ require.Equal(t, baseTemplate, lc.createRequest.TemplateID,+ "共享的 createRequest 被改了,同 config 下其他会话会从别人的快照启动")+}++func TestAfterCreateRunsWithTheNewHandle(t *testing.T) {+ lc, _, _ := newLifecycleForTest(t)+ b := &recordingBootstrapper{override: "snap-1"}+ lc.bootstrapper = b++ handle, err := lc.Resolve(context.Background(), testSessionKey)++ require.NoError(t, err)+ require.Equal(t, 1, b.afterCalls)+ require.Equal(t, handle.ID(), b.afterHandleID)+}++// 全有或全无:引导失败必须销毁沙箱并删掉 binding,否则用户会在一个+// 「文件系统停在分叉时刻而不是分叉点」的沙箱里干活。+func TestAfterCreateFailureDestroysSandboxAndBinding(t *testing.T) {+ lc, client, store := newLifecycleForTest(t)+ lc.bootstrapper = &recordingBootstrapper{override: "snap-1", afterErr: errors.New("git reset failed")}++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.Error(t, err)+ require.Contains(t, client.deleteIDs, client.lastCreatedID)++ binding, getErr := store.Get(context.Background(), testSessionKey)+ require.NoError(t, getErr)+ require.Nil(t, binding, "引导失败后不得留下 binding")+}++func TestTemplateOverrideErrorAbortsCreate(t *testing.T) {+ lc, client, _ := newLifecycleForTest(t)+ lc.bootstrapper = &recordingBootstrapper{overrideErr: errors.New("db down")}++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.Error(t, err)+ require.Empty(t, client.lastCreatedID, "读不到 override 就不该建沙箱")+}++type recordingCreateFailureHandler struct {+ recordingBootstrapper+ failedCalls int+ lastFailErr error+}++func (b *recordingCreateFailureHandler) OnCreateFailed(_ context.Context, _ SessionSandboxKey, err error) {+ b.failedCalls+++ b.lastFailErr = err+}++func TestNilBootstrapperIsANoOp(t *testing.T) {+ lc, client, _ := newLifecycleForTest(t)+ lc.bootstrapper = nil++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.NoError(t, err)+ require.Equal(t, lc.createRequest.TemplateID, client.lastCreateRequest.TemplateID)+}++// A missing fork snapshot must not be retried forever. Create using the+// override failed, so the bootstrapper has to be told — AfterCreate never+// runs, and abandon on git-reset-failure cannot fire.+func TestCreateFailureWithOverrideNotifiesBootstrapper(t *testing.T) {+ lc, client, _ := newLifecycleForTest(t)+ handler := &recordingCreateFailureHandler{+ recordingBootstrapper: recordingBootstrapper{override: "snap-1"},+ }+ lc.bootstrapper = handler+ client.createErr = NewRemoteError(+ SandboxTypeCube, "Create", RemoteErrorKindNotFound, "template gone", nil,+ )++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.Error(t, err)+ require.Equal(t, 1, handler.failedCalls)+ require.True(t, IsRemoteNotFound(handler.lastFailErr))+ require.Empty(t, client.lastCreatedID)+}++func TestCreateFailureWithoutOverrideDoesNotNotifyBootstrapper(t *testing.T) {+ lc, client, _ := newLifecycleForTest(t)+ handler := &recordingCreateFailureHandler{}+ lc.bootstrapper = handler+ client.createErr = NewRemoteError(+ SandboxTypeCube, "Create", RemoteErrorKindNotFound, "template gone", nil,+ )++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.Error(t, err)+ require.Zero(t, handler.failedCalls)+}++func TestTransientCreateFailureWithOverrideStillNotifiesBootstrapper(t *testing.T) {+ lc, client, _ := newLifecycleForTest(t)+ handler := &recordingCreateFailureHandler{+ recordingBootstrapper: recordingBootstrapper{override: "snap-1"},+ }+ lc.bootstrapper = handler+ client.createErr = NewRemoteError(+ SandboxTypeCube, "Create", RemoteErrorKindUnavailable, "provider down", nil,+ )++ _, err := lc.Resolve(context.Background(), testSessionKey)++ require.Error(t, err)+ require.Equal(t, 1, handler.failedCalls)+}diff --git a/internal/sandbox/session_lifecycle.go b/internal/sandbox/session_lifecycle.goindex 304ea8f1c..ea48adf69 100644--- a/internal/sandbox/session_lifecycle.go+++ b/internal/sandbox/session_lifecycle.go@@ -44,6 +44,10 @@ type remoteSessionLifecycle struct {cleanupTimeout time.DurationsandboxConfigID stringnow func() time.Time++ // bootstrapper customises the first create of individual sessions+ // (session fork). Optional; nil keeps the default behaviour.+ bootstrapper SessionBootstrapper}func newRemoteSessionLifecycle(@@ -53,6 +57,7 @@ func newRemoteSessionLifecycle(createRequest RemoteCreateRequest,cleanupTimeout time.Duration,sandboxConfigID string,+ bootstrapper SessionBootstrapper,) (*remoteSessionLifecycle, error) {if client == nil {return nil, errors.New("remote sandbox client is required")@@ -88,6 +93,7 @@ func newRemoteSessionLifecycle(cleanupTimeout: cleanupTimeout,sandboxConfigID: sandboxConfigID,now: time.Now,+ bootstrapper: bootstrapper,}, nil}@@ -437,6 +443,11 @@ func (l *remoteSessionLifecycle) createAndBind(ctx context.Context,key SessionSandboxKey,) (RemoteSandboxHandle, error) {+ // request is a VALUE copy of l.createRequest, and every mutation below+ // must stay on the copy. l.createRequest is shared by every session this+ // config serves, so writing the override onto it would make unrelated+ // sessions boot from another session's fork snapshot — a failure that+ // reproduces only under specific interleavings and is brutal to diagnose.request := l.createRequestrequest.Metadata = nilif l.client.Capabilities().SupportsMetadata {@@ -450,8 +461,23 @@ func (l *remoteSessionLifecycle) createAndBind(}request.EnvVars = cloneMetadata(l.createRequest.EnvVars)+ usedOverride := false+ if l.bootstrapper != nil {+ override, err := l.bootstrapper.TemplateOverride(ctx, key)+ if err != nil {+ return nil, fmt.Errorf("resolve session template override: %w", err)+ }+ if strings.TrimSpace(override) != "" {+ request.TemplateID = override+ usedOverride = true+ }+ }+handle, err := l.client.Create(ctx, request)if err != nil {+ if usedOverride {+ l.notifyCreateFailed(ctx, key, err)+ }return nil, fmt.Errorf("create remote sandbox: %w", err)}if err := l.validateHandle(handle, ""); err != nil {@@ -497,6 +523,9 @@ func (l *remoteSessionLifecycle) createAndBind()}if created {+ if err := l.runBootstrap(ctx, key, handle); err != nil {+ return nil, err+ }return handle, nil}@@ -520,6 +549,43 @@ func (l *remoteSessionLifecycle) createAndBind(return l.connectKnownWinner(ctx, *winner)}+// runBootstrap applies the session bootstrapper to a freshly bound sandbox.+//+// Failure is all-or-nothing: the sandbox is destroyed and the binding deleted+// so the next resolve starts from a clean slate. Leaving a half-bootstrapped+// sandbox in place would hand the user an environment that looks right and is+// not.+func (l *remoteSessionLifecycle) runBootstrap(+ ctx context.Context, key SessionSandboxKey, handle RemoteSandboxHandle,+) error {+ if l.bootstrapper == nil {+ return nil+ }+ bootstrapErr := l.bootstrapper.AfterCreate(ctx, key, handle)+ if bootstrapErr == nil {+ return nil+ }+ // Use a cancellation-immune context: the caller may already be gone, and+ // abandoning the rollback would leak both a sandbox and a wrong binding.+ cleanupCtx := context.WithoutCancel(ctx)+ if _, delErr := l.bindings.DeleteIfMatch(+ cleanupCtx, key, l.client.Provider(), handle.ID(),+ ); delErr != nil {+ return errors.Join(bootstrapErr, fmt.Errorf("delete binding after failed bootstrap: %w", delErr))+ }+ return errors.Join(bootstrapErr, l.cleanupCreated(cleanupCtx, handle))+}++func (l *remoteSessionLifecycle) notifyCreateFailed(+ ctx context.Context, key SessionSandboxKey, createErr error,+) {+ handler, ok := l.bootstrapper.(SessionCreateFailureHandler)+ if !ok {+ return+ }+ handler.OnCreateFailed(context.WithoutCancel(ctx), key, createErr)+}+func (l *remoteSessionLifecycle) connectWinner(ctx context.Context,key SessionSandboxKey,diff --git a/internal/sandbox/session_lifecycle_test.go b/internal/sandbox/session_lifecycle_test.goindex 429df6ff8..ba0c37472 100644--- a/internal/sandbox/session_lifecycle_test.go+++ b/internal/sandbox/session_lifecycle_test.go@@ -177,6 +177,7 @@ func newTestRemoteSessionLifecycle(},time.Second,"",+ nil,)require.NoError(t, err)return lifecycle@@ -542,6 +543,7 @@ func newTestRemoteSessionLifecycleWithPolicy(},time.Second,"",+ nil,)require.NoError(t, err)return lifecycle@@ -1181,6 +1183,7 @@ func newLifecycleFixture(t *testing.T) *lifecycleFixture {RemoteCreateRequest{TemplateID: "template-a"},time.Minute,"cfg-1",+ nil,)require.NoError(t, err)return &lifecycleFixture{@@ -1348,6 +1351,7 @@ func newTestLifecycleWithConfigID(t *testing.T, configID string) *remoteSessionLRemoteCreateRequest{TemplateID: "template-a"},time.Minute,configID,+ nil,)require.NoError(t, err)return lifecyclediff --git a/internal/sandbox/session_manager.go b/internal/sandbox/session_manager.goindex 712bf69b2..05bf3dbfb 100644--- a/internal/sandbox/session_manager.go+++ b/internal/sandbox/session_manager.go@@ -109,6 +109,10 @@ type SessionBoundManagerConfig struct {// Set by the per-tenant resolver, which builds a manager per request.// See NewSessionBoundManager.SkipHealthProbe bool++ // Bootstrapper customises the first sandbox create of individual sessions+ // (session fork). Optional: nil is the ordinary path.+ Bootstrapper SessionBootstrapper}// NewSessionBoundManager wires the manager with an explicit RemoteSandboxClient@@ -173,6 +177,11 @@ func NewSessionBoundManager(deps SessionBoundManagerConfig) (*SessionBoundManageclient := wrapLangfuseRemoteClient(deps.Client)+ bootstrapper := deps.Bootstrapper+ if withClient, ok := bootstrapper.(SessionBootstrapperWithClient); ok {+ bootstrapper = withClient.WithClient(client)+ }+lifecycle, err := newRemoteSessionLifecycle(client,deps.Store,@@ -180,6 +189,7 @@ func NewSessionBoundManager(deps SessionBoundManagerConfig) (*SessionBoundManagecreateRequest,sessionLifecycleCleanupTimeout,deps.ConfigID,+ bootstrapper,)if err != nil {return nil, fmt.Errorf("session bound manager: %w", err)@@ -445,6 +455,14 @@ func (m *SessionBoundManager) DeleteSnapshot(ctx context.Context, snapshotID strreturn snapshots.DeleteSnapshot(ctx, snapshotID)}+// DeleteForkSnapshot removes a fork snapshot. sessionID is accepted so the+// method matches SessionForkSandboxPort; deletion is by snapshot ID.+func (m *SessionBoundManager) DeleteForkSnapshot(+ ctx context.Context, _ /* sessionID */, snapshotID string,+) error {+ return m.DeleteSnapshot(ctx, snapshotID)+}+// ListSnapshots forwards provider snapshot listing for audit and later cleanup// tasks.func (m *SessionBoundManager) ListSnapshots(@@ -1021,6 +1039,72 @@ func (m *SessionBoundManager) EndSessionTurn(ctx context.Context, sessionID strireturn leaser.EndTurn(context.WithoutCancel(ctx), key)}+// HasActiveTurn reports whether an agent turn currently holds the session's+// sandbox lease. A store without turn-lease support is treated as not busy+// so fork can proceed.+func (m *SessionBoundManager) HasActiveTurn(ctx context.Context, sessionID string) (bool, error) {+ if m == nil {+ return false, nil+ }+ leaser, ok := m.bindings.(sessionTurnLeaseStore)+ if !ok {+ return false, nil+ }+ key, err := m.sessionKey(ctx, sessionID)+ if err != nil {+ return false, err+ }+ active, _, err := leaser.TurnState(ctx, key)+ return active, err+}++// CreateForkSnapshot snapshots the session's already-bound sandbox. It never+// provisions: an unbound session or a backend without snapshots returns an+// error so fork can degrade.+func (m *SessionBoundManager) CreateForkSnapshot(+ ctx context.Context, sessionID, name string,+) (string, error) {+ if err := m.requireRemoteBackend(); err != nil {+ return "", err+ }+ snapshots, ok := SnapshotManagerFrom(m.client)+ if !ok || !m.client.Capabilities().SupportsSnapshots {+ return "", errors.New("sandbox: remote provider does not support snapshots")+ }+ sandboxID, bound := m.BoundSandboxID(ctx, sessionID)+ if !bound || sandboxID == "" {+ return "", errors.New("sandbox: session has no bound sandbox")+ }+ ref, err := createForkOrProviderSnapshot(ctx, m.client, snapshots, sandboxID, name)+ if err != nil {+ return "", err+ }+ id := strings.TrimSpace(ref.ID)+ if id == "" {+ return "", errors.New("sandbox: snapshot returned empty id")+ }+ return id, nil+}++type forkSnapshotCreator interface {+ CreateForkSnapshot(ctx context.Context, sandboxID, name string) (RemoteSnapshotRef, error)+}++// createForkOrProviderSnapshot uses a fork-specific commit when the client+// has one (Docker's weknora-fork/ namespace). Cube and E2B have no extra+// namespace, so they keep using CreateSnapshot.+func createForkOrProviderSnapshot(+ ctx context.Context,+ client RemoteSandboxClient,+ snapshots RemoteSnapshotManager,+ sandboxID, name string,+) (RemoteSnapshotRef, error) {+ if creator, ok := client.(forkSnapshotCreator); ok {+ return creator.CreateForkSnapshot(ctx, sandboxID, name)+ }+ return snapshots.CreateSnapshot(ctx, sandboxID, name)+}+var _ SessionTurnHolder = (*SessionBoundManager)(nil)// resolveSession resolves (or lazily creates) the remote sandbox bound to@@ -1084,6 +1168,33 @@ func (m *SessionBoundManager) peekBoundSandboxState(return RemoteStateUnknown, true, nil}+// BoundSandboxID returns the ID of the sandbox currently bound to sessionID.+// It never provisions and never Connects: a session with no live binding+// reports ok=false, which callers treat as "nothing to check point".+func (m *SessionBoundManager) BoundSandboxID(+ ctx context.Context, sessionID string,+) (string, bool) {+ if m.remoteDisabled() || strings.TrimSpace(sessionID) == "" {+ return "", false+ }+ key, err := m.sessionKey(ctx, sessionID)+ if err != nil {+ return "", false+ }+ binding, err := m.bindings.Get(ctx, key)+ if err != nil {+ return "", false+ }+ if binding == nil || binding.Provider != m.client.Provider() {+ return "", false+ }+ sandboxID := strings.TrimSpace(binding.SandboxID)+ if sandboxID == "" {+ return "", false+ }+ return sandboxID, true+}+// lookupSessionHandle reads the authoritative binding and, when one exists// with the current provider, connects to the remote sandbox without// allocating. Used by artifact / staging paths that must never provision.diff --git a/internal/sandbox/session_manager_test.go b/internal/sandbox/session_manager_test.goindex 781b5266e..840d55d9d 100644--- a/internal/sandbox/session_manager_test.go+++ b/internal/sandbox/session_manager_test.go@@ -2,6 +2,7 @@ package sandboximport ("context"+ "errors""strings""testing""time"@@ -548,3 +549,323 @@ func TestOpenSessionDesktopUnsupportedBackend(t *testing.T) {_, err := mgr.OpenSessionDesktop(context.Background(), "sess-1", RemoteDesktopOptions{})require.ErrorIs(t, err, ErrDesktopUnsupported)}++func TestBoundSandboxIDReadsBindingWithoutConnect(t *testing.T) {+ client := newFakeRemoteClient(SandboxTypeCube)+ store := NewMemorySessionSandboxBindingStore()+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: client,+ Store: store,+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ })+ require.NoError(t, err)++ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ key := SessionSandboxKey{TenantID: 10000, SessionID: "session-a"}+ created, err := store.Create(ctx, key, validSessionSandboxBinding(key, "sbx-existing"))+ require.NoError(t, err)+ require.True(t, created)++ id, ok := mgr.BoundSandboxID(ctx, "session-a")+ require.True(t, ok)+ require.Equal(t, "sbx-existing", id)++ client.mu.Lock()+ connects := append([]string(nil), client.connectIDs...)+ client.mu.Unlock()+ require.Empty(t, connects, "BoundSandboxID must not Connect")+}++func TestBoundSandboxIDReportsUnbound(t *testing.T) {+ mgr, client := newSessionManagerExecTestHarness(t)+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))++ id, ok := mgr.BoundSandboxID(ctx, "session-a")+ require.False(t, ok)+ require.Empty(t, id)++ client.mu.Lock()+ connects := append([]string(nil), client.connectIDs...)+ client.mu.Unlock()+ require.Empty(t, connects)+}++func TestHasActiveTurnReportsLeaseState(t *testing.T) {+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ store := NewMemorySessionSandboxBindingStore()+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: newFakeRemoteClient(SandboxTypeCube),+ Store: store,+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ })+ require.NoError(t, err)++ busy, err := mgr.HasActiveTurn(ctx, "sess-1")+ require.NoError(t, err)+ require.False(t, busy)++ require.NoError(t, mgr.BeginSessionTurn(ctx, "sess-1"))+ busy, err = mgr.HasActiveTurn(ctx, "sess-1")+ require.NoError(t, err)+ require.True(t, busy)+}++func TestHasActiveTurnWithoutLeaseStoreIsNotBusy(t *testing.T) {+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ store := leaseFreeBindingStore{SessionSandboxBindingStore: NewMemorySessionSandboxBindingStore()}+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: newFakeRemoteClient(SandboxTypeCube),+ Store: store,+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ })+ require.NoError(t, err)++ busy, err := mgr.HasActiveTurn(ctx, "sess-1")+ require.NoError(t, err)+ require.False(t, busy)+}++func TestCreateForkSnapshotSnapshotsBoundSandboxWithoutProvisioning(t *testing.T) {+ client := newFakeRemoteClient(SandboxTypeCube)+ client.capabilities.SupportsSnapshots = true+ store := NewMemorySessionSandboxBindingStore()+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: client,+ Store: store,+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ })+ require.NoError(t, err)++ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ key := SessionSandboxKey{TenantID: 10000, SessionID: "session-a"}+ created, err := store.Create(ctx, key, validSessionSandboxBinding(key, "sbx-existing"))+ require.NoError(t, err)+ require.True(t, created)++ id, err := mgr.CreateForkSnapshot(ctx, "session-a", "fork-session-a-1")+ require.NoError(t, err)+ require.Equal(t, "snap-1", id)++ creates, connects, _, _, _ := client.counts()+ require.Zero(t, creates, "CreateForkSnapshot must not provision")+ require.Zero(t, connects, "CreateForkSnapshot must not Connect")+ client.mu.Lock()+ src := client.snapshots[id]+ client.mu.Unlock()+ require.Equal(t, "sbx-existing", src)+}++func TestCreateForkSnapshotErrorsWhenUnbound(t *testing.T) {+ client := newFakeRemoteClient(SandboxTypeCube)+ client.capabilities.SupportsSnapshots = true+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: client,+ Store: NewMemorySessionSandboxBindingStore(),+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ })+ require.NoError(t, err)++ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ _, err = mgr.CreateForkSnapshot(ctx, "session-a", "fork-session-a-1")+ require.Error(t, err)++ creates, connects, _, _, _ := client.counts()+ require.Zero(t, creates)+ require.Zero(t, connects)+}++func TestCreateForkSnapshotErrorsWhenUnsupported(t *testing.T) {+ client := newFakeRemoteClient(SandboxTypeCube)+ store := NewMemorySessionSandboxBindingStore()+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: client,+ Store: store,+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ })+ require.NoError(t, err)++ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ key := SessionSandboxKey{TenantID: 10000, SessionID: "session-a"}+ created, err := store.Create(ctx, key, validSessionSandboxBinding(key, "sbx-existing"))+ require.NoError(t, err)+ require.True(t, created)++ _, err = mgr.CreateForkSnapshot(ctx, "session-a", "fork-session-a-1")+ require.Error(t, err)++ creates, connects, _, _, _ := client.counts()+ require.Zero(t, creates)+ require.Zero(t, connects)+}++type recordingForkSnapshotClient struct {+ *fakeRemoteClient+ forkCalls int+ forkName string+ forkSrc string+}++func (c *recordingForkSnapshotClient) CreateForkSnapshot(+ _ context.Context, sandboxID, name string,+) (RemoteSnapshotRef, error) {+ c.forkCalls+++ c.forkName = name+ c.forkSrc = sandboxID+ return RemoteSnapshotRef{ID: "fork-" + sandboxID, Names: []string{name}}, nil+}++func TestCreateForkSnapshotPrefersClientCreateForkSnapshot(t *testing.T) {+ inner := newFakeRemoteClient(SandboxTypeCube)+ inner.capabilities.SupportsSnapshots = true+ client := &recordingForkSnapshotClient{fakeRemoteClient: inner}+ store := NewMemorySessionSandboxBindingStore()+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: client,+ Store: store,+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ })+ require.NoError(t, err)++ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ key := SessionSandboxKey{TenantID: 10000, SessionID: "session-a"}+ created, err := store.Create(ctx, key, validSessionSandboxBinding(key, "sbx-existing"))+ require.NoError(t, err)+ require.True(t, created)++ id, err := mgr.CreateForkSnapshot(ctx, "session-a", "fork-session-a-1")+ require.NoError(t, err)+ require.Equal(t, "fork-sbx-existing", id)+ require.Equal(t, 1, client.forkCalls)+ require.Equal(t, "fork-session-a-1", client.forkName)+ require.Equal(t, "sbx-existing", client.forkSrc)++ creates, connects, _, _, _ := inner.counts()+ require.Zero(t, creates, "CreateForkSnapshot must not provision")+ require.Zero(t, connects, "CreateForkSnapshot must not Connect")+ inner.mu.Lock()+ _, usedCreateSnapshot := inner.snapshots["snap-1"]+ inner.mu.Unlock()+ require.False(t, usedCreateSnapshot, "Docker must not fall back to skill CreateSnapshot")+}++type clientBoundRecordingState struct {+ withClientCalls int+ afterExecs int+}++type clientBoundRecordingBootstrapper struct {+ state *clientBoundRecordingState+ client RemoteSandboxClient+}++func (b *clientBoundRecordingBootstrapper) WithClient(client RemoteSandboxClient) SessionBootstrapper {+ b.state.withClientCalls+++ cp := *b+ cp.client = client+ return &cp+}++func (b *clientBoundRecordingBootstrapper) TemplateOverride(+ context.Context, SessionSandboxKey,+) (string, error) {+ return "", nil+}++func (b *clientBoundRecordingBootstrapper) AfterCreate(+ ctx context.Context, _ SessionSandboxKey, handle RemoteSandboxHandle,+) error {+ if b.client == nil || handle == nil {+ return errors.New("AfterCreate must use the bound remote client")+ }+ _, err := b.client.Exec(ctx, handle, RemoteExecRequest{+ Command: "echo weknora-fork-after-create",+ Shell: true,+ WorkDir: SessionWorkspaceRoot,+ Timeout: time.Second,+ User: DefaultSandboxExecUser,+ })+ if err != nil {+ return err+ }+ b.state.afterExecs+++ return nil+}++var _ SessionBootstrapper = (*clientBoundRecordingBootstrapper)(nil)++var _ SessionBootstrapperWithClient = (*clientBoundRecordingBootstrapper)(nil)++func TestNewSessionBoundManagerBindsBootstrapperToClient(t *testing.T) {+ client := newFakeRemoteClient(SandboxTypeCube)+ state := &clientBoundRecordingState{}+ boot := &clientBoundRecordingBootstrapper{state: state}+ cfg := DefaultConfig()+ cfg.CubeTemplate = "tpl-test"+ mgr, err := NewSessionBoundManager(SessionBoundManagerConfig{+ Config: cfg,+ Client: client,+ Store: NewMemorySessionSandboxBindingStore(),+ Checker: &fakeSessionExistenceChecker{exists: true},+ SkipHealthProbe: true,+ Bootstrapper: boot,+ })+ require.NoError(t, err)++ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000))+ _, err = mgr.Execute(ctx, &ExecuteConfig{+ SessionID: "session-fork-boot",+ SkipValidation: true,+ ScriptContent: "print('ok')\n",+ Script: "hello.py",+ })+ require.NoError(t, err)+ require.Equal(t, 1, state.withClientCalls)+ require.Equal(t, 1, state.afterExecs)++ found := false+ client.mu.Lock()+ for _, req := range client.execRequests {+ if strings.Contains(req.Command, "weknora-fork-after-create") {+ found = true+ require.True(t, req.Shell)+ require.Equal(t, SessionWorkspaceRoot, req.WorkDir)+ require.Equal(t, DefaultSandboxExecUser, req.User)+ }+ }+ client.mu.Unlock()+ require.True(t, found, "AfterCreate must Exec on the handle's client")+}++// leaseFreeBindingStore implements only SessionSandboxBindingStore so the+// optional turn-lease type assert fails.+type leaseFreeBindingStore struct {+ SessionSandboxBindingStore+}diff --git a/internal/sandbox/tenant_resolver.go b/internal/sandbox/tenant_resolver.goindex 594a2c5df..9f1c75805 100644--- a/internal/sandbox/tenant_resolver.go+++ b/internal/sandbox/tenant_resolver.go@@ -85,6 +85,10 @@ type TenantSandboxResolverDeps struct {Store SessionSandboxBindingStoreChecker SessionExistenceChecker+ // Bootstrapper customises the first sandbox create of individual sessions+ // (session fork). Optional: nil is the ordinary path.+ Bootstrapper SessionBootstrapper+// SharedTransport is reused by every tenant's HTTP client. Optional; a// guarded transport is installed when nil.SharedTransport *http.Transport@@ -194,6 +198,7 @@ func (r *tenantSandboxResolver) Resolve(Checker: r.deps.Checker,SkipHealthProbe: true,ConfigID: configID,+ Bootstrapper: r.deps.Bootstrapper,})default:return NewDisabledManager(), nildiff --git a/internal/types/interfaces/message.go b/internal/types/interfaces/message.goindex 98f7352c7..195c60fbe 100644--- a/internal/types/interfaces/message.go+++ b/internal/types/interfaces/message.go@@ -89,6 +89,12 @@ type MessageRepository interface {) ([]*types.Message, error)// ListMessagesBySessionAfterCursor uses (created_at, id) for lossless paging.ListMessagesBySessionAfterCursor(ctx context.Context, sessionID string, cursor types.MemoryMessageCursor, limit int) ([]*types.Message, error)+ // ListMessagesBySessionUpTo returns every message sorting strictly before+ // the (boundary, boundaryID) composite cursor, oldest first. Used by+ // session fork to copy the history preceding a fork point.+ ListMessagesBySessionUpTo(+ ctx context.Context, sessionID string, boundary time.Time, boundaryID string,+ ) ([]*types.Message, error)// UpdateMessage updates a messageUpdateMessage(ctx context.Context, message *types.Message) error// UpdateMessageImages updates only the images JSONB column for a message@@ -107,8 +113,11 @@ type MessageRepository interface {SearchMessagesByKeyword(ctx context.Context, tenantID uint64, ownerID, keyword string, sessionIDs []string, limit int) ([]*types.MessageWithSession, error)// GetMessagesByKnowledgeIDs retrieves messages by their associated Knowledge IDsGetMessagesByKnowledgeIDs(ctx context.Context, knowledgeIDs []string) ([]*types.MessageWithSession, error)- // GetMessagesByRequestIDs retrieves messages by their request IDs (used to fetch Q&A pair partners)- GetMessagesByRequestIDs(ctx context.Context, requestIDs []string) ([]*types.MessageWithSession, error)+ // GetMessagesByRequestIDs retrieves messages by request ID inside one session+ // (used to fetch Q&A pair partners). Empty sessionID returns no rows.+ GetMessagesByRequestIDs(+ ctx context.Context, sessionID string, requestIDs []string,+ ) ([]*types.MessageWithSession, error)// GetKnowledgeIDsBySessionID retrieves all knowledge IDs for messages in a sessionGetKnowledgeIDsBySessionID(ctx context.Context, sessionID string) ([]string, error)// UpdateMessageKnowledgeID updates the knowledge_id field for a message@@ -122,4 +131,9 @@ type MessageRepository interface {// GetSessionAttachments returns every user-uploaded attachment recorded in// the session. Implementations should project only the attachments column.GetSessionAttachments(ctx context.Context, sessionID string) (types.MessageAttachments, error)+ // RewriteSandboxCheckpoints replaces SandboxID on every copied checkpoint+ // in the session that still points at oldSandboxID, keeping CommitSHA and+ // CommittedAt. Used after a forked sandbox boots so a later fork-of-fork+ // compares against the live handle rather than the parent's sandbox.+ RewriteSandboxCheckpoints(ctx context.Context, sessionID, oldSandboxID, newSandboxID string) error}diff --git a/internal/types/interfaces/session.go b/internal/types/interfaces/session.goindex c8d13bfc7..f109e5dbd 100644--- a/internal/types/interfaces/session.go+++ b/internal/types/interfaces/session.go@@ -2,6 +2,7 @@ package interfacesimport ("context"+ "time""github.com/Tencent/WeKnora/internal/event""github.com/Tencent/WeKnora/internal/types"@@ -106,4 +107,29 @@ type SessionRepository interface {BatchDelete(ctx context.Context, tenantID uint64, userID string, ids []string) (int64, error)// DeleteAllByTenantID deletes all sessions visible to the tenant/user scope.DeleteAllByTenantID(ctx context.Context, tenantID uint64, userID string) (int64, error)+ // CreateForked persists a forked session and its copied history atomically.+ CreateForked(ctx context.Context, session *types.Session, messages []*types.Message) error+ // UpdateForkBootstrap overwrites a session's fork bootstrap. Passing nil clears it.+ UpdateForkBootstrap(ctx context.Context, sessionID string, b *types.ForkBootstrap) error+ // ListUnconsumedForks returns fork bootstraps the snapshot reaper should+ // try to retire: unopened forks older than olderThan, plus consumed forks+ // that still name a snapshot.+ ListUnconsumedForks(ctx context.Context, olderThan time.Time) ([]*types.Session, error)+ // HasOtherUnconsumedForkSnapshot reports whether another session still+ // needs snapshotID to boot. excludeSessionID is the row currently being+ // consumed or reaped.+ HasOtherUnconsumedForkSnapshot(ctx context.Context, snapshotID, excludeSessionID string) (bool, error)+ // UnconsumedForkSnapshotHolders returns session IDs that still need+ // snapshotID to provision. The reaper uses this to avoid deleting a+ // snapshot while a fork within retention still depends on it.+ UnconsumedForkSnapshotHolders(ctx context.Context, snapshotID string) ([]string, error)+ // CreateForkSnapshotLease records a provider snapshot ID before the forked+ // session row exists, so a crash or CreateForked failure cannot hide it+ // from the reaper.+ CreateForkSnapshotLease(ctx context.Context, lease *types.ForkSnapshotLease) error+ // DeleteForkSnapshotLease drops a lease after the session owns the+ // snapshot, or after the snapshot itself has been deleted.+ DeleteForkSnapshotLease(ctx context.Context, snapshotID string) error+ // ListStaleForkSnapshotLeases returns leases older than olderThan.+ ListStaleForkSnapshotLeases(ctx context.Context, olderThan time.Time) ([]*types.ForkSnapshotLease, error)}diff --git a/internal/types/message.go b/internal/types/message.goindex b15ee7f16..e143b064f 100644--- a/internal/types/message.go+++ b/internal/types/message.go@@ -228,18 +228,18 @@ func (m *MessageAttachments) Scan(value interface{}) error {// behalf and that WeKnora has persisted to its file service so the user can// download them after the sandbox is reaped.//-// URL is the provider-scoped storage path (e.g. "local://tenant/..."), never-// exposed directly to the client. SourcePath + ModTime form the sandbox-side-// identity used by ArtifactCollector to de-duplicate files across multi-turn-// runs (see docs/superpowers/specs/2026-07-10-skill-artifact-download-design.md).+// SourcePath + ModTime is the cheap identity for an unchanged sandbox file.+// When mtime moves, ArtifactCollector compares content hashes so a git+// checkout cannot duplicate a blob and a same-size rewrite still attaches.type MessageArtifact struct {- URL string `json:"url"` // Storage URL (provider://path); persisted, not sent to client- FileName string `json:"file_name"` // Original filename inside the sandbox- FileType string `json:"file_type"` // File extension (e.g., ".pptx", ".pdf")- FileSize int64 `json:"file_size"` // File size in bytes- SourcePath string `json:"source_path"` // Absolute path inside the sandbox (used for diff)- ModTime time.Time `json:"mod_time"` // Sandbox-side modification time (used for diff)- CreatedAt time.Time `json:"created_at"` // When WeKnora persisted the blob+ URL string `json:"url"` // Storage URL (provider://path); persisted, not sent to client+ FileName string `json:"file_name"` // Original filename inside the sandbox+ FileType string `json:"file_type"` // File extension (e.g., ".pptx", ".pdf")+ FileSize int64 `json:"file_size"` // File size in bytes+ ContentHash string `json:"content_hash,omitempty"` // SHA-256 of the persisted bytes+ SourcePath string `json:"source_path"` // Absolute path inside the sandbox (used for diff)+ ModTime time.Time `json:"mod_time"` // Sandbox-side modification time (used for diff)+ CreatedAt time.Time `json:"created_at"` // When WeKnora persisted the blob}// MessageArtifacts is a slice of MessageArtifact for database storage.@@ -272,6 +272,37 @@ func (m *MessageArtifacts) Scan(value interface{}) error {return json.Unmarshal(b, m)}+// WithRestoredMtime stamps sandbox mtime onto the artifact at sourcePath+// whose ContentHash already matches. Used after a fork checkout so later+// collects can skip by path+mtime. Other versions at the same path —+// including empty-hash legacy rows — are left alone. The returned slice is a+// copy.+func (m MessageArtifacts) WithRestoredMtime(sourcePath string, mod time.Time, hash string) (MessageArtifacts, bool) {+ if len(m) == 0 || sourcePath == "" || hash == "" {+ return m, false+ }+ out := make(MessageArtifacts, len(m))+ copy(out, m)+ changed := false+ for i := range out {+ if out[i].SourcePath != sourcePath {+ continue+ }+ // Empty hashes are not a match: a restore must not stamp every+ // historical version at this path. Only the row whose content+ // already hashed to `hash` gets the new mtime.+ if out[i].ContentHash != hash {+ continue+ }+ if out[i].ModTime.Equal(mod) {+ continue+ }+ out[i].ModTime = mod+ changed = true+ }+ return out, changed+}+// MentionedItems is a slice of MentionedItem for database storagetype MentionedItems []MentionedItem@@ -369,6 +400,12 @@ type Message struct {// spot. Persisted rather than only streamed so reopening a conversation// still explains what the answer saw.UsedMemories UsedMemories `json:"used_memories,omitempty" gorm:"type:jsonb;column:used_memories"`+ // SandboxCheckpoint is the git commit this assistant turn produced in the+ // session sandbox's /workspace. Nil for user messages, for turns that ran+ // without a sandbox, and for turns whose commit failed (best-effort — a+ // failed checkpoint must never block the reply). A message without a+ // checkpoint cannot serve as a fork point with sandbox state.+ SandboxCheckpoint *SandboxCheckpoint `json:"sandbox_checkpoint,omitempty" gorm:"type:jsonb"`// Message creation timestampCreatedAt time.Time `json:"created_at"`// Last update timestampdiff --git a/internal/types/message_test.go b/internal/types/message_test.goindex 9f8abf429..ccbdc0b25 100644--- a/internal/types/message_test.go+++ b/internal/types/message_test.go@@ -120,6 +120,31 @@ func TestMessageArtifacts_ScanUnknownType(t *testing.T) {}}+func TestWithRestoredMtimeLeavesEmptyHashOlderVersionAlone(t *testing.T) {+ path := "/workspace/output/deck.pptx"+ oldMod := time.Date(2026, 7, 10, 10, 20, 30, 0, time.UTC)+ newMod := time.Date(2026, 7, 10, 10, 21, 0, 0, time.UTC)+ arts := MessageArtifacts{+ {URL: "resource://old", FileName: "deck.pptx", SourcePath: path, ModTime: oldMod},+ {URL: "resource://new", FileName: "deck.pptx", SourcePath: path, ContentHash: "abc", ModTime: oldMod},+ }++ got, changed := arts.WithRestoredMtime(path, newMod, "abc")++ if !changed {+ t.Fatal("matching hashed version should be stamped")+ }+ if got[0].ContentHash != "" || !got[0].ModTime.Equal(oldMod) {+ t.Fatalf("empty-hash older version was rewritten: %+v", got[0])+ }+ if got[1].ContentHash != "abc" || !got[1].ModTime.Equal(newMod) {+ t.Fatalf("matching version not stamped: %+v", got[1])+ }+ if arts[1].ModTime.Equal(newMod) {+ t.Fatal("WithRestoredMtime must not mutate the input slice")+ }+}+// TestMessageArtifacts_ValueNil pins the "nil slice → JSON empty array" path// so a fresh Message without artifacts serialises as `[]` rather than `null`.func TestMessageArtifacts_ValueNil(t *testing.T) {diff --git a/internal/types/session.go b/internal/types/session.goindex d80d6270f..e022ad7fd 100644--- a/internal/types/session.go+++ b/internal/types/session.go@@ -107,6 +107,23 @@ type Session struct {// permanent would make "no session references this config" never true.SandboxConfigID string `json:"sandbox_config_id,omitempty" gorm:"type:varchar(36)"`+ // ParentSessionID names the session this one was forked from. Empty for+ // ordinary sessions. Deliberately not a foreign key: the parent may be+ // deleted while the branch lives on, and a branch must not cascade away+ // with it. A dangling value simply renders as an ordinary session.+ ParentSessionID string `json:"parent_session_id,omitempty" gorm:"type:varchar(36);index"`++ // ForkedFromMessageID is the user or assistant message, IN THE PARENT+ // SESSION, that the fork branched at. For a user point, messages strictly+ // before it were copied here. For an assistant point, that answer is+ // included so the branch continues after it.+ ForkedFromMessageID string `json:"forked_from_message_id,omitempty" gorm:"type:varchar(36)"`++ // ForkBootstrap holds the one-shot sandbox provisioning instructions for a+ // forked session. Nil for ordinary sessions and for forks that have+ // already provisioned. See types.ForkBootstrap.+ ForkBootstrap *ForkBootstrap `json:"-" gorm:"type:jsonb;column:fork_bootstrap"`+// // Strategy configuration// KnowledgeBaseID string `json:"knowledge_base_id"` // 关联的知识库ID// MaxRounds int `json:"max_rounds"` // 多轮保持轮数diff --git a/internal/types/session_fork.go b/internal/types/session_fork.gonew file mode 100644index 000000000..10d07dcad--- /dev/null+++ b/internal/types/session_fork.go@@ -0,0 +1,115 @@+package types++import (+ "database/sql/driver"+ "encoding/json"+ "errors"+ "time"+)++// SandboxCheckpoint records the git commit an agent turn produced inside the+// session sandbox's /workspace. It is written on assistant messages only.+//+// SandboxID is stored alongside CommitSHA because commit hashes are only+// meaningful within one sandbox's repository. When a session's sandbox is+// reaped and rebuilt mid-conversation the in-sandbox git history restarts from+// zero, so every checkpoint written before the rebuild becomes unreachable.+// Comparing SandboxID against the session's current binding detects that+// purely from the database, without probing the sandbox.+type SandboxCheckpoint struct {+ SandboxID string `json:"sandbox_id"`+ CommitSHA string `json:"commit_sha"`+ CommittedAt time.Time `json:"committed_at"`+}++// Value implements the driver.Valuer interface for database serialization.+func (c SandboxCheckpoint) Value() (driver.Value, error) {+ return json.Marshal(c)+}++// Scan implements the sql.Scanner interface for database deserialization.+func (c *SandboxCheckpoint) Scan(value any) error {+ if value == nil {+ *c = SandboxCheckpoint{}+ return nil+ }+ var b []byte+ switch v := value.(type) {+ case []byte:+ b = v+ case string:+ b = []byte(v)+ default:+ return errors.New("types: cannot scan sandbox checkpoint from unsupported type")+ }+ if len(b) == 0 {+ *c = SandboxCheckpoint{}+ return nil+ }+ return json.Unmarshal(b, c)+}++// ForkBootstrap carries the one-shot instructions a forked session needs the+// first time it provisions a sandbox: boot from SnapshotID instead of the+// config's template, then roll /workspace back to CommitSHA.+//+// It is consumed exactly once. After ConsumedAt is set the forked session is+// indistinguishable from an ordinary session — matching the durability+// semantics every session already has, where a reaped sandbox loses+// /workspace.+type ForkBootstrap struct {+ SnapshotID string `json:"snapshot_id"`+ CommitSHA string `json:"commit_sha"`+ SourceSandboxID string `json:"source_sandbox_id"`+ CreatedAt time.Time `json:"created_at"`+ ConsumedAt *time.Time `json:"consumed_at,omitempty"`+}++// Consumed reports whether the bootstrap has already been applied.+func (f ForkBootstrap) Consumed() bool {+ return f.ConsumedAt != nil+}++// Value implements the driver.Valuer interface for database serialization.+func (f ForkBootstrap) Value() (driver.Value, error) {+ return json.Marshal(f)+}++// Scan implements the sql.Scanner interface for database deserialization.+func (f *ForkBootstrap) Scan(value any) error {+ if value == nil {+ *f = ForkBootstrap{}+ return nil+ }+ var b []byte+ switch v := value.(type) {+ case []byte:+ b = v+ case string:+ b = []byte(v)+ default:+ return errors.New("types: cannot scan fork bootstrap from unsupported type")+ }+ if len(b) == 0 {+ *f = ForkBootstrap{}+ return nil+ }+ return json.Unmarshal(b, f)+}++// ForkSnapshotLease is the durable record of a provider snapshot taken before+// the forked session row exists. CreateForked can fail or the process can+// crash in that window; the reaper scans these rows so a snapshot without a+// session is still collectable.+type ForkSnapshotLease struct {+ SnapshotID string `json:"snapshot_id" gorm:"column:snapshot_id;primaryKey;type:varchar(128)"`+ TenantID uint64 `json:"tenant_id" gorm:"column:tenant_id"`+ SandboxConfigID string `json:"sandbox_config_id" gorm:"column:sandbox_config_id;type:varchar(36)"`+ CreatedAt time.Time `json:"created_at" gorm:"column:created_at"`+}++// TableName is the lease table. It is separate from sessions: a rolled-back+// CreateForked must not erase the only copy of the snapshot ID.+func (ForkSnapshotLease) TableName() string {+ return "fork_snapshot_leases"+}diff --git a/internal/types/session_fork_test.go b/internal/types/session_fork_test.gonew file mode 100644index 000000000..6fe358263--- /dev/null+++ b/internal/types/session_fork_test.go@@ -0,0 +1,62 @@+package types++import (+ "testing"+ "time"++ "github.com/stretchr/testify/require"+)++func TestSandboxCheckpointRoundTrips(t *testing.T) {+ at := time.Date(2026, 9, 10, 9, 59, 0, 0, time.UTC)+ original := SandboxCheckpoint{SandboxID: "sbx-1", CommitSHA: "abc123", CommittedAt: at}++ raw, err := original.Value()+ require.NoError(t, err)++ var decoded SandboxCheckpoint+ require.NoError(t, decoded.Scan(raw))+ require.Equal(t, original.SandboxID, decoded.SandboxID)+ require.Equal(t, original.CommitSHA, decoded.CommitSHA)+ require.True(t, original.CommittedAt.Equal(decoded.CommittedAt))+}++func TestSandboxCheckpointScanNilYieldsZeroValue(t *testing.T) {+ var decoded SandboxCheckpoint+ require.NoError(t, decoded.Scan(nil))+ require.Equal(t, SandboxCheckpoint{}, decoded)+}++func TestSandboxCheckpointScanRejectsGarbage(t *testing.T) {+ var decoded SandboxCheckpoint+ require.Error(t, decoded.Scan([]byte("not json")))+}++func TestForkBootstrapConsumedReportsState(t *testing.T) {+ pending := ForkBootstrap{SnapshotID: "snap-1", CommitSHA: "abc123"}+ require.False(t, pending.Consumed())++ at := time.Now().UTC()+ done := ForkBootstrap{SnapshotID: "snap-1", CommitSHA: "abc123", ConsumedAt: &at}+ require.True(t, done.Consumed())+}++func TestForkBootstrapRoundTripsConsumedAt(t *testing.T) {+ at := time.Date(2026, 9, 10, 10, 0, 0, 0, time.UTC)+ original := ForkBootstrap{+ SnapshotID: "snap-1",+ CommitSHA: "abc123",+ SourceSandboxID: "sbx-1",+ CreatedAt: at,+ ConsumedAt: &at,+ }++ raw, err := original.Value()+ require.NoError(t, err)++ var decoded ForkBootstrap+ require.NoError(t, decoded.Scan(raw))+ require.Equal(t, original.SnapshotID, decoded.SnapshotID)+ require.NotNil(t, decoded.ConsumedAt)+ require.True(t, at.Equal(*decoded.ConsumedAt))+}diff --git a/migrations/sqlite/000018_session_fork.down.sql b/migrations/sqlite/000018_session_fork.down.sqlnew file mode 100644index 000000000..e955c05e1--- /dev/null+++ b/migrations/sqlite/000018_session_fork.down.sql@@ -0,0 +1,7 @@+DROP INDEX IF EXISTS idx_sessions_parent_session_id;++ALTER TABLE sessions DROP COLUMN fork_bootstrap;+ALTER TABLE sessions DROP COLUMN forked_from_message_id;+ALTER TABLE sessions DROP COLUMN parent_session_id;++ALTER TABLE messages DROP COLUMN sandbox_checkpoint;diff --git a/migrations/sqlite/000018_session_fork.up.sql b/migrations/sqlite/000018_session_fork.up.sqlnew file mode 100644index 000000000..793f613fb--- /dev/null+++ b/migrations/sqlite/000018_session_fork.up.sql@@ -0,0 +1,13 @@+-- Mirrors versioned migration 000097_session_fork:+-- session lineage plus the per-turn sandbox checkpoint used as a fork point.+-- Existing Lite databases are already at version 13 and never replay 000000_init,+-- so these columns must be added here.++ALTER TABLE sessions ADD COLUMN parent_session_id TEXT;+ALTER TABLE sessions ADD COLUMN forked_from_message_id TEXT;+ALTER TABLE sessions ADD COLUMN fork_bootstrap TEXT;++CREATE INDEX IF NOT EXISTS idx_sessions_parent_session_id+ ON sessions (parent_session_id);++ALTER TABLE messages ADD COLUMN sandbox_checkpoint TEXT;diff --git a/migrations/sqlite/000019_fork_snapshot_lease.down.sql b/migrations/sqlite/000019_fork_snapshot_lease.down.sqlnew file mode 100644index 000000000..ac56ebe64--- /dev/null+++ b/migrations/sqlite/000019_fork_snapshot_lease.down.sql@@ -0,0 +1,2 @@+DROP INDEX IF EXISTS idx_fork_snapshot_leases_created_at;+DROP TABLE IF EXISTS fork_snapshot_leases;diff --git a/migrations/sqlite/000019_fork_snapshot_lease.up.sql b/migrations/sqlite/000019_fork_snapshot_lease.up.sqlnew file mode 100644index 000000000..df4c4d293--- /dev/null+++ b/migrations/sqlite/000019_fork_snapshot_lease.up.sql@@ -0,0 +1,12 @@+-- Mirrors versioned migration 000098_fork_snapshot_lease:+-- durable snapshot IDs taken before the forked session row is committed.++CREATE TABLE IF NOT EXISTS fork_snapshot_leases (+ snapshot_id TEXT PRIMARY KEY,+ tenant_id INTEGER NOT NULL DEFAULT 0,+ sandbox_config_id TEXT NOT NULL DEFAULT '',+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP+);++CREATE INDEX IF NOT EXISTS idx_fork_snapshot_leases_created_at+ ON fork_snapshot_leases (created_at);diff --git a/migrations/versioned/000097_session_fork.down.sql b/migrations/versioned/000097_session_fork.down.sqlnew file mode 100644index 000000000..8c83f2f40--- /dev/null+++ b/migrations/versioned/000097_session_fork.down.sql@@ -0,0 +1,8 @@+DROP INDEX IF EXISTS idx_sessions_unconsumed_fork;+DROP INDEX IF EXISTS idx_sessions_parent_session_id;++ALTER TABLE sessions DROP COLUMN IF EXISTS fork_bootstrap;+ALTER TABLE sessions DROP COLUMN IF EXISTS forked_from_message_id;+ALTER TABLE sessions DROP COLUMN IF EXISTS parent_session_id;++ALTER TABLE messages DROP COLUMN IF EXISTS sandbox_checkpoint;diff --git a/migrations/versioned/000097_session_fork.up.sql b/migrations/versioned/000097_session_fork.up.sqlnew file mode 100644index 000000000..a29424c39--- /dev/null+++ b/migrations/versioned/000097_session_fork.up.sql@@ -0,0 +1,17 @@+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS parent_session_id VARCHAR(36);+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS forked_from_message_id VARCHAR(36);+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS fork_bootstrap JSONB;++CREATE INDEX IF NOT EXISTS idx_sessions_parent_session_id+ ON sessions (parent_session_id)+ WHERE parent_session_id IS NOT NULL;++-- Drives the orphan-snapshot reaper, which scans for forks whose bootstrap was+-- never consumed. Partial so the index stays tiny: the overwhelming majority of+-- sessions have no bootstrap at all.+CREATE INDEX IF NOT EXISTS idx_sessions_unconsumed_fork+ ON sessions ((fork_bootstrap ->> 'snapshot_id'))+ WHERE fork_bootstrap IS NOT NULL+ AND fork_bootstrap ->> 'consumed_at' IS NULL;++ALTER TABLE messages ADD COLUMN IF NOT EXISTS sandbox_checkpoint JSONB;diff --git a/migrations/versioned/000098_fork_snapshot_lease.down.sql b/migrations/versioned/000098_fork_snapshot_lease.down.sqlnew file mode 100644index 000000000..ac56ebe64--- /dev/null+++ b/migrations/versioned/000098_fork_snapshot_lease.down.sql@@ -0,0 +1,2 @@+DROP INDEX IF EXISTS idx_fork_snapshot_leases_created_at;+DROP TABLE IF EXISTS fork_snapshot_leases;diff --git a/migrations/versioned/000098_fork_snapshot_lease.up.sql b/migrations/versioned/000098_fork_snapshot_lease.up.sqlnew file mode 100644index 000000000..20ac0b898--- /dev/null+++ b/migrations/versioned/000098_fork_snapshot_lease.up.sql@@ -0,0 +1,9 @@+CREATE TABLE IF NOT EXISTS fork_snapshot_leases (+ snapshot_id VARCHAR(128) PRIMARY KEY,+ tenant_id BIGINT NOT NULL DEFAULT 0,+ sandbox_config_id VARCHAR(36) NOT NULL DEFAULT '',+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()+);++CREATE INDEX IF NOT EXISTS idx_fork_snapshot_leases_created_at+ ON fork_snapshot_leases (created_at);