newmark-agent 0.6.2 → 0.6.4

package/dist/core/agent.d.ts

@@ -85,6 +85,8 @@ export interface CompressionCacheEntry {
     foldedChars: number;
     model: string;
     fallback: boolean;
+    /** Branch node that owns this folded history. Sibling pages must never read it. */
+    branchNodeId?: string;
 }
 type ConversationModelSelection = {
     kind: 'auto';
@@ -294,8 +296,15 @@ export interface ConversationBranchGroupSnapshot {
 export interface ConversationContinuation {
     content: string;
     queueMode: 'steer' | 'followUp';
+    buildId?: string;
     clientMessageId?: string;
     runId?: string;
+    branchNodeId?: string;
+    branchPath?: string[];
+    ledgerBranchId?: string;
+    targetRuntimeKey?: string;
+    workspaceKey?: string;
+    modelSelection?: string;
     images?: Array<{
         dataUrl: string;
         name?: string;
@@ -521,6 +530,16 @@ export declare class Agent {
     activeModelName(): string;
     modelSelectionValue(): string;
     currentWorkRunId(): string;
+    /**
+     * The branch node that owns the currently active Build. Provider session ids
+     * and branch-scoped caches must use this identity instead of "the branch that
+     * happens to be active", otherwise a concurrently running sibling branch
+     * (branch-communication mode) or a page switched mid-Build would read another
+     * branch's remote session and folded history.
+     */
+    activeWorkRunBranchId(): string;
+    /** Full conversation identity of one branch node (shared by every branch kind). */
+    branchConversationIdentity(branchNodeId: string): string;
     activeModelConfig(): ReturnType<ConfigManager['allModels']>[number] | undefined;
     requestedModelSelection(): ModelSelection;
     resetAutoRoute(): void;
@@ -787,6 +806,13 @@ export declare class Agent {
      */
     private deriveConversationTitleFromProvider;
     private conversationTitleFailureCause;
+    /**
+     * Deterministic provider rejections (bad key, forbidden endpoint, unknown
+     * model, invalid request, payment required) cannot succeed by retrying the
+     * identical title probe. Only transient transport, timeout, rate-limit and
+     * provider-internal failures enter the bounded 5-stage backoff.
+     */
+    private conversationTitleFailureIsRetryable;
     private waitForConversationTitleRetry;
     /** Legacy completion hook retained as a no-op; naming is pre-response only. */
     private maybeAutoRenameConversationFromRun;
@@ -1215,6 +1241,17 @@ export declare class Agent {
     private formatCompressionSummary;
     private persistCompressedHistory;
     private compressionArchiveScopeKey;
+    /**
+     * The hot folded-history cache belongs to one branch node. Legacy entries
+     * (created before branch scoping) belong to the root node, which is where
+     * they were produced.
+     */
+    private compressionCacheForBranch;
+    /**
+     * Persist the union of every branch's folded history: the live in-memory
+     * cache only holds the active branch, and the stored entry holds the rest.
+     */
+    private mergedCompressionCacheForPersist;
     private coldCompressionEntries;
     private compressionArchiveEntryCount;
     private archiveColdCompressionEntries;

package/dist/core/agent.js

@@ -58,6 +58,7 @@ const skills_1 = require("./skills");
 const flow_1 = require("./flow");
 const memoryLab_1 = require("./memoryLab");
 const agentKernelRunner_1 = require("./agentKernelRunner");
+const branchIdentity_1 = require("./branchIdentity");
 const toolPolicy_1 = require("./toolPolicy");
 const conversationTarget_1 = require("./conversationTarget");
 const utilityHostToolBridge_1 = require("./utilityHostToolBridge");
@@ -1020,6 +1021,22 @@ class Agent {
     currentWorkRunId() {
         return this.activeWorkRunId || this.finalizingWorkRunId || '';
     }
+    /**
+     * The branch node that owns the currently active Build. Provider session ids
+     * and branch-scoped caches must use this identity instead of "the branch that
+     * happens to be active", otherwise a concurrently running sibling branch
+     * (branch-communication mode) or a page switched mid-Build would read another
+     * branch's remote session and folded history.
+     */
+    activeWorkRunBranchId() {
+        const runId = this.currentWorkRunId();
+        const run = runId ? this.workRuns.find(item => String(item.runId || '') === runId) : undefined;
+        return String(run?.branchNodeId || '') || this.currentBranchNodeId();
+    }
+    /** Full conversation identity of one branch node (shared by every branch kind). */
+    branchConversationIdentity(branchNodeId) {
+        return (0, branchIdentity_1.branchConversationIdentity)(this.activeConversationId || 'default', branchNodeId);
+    }
     activeModelConfig() {
         const deployment = this.activeDeployment();
         return deployment ? this.config.findDeployment(deployment) : this.config.findModel(this.model);
@@ -2735,8 +2752,15 @@ class Agent {
             deduped.set(key, {
                 content,
                 queueMode,
+                buildId: String(raw.buildId || '').trim() || undefined,
                 clientMessageId,
                 runId: String(raw.runId || '').trim() || undefined,
+                branchNodeId: String(raw.branchNodeId || '').trim() || undefined,
+                branchPath: Array.isArray(raw.branchPath) ? raw.branchPath.map(id => String(id || '')).filter(Boolean) : undefined,
+                ledgerBranchId: String(raw.ledgerBranchId || '').trim() || undefined,
+                targetRuntimeKey: String(raw.targetRuntimeKey || '').trim() || undefined,
+                workspaceKey: String(raw.workspaceKey || '').trim() || undefined,
+                modelSelection: String(raw.modelSelection || '').trim() || undefined,
                 images: images.length ? images : undefined,
                 attachments: attachments.length ? attachments : undefined,
                 hiddenUserInput: raw.hiddenUserInput === true,
@@ -3608,6 +3632,10 @@ class Agent {
                 && ((targetGuideNodeId && group.pageGuideIds?.[parentNodeId] === targetGuideNodeId)
                     || (!targetGuideNodeId && targetMessageId && group.pageMessageIds?.[parentNodeId] === targetMessageId))));
         const branchId = crypto.randomUUID();
+        // dev-0.6.4: 新分支（用户分页编辑与实验性分支交流共用这一事务）必须拿到
+        // 全新的全对话 id。复用节点 id 会让两个分支共享 provider 会话序列、
+        // 压缩历史与本地缓存，正是「跨分支缓存」必须禁止的情形。
+        (0, branchIdentity_1.assertFreshBranchIdentity)(clean || this.activeConversationId || 'default', branchId, Object.keys(tree.nodes));
         const branch = this.treeNodeFromEntry(branchId, parentNodeId, index, text, {
             ...entry,
             chatMessages: sourceNode.chatMessages.slice(0, index),
@@ -3950,6 +3978,19 @@ class Agent {
             return 'provider returned invalid JSON';
         return 'provider request failed';
     }
+    /**
+     * Deterministic provider rejections (bad key, forbidden endpoint, unknown
+     * model, invalid request, payment required) cannot succeed by retrying the
+     * identical title probe. Only transient transport, timeout, rate-limit and
+     * provider-internal failures enter the bounded 5-stage backoff.
+     */
+    conversationTitleFailureIsRetryable(error) {
+        const message = error instanceof Error ? error.message : '';
+        const status = message.match(/^\[LLM Error:\s*([1-5]\d{2})\]/)?.[1];
+        if (!status)
+            return true;
+        return status === '408' || status === '429' || status.startsWith('5');
+    }
     async waitForConversationTitleRetry(delayMs, signal) {
         if (signal?.aborted || delayMs <= 0)
             return;
@@ -3981,17 +4022,20 @@ class Agent {
         // Failure state belongs to this title attempt sequence, not the Agent or
         // another conversation. A later empty title replaces an earlier HTTP error.
         let lastFailure = 'provider returned an empty or unusable title';
+        let terminalFailure = false;
         const requestTitle = async () => {
             lastFailure = 'provider returned an empty or unusable title';
+            terminalFailure = false;
             try {
                 return await this.deriveConversationTitleFromProvider(firstUserInput, provider, modelName, intelligence, signal);
             }
             catch (error) {
                 lastFailure = this.conversationTitleFailureCause(error, provider);
+                terminalFailure = !this.conversationTitleFailureIsRetryable(error);
                 return '';
             }
         };
-        const exhaustedFailure = () => new Error(`Conversation title generation failed; ${lastFailure}. The first Agent request was not started. Retry the first input.`);
+        const exhaustedFailure = () => new Error(`Conversation title generation failed for ${provider.name}/${modelName}; ${lastFailure}. The first Agent request was not started. Retry the first input or switch the model.`);
         if (!stateKey) {
             // Pure Agent/CLI mode has no workspace conversation file to rename, but
             // still uses the title request as the required first model-availability
@@ -3999,6 +4043,8 @@ class Agent {
             for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
                 if (await requestTitle())
                     return true;
+                if (terminalFailure)
+                    break;
                 if (signal?.aborted)
                     return false;
                 if (attempt < maxAttempts - 1)
@@ -4036,6 +4082,8 @@ class Agent {
                 this.publishConversationTitle(title, conversationId);
                 return true;
             }
+            if (terminalFailure)
+                break;
             if (signal?.aborted)
                 return false;
             if (attempt < maxAttempts - 1)
@@ -4290,7 +4338,7 @@ class Agent {
             chatMessages: [...this.chatMessages],
             history: [...this.history],
             providerUsage: this.conversationProviderUsage(),
-            compressionCache: [...this.compressionCache],
+            compressionCache: this.mergedCompressionCacheForPersist(stored.conversations[stateKey]),
             branchMailbox: [...this.branchMailbox],
             branchCommunication: this.branchCommunicationEnabled,
             plan: this.normalizeConversationPlan(this.conversationPlan),
@@ -4350,7 +4398,7 @@ class Agent {
         if (saved) {
             this.restoreProviderUsage(saved.providerUsage);
             this.history = [...saved.history];
-            this.compressionCache = saved.compressionCache ? saved.compressionCache.map(entry => ({ ...entry, messages: [...entry.messages] })) : [];
+            this.compressionCache = this.compressionCacheForBranch(saved.compressionCache);
             this.nextCompressionCacheId = Math.max(1, ...this.compressionCache.map(entry => Number(entry.id.replace(/^ctx-cache-/, '')) || 0)) + 1;
             this.branchMailbox = (saved.branchMailbox || []).map(message => ({ ...message }));
             this.nextBranchMessageSequence = Math.max(1, ...this.branchMailbox.map(message => Number(message.sequence) || 0)) + 1;
@@ -4379,7 +4427,7 @@ class Agent {
         this.restoreProviderUsage(persisted?.providerUsage);
         const repairedHistory = this.repairDanglingToolCalls(persisted?.history ? [...persisted.history] : []);
         this.history = repairedHistory.messages;
-        this.compressionCache = persisted?.compressionCache ? persisted.compressionCache.map(entry => ({ ...entry, messages: [...entry.messages] })) : [];
+        this.compressionCache = this.compressionCacheForBranch(persisted?.compressionCache);
         this.nextCompressionCacheId = Math.max(1, ...this.compressionCache.map(entry => Number(entry.id.replace(/^ctx-cache-/, '')) || 0)) + 1;
         this.branchMailbox = (persisted?.branchMailbox || []).map(message => ({ ...message }));
         this.nextBranchMessageSequence = Math.max(1, ...this.branchMailbox.map(message => Number(message.sequence) || 0)) + 1;
@@ -6015,7 +6063,7 @@ class Agent {
         let requestContext = null;
         const context = saved?.version === 1 ? saved.requestContext : null;
         if (context && typeof context.requestId === 'string' && typeof context.runId === 'string' && typeof context.at === 'string') {
-            requestContext = { requestId: context.requestId, runId: context.runId, model: String(context.model || ''), at: context.at,
+            requestContext = { requestId: context.requestId, runId: context.runId, branchId: String(context.branchId || ''), contextHash: String(context.contextHash || ''), model: String(context.model || ''), at: context.at,
                 estimatedTokens: 0, longHistoryTokens: 0, buildBlockTokens: 0, systemPromptTokens: 0, toolSchemaTokens: 0, messageCount: 0, hasImages: context.hasImages === true };
             for (const key of ['estimatedTokens', 'longHistoryTokens', 'buildBlockTokens', 'systemPromptTokens', 'toolSchemaTokens', 'messageCount', 'inputTokens', 'cacheReadTokens']) {
                 const value = context[key];
@@ -6083,9 +6131,16 @@ class Agent {
         return request;
     }
     recordRequestContext(request, messages, system, tools, model) {
+        const contextHash = crypto.createHash('sha256').update(JSON.stringify({
+            model,
+            system,
+            tools,
+            messages,
+        })).digest('hex').slice(0, 24);
         const context = {
             ...(0, requestContextEstimate_1.estimateSubmittedContext)(messages, system, tools, this.compressionBuildBlockStart(messages)),
-            requestId: request.id, runId: this.currentWorkRunId(), model, at: new Date().toISOString(),
+            requestId: request.id, runId: this.currentWorkRunId(), branchId: this.currentBranchNodeId(),
+            contextHash, model, at: new Date().toISOString(),
         };
         this.mutateRequestUsage(request, usage => { usage.requestContext = context; });
     }
@@ -8187,6 +8242,13 @@ class Agent {
                 if (!titleProvider || !titleModelName) {
                     throw new Error('Conversation title generation failed; no resolved model deployment is available. No LLM configured. Add provider in Settings > Models.');
                 }
+                // The title probe is a hard gate before the first formal request. Show
+                // the exact deployment being checked immediately so a slow or failing
+                // first turn never looks like an unexplained freeze.
+                this.emitWorkEvent({
+                    type: 'status',
+                    content: `Preparing the first response: checking ${titleProvider.name}/${titleModelName} and generating the conversation title.`,
+                });
                 const titled = await this.startFirstInputConversationTitle(firstResponseTitleInput.messageId, firstResponseTitleInput.input, titleProvider, titleModelName, titleIntelligence, processSignal);
                 if (!titled)
                     throw new Error('Conversation title generation failed; the first Agent request was not started. Retry the first input.');
@@ -9754,7 +9816,41 @@ class Agent {
     compressionArchiveScopeKey() {
         if (this.isSubagentRuntime || !this.config.getBool('context', 'compression_archive_enabled'))
             return null;
-        return this.workspaceConversationKey();
+        const base = this.workspaceConversationKey();
+        if (!base)
+            return null;
+        // dev-0.6.4: 折叠历史必须按分支节点隔离——用户分页产生的分支与实验性分支
+        // 交流产生的分支共用这一条身份规则，兄弟分支不得互相读取压缩归档。
+        return (0, branchIdentity_1.branchConversationIdentity)(base, this.currentBranchNodeId());
+    }
+    /**
+     * The hot folded-history cache belongs to one branch node. Legacy entries
+     * (created before branch scoping) belong to the root node, which is where
+     * they were produced.
+     */
+    compressionCacheForBranch(entries) {
+        const branch = String(this.currentBranchNodeId() || '');
+        const root = String(this.conversationTree()?.rootNodeId || '');
+        return (Array.isArray(entries) ? entries : []).flatMap(entry => {
+            const owner = String(entry.branchNodeId || root || '');
+            if (branch && owner && owner !== branch)
+                return [];
+            if (branch && !owner)
+                return [];
+            return [{ ...entry, branchNodeId: owner || branch || undefined, messages: [...entry.messages] }];
+        });
+    }
+    /**
+     * Persist the union of every branch's folded history: the live in-memory
+     * cache only holds the active branch, and the stored entry holds the rest.
+     */
+    mergedCompressionCacheForPersist(storedEntry) {
+        const branch = String(this.currentBranchNodeId() || '');
+        const others = (storedEntry?.compressionCache || []).filter(entry => {
+            const owner = String(entry.branchNodeId || '');
+            return !!owner && owner !== branch;
+        });
+        return [...others, ...this.compressionCache.map(entry => ({ ...entry, messages: [...entry.messages] }))];
     }
     coldCompressionEntries() {
         const scopeKey = this.compressionArchiveScopeKey();
@@ -9831,6 +9927,7 @@ class Agent {
             foldedChars,
             model,
             fallback,
+            branchNodeId: this.currentBranchNodeId() || undefined,
         });
         this.nextCompressionCacheId += 1;
         const maxEntries = Math.max(0, Math.floor(this.config.getNum('context', 'compression_cache_max') || 8));

package/dist/core/agentKernelRunner.js

@@ -39,6 +39,7 @@ exports.resetPublicAssistantDeltaFilter = resetPublicAssistantDeltaFilter;
 exports.runAgentKernel = runAgentKernel;
 exports.routeToolSurfaceV2 = routeToolSurfaceV2;
 exports.toolResultObjectiveOutcome = toolResultObjectiveOutcome;
+const branchIdentity_1 = require("./branchIdentity");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const terminalTakeover_1 = require("../tools/terminalTakeover");
@@ -69,6 +70,36 @@ const HIDDEN_LINE_PREFIXES = [
     'analysis:',
     'analysis：',
 ];
+/**
+ * Optional provider-side session cache identity. A remote session is mutable
+ * state, so it must never be shared by two branches of the same conversation:
+ * a fork that reuses the root conversation id can read the other branch's
+ * history. Keep the id stable within one branch (normal sequential turns still
+ * cache-hit) and change it the moment the runtime branch changes.
+ *
+ * dev-0.6.4: 分支身份固定在 Build 启动时创建的那条分支节点上（用户分页分支与
+ * 实验性分支交流分支共用同一规则）。这里绝不读取「当前正在查看/激活的分支」，
+ * 否则正在并行运行的兄弟分支或中途切换的页面会把请求绑到别的分支的远程会话。
+ */
+function providerSessionIdentity(agent) {
+    const conversationId = String(agent.activeConversationId || 'default');
+    let runBranchId = '';
+    try {
+        runBranchId = String(agent.activeWorkRunBranchId() || '');
+    }
+    catch {
+        runBranchId = '';
+    }
+    if (runBranchId)
+        return (0, branchIdentity_1.branchConversationIdentity)(conversationId, runBranchId);
+    try {
+        const snapshot = agent.getConversationSnapshot(conversationId);
+        return (0, branchIdentity_1.branchConversationIdentity)(conversationId, String(snapshot.runtimeBranchId || snapshot.activeBranchId || ''));
+    }
+    catch {
+        return conversationId;
+    }
+}
 function partialMarkerSuffix(value, marker) {
     const lower = value.toLowerCase();
     const target = marker.toLowerCase();
@@ -660,7 +691,11 @@ async function runAgentKernel(agent) {
                         currentAgent.checkpointPeerInput();
                         peerInputCheckpointed = true;
                     }
-                    const { temperature, maxTokens, reasoningEffort } = currentProvider.intelligenceConfig(currentAgent.intelligence);
+                    const { temperature, reasoningEffort } = currentProvider.intelligenceConfig(currentAgent.intelligence);
+                    // A normal Agent reply has no client-side output cap. The provider
+                    // endpoint owns its real limit; protocols that require a positive
+                    // max_tokens resolve one internally.
+                    const maxTokens = 0;
                     const newmarkMessages = fromKernelMessages(context.messages).map(message => message.role === 'assistant'
                         // Use the same public-content boundary on its first provider
                         // submission and after persistence. Trimming only the durable
@@ -697,7 +732,7 @@ async function runAgentKernel(agent) {
                         });
                     }
                     for await (const token of currentProvider.chatStreamWithTools(currentModelName, newmarkMessages, requestSystemPrompt, temperature, maxTokens, providerTools, options?.signal, reasoningEffort, currentAgent.config.getBool('context', 'provider_session_id')
-                        ? currentAgent.activeConversationId
+                        ? providerSessionIdentity(currentAgent)
                         : undefined)) {
                         if (!firstTokenRecorded && ((token.type === 'text' && token.text) || (token.type === 'tool_call' && token.toolCall))) {
                             firstTokenRecorded = true;

package/dist/core/branchIdentity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Branch conversation identity (dev-0.6.4).
+ *
+ * A conversation owns a tree of branch nodes. Every node is its own full
+ * conversation: the provider-side session sequence id, the folded-history
+ * archive and every local transcript cache are scoped by the node id, so
+ * sibling pages can never read each other's remote session or cached history.
+ *
+ * The user's pagination edits and the experimental branch-communication
+ * branches are created by the same `Agent.branchConversation` transaction, so
+ * both kinds of branch must share this single identity function. Never derive
+ * the identity from "the branch that happens to be active" at request time.
+ */
+export declare const BRANCH_IDENTITY_SEPARATOR = "::branch:";
+/** The full conversation id of one branch node: `<conversationId>::branch:<branchNodeId>`. */
+export declare function branchConversationIdentity(conversationId: string, branchNodeId: string): string;
+/** True when a value already carries a branch node identity. */
+export declare function isBranchConversationIdentity(value: string): boolean;
+/**
+ * Workspace-wide cache scope for one branch. Used by caches that must never be
+ * shared across sibling branches (compression history, provider payloads).
+ */
+export declare function branchCacheScopeKey(workspaceId: string, conversationId: string, branchNodeId: string): string;
+/**
+ * A branch may never reuse the identity of another node. Callers that mint a
+ * new page assert this before the node becomes reachable.
+ */
+export declare function assertFreshBranchIdentity(conversationId: string, branchNodeId: string, existing: Iterable<string>): void;
+//# sourceMappingURL=branchIdentity.d.ts.map

package/dist/core/branchIdentity.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Branch conversation identity (dev-0.6.4).
+ *
+ * A conversation owns a tree of branch nodes. Every node is its own full
+ * conversation: the provider-side session sequence id, the folded-history
+ * archive and every local transcript cache are scoped by the node id, so
+ * sibling pages can never read each other's remote session or cached history.
+ *
+ * The user's pagination edits and the experimental branch-communication
+ * branches are created by the same `Agent.branchConversation` transaction, so
+ * both kinds of branch must share this single identity function. Never derive
+ * the identity from "the branch that happens to be active" at request time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BRANCH_IDENTITY_SEPARATOR = void 0;
+exports.branchConversationIdentity = branchConversationIdentity;
+exports.isBranchConversationIdentity = isBranchConversationIdentity;
+exports.branchCacheScopeKey = branchCacheScopeKey;
+exports.assertFreshBranchIdentity = assertFreshBranchIdentity;
+exports.BRANCH_IDENTITY_SEPARATOR = '::branch:';
+/** The full conversation id of one branch node: `<conversationId>::branch:<branchNodeId>`. */
+function branchConversationIdentity(conversationId, branchNodeId) {
+    const conversation = String(conversationId || '').trim() || 'default';
+    const branch = String(branchNodeId || '').trim();
+    return branch ? `${conversation}${exports.BRANCH_IDENTITY_SEPARATOR}${branch}` : conversation;
+}
+/** True when a value already carries a branch node identity. */
+function isBranchConversationIdentity(value) {
+    return String(value || '').includes(exports.BRANCH_IDENTITY_SEPARATOR);
+}
+/**
+ * Workspace-wide cache scope for one branch. Used by caches that must never be
+ * shared across sibling branches (compression history, provider payloads).
+ */
+function branchCacheScopeKey(workspaceId, conversationId, branchNodeId) {
+    const workspace = String(workspaceId || '').trim() || 'none';
+    return `${workspace}::${branchConversationIdentity(conversationId, branchNodeId)}`;
+}
+/**
+ * A branch may never reuse the identity of another node. Callers that mint a
+ * new page assert this before the node becomes reachable.
+ */
+function assertFreshBranchIdentity(conversationId, branchNodeId, existing) {
+    const branch = String(branchNodeId || '').trim();
+    if (!branch)
+        throw new Error('Branch conversation identity requires a branch node id.');
+    for (const known of existing) {
+        if (String(known || '') === branch) {
+            throw new Error(`Branch conversation identity ${branchConversationIdentity(conversationId, branch)} is already in use.`);
+        }
+    }
+}
+//# sourceMappingURL=branchIdentity.js.map

package/dist/core/continuation/contracts.d.ts

@@ -0,0 +1,197 @@
+/**
+ * continuation-v1 contracts.
+ *
+ * These are the runtime-checked boundaries shared by the PC GUI, the hosted
+ * mobile API and the isolated runtimes. A view may read a snapshot, but it can
+ * never supply the execution identity that a write is allowed to use.
+ */
+export type WorkspaceId = string;
+export type RootId = string;
+export type BranchId = string;
+export type BuildId = string;
+export type AttemptId = string;
+export type CommandId = string;
+export type SnapshotId = string;
+export declare const CONTINUATION_SCHEMA_VERSION: 1;
+export type BuildStatus = 'QUEUED' | 'RUNNING' | 'WAITING_TOOL' | 'WAITING_APPROVAL' | 'WAITING_SUBAGENT' | 'FINALIZING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
+export type AttemptStatus = 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'EXPIRED';
+export type ContinuationErrorCode = 'TARGET_REQUIRED' | 'ROUTE_MISMATCH' | 'QUEUE_REVISION_CONFLICT' | 'ANCHOR_NOT_IN_LINEAGE' | 'ANCHOR_NOT_COMMITTED' | 'IDEMPOTENCY_KEY_REUSE' | 'STALE_EXECUTION' | 'FINAL_ALREADY_COMMITTED' | 'BUILD_NOT_READY' | 'BRANCH_PAUSED' | 'EFFECT_UNCERTAIN' | 'UNKNOWN_BRANCH' | 'UNKNOWN_BUILD' | 'UNKNOWN_COMMAND';
+export declare class ContinuationError extends Error {
+    readonly code: ContinuationErrorCode;
+    readonly detail?: Record<string, unknown> | undefined;
+    constructor(code: ContinuationErrorCode, message: string, detail?: Record<string, unknown> | undefined);
+}
+export interface CommandTarget {
+    workspaceId: WorkspaceId;
+    expectedRootId: RootId;
+    branchId: BranchId;
+}
+export interface BuildInput {
+    text: string;
+    images?: Array<{
+        dataUrl: string;
+        name?: string;
+        type?: string;
+    }>;
+    attachments?: Array<{
+        id: string;
+        name: string;
+        mimeType: string;
+        dataUrl?: string;
+    }>;
+    requestedMode?: string;
+    goalObjective?: string;
+    /** Provider-qualified model frozen at command acceptance time. */
+    modelSelection?: string;
+    /** Branch node captured when the user submitted the command. */
+    branchNodeId?: string;
+    branchPath?: string[];
+}
+export interface EnqueueBuildCommand {
+    schemaVersion: typeof CONTINUATION_SCHEMA_VERSION;
+    type: 'ENQUEUE_BUILD';
+    commandId: CommandId;
+    actorId: string;
+    target: CommandTarget;
+    expectedTailBuildId: BuildId | null;
+    expectedQueueRevision: number;
+    input: BuildInput;
+    recipeSnapshotId: SnapshotId;
+    createdAt: string;
+}
+export interface CommandReceipt {
+    schemaVersion: typeof CONTINUATION_SCHEMA_VERSION;
+    commandId: CommandId;
+    requestHash: string;
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    buildId: BuildId;
+    parentBuildId: BuildId | null;
+    queueSequence: number;
+    queueRevision: number;
+    lifecycleRevision: number;
+    acceptedAt: string;
+    duplicate?: boolean;
+}
+export interface ExecutionScope {
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    buildId: BuildId;
+    attemptId: AttemptId;
+    fence: number;
+    parentBuildId: BuildId | null;
+    baseContextSnapshotId: SnapshotId;
+    environmentSnapshotId: SnapshotId;
+    workerCapability: string;
+}
+export interface BranchGuardSnapshot {
+    branchId: BranchId;
+    activeBuildId: BuildId | null;
+    activeAttemptId: AttemptId | null;
+    fence: number;
+    leaseUntil: number;
+    workerCapability: string;
+}
+export interface QueueSnapshot {
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    headBuildId: BuildId | null;
+    tailBuildId: BuildId | null;
+    queueRevision: number;
+    lifecycleRevision: number;
+    paused: boolean;
+    activeBuildId: BuildId | null;
+    guard: BranchGuardSnapshot;
+    builds: BuildRecord[];
+}
+export interface BuildRecord {
+    buildId: BuildId;
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    parentBuildId: BuildId | null;
+    inputHash: string;
+    input: BuildInput;
+    recipeSnapshotId: SnapshotId;
+    status: BuildStatus;
+    queueSequence: number;
+    createdAt: string;
+    updatedAt: string;
+    finalId?: string;
+    waitingReason?: string;
+}
+export interface AttemptRecord {
+    attemptId: AttemptId;
+    buildId: BuildId;
+    branchId: BranchId;
+    fence: number;
+    status: AttemptStatus;
+    leaseUntil: number;
+    workerCapability: string;
+    startedAt: string;
+    endedAt?: string;
+}
+export interface FinalRecord {
+    finalId: string;
+    buildId: BuildId;
+    branchId: BranchId;
+    finalHash: string;
+    stateSnapshotId: SnapshotId;
+    text: string;
+    committedAt: string;
+}
+export interface ContinuationEvent {
+    eventId: string;
+    cursor: number;
+    type: 'BuildAccepted' | 'AttemptStarted' | 'AttemptHeartbeat' | 'BuildCommitted' | 'BuildFailed' | 'BuildCancelled' | 'BranchForked' | 'BranchPaused' | 'BranchResumed' | 'BuildQueueRepaired' | 'StaleWriteRejected';
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    branchId: BranchId;
+    buildId: BuildId | null;
+    attemptId: AttemptId | null;
+    fence: number | null;
+    at: string;
+    payload?: Record<string, unknown>;
+}
+export interface LedgerFile {
+    version: typeof CONTINUATION_SCHEMA_VERSION;
+    workspaceId: WorkspaceId;
+    roots: Record<RootId, {
+        rootId: RootId;
+        workspaceId: WorkspaceId;
+        defaultBranchId: BranchId;
+        createdAt: string;
+    }>;
+    branches: Record<BranchId, BranchRecord>;
+    builds: Record<BuildId, BuildRecord>;
+    attempts: Record<AttemptId, AttemptRecord>;
+    guards: Record<BranchId, BranchGuardSnapshot>;
+    commands: Record<string, CommandReceipt>;
+    finals: Record<BuildId, FinalRecord>;
+    events: ContinuationEvent[];
+    nextEventCursor: number;
+    nextQueueSequence: number;
+}
+export interface BranchRecord {
+    branchId: BranchId;
+    workspaceId: WorkspaceId;
+    rootId: RootId;
+    parentAnchorBuildId: BuildId | null;
+    headBuildId: BuildId | null;
+    tailBuildId: BuildId | null;
+    queueRevision: number;
+    lifecycleRevision: number;
+    paused: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function stableJson(value: unknown): string;
+export declare function emptyLedger(workspaceId: WorkspaceId): LedgerFile;
+export declare function defaultGuard(branchId: BranchId): BranchGuardSnapshot;
+export declare function commandKey(actorId: string, commandId: CommandId): string;
+export declare function buildInputHash(input: BuildInput): string;
+export declare function requestHash(command: EnqueueBuildCommand): string;
+//# sourceMappingURL=contracts.d.ts.map