newmark-agent 0.3.11 → 0.4.0

package/dist/core/agentKernel/agent-loop.js

@@ -193,9 +193,35 @@ async function executeToolCalls(toolCalls, context, config, signal) {
         }
     };
     if (config.toolExecution === 'parallel') {
-        // Promise.all is the batch barrier: every launch succeeds or fails before
-        // the provider receives any result and starts the next reasoning step.
-        return await Promise.all(toolCalls.map(call => executeOne(call)));
+        // DSH 式并发安全分级：只有 concurrencySafe 工具才能与兄弟调用重叠执行，
+        // 有副作用的工具（缺省独占）形成串行屏障，避免盲目 Promise.all 导致
+        // write/edit/bash/browser_* 等副作用工具竞态。连续的并发安全调用聚合为
+        // 一个 Promise.all 批次；独占调用等待前面批次全部 settle 后单独执行。
+        const results = [];
+        let index = 0;
+        while (index < toolCalls.length) {
+            const call = toolCalls[index];
+            const tool = tools.find(candidate => candidate.name === call.name);
+            if (tool && tool.concurrencySafe === true) {
+                // 聚合连续的并发安全调用为一个并行批次。
+                const batch = [];
+                while (index < toolCalls.length) {
+                    const candidate = toolCalls[index];
+                    const candidateTool = tools.find(t => t.name === candidate.name);
+                    if (!candidateTool || candidateTool.concurrencySafe !== true)
+                        break;
+                    batch.push(candidate);
+                    index += 1;
+                }
+                results.push(...(await Promise.all(batch.map(c => executeOne(c)))));
+            }
+            else {
+                // 独占工具：串行屏障，等待前面批次全部 settle 后单独执行。
+                results.push(await executeOne(call));
+                index += 1;
+            }
+        }
+        return results;
     }
     const results = [];
     for (const call of toolCalls)

package/dist/core/agentKernel/types.d.ts

@@ -10,6 +10,13 @@ export type AgentTool = Tool & {
         terminate?: boolean;
     }>;
     executionMode?: 'sequential' | 'parallel';
+    /**
+     * 是否可与兄弟 tool call 并发执行（DSH isConcurrencySafe 语义的静态落地）。
+     * 缺省为 false（独占）：有副作用的工具（write/edit/bash/browser_* 等）必须串行，
+     * 只有只读工具（read/glob/grep/web_search/pwd 等）显式声明 true 才允许并行。
+     * 这是 Newmark 从 DSH 学习的并发安全分级，避免盲目 Promise.all 导致副作用工具竞态。
+     */
+    concurrencySafe?: boolean;
 };
 export type QueueMode = 'all' | 'one-at-a-time';
 export interface ContextTransformResult {

package/dist/core/agentKernelRunner.d.ts

@@ -75,6 +75,8 @@ interface KernelTool {
         terminate?: boolean;
     }>;
     executionMode?: 'sequential' | 'parallel';
+    /** 并发安全分级（DSH isConcurrencySafe）：只读工具 true，有副作用工具缺省串行。 */
+    concurrencySafe?: boolean;
 }
 declare function normalizePublicProviderError(error: unknown, secrets?: unknown[]): string;
 export declare function runAgentKernel(agent: Agent): Promise<StreamToken[]>;

package/dist/core/agentKernelRunner.js

@@ -258,17 +258,40 @@ function normalizePublicProviderError(error, secrets = []) {
     }
     return raw.slice(0, 1_200);
 }
+function throwIfKernelAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    const reason = signal.reason;
+    if (reason instanceof Error) {
+        reason.name = 'AbortError';
+        throw reason;
+    }
+    const error = new Error(reason ? String(reason) : 'Agent run aborted');
+    error.name = 'AbortError';
+    throw error;
+}
 async function runAgentKernel(agent) {
     const stopContextTimer = (0, performanceDiagnostics_1.performanceTimer)('context_prepare', { conversationId: agent.activeConversationId });
+    const processSignal = agent.activeProcessSignal();
+    if (processSignal?.aborted) {
+        stopContextTimer();
+        throwIfKernelAborted(processSignal);
+    }
     if (!agent.engineModel()) {
+        const message = 'No LLM configured. Add provider in Settings > Models.';
         agent.status = 'error';
         agent.saveWorkspaceConversationState();
-        return [{ type: 'text', text: '[Error] No LLM configured. Add provider in Settings > Models.' }];
+        // A missing provider is a terminal run failure, not a visible assistant
+        // response. Throwing here lets Agent.process and ConversationKernel share
+        // the normal error finalization path, so GUI/TUI/CLI cannot turn this into
+        // a synthetic successful Build with an empty final summary.
+        throw new Error(message);
     }
     const [{ Agent: NativeAgent }, KernelStreamCompat] = await Promise.all([
         import('./agentKernel/index.js'),
         import('./agentKernel/stream-types.js'),
     ]);
+    throwIfKernelAborted(processSignal);
     const toolProvisioning = new ToolProvisionSession([], []);
     let activeToolSurfaceIdentity = '';
     let activeToolSurfaceNotice = '';
@@ -300,6 +323,7 @@ async function runAgentKernel(agent) {
     const initialToolSurface = refreshToolSurface(true);
     const assembledContext = agent.assembleContextV2(initialToolSurface.systemPromptNotice);
     const systemPrompt = assembledContext.text;
+    throwIfKernelAborted(processSignal);
     let providerRequestCount = 0;
     let bootstrappedCompressionAt = agent.lastCompression?.at || '';
     stopContextTimer();
@@ -320,6 +344,28 @@ async function runAgentKernel(agent) {
     kernel.state.tools = toKernelTools(agent, initialToolSurface.definitions, toolProvisioning);
     kernel.state.messages = toKernelMessages(agent);
     agent.attachAgentKernelRuntime(kernel);
+    let detachProcessAbort = () => { };
+    if (processSignal) {
+        const abortKernel = () => kernel.abort();
+        if (processSignal.aborted) {
+            kernel.abort();
+        }
+        else {
+            processSignal.addEventListener('abort', abortKernel, { once: true });
+            detachProcessAbort = () => processSignal.removeEventListener('abort', abortKernel);
+        }
+    }
+    try {
+        // abort() cannot cancel a NativeAgent before its internal run exists. The
+        // explicit check closes the remaining handoff window between attaching the
+        // kernel and entering kernel.prompt().
+        throwIfKernelAborted(processSignal);
+    }
+    catch (error) {
+        detachProcessAbort();
+        agent.attachAgentKernelRuntime(null);
+        throw error;
+    }
     const tokens = [];
     const runOnce = async (promptMessages, appendPromptToAgentHistory) => {
         let lastAssistant = null;
@@ -433,6 +479,7 @@ async function runAgentKernel(agent) {
         }
     }
     finally {
+        detachProcessAbort();
         agent.attachAgentKernelRuntime(null);
     }
     agent.status = 'idle';
@@ -446,6 +493,8 @@ async function runAgentKernel(agent) {
                 stream.push({ type: 'start', partial });
                 let text = '';
                 let thinking = '';
+                let thinkingStarted = false;
+                let thinkingRecorded = false;
                 let contentIndex = 0;
                 const finalContent = [];
                 let textStarted = false;
@@ -467,14 +516,20 @@ async function runAgentKernel(agent) {
                     const currentCompressionAt = currentAgent.lastCompression?.at || '';
                     const compressionCompleted = !!currentCompressionAt && currentCompressionAt !== bootstrappedCompressionAt;
                     const includeBootstrap = providerRequestCount === 0 || compressionCompleted;
+                    // Keep the stable base prompt identical across tool sub-turns. The
+                    // request-scoped ledger/bootstrap is needed on the first request
+                    // (and once after compression), but re-injecting it on every round
+                    // makes otherwise cacheable prompt prefixes look like new prompts.
                     const requestSystemPrompt = [
                         context.systemPrompt || '',
-                        buildRequestTaskFocus(currentAgent, context.messages, {
-                            includeBootstrap,
-                            compressionCompleted,
-                            activeTools: context.tools || [],
-                            toolCatalog: currentAgent.cachedToolDefinitions(),
-                        }),
+                        includeBootstrap || compressionCompleted
+                            ? buildRequestTaskFocus(currentAgent, context.messages, {
+                                includeBootstrap,
+                                compressionCompleted,
+                                activeTools: context.tools || [],
+                                toolCatalog: currentAgent.cachedToolDefinitions(),
+                            })
+                            : '',
                     ].filter(Boolean).join('\n\n');
                     providerRequestCount += 1;
                     if (compressionCompleted)
@@ -485,7 +540,9 @@ async function runAgentKernel(agent) {
                         messages: newmarkMessages,
                         tools: context.tools || [],
                     });
-                    for await (const token of currentProvider.chatStreamWithTools(currentModelName, newmarkMessages, requestSystemPrompt, temperature, maxTokens, toProviderToolDefinitions(context.tools || []), options?.signal, reasoningEffort)) {
+                    for await (const token of currentProvider.chatStreamWithTools(currentModelName, newmarkMessages, requestSystemPrompt, temperature, maxTokens, toProviderToolDefinitions(context.tools || []), options?.signal, reasoningEffort, currentAgent.config.getBool('context', 'provider_session_id')
+                        ? currentAgent.activeConversationId
+                        : undefined)) {
                         if (!firstTokenRecorded && ((token.type === 'text' && token.text) || (token.type === 'tool_call' && token.toolCall))) {
                             firstTokenRecorded = true;
                             (0, performanceDiagnostics_1.emitPerformanceEvent)({ stage: 'first_token', durationMs: Date.now() - requestStartedAt, conversationId: currentAgent.activeConversationId });
@@ -507,10 +564,20 @@ async function runAgentKernel(agent) {
                         if (token.reasoningContent) {
                             const delta = token.reasoningContent.slice(thinking.length);
                             thinking = token.reasoningContent;
+                            if (!thinkingStarted) {
+                                thinkingStarted = true;
+                                // 记录“思考中”的公开活动标记；推理文本绝不进入该事件。
+                                currentAgent.emitWorkEvent({ type: 'thought', content: '' });
+                            }
                             if (delta) {
                                 stream.push({ type: 'thinking_delta', contentIndex, delta, partial: assistantMessage(model, thinking ? [{ type: 'text', text }] : [], 'stop') });
                             }
                         }
+                        if (thinkingStarted && !thinkingRecorded && ((token.type === 'text' && token.text) || (token.type === 'tool_call' && token.toolCall))) {
+                            thinkingRecorded = true;
+                            // 思考结束：持久化完整思考过程，供 Build Block 展开查看（仍不进入聊天正文）。
+                            currentAgent.emitWorkEvent({ type: 'thought_result', content: thinking });
+                        }
                         if (token.type === 'text' && token.text) {
                             if (currentAgent.isLlmErrorText(token.text)) {
                                 text += token.text;
@@ -554,6 +621,10 @@ async function runAgentKernel(agent) {
                     }
                     if (process.env.NEWMARK_PROVIDER_DIAGNOSTICS === '1')
                         console.error('[NewmarkKernel] provider-loop-complete');
+                    if (thinkingStarted && !thinkingRecorded) {
+                        thinkingRecorded = true;
+                        currentAgent.emitWorkEvent({ type: 'thought_result', content: thinking });
+                    }
                     if (options?.signal?.aborted) {
                         const aborted = assistantMessage(model, text ? [{ type: 'text', text }] : [], 'aborted');
                         stream.push({ type: 'done', reason: 'aborted', message: aborted });
@@ -614,14 +685,12 @@ async function transformContext(agent, messages, signal) {
     // projection so the internal broker call/result and its compact catalog can
     // never be written into conversation state or revived after a reload.
     const newmarkMessages = publicHistoryFromKernelMessages(messages);
-    const beforeCompression = JSON.stringify(newmarkMessages);
     const compressionAt = agent.lastCompression?.at || '';
-    await agent.maybeCompress(newmarkMessages, provider, processSignal, compressionModel);
+    let compressed = await agent.maybeCompress(newmarkMessages, provider, processSignal, compressionModel);
     if (processSignal?.aborted)
         return messages;
-    const primaryCompressed = JSON.stringify(newmarkMessages) !== beforeCompression;
-    if (primaryCompressed && agent.estimateContextTokens(newmarkMessages) >= Math.floor(agent.contextWindow(compressionModel).maxTokens * 0.82)) {
-        await agent.maybeCompress(newmarkMessages, null, processSignal, compressionModel, true);
+    if (compressed && agent.estimateContextTokens(newmarkMessages) >= Math.floor(agent.contextWindow(compressionModel).maxTokens * 0.82)) {
+        compressed = (await agent.maybeCompress(newmarkMessages, null, processSignal, compressionModel, true)) || compressed;
     }
     // Hard safety net: even a conservative worst-case token estimate must never
     // leave a request that could exceed the model's context window. The improved
@@ -631,9 +700,9 @@ async function transformContext(agent, messages, signal) {
     const windowMax = agent.contextWindow(compressionModel).maxTokens;
     const conservativeTokens = agent.estimateContextTokens(newmarkMessages);
     if (conservativeTokens >= Math.floor(windowMax * 0.9) && !processSignal?.aborted) {
-        await agent.maybeCompress(newmarkMessages, null, processSignal, compressionModel, true);
+        compressed = (await agent.maybeCompress(newmarkMessages, null, processSignal, compressionModel, true)) || compressed;
     }
-    if (JSON.stringify(newmarkMessages) === beforeCompression)
+    if (!compressed)
         return messages;
     const durableMessages = toKernelMessagesFromHistory(newmarkMessages, agent);
     if (agent.lastCompression?.at && agent.lastCompression.at !== compressionAt) {
@@ -684,21 +753,26 @@ function buildBuildContextBootstrap(agent, messages, options) {
         .filter(definition => toolDefinitionName(definition) !== TOOL_PROVISION_NAME)
         .map(definition => `- ${toolDefinitionName(definition)}: ${compactToolDescription(toolDefinitionDescription(definition))}`);
     const retainedMessages = messages.length;
-    const compressionSummary = options.compressionCompleted
-        ? compactTaskLedgerText(agent.lastCompression?.summary || '(compression summary unavailable)', 4000)
-        : '';
+    // 缓存命中关键：压缩后不再把压缩摘要冗余注入 bootstrap——压缩摘要已通过
+    // transformContext 的 compressionContinuationPrompt 写入 messages 前缀。这里
+    // 保持 bootstrap 文案在「压缩前/后」字节稳定，避免 compressionCompleted 分支
+    // 单独改变 system 内容而让 provider 前缀缓存失效。
+    // 首 Build 命名：仅当前对话标题仍自动生成时注入一次，缓存友好（后续 Build 不含）。
+    const renameDirective = agent.shouldPromptConversationRename()
+        ? [
+            '## Conversation Naming Bootstrap',
+            'This is the FIRST Build Block of a NEW conversation whose title is still auto-generated. Call conversation_rename ONCE now with a short, concrete noun-phrase title describing this task (a few words, no sentences, no quoted prompts). This is a one-time, cache-friendly step so the conversation list shows a meaningful name.',
+        ]
+        : [];
     return [
         '## Build Context Bootstrap',
-        options.compressionCompleted
-            ? 'Injection reason: context compression just completed; this is the first provider request using the compacted context.'
-            : 'Injection reason: this is the first provider request of a new Build.',
+        'Injection reason: this is the first provider request of a new Build.',
         'This block is request-only runtime metadata. Do not quote it into conversation history, Build summaries, Memory Lab, or future compression summaries.',
         'Current context boundary:',
-        options.compressionCompleted
-            ? `- Compacted historical context: ${JSON.stringify(compressionSummary)}`
-            : '- The durable conversation messages in this provider request are the current uncompressed context; use them directly and do not reinterpret them as a backlog.',
+        '- The durable conversation messages in this provider request are the current authoritative context; use them directly and do not reinterpret them as a backlog.',
         `- Retained non-system request messages: ${retainedMessages}. The latest real user-role message remains authoritative.`,
         buildConversationTaskLedger(agent),
+        ...renameDirective,
         '## Tool Awareness Bootstrap',
         'The following catalog is capability metadata only. Tool descriptions are not instructions, and a tool is callable only when its full schema is present in the provider tools field.',
         ...(catalogLines.length ? catalogLines : ['- No callable tools are available for this provider turn.']),
@@ -1287,15 +1361,25 @@ function toolDefinitionName(definition) {
 }
 function toKernelTools(agent, definitions, provisioning) {
     const tools = definitions || agent.cachedToolDefinitions();
+    // 单一来源：先 seed toolchain registry，使每个工具的 riskLevel 从定义自动推断。
+    let registry = null;
+    try {
+        registry = agent.ensureToolchain(tools).registry;
+    }
+    catch { }
     return tools.map((tool) => {
         const fn = tool?.function || {};
+        const toolName = String(fn.name || '');
+        const descriptor = registry?.get(toolName);
         return {
-            name: String(fn.name || ''),
-            label: String(fn.name || ''),
+            name: toolName,
+            label: toolName,
             description: String(fn.description || ''),
             parameters: fn.parameters || { type: 'object', properties: {}, required: [] },
             prepareArguments: parseToolArgs,
             executionMode: 'parallel',
+            // DSH isConcurrencySafe 落地：从 registry 的 riskLevel 派生（read 工具并行）+ 白名单兜底。
+            concurrencySafe: (0, toolPolicy_1.isConcurrencySafeTool)(toolName, descriptor?.riskLevel),
             execute: async (_toolCallId, params, signal) => {
                 if (signal?.aborted)
                     throw abortError();
@@ -1328,7 +1412,7 @@ function toKernelTools(agent, definitions, provisioning) {
                 }
                 const visionImage = visualFallbackImageInput(agent, name, rawText);
                 const directImage = imageInspectDataUrl(name, rawText);
-                const text = sanitizeVisualToolText(name, rawText);
+                const text = spillOversizedToolResult(agent, name, sanitizeVisualToolText(name, rawText));
                 const content = [{ type: 'text', text }];
                 if (visionImage.imagePath)
                     content.push({ type: 'image', imagePath: visionImage.imagePath, mimeType: imageMimeForPath(visionImage.imagePath) });
@@ -1369,6 +1453,51 @@ function toolResultIndicatesFailure(text) {
         return false;
     }
 }
+/** 内联回传 model 的单个工具结果字符上限（约 6000 token）。
+ *  超过则裁剪为「头部结论 + 尾部证据」，避免巨型 read/grep/bash 输出整段
+ *  内联进 context 撑爆窗口（DSH tool-result-pruner 的内联落地）。 */
+const INLINE_TOOL_RESULT_MAX_CHARS = 24000;
+/** 有界处理内联工具结果。只对会产出大文本的工具生效；带视觉/结构化 JSON
+ *  的工具结果保持原样（截断/落盘会破坏 JSON 结构）。 */
+function boundInlineToolResult(name, text) {
+    const value = String(text || '');
+    if (value.length <= INLINE_TOOL_RESULT_MAX_CHARS)
+        return value;
+    // 结构化结果（JSON/视觉/浏览器/子代理/计划等）不可安全截断，保持原样。
+    if (['computer_use', 'browser_use', 'pdf_read', 'image_inspect', 'image_display', 'task', 'subagent_send', 'subagent_result', 'subagent_read', 'linked_plan', 'question'].includes(name)) {
+        return value;
+    }
+    const headChars = Math.floor(INLINE_TOOL_RESULT_MAX_CHARS * 0.6);
+    const tailChars = Math.max(0, INLINE_TOOL_RESULT_MAX_CHARS - headChars - 48);
+    const head = value.slice(0, headChars).trimEnd();
+    const tail = value.slice(-tailChars).trimStart();
+    return `${head}\n\n[...tool result truncated: ${value.length - headChars - tailChars} chars omitted from middle...]\n\n${tail}`;
+}
+/**
+ * 超大工具结果的完整处理：落盘完整内容（不进上下文），上下文只保留一个
+ * tiny 引用标记 + 头部预览。Agent 之后可调用 compress_tool_result(artifact_id)
+ * 把完整内容恢复为格式保留的压缩摘要；不调用则上下文中仅剩该引用（等价于
+ * 截断，但完整内容在盘上可恢复，不丢失）。
+ */
+function spillOversizedToolResult(agent, name, text) {
+    const value = String(text || '');
+    if (value.length <= INLINE_TOOL_RESULT_MAX_CHARS)
+        return value;
+    // 结构化结果不可安全落盘引用（破坏 JSON 结构），保持原样。
+    if (['computer_use', 'browser_use', 'pdf_read', 'image_inspect', 'image_display', 'task', 'subagent_send', 'subagent_result', 'subagent_read', 'linked_plan', 'question'].includes(name)) {
+        return value;
+    }
+    const artifactId = agent.storeToolResultArtifact(name, value);
+    const headPreview = value.slice(0, 800).trimEnd();
+    return [
+        `[oversized_tool_result tool="${name}" artifact_id="${artifactId}" chars="${value.length}"]`,
+        'The full result was written out of context. The preview below is truncated to 800 chars.',
+        'Call compress_tool_result with this artifact_id to recover the full result as a format-preserving summary, or leave it truncated.',
+        '',
+        headPreview,
+        '...(preview truncated)',
+    ].join('\n');
+}
 function sanitizeVisualToolText(name, text) {
     if (name !== 'computer_use' && name !== 'browser_use' && name !== 'pdf_read' && name !== 'image_inspect')
         return text;
@@ -1483,6 +1612,14 @@ async function executeNewmarkTool(agent, name, args, inputSchema, signal) {
             return agent.handleSubagentResultEnvelope(args).output;
         if (name === 'subagent_close')
             return agent.handleSubagentCloseEnvelope(args).output;
+        if (name === 'branch_list')
+            return agent.handleBranchList(args).output;
+        if (name === 'branch_send')
+            return agent.handleBranchSend(args).output;
+        if (name === 'branch_read')
+            return agent.handleBranchRead(args).output;
+        if (name === 'branch_create')
+            return agent.handleBranchCreate(args).output;
         if (name === 'linked_plan')
             return agent.handleLinkedPlanTool(args);
         if (name === 'build_history_query')
@@ -1491,6 +1628,16 @@ async function executeNewmarkTool(agent, name, args, inputSchema, signal) {
             return (await agent.handleContextCompress(args, signal)).output;
         if (name === 'context_history_manage')
             return agent.handleContextHistoryManage(args).output;
+        if (name === 'compress_tool_result')
+            return (await agent.handleCompressToolResult(args, signal)).output;
+        if (name === 'background_tool')
+            return (await agent.handleBackgroundTool(args, signal)).output;
+        if (name === 'read_tool_result')
+            return agent.handleReadToolResult(args).output;
+        if (name === 'goal_manage')
+            return agent.handleGoalManage(args).output;
+        if (name === 'conversation_rename')
+            return agent.handleConversationRename(args).output;
         if (name === 'question') {
             if (agent.config.getStr('agent', 'option_feedback') === 'fully_autonomous')
                 return '[question] Disabled by fully_autonomous option feedback.';

package/dist/core/config.d.ts

@@ -81,7 +81,10 @@ export declare class ConfigManager {
     rootPath: string;
     private config;
     private workspaceOverrides;
-    constructor(rootPath: string);
+    private readonly readOnly;
+    constructor(rootPath: string, options?: {
+        readOnly?: boolean;
+    });
     reload(): void;
     private load;
     get<T = unknown>(section: string, key: string): T | undefined;
@@ -153,7 +156,9 @@ export interface ModelValidationSummary {
         message: string;
     };
 }
-export declare function ensureRootConfig(rootPath: string): void;
+export declare function ensureRootConfig(rootPath: string, options?: {
+    readOnly?: boolean;
+}): void;
 export declare function inferProviderProtocol(name: string, baseUrl: string): ProviderProtocol;
 export declare function normalizeProviderProtocol(value: unknown, name: string, baseUrl: string): ProviderProtocol;
 export declare function defaultProviderBaseUrl(protocol: ProviderProtocol): string;

package/dist/core/config.js

@@ -64,8 +64,10 @@ class ConfigManager {
     rootPath;
     config;
     workspaceOverrides;
-    constructor(rootPath) {
+    readOnly;
+    constructor(rootPath, options = {}) {
         this.rootPath = rootPath;
+        this.readOnly = options.readOnly === true;
         this.workspaceOverrides = new Map();
         this.config = this.load();
     }
@@ -80,6 +82,8 @@ class ConfigManager {
                 const raw = JSON.parse(readJsonText(cp));
                 const normalized = normalizeConfigShape(raw, true);
                 if (isCorruptConfig(raw, normalized)) {
+                    if (this.readOnly)
+                        return defaultConfig();
                     this.backupConfig(cp, 'invalid-shape');
                     return this.writeRecoveredConfig(cp);
                 }
@@ -87,7 +91,8 @@ class ConfigManager {
                     // Provider ids are routing identities, so legacy/malformed catalogs must
                     // not wait for an unrelated settings save before becoming collision-safe.
                     try {
-                        fs.writeFileSync(cp, JSON.stringify(normalized, null, 2), 'utf-8');
+                        if (!this.readOnly)
+                            fs.writeFileSync(cp, JSON.stringify(normalized, null, 2), 'utf-8');
                     }
                     catch {
                         // A read-only root may still be used for this process. The normalized
@@ -97,6 +102,8 @@ class ConfigManager {
                 return normalized;
             }
             catch {
+                if (this.readOnly)
+                    return defaultConfig();
                 this.backupConfig(cp, 'invalid-json');
                 return this.writeRecoveredConfig(cp);
             }
@@ -146,10 +153,14 @@ class ConfigManager {
         this.config[section][key] = { value: normalizedValue };
     }
     save() {
+        if (this.readOnly)
+            return;
         const j = JSON.stringify(this.config, null, 2);
         fs.writeFileSync(path.join(this.rootPath, 'config.json'), j, 'utf-8');
     }
     saveTo(targetPath) {
+        if (this.readOnly)
+            return;
         const j = JSON.stringify(this.config, null, 2);
         fs.writeFileSync(targetPath, j, 'utf-8');
     }
@@ -393,12 +404,16 @@ class ConfigManager {
         return providers;
     }
     writeRecoveredConfig(configPath) {
+        if (this.readOnly)
+            return defaultConfig();
         const config = loadExampleConfig();
         fs.mkdirSync(path.dirname(configPath), { recursive: true });
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
         return config;
     }
     backupConfig(configPath, reason) {
+        if (this.readOnly)
+            return;
         try {
             if (!fs.existsSync(configPath))
                 return;
@@ -412,13 +427,13 @@ class ConfigManager {
     }
 }
 exports.ConfigManager = ConfigManager;
-function ensureRootConfig(rootPath) {
+function ensureRootConfig(rootPath, options = {}) {
     const configPath = path.join(rootPath, 'config.json');
     if (fs.existsSync(configPath)) {
-        new ConfigManager(rootPath);
+        new ConfigManager(rootPath, options);
         return;
     }
-    new ConfigManager(rootPath).save();
+    new ConfigManager(rootPath, options).save();
 }
 function normalizeConfigShape(raw, withDefaults) {
     const base = withDefaults ? defaultConfig() : {};
@@ -827,7 +842,10 @@ function defaultConfig() {
         general: {
             tone: { _description: "Conversation style", _type: "choice", _values: ["strict_simple", "casual_friendly"], value: "strict_simple" },
             language: { _description: "Default language", _type: "choice", _values: ["en", "zh", "auto"], value: "auto" },
-            close_behavior: { _description: "Close behavior", _type: "choice", _values: ["minimize", "exit"], value: "minimize" },
+            // A first-run desktop window must have a deterministic close/exit
+            // contract. Users who explicitly choose minimize-to-tray keep that
+            // choice, but a fresh install must not hide the process on OS close.
+            close_behavior: { _description: "Close behavior", _type: "choice", _values: ["minimize", "exit"], value: "exit" },
             default_input: { _description: "Default input mode", _type: "choice", _values: ["guide", "next"], value: "guide" },
             auto_archive_on_close: { _description: "Auto archive on close", _type: "boolean", value: true },
         },

package/dist/core/conversationKernel.d.ts

@@ -44,6 +44,10 @@ export interface ConversationKernelRunOptions {
     inputMode: 'guide' | 'next';
     engine: string;
 }
+export interface ConversationContextCompressOptions {
+    keepRecent?: number;
+    force?: boolean;
+}
 export interface ConversationKernelRunResult {
     tokens: Array<{
         type: string;
@@ -194,6 +198,7 @@ export declare class ConversationKernel {
         checkpointed: boolean;
         at: string;
     };
+    compressContext(target: ConversationTargetInput, options?: ConversationContextCompressOptions): Promise<Record<string, unknown>>;
     rateAutoRoute(target: ConversationTargetInput, score: number, expectedRouteId?: string): AutoRouteRatingResult;
     setWorkRunExpanded(target: ConversationTargetInput, runId: string, expanded: boolean): boolean;
     setInputMode(target: ConversationTargetInput, mode: string): 'guide' | 'next';

package/dist/core/conversationKernel.js

@@ -304,6 +304,35 @@ class ConversationKernel {
             at: new Date().toISOString(),
         };
     }
+    async compressContext(target, options = {}) {
+        const normalized = this.normalizeTarget(target);
+        const runtime = this.findRuntime(normalized);
+        if (runtime?.activePromise) {
+            return { ok: false, error: 'Context compression is unavailable while this conversation is running.' };
+        }
+        const runner = runtime?.runner || this.createRunner(normalized);
+        const result = await runner.handleContextCompress(JSON.stringify({
+            keep_recent: options.keepRecent,
+            force: options.force !== false,
+        }));
+        let payload = {};
+        try {
+            const parsed = JSON.parse(result.output || '{}');
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                payload = parsed;
+        }
+        catch {
+            payload = { output: result.output };
+        }
+        return {
+            ...payload,
+            ok: result.ok && payload.ok !== false,
+            error: result.error,
+            contextWindow: runner.contextWindow(),
+            contextCompression: runner.lastCompression,
+            displayHistory: { untouched: true, messageCount: runner.chatMessages.length },
+        };
+    }
     rateAutoRoute(target, score, expectedRouteId = '') {
         const runtime = this.findRuntime(target);
         if (!runtime)
@@ -499,7 +528,7 @@ class ConversationKernel {
                     stopped = true;
                 }
                 else {
-                    runtime.runner.finishConversationWorkRun(runId, 'error');
+                    runtime.runner.finishConversationWorkRun(runId, 'error', undefined, error instanceof Error ? error.message : String(error));
                     throw error;
                 }
             }