newmark-agent 0.3.11 → 0.4.0

package/dist/conversation-utility-host.js

@@ -81,6 +81,9 @@ async function handle(request) {
     }
     if (request.method === 'checkpoint')
         return kernel.checkpoint(checkedTarget(request.params.target));
+    if (request.method === 'context_compress') {
+        return kernel.compressContext(checkedTarget(request.params.target), request.params.options);
+    }
     if (request.method === 'rate_auto_route') {
         return kernel.rateAutoRoute(checkedTarget(request.params.target), request.params.score, request.params.routeId);
     }

package/dist/core/agent.d.ts

@@ -33,6 +33,7 @@ export interface AgentRuntimeOptions {
     actorId?: string;
     conversationId?: string;
     runtimeLifecycleRole?: RuntimeLifecycleRole;
+    readOnlyConfig?: boolean;
     linkedPlanAccess?: {
         get(conversationId?: string): LinkedPlanState;
         update(markdown: string, expectedRevision: number, actorId: string, conversationId?: string): LinkedPlanState;
@@ -60,6 +61,19 @@ export interface AutoRouteRatingResult {
 }
 export declare const ROOT_AGENT_ACTOR_ID = "00000000-0000-4000-8000-000000000001";
 export declare function normalizeIntelligenceTier(value: unknown): 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
+export interface BranchMessage {
+    id: string;
+    conversationId: string;
+    sequence: number;
+    fromBranchId: string;
+    toBranchId: string;
+    kind: 'message' | 'directive' | 'result';
+    body: string;
+    correlationId?: string;
+    replyTo?: string;
+    createdAt: string;
+    readAt?: string;
+}
 export interface CompressionCacheEntry {
     id: string;
     at: string;
@@ -174,6 +188,8 @@ export interface ConversationTreeState {
     rootNodeId: string;
     activeNodeId: string;
     activeGroupId: string;
+    /** Branch-communication mode only: every branch id that is currently running (removes single-runtime uniqueness). */
+    runningNodeIds?: string[];
     nodes: Record<string, ConversationTreeNode>;
     branchGroups: Record<string, ConversationBranchGroupState>;
     nodeIndex: Record<string, ConversationTreeNodeIndexEntry>;
@@ -299,6 +315,11 @@ export declare class Agent {
         fallback: boolean;
     } | null;
     private compressionCache;
+    private pendingHistoryRemovals;
+    private branchMailbox;
+    private nextBranchMessageSequence;
+    private branchCommunicationEnabled;
+    private compressionArchiveCountCache;
     private nextCompressionCacheId;
     private readonly compressionHistoryArchive;
     private workspaceConversations;
@@ -357,6 +378,10 @@ export declare class Agent {
     readonly runtimeLifecycleRole: RuntimeLifecycleRole;
     /** dev-0.3.0 context system facade (feature-flagged, default off). */
     readonly contextV2: AgentContextManager;
+    /** 工具结果的持久化引用（artifact_id -> 状态 + 内容）。
+     *  两种来源：超大结果落盘（content 立即可得）与后台工具（status=running 直到完成）。
+     *  压缩前/后台中的大内容不进上下文，只通过 artifact_id 引用；读取后再释放。 */
+    private readonly toolResultArtifacts;
     private readonly runtimeLifecycle;
     /** dev-0.3.0 toolchain core (registry + capability catalog). Seeded lazily from cachedToolDefinitions; not consumed by the legacy path. */
     private toolchainCore;
@@ -385,6 +410,11 @@ export declare class Agent {
     private branchGroupMetadata;
     private treeAncestry;
     private treePath;
+    /** 确定性消息 ID：基于角色+内容+索引的 sha256，保证旧数据缺失 messageId 时补生成稳定、
+     * 不漂移，且跨分支共享 fork 前缀消息得到一致 ID。 */
+    private deterministicMessageId;
+    /** 确定性 Guide ID：基于消息 ID + 索引，保证补生成稳定唯一。 */
+    private deterministicGuideId;
     private rebuildConversationTreeIndex;
     private validateConversationTree;
     private resolveConversationTreePath;
@@ -482,12 +512,25 @@ export declare class Agent {
     setConversationWorkRunFlowMetadata(runId: string, flow: NonNullable<ConversationWorkRun['flow']>): boolean;
     replaceConversationWorkRunFinalResponse(runId: string, content: string): boolean;
     resumeConversationWorkRun(runId: string): boolean;
+    /**
+     * Close any running Build ledger entries owned by an explicitly interrupted
+     * lifecycle before a Flow is resumed or a conversation is archived.
+     *
+     * The normal Flow runner guard must continue to reject a genuinely
+     * concurrent Build. This method is deliberately explicit and target-scoped:
+     * callers use it only after the owning Flow has been stopped/paused or when
+     * archive has won the lifecycle race. Without this boundary, an isolated
+     * Agent created during resume can legitimately reload the previous snapshot
+     * while its runtime owner is still this Electron process and the guard would
+     * mistake that stale ledger entry for an active Build.
+     */
+    interruptRunningConversationWorkRuns(target?: ConversationTarget, status?: Extract<ConversationWorkRunStatus, 'interrupted' | 'force_interrupted'>): number;
     recordGuideReceipt(input: GuideReceipt): GuideReceipt;
     private durableAttachmentsFromHistoryContent;
     private normalizeConversationChatMessages;
     persistGuideMessage(clientMessageId: string, content: string, runId?: string, historyContent?: unknown, attachments?: ConversationImageAttachment[], guideId?: string): boolean;
     setConversationWorkRunExpanded(runId: string, expanded: boolean): boolean;
-    finishConversationWorkRun(runId: string, status: Exclude<ConversationWorkRunStatus, 'running'>, endedAt?: string): boolean;
+    finishConversationWorkRun(runId: string, status: Exclude<ConversationWorkRunStatus, 'running'>, endedAt?: string, errorMessage?: string): boolean;
     private ensureCompletedWorkRunFinalResult;
     emitWorkEvent(input: Omit<AgentWorkEvent, 'id' | 'conversationId' | 'mode' | 'model' | 'timestamp'> & Partial<Pick<AgentWorkEvent, 'conversationId' | 'mode' | 'model' | 'timestamp'>>): AgentWorkEvent;
     appendWorkflowMessage(content: string, toolName?: string, toolArgs?: string, persist?: boolean): void;
@@ -563,6 +606,7 @@ export declare class Agent {
         pinned: boolean;
         pinnedAt: string;
         order: number;
+        branchCommunication: boolean;
     }>;
     private normalizeLinkedPlan;
     private subagentManagerKey;
@@ -581,9 +625,18 @@ export declare class Agent {
     ensureConversationSnapshot(conversationId?: string): ConversationSnapshot;
     rewindConversation(conversationId: string, messageIndex: number): ConversationSnapshot;
     branchConversation(conversationId: string, messageIndex: number, editedText: string, locator?: ConversationBranchLocator): ConversationSnapshot;
+    setBranchCommunication(enabled: boolean): boolean;
+    isBranchCommunicationEnabled(): boolean;
     switchConversationBranch(conversationId: string, branchId: string, branchGroupId?: string): ConversationSnapshot;
     setConversationPinned(id: string, pinned: boolean): boolean;
     renameConversation(id: string, title: string): boolean;
+    /**
+     * 首 Build 命名提示判定：仅当 (1) 当前对话尚无历史 Build（排除当前 run）且
+     * (2) 其持久化 title 仍是自动生成（含为空）时返回 true。满足条件时运行时会
+     * 在首个 provider request 的 bootstrap 注入一次性命名指令，让 Agent 调用
+     * conversation_rename 自行命名。判定本身只读存储、无副作用，保缓存稳定。
+     */
+    shouldPromptConversationRename(): boolean;
     reorderConversations(ids: string[]): boolean;
     flushConversationState(): void;
     private titleFromMessages;
@@ -598,6 +651,7 @@ export declare class Agent {
     private applyWorkspaceContext;
     selectWorkspace(id: string): WorkspaceInfo | null;
     selectWorkspaceFromStorage(id: string): WorkspaceInfo | null;
+    refreshWorkspaceRegistryFromStorage(): WorkspaceInfo | null;
     setConversation(id: string): string;
     setConversationFromStorage(id: string): string;
     persistActiveConversationSelection(id: string, ws?: WorkspaceInfo | null): string;
@@ -617,6 +671,71 @@ export declare class Agent {
     }>;
     handleBuildHistoryQuery(args: string): string;
     handleContextCompress(args: string, signal?: AbortSignal): Promise<NewmarkToolResult>;
+    /**
+     * 落盘一个超大工具结果，返回 artifact_id。完整内容不进上下文——上下文只保留
+     * tiny 引用；compress_tool_result 按 id 读取后再压缩。落盘后状态即 done。
+     */
+    storeToolResultArtifact(tool: string, content: string): string;
+    /**
+     * 注册一个后台工具任务，立即返回 background_id（status=running）。真实工具在
+     * 后台执行，完成后由 finishToolResultArtifact 标记 done/error。后台结果持久化
+     * 等待 read_tool_result 读取后再释放。
+     */
+    beginBackgroundTool(tool: string): string;
+    /** 标记后台任务完成（写结果）或失败（写错误）。 */
+    finishToolResultArtifact(id: string, content: string, error?: string): void;
+    /**
+     * 按 artifact_id 读取工具结果引用（compress_tool_result / read_tool_result 共用）。
+     */
+    readToolResultArtifact(id: string): {
+        tool: string;
+        content: string;
+        status: 'running' | 'done' | 'error';
+        error?: string;
+        createdAt: number;
+    } | null;
+    /**
+     * 压缩一个极大的工具调用结果（保留格式），供 Agent 主动选用以替代硬截断。
+     *
+     * 入参为 artifact_id（而非完整 content），故压缩前的大内容不进入上下文。
+     * 缓存命中隔离：压缩 LLM 调用使用独立 system + 单条 user 消息，与主对话
+     * system/历史前缀不相交，不污染缓存命中。
+     */
+    handleCompressToolResult(args: string, signal?: AbortSignal): Promise<NewmarkToolResult>;
+    /**
+     * 工具后台化：把一个工具调用派发到后台运行，立即返回 background_id，不阻塞
+     * 对话回合。真实工具在后台执行，完成后持久化到 toolResultArtifacts，
+     * read_tool_result 按 background_id 读取后再释放。
+     *
+     * 缓存命中优化：后台化工具只返回 tiny 的 background_id（不进大结果到上下文），
+     * 真实结果按需读取，避免大结果撑爆上下文、破坏前缀缓存。
+     */
+    handleBackgroundTool(args: string, signal?: AbortSignal): Promise<NewmarkToolResult>;
+    /**
+     * 读取后台工具结果：done 时返回结果（按需释放），running 时返回状态，error
+     * 时返回错误。与 compress_tool_result 共享 toolResultArtifacts。
+     */
+    handleReadToolResult(args: string): NewmarkToolResult;
+    /**
+     * Agent 主动管理 Goal 状态：进入 / 编辑 objective / 标记完成 / 退出。
+     * 兼容原有 Goal 机制：enter/update 复用 updateGoal（记录 change、mode=goal、
+     * 尊重已暂停状态），complete 复用 markGoalComplete（verified + clearGoal），
+     * exit 复用 clearGoal（回 build 不声称完成）。不破坏「用户 Stop 暂停」边界：
+     * 本工具不提供 pause/resume，避免 Agent 绕过用户的显式暂停。
+     */
+    handleGoalManage(args: string): NewmarkToolResult;
+    /**
+     * Agent 自行命名当前对话。首 Build Block 上运行时通过 bootstrap 提示（见
+     * agentKernelRunner.buildBuildContextBootstrap）请求 Agent 调用一次；这里复用
+     * 已有的 renameConversation 持久化路径。返回简短结果以保缓存友好。
+     */
+    handleConversationRename(args: string): NewmarkToolResult;
+    private conversationTree;
+    private currentRuntimeBranchId;
+    handleBranchList(args: string): NewmarkToolResult;
+    handleBranchSend(args: string): NewmarkToolResult;
+    handleBranchRead(args: string): NewmarkToolResult;
+    handleBranchCreate(args: string): NewmarkToolResult;
     handleContextHistoryManage(args: string): NewmarkToolResult;
     recordContextCompressionStep(): void;
     compressionContinuationPrompt(): string;
@@ -653,16 +772,28 @@ export declare class Agent {
     removeWorkspace(name: string): boolean;
     modelLabel(): string;
     estimateContextTokens(messages?: Array<Record<string, unknown>>): number;
+    private estimateContextTokenComponents;
     contextWindow(modelName?: string): {
         estimatedTokens: number;
         maxTokens: number;
         ratio: number;
         warning: 'ok' | 'near_limit' | 'over_limit';
         model: string;
+        buildBlockTokens?: number;
+        longHistoryTokens?: number;
+        buildBlockTriggerTokens?: number;
+        longHistoryTriggerTokens?: number;
+        buildBlockRetentionTokens?: number;
+        longHistoryRetentionTokens?: number;
+        thresholdReached?: boolean;
+        compressionEnabled?: boolean;
+        cacheEntries?: number;
+        archiveEntries?: number;
     };
     private resolveWindowModel;
     private contextMaxTokens;
     private compressionBudget;
+    private compressionBuildBlockStart;
     private recentContextSuffix;
     private compressionSegments;
     compressForModelSwitch(signal?: AbortSignal): Promise<{
@@ -688,9 +819,20 @@ export declare class Agent {
     claimGoalContinuationMessage(options?: {
         force?: boolean;
     }): AgentPromptMessage | null;
+    private buildSessionArchive;
     private writeSessionArchive;
+    private writeSessionArchiveAsync;
     archiveSession(): string;
     archiveConversation(conversationId: string): string | null;
+    /**
+     * Non-blocking archive writer used by the desktop IPC path. The conversation
+     * state merge remains synchronous and lock-protected, but the potentially
+     * large markdown payload and manifest use promise-based filesystem I/O so
+     * independent workspaces can archive in parallel without freezing Electron.
+     */
+    archiveConversationAsync(conversationId: string): Promise<string | null>;
+    private archiveConversationAsyncUnlocked;
+    private finalizeAsyncConversationArchive;
     private listStoredConversationIds;
     listArchives(scope?: 'workspace' | 'all'): Array<{
         id: string;
@@ -743,7 +885,9 @@ export declare class Agent {
     switchToFallbackModel(errorText?: string): string | null;
     isLlmErrorText(text: string): boolean;
     private scopedSwitchModels;
-    validateModels(selectedNames?: string[]): Promise<ModelValidationResult[]>;
+    validateModels(selectedNames?: string[], options?: {
+        persist?: boolean;
+    }): Promise<ModelValidationResult[]>;
     isModelValidationRunning(): boolean;
     modelValidationStatus(): ModelValidationProgress;
     private runModelValidation;
@@ -757,6 +901,7 @@ export declare class Agent {
         instruction?: string;
         completion?: boolean;
         preferCopilot?: boolean;
+        onTextDelta?: (text: string) => void;
     }, signal?: AbortSignal): Promise<{
         ok: boolean;
         text: string;
@@ -825,20 +970,26 @@ export declare class Agent {
     handleSkillDownload(args: string): Promise<void>;
     refreshSkills(): void;
     private processOpencode;
-    maybeCompress(msgs: Array<Record<string, unknown>>, provider?: LLMProvider | null, signal?: AbortSignal, compressionModel?: string, force?: boolean): Promise<void>;
+    maybeCompress(msgs: Array<Record<string, unknown>>, provider?: LLMProvider | null, signal?: AbortSignal, compressionModel?: string, force?: boolean): Promise<boolean>;
     private buildCompressionSummary;
     private localCompressionSummary;
     private latestUserHistoryText;
+    /** 裁剪超长工具结果：保留头部结论性内容 + 尾部证据（路径/错误/收尾），
+     *  中间用占位标记省略。与 DSH toolResultPruner 的语义一致。 */
+    private pruneToolResultContent;
     private compressionHistoryContent;
     private compactSummaryBody;
     private formatCompressionSummary;
     private persistCompressedHistory;
     private compressionArchiveScopeKey;
     private coldCompressionEntries;
+    private compressionArchiveEntryCount;
     private archiveColdCompressionEntries;
     private markColdCompressionRestored;
     private pushCompressionCacheEntry;
     private contextHistoryProtectedStartIndex;
+    private historyRecordFingerprint;
+    private flushPendingHistoryRemovals;
     private contextHistoryProtectedZone;
     private snippetAround;
     buildSystemPrompt(): string;
@@ -846,11 +997,9 @@ export declare class Agent {
      * dev-0.3.0: assemble the model-request system prompt through the Context
      * Orchestrator, the single assembly point for every model request. No inline
      * prompt concatenation remains in agent.ts: buildSystemPrompt() itself
-     * routes its section content through the orchestrator (byte-identical to the
-     * legacy parts.join), and this method appends the tool surface notice.
-     * Later iterations split content into the fixed 18 sections with exact
-     * semantics; for now the legacy sections occupy the first string slots in
-     * their original order and empty sections are skipped.
+     * routes its stable base prompt through the orchestrator, and this method
+     * appends the tool surface notice. The linked-plan section is deliberately
+     * empty here; linked-plan content is tool-retrieved on demand.
      */
     assembleContextV2(toolSurfaceNotice: string): AssembledContext;
     cachedToolDefinitions(): unknown[];