@hunterzhu/pulse-runtime 0.5.0 → 0.6.0

package/dist/context/builder.d.ts

@@ -1,6 +1,9 @@
 import type { AgentRecord, ArtifactRef, ConversationMessage, LaneRecord, LLMRequestProjection, PrivacyLabel, PrivacyTaint, ResultRef, RuntimeState, JsonValue, ContextDelta } from '../core/types.js';
 export interface ContextBuildInput {
     explicitContext?: boolean;
+    /** Include this lane's append-only history without implicitly exposing Global/Lane state. */
+    includeLaneHistory?: boolean;
+    historySeqs?: readonly number[];
     agent: AgentRecord;
     lane: LaneRecord;
     resultRefs?: ResultRef[];

package/dist/context/builder.js

@@ -32,6 +32,13 @@ function projectResultValue(result) {
         originalBytes,
     };
 }
+function visibleModelOutput(value) {
+    if (Array.isArray(value))
+        return value.map(visibleModelOutput);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).filter(([key]) => !['providerContinuation', 'reasoningContent', 'reasoning_content'].includes(key)).map(([key, item]) => [key, visibleModelOutput(item)]));
+    return value;
+}
 function buildProviderHistory(state, history, visible) {
     if (!history.length)
         return undefined;
@@ -110,7 +117,9 @@ export class ContextBuilder {
         const global = input.agent.globalVersions.get(input.lane.contextSnapshotVersion);
         if (global === undefined)
             throw new Error('UNKNOWN_CONTEXT_VERSION');
-        const resultRefs = input.resultRefs ?? [];
+        const history = (input.includeLaneHistory || !input.explicitContext ? input.lane.context.history : []).filter(record => input.historySeqs === undefined || input.historySeqs.includes(record.seq));
+        const historyRefs = input.includeLaneHistory ? [...new Set(history.flatMap(r => r.resultRefs))].filter(ref => this.state.results.has(ref) && (input.lane.visibleResultRefs === undefined || input.lane.visibleResultRefs.has(ref))) : [];
+        const resultRefs = [...new Set([...(input.resultRefs ?? []), ...historyRefs])];
         const results = resultRefs.map((ref) => {
             const result = this.state.results.get(ref);
             if (!result)
@@ -119,7 +128,18 @@ export class ContextBuilder {
                 throw new Error(`RESULT_NOT_VISIBLE:${ref}`);
             return result;
         });
-        const artifactRefs = input.artifactRefs ?? [];
+        const imageRefs = [...(input.explicitContext ? [] : input.lane.context.history.flatMap(record => record.resultRefs).flatMap(ref => {
+                if (input.lane.visibleResultRefs && !input.lane.visibleResultRefs.has(ref))
+                    return [];
+                const result = this.state.results.get(ref);
+                return result ? [result] : [];
+            })), ...results].flatMap(result => {
+            const value = result.value;
+            const ref = value && typeof value === 'object' && !Array.isArray(value) ? value.artifactRef : undefined;
+            const artifact = typeof ref === 'string' ? this.state.artifacts.get(ref) : undefined;
+            return artifact && (artifact.mediaType === 'image/png' || artifact.mediaType === 'image/jpeg') ? [artifact.ref] : [];
+        });
+        const artifactRefs = [...new Set([...(input.artifactRefs ?? []), ...[...new Set(imageRefs)].slice(-2)])];
         const artifacts = artifactRefs.map((ref) => {
             const artifact = this.state.artifacts.get(ref);
             if (!artifact)
@@ -146,23 +166,42 @@ export class ContextBuilder {
             ...effectiveArtifacts.flatMap((item) => (item.artifact.privacyTaints ?? []).map((taint) => ({ path: [item.artifact.ref, ...taint.path], privacy: taint.privacy }))),
         ];
         const conversation = input.conversation ?? [];
-        const providerHistory = input.explicitContext ? undefined : buildProviderHistory(this.state, input.lane.context.history, input.lane.visibleResultRefs);
+        const providerHistory = input.explicitContext ? undefined : buildProviderHistory(this.state, history, input.lane.visibleResultRefs);
+        const emitted = new Set();
+        const historyResult = (ref) => {
+            const result = this.state.results.get(ref);
+            const effectId = result.effectId ?? (result.producer?.kind === 'effect' ? result.producer.id : undefined);
+            return effectId && this.state.effects.get(effectId)?.kind === 'llm'
+                ? projectResultValue({ value: visibleModelOutput(result.value ?? null), ...(result.summary === undefined ? {} : { summary: visibleModelOutput(result.summary) }) }) : projectResultValue(result);
+        };
+        const historyBlock = { kind: 'history', content: history.map(record => {
+                const output = record.output && typeof record.output === 'object' && !Array.isArray(record.output) ? record.output : undefined;
+                return { seq: record.seq, ...(record.effectId === undefined ? {} : { effectId: record.effectId }), instruction: record.instruction, resultRefs: record.resultRefs,
+                    ...(record.resultSelection === undefined ? {} : { resultSelection: record.resultSelection }), ...(record.result === undefined ? {} : { result: record.result }),
+                    ...(record.findings === undefined ? {} : { findings: record.findings }),
+                    output: input.includeLaneHistory && output ? visibleModelOutput(output) : record.output,
+                    ...(input.includeLaneHistory ? { evidence: record.resultRefs.filter(ref => historyRefs.includes(ref) && !emitted.has(ref) && !!emitted.add(ref)).map(ref => ({ ref, ...historyResult(ref) })) } : {}),
+                    privacy: record.privacy, ...(record.privacyTaints === undefined ? {} : { privacyTaints: record.privacyTaints }) };
+            }) };
         const contextSpec = { globalSnapshotVersion: input.lane.contextSnapshotVersion, laneSnapshotVersion: input.lane.context.version, resultRefs, ...(artifactRefs.length ? { artifactRefs } : {}), eventIds: input.eventIds ?? [], toolSetId: input.toolSetId, instruction: input.instruction, ...(conversation.length ? { conversation: structuredClone(conversation) } : {}), ...(providerHistory === undefined ? {} : { providerHistory }), privacy, privacyRefs, ...(privacyTaints.length ? { privacyTaints } : {}) };
         const prefixBlocks = [
             { kind: 'system', content: input.system ?? '' },
             { kind: 'policy', content: input.policy ?? {} },
             { kind: 'tools', content: input.tools ?? {} },
             { kind: 'global', content: input.explicitContext ? {} : global },
-            ...(conversation.length ? [{ kind: 'conversation', content: structuredClone(conversation) }] : []),
-            { kind: 'history', content: (input.explicitContext ? [] : input.lane.context.history).map((record) => ({ seq: record.seq, ...(record.effectId === undefined ? {} : { effectId: record.effectId }), instruction: record.instruction, resultRefs: record.resultRefs, ...(record.resultSelection === undefined ? {} : { resultSelection: record.resultSelection }), ...(record.result === undefined ? {} : { result: record.result }), ...(record.findings === undefined ? {} : { findings: record.findings }), output: record.output, privacy: record.privacy, ...(record.privacyTaints === undefined ? {} : { privacyTaints: record.privacyTaints }) })) },
+            ...(!input.includeLaneHistory && conversation.length ? [{ kind: 'conversation', content: structuredClone(conversation) }] : []),
+            historyBlock,
         ];
         const correlatedRefs = new Set((providerHistory ?? []).flatMap((message) => message.role === 'tool' ? [message.resultRef] : []));
-        const remainingResults = results.filter((result) => !correlatedRefs.has(result.id));
-        const blocks = [...prefixBlocks, ...(providerHistory === undefined ? [] : [{ kind: 'provider_history', content: providerHistory }]), { kind: 'lane', content: input.explicitContext ? {} : input.lane.context.state }, { kind: 'events', content: input.eventIds ?? [] }, { kind: 'results', content: remainingResults.map((result) => {
+        const remainingResults = results.filter((result) => !correlatedRefs.has(result.id) && (!emitted.has(result.id) || input.resultRefs?.includes(result.id)));
+        const blocks = [...prefixBlocks, ...(input.includeLaneHistory && conversation.length ? [{ kind: 'conversation', content: structuredClone(conversation) }] : []), ...(providerHistory === undefined ? [] : [{ kind: 'provider_history', content: providerHistory }]), { kind: 'lane', content: input.explicitContext ? {} : input.lane.context.state }, { kind: 'events', content: input.eventIds ?? [] }, { kind: 'results', content: remainingResults.map((result) => {
+                    if (emitted.has(result.id))
+                        return { id: result.id, fromHistory: true };
                     const projected = projectResultValue(result);
                     return { id: result.id, value: projected.value, ...(projected.summarized ? { summarized: true, ...(projected.originalBytes === undefined ? {} : { originalBytes: projected.originalBytes }) } : {}), ...(result.privacyTaints === undefined ? {} : { privacyTaints: result.privacyTaints.map((taint) => ({ path: [...taint.path], privacy: taint.privacy })) }) };
                 }) }, { kind: 'artifacts', content: artifacts.map((artifact) => ({ ref: artifact.ref, mediaType: artifact.mediaType, sizeBytes: artifact.sizeBytes, contentHash: artifact.contentHash })) }, { kind: 'instruction', content: input.instruction }];
-        return { contextSpec, blocks, prefixHash: hash(prefixBlocks), projectionHash: hash(blocks), builderVersion: this.version, policyVersion: '1', toolSetVersion: input.toolSetId, privacy, privacyRefs, ...(privacyTaints.length ? { privacyTaints } : {}) };
+        const images = artifacts.filter(artifact => artifact.mediaType === 'image/png' || artifact.mediaType === 'image/jpeg').slice(-2).map(artifact => ({ ref: artifact.ref, mediaType: artifact.mediaType }));
+        return { contextSpec, blocks, ...(images.length ? { images } : {}), prefixHash: hash(prefixBlocks), projectionHash: hash(blocks), builderVersion: this.version, policyVersion: '1', toolSetVersion: input.toolSetId, privacy, privacyRefs, ...(privacyTaints.length ? { privacyTaints } : {}) };
     }
 }
 export function appendHistory(lane, record) {

package/dist/core/tool-image.d.ts

@@ -0,0 +1,9 @@
+import type { JsonValue } from './types.js';
+/** Extract an explicit tool image before JSON history/result summarization. */
+export declare function extractToolImage(value: JsonValue): {
+    value: JsonValue;
+    artifact?: {
+        mediaType: string;
+        content: Uint8Array;
+    };
+};

package/dist/core/tool-image.js

@@ -0,0 +1,13 @@
+/** Extract an explicit tool image before JSON history/result summarization. */
+export function extractToolImage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || !value.pulseImage)
+        return { value };
+    const image = value.pulseImage;
+    if (typeof image !== 'object' || Array.isArray(image) || !['image/png', 'image/jpeg'].includes(String(image.mediaType)) || typeof image.data !== 'string' || image.data.length > 4 * 1024 * 1024 || !/^[A-Za-z0-9+/]*={0,2}$/.test(image.data))
+        throw new Error('INVALID_TOOL_IMAGE');
+    const bytes = Buffer.from(image.data, 'base64');
+    if (bytes.length < 16 || (image.mediaType === 'image/png' ? bytes.readUInt32BE(0) !== 0x89504e47 : bytes.readUInt16BE(0) !== 0xffd8))
+        throw new Error('INVALID_TOOL_IMAGE');
+    const { pulseImage: _image, ...metadata } = value;
+    return { value: metadata, artifact: { mediaType: image.mediaType, content: bytes } };
+}

package/dist/core/types.d.ts

@@ -205,6 +205,8 @@ export interface EffectRecord {
     locks?: ResourceLockSpec[];
 }
 export interface AttemptRecord {
+    /** Actual provider requests admitted by the Host, including transport retries. */
+    providerAttempts?: number;
     id: string;
     effectId: EffectId;
     modelId?: string;
@@ -491,6 +493,8 @@ export interface MergeProposal {
 }
 export interface LaneStepOutput {
     contextDelta?: ContextDelta;
+    /** Optional lane update committed atomically alongside a global ContextDelta. */
+    laneContextDelta?: ContextDelta;
     adoptCommittedContext?: boolean;
     actions: RuntimeAction[];
     next: ResumePoint;
@@ -535,6 +539,12 @@ export type ProviderHistoryMessage = {
     resultRef: ResultRef;
 };
 export interface LLMRequestProjection {
+    /** Resolved, visible image artifacts. Never serialize these into text history. */
+    images?: Array<{
+        ref: ArtifactRef;
+        mediaType: 'image/png' | 'image/jpeg';
+        data?: string;
+    }>;
     contextSpec: LLMContextSpec;
     blocks: Array<{
         kind: 'system' | 'policy' | 'tools' | 'global' | 'conversation' | 'history' | 'provider_history' | 'lane' | 'events' | 'results' | 'artifacts' | 'instruction';

package/dist/dsl/evidence-reuse.d.ts

@@ -0,0 +1,11 @@
+import type { JsonValue } from '../core/types.js';
+import type { StepContext } from './program.js';
+export interface ProposedEvidenceCall {
+    toolName: string;
+    input: JsonValue;
+}
+/** Pure proposal filter. Host freshness checks remain mandatory at verification. */
+export declare function reusableEvidence(ctx: Pick<StepContext, 'results'>, calls: ProposedEvidenceCall[], refs: string[]): {
+    refs: string[];
+    checksOnly: boolean;
+} | undefined;

package/dist/dsl/evidence-reuse.js

@@ -0,0 +1,50 @@
+const row = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+/** Pure proposal filter. Host freshness checks remain mandatory at verification. */
+export function reusableEvidence(ctx, calls, refs) {
+    if (!calls.length || calls.some(c => !['fs.read', 'shell.exec'].includes(c.toolName)))
+        return undefined;
+    const ordered = [...new Set(refs)].sort((a, b) => Number(a.match(/\d+$/)?.[0] ?? 0) - Number(b.match(/\d+$/)?.[0] ?? 0));
+    const latestAnswer = [...ordered].reverse().find(ref => ctx.results.meta(ref)?.effectKind === 'human');
+    const versions = new Map();
+    for (const ref of ordered) {
+        const meta = ctx.results.meta(ref), v = row(ctx.results.read(ref)), args = row(meta?.toolArguments);
+        if (!meta?.toolName?.startsWith('fs.'))
+            continue;
+        if (meta.toolName === 'fs.stage' && v.committed !== true)
+            continue;
+        const path = v.path ?? v.target ?? args.path;
+        if (typeof path === 'string' && ['fs.read', 'fs.write', 'fs.apply_patch', 'fs.apply_patches', 'fs.stage'].includes(meta.toolName))
+            versions.set(path, typeof v.hash === 'string' ? v.hash : undefined);
+    }
+    const matched = [];
+    for (const call of calls) {
+        const input = row(call.input);
+        const newestCheck = call.toolName === 'shell.exec' ? [...ordered].reverse().find(ref => {
+            const meta = ctx.results.meta(ref), args = row(meta?.toolArguments);
+            return meta?.toolName === call.toolName && args.command === input.command && JSON.stringify(args.args ?? []) === JSON.stringify(input.args ?? []) && (args.cwd ?? '.') === (input.cwd ?? '.');
+        }) : undefined;
+        const ref = [...ordered].reverse().find(ref => {
+            const meta = ctx.results.meta(ref), v = row(ctx.results.read(ref)), args = row(meta?.toolArguments);
+            if (meta?.toolName !== call.toolName || meta.outcomeStatus !== 'succeeded')
+                return false;
+            if (latestAnswer && ordered.indexOf(ref) < ordered.indexOf(latestAnswer))
+                return false;
+            if (call.toolName === 'fs.read')
+                return typeof v.hash === 'string' && v.path === input.path && (v.offset ?? 0) === (input.offset ?? 0) && versions.get(v.path) === v.hash;
+            if (ref !== newestCheck)
+                return false; // A later failure cannot fall back to an old pass.
+            const receipt = row(v.checkReceipt);
+            if (v.code !== 0 || v.timedOut || v.aborted || v.truncated || receipt.stable !== true || receipt.definitionChanged !== false)
+                return false;
+            if (args.command !== input.command || JSON.stringify(args.args ?? []) !== JSON.stringify(input.args ?? []) || (args.cwd ?? '.') !== (input.cwd ?? '.'))
+                return false;
+            if (!receipt.files || !Object.keys(receipt.files).length)
+                return false;
+            return Object.entries(receipt.files).every(([path, hash]) => !versions.has(path) || versions.get(path) === hash);
+        });
+        if (!ref)
+            return undefined;
+        matched.push(ref);
+    }
+    return { refs: [...new Set(matched)], checksOnly: calls.every(c => c.toolName === 'shell.exec') };
+}

package/dist/dsl/index.d.ts

@@ -2,3 +2,4 @@ export * from './program.js';
 export * from './templates.js';
 export * from './session.js';
 export * from './context-proxy.js';
+export { isUnreadFileWindow, isReadProgress } from './read-continuation.js';

package/dist/dsl/index.js

@@ -2,3 +2,4 @@ export * from './program.js';
 export * from './templates.js';
 export * from './session.js';
 export * from './context-proxy.js';
+export { isUnreadFileWindow, isReadProgress } from './read-continuation.js';

package/dist/dsl/patch-recovery.d.ts

@@ -0,0 +1,33 @@
+import type { JsonValue } from '../core/types.js';
+import type { StepContext } from './program.js';
+export interface PatchRecovery {
+    path: string;
+    workspaceRoot?: string;
+    currentHash: string;
+    reason: string;
+    attempts: number;
+    corrected: boolean;
+    afterRef: number;
+    findHashes: string[];
+    missingFindHashes: string[];
+    readPending: boolean;
+    suggestedRead: {
+        path: string;
+        offset: number;
+        maxBytes: number;
+    };
+}
+export declare function readPatchRecoveries(value: unknown): PatchRecovery[];
+export declare function rememberPatchFailures(prior: PatchRecovery[], failures: Array<{
+    code: string;
+    details?: JsonValue | undefined;
+}>, afterRef: number): PatchRecovery[];
+export declare function refreshPatchRecoveries(ctx: Pick<StepContext, 'results'>, records: PatchRecovery[], refs: string[]): PatchRecovery[];
+export declare function isPatchRecoveryRead(call: {
+    toolName: JsonValue;
+    input: JsonValue;
+}, records: PatchRecovery[]): boolean;
+export declare function stalePatchRecord(call: {
+    toolName: string;
+    input: JsonValue;
+}, records: PatchRecovery[]): PatchRecovery | undefined;

package/dist/dsl/patch-recovery.js

@@ -0,0 +1,51 @@
+import { normalize, relative, resolve, isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+const fragmentHash = (text) => createHash('sha256').update(text).digest('hex');
+const row = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+const hash = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const order = (ref) => Number(ref.match(/\d+$/)?.[0] ?? 0);
+const pathMatches = (record, path) => typeof path === 'string' && (record.workspaceRoot ? relative(record.workspaceRoot, resolve(record.workspaceRoot, path)) : normalize(path)).replaceAll('\\', '/') === normalize(record.path).replaceAll('\\', '/');
+export function readPatchRecoveries(value) {
+    return structuredClone(Array.isArray(value) ? value.filter(v => typeof v?.path === 'string' && hash(v?.currentHash) && Array.isArray(v?.findHashes) && v.findHashes.length <= 64 && v.findHashes.every(hash) && Array.isArray(v?.missingFindHashes) && v.missingFindHashes.every((h) => v.findHashes.includes(h)) && typeof v.corrected === 'boolean' && typeof v.readPending === 'boolean' && (v.workspaceRoot === undefined || typeof v.workspaceRoot === 'string' && isAbsolute(v.workspaceRoot)) && Number.isSafeInteger(v?.attempts) && Number.isSafeInteger(v?.afterRef) && v?.suggestedRead?.path === v.path && Number.isSafeInteger(v?.suggestedRead?.offset) && v.suggestedRead.offset >= 0 && Number.isSafeInteger(v.suggestedRead.maxBytes) && v.suggestedRead.maxBytes > 0 && v.suggestedRead.maxBytes <= 3000).slice(-8) : []);
+}
+export function rememberPatchFailures(prior, failures, afterRef) {
+    const result = structuredClone(prior);
+    for (const failure of failures) {
+        const d = row(failure.details), read = row(d.suggestedRead);
+        if (!['FILE_BASELINE_CONFLICT', 'PATCH_CONTEXT_NOT_FOUND', 'PATCH_CONTEXT_AMBIGUOUS', 'PATCH_RANGES_OVERLAP'].includes(failure.code) || d.kind !== 'patch-conflict' || !['fs.apply_patch', 'fs.apply_patches'].includes(d.toolName) || typeof d.path !== 'string' || !hash(d.currentHash) || !Array.isArray(d.findHashes) || !d.findHashes.length || d.findHashes.length > 16 || !d.findHashes.every(hash) || !Array.isArray(d.missingFindHashes) || !d.missingFindHashes.every(h => d.findHashes.includes(h)) || read.path !== d.path || !Number.isSafeInteger(read.offset) || read.offset < 0 || !Number.isSafeInteger(read.maxBytes) || read.maxBytes < 1 || read.maxBytes > 3000)
+            continue;
+        const previous = result.find(r => r.path === d.path && r.currentHash === d.currentHash);
+        const next = { path: d.path, ...(typeof d.workspaceRoot === 'string' && isAbsolute(d.workspaceRoot) ? { workspaceRoot: d.workspaceRoot } : previous?.workspaceRoot ? { workspaceRoot: previous.workspaceRoot } : {}), currentHash: d.currentHash, reason: failure.code, attempts: (previous?.attempts ?? 0) + 1, corrected: previous?.corrected ?? false, afterRef,
+            findHashes: [...new Set([...(previous?.findHashes ?? []), ...d.findHashes])].slice(-64), missingFindHashes: [...new Set([...(previous?.missingFindHashes ?? []), ...d.missingFindHashes])].slice(-64), readPending: true, suggestedRead: { path: read.path, offset: read.offset, maxBytes: read.maxBytes } };
+        const index = result.findIndex(r => r.path === d.path);
+        if (index >= 0)
+            result.splice(index, 1);
+        result.push(next);
+    }
+    return result.slice(-8);
+}
+export function refreshPatchRecoveries(ctx, records, refs) {
+    return records.flatMap(record => {
+        const newest = [...new Set(refs)].sort((a, b) => order(b) - order(a)).find(ref => {
+            const meta = ctx.results.meta(ref), body = row(ctx.results.read(ref)), args = row(meta?.toolArguments);
+            return order(ref) > record.afterRef && meta?.outcomeStatus === 'succeeded' && ['fs.read', 'fs.write', 'fs.apply_patch', 'fs.apply_patches', 'fs.stage'].includes(meta.toolName ?? '') && pathMatches(record, body.path ?? body.target ?? args.path) && hash(body.hash) && (meta.toolName !== 'fs.stage' || body.committed === true);
+        });
+        if (!newest)
+            return [record];
+        const body = row(ctx.results.read(newest)), meta = ctx.results.meta(newest);
+        if (body.hash !== record.currentHash)
+            return [];
+        return [{ ...record, afterRef: order(newest), readPending: meta?.toolName === 'fs.read' ? false : record.readPending }];
+    });
+}
+export function isPatchRecoveryRead(call, records) {
+    const a = row(call.input);
+    return call.toolName === 'fs.read' && a.startLine === undefined && records.some(r => r.readPending && pathMatches(r, a.path) && (a.offset ?? 0) === r.suggestedRead.offset && Math.min(a.maxBytes ?? 3000, 3000) === r.suggestedRead.maxBytes);
+}
+export function stalePatchRecord(call, records) {
+    if (!['fs.apply_patch', 'fs.apply_patches'].includes(call.toolName))
+        return undefined;
+    const a = row(call.input), patches = call.toolName === 'fs.apply_patch' ? [a] : Array.isArray(a.patches) ? a.patches.map(row) : [];
+    const finds = patches.filter(p => typeof p.find === 'string').map(p => fragmentHash(p.find));
+    return records.find(r => pathMatches(r, a.path) && (finds.some(h => r.missingFindHashes.includes(h)) || a.expectedHash !== r.currentHash && finds.some(h => r.findHashes.includes(h))));
+}

package/dist/dsl/program.d.ts

@@ -63,6 +63,8 @@ export interface ResultMeta {
     outcomeStatus?: string;
     sideEffectPolicy?: 'none' | 'read' | 'write' | 'external';
     toolName?: string;
+    toolArguments?: JsonValue;
+    humanQuestion?: JsonValue;
     toolCommand?: string;
     toolExitCode?: number;
     ref: ResultRef;
@@ -92,6 +94,13 @@ export interface StepContext<TState = JsonValue> {
         summary(ref: ResultRef): JsonValue | undefined;
         read(ref: ResultRef): JsonValue | undefined;
     };
+    /** Evidence of a settled direct child, even when it produced no completion result. */
+    settledLaneEvidence(laneId: LaneId): {
+        evidenceRefs: ResultRef[];
+        modelEffectIds: string[];
+        modelCalls: number;
+        laneState?: JsonValue;
+    } | undefined;
     mergeProposals: ReadonlyArray<MergeProposal>;
     mutateLane(mutator: (draft: TState) => void): void;
     proposeGlobal(delta: {
@@ -155,6 +164,17 @@ interface AffinityAdviceGroup {
     keys: string[];
     signals: string[];
 }
+/** Keep assertions verbatim; strip only timing syntax from recognized test reporters. */
+export declare function stableCheckOutput(text: string): string;
+/** Timing metadata is not new evidence; preserve the command's actual output and exit code. */
+export declare function toolEvidenceHash(meta: Pick<ResultMeta, 'toolName' | 'toolArguments'> | undefined, value: JsonValue): string;
+/** Stable identity includes the actual decision, never the prompt alone. */
+export declare function interactionIdentity(tool: string, input: JsonValue): {
+    exact: string;
+    semantic?: string;
+};
+/** The model-facing surface is bounded; full answers stay in durable results. */
+export declare function confirmedInteractionSurface(answers: JsonValue[], scopes?: string[]): JsonValue;
 /** A stop response that still contains tool-call markup was not executed. */
 export declare function looksLikeUnexecutedToolRequest(text: string): boolean;
 /** Models often wrap the real arguments, put a path in title, or pack a shell command line into one string. */
@@ -165,6 +185,7 @@ export declare class StepBuilder<TState = JsonValue> {
         version: string;
         system?: string;
         explicitContext?: boolean;
+        includeLaneHistory?: boolean;
         toolSet?: string;
         state?: z.ZodType<TState>;
         historyCompaction?: HistoryCompactionOptions;
@@ -183,6 +204,7 @@ export declare class StepBuilder<TState = JsonValue> {
         version: string;
         system?: string;
         explicitContext?: boolean;
+        includeLaneHistory?: boolean;
         toolSet?: string;
         state?: z.ZodType<TState>;
         historyCompaction?: HistoryCompactionOptions;
@@ -221,10 +243,15 @@ export declare class StepBuilder<TState = JsonValue> {
         maxTurns?: number;
         maxTruncationRetries?: number;
         maxToolsPerTurn?: number;
+        maxReadOnlyRounds?: number | ((ctx: StepContext<TState>) => number | undefined);
         serialTools?: string[];
         stopAfterFirstSerialTool?: boolean;
         blockReadOnlyTools?: (ctx: StepContext<TState>) => boolean;
+        preserveReadContinuations?: boolean;
         scopeToolCallsToEffect?: boolean;
+        reuseSettledEvidence?: boolean;
+        onEvidenceReused?: (refs: ResultRef[], ctx: StepContext<TState>) => void;
+        onReuseEvidence?: (refs: ResultRef[], ctx: StepContext<TState>) => NextStepTarget<TState>;
         resetTurnsOnEntry?: (ctx: StepContext<TState>) => string | number | undefined;
         outputSchema?: ZodTypeAny;
         requirements?: Record<string, JsonValue>;
@@ -240,6 +267,8 @@ export declare class StepBuilder<TState = JsonValue> {
             };
         };
         onMaxTurns?: (ctx: StepContext<TState>) => NextStepTarget<TState>;
+        prepareQuestion?: (toolName: string, input: JsonValue, ctx: StepContext<TState>) => JsonValue;
+        onHumanReply?: (question: JsonValue, answer: JsonValue, ctx: StepContext<TState>) => NextStepTarget<TState> | undefined;
         onError?: (error: RuntimeError, ctx: StepContext<TState>) => NextStepTarget<TState>;
     }): this;
     addParallelStep(name: string, options: {
@@ -335,6 +364,7 @@ export declare function defineLaneProgram<TState = JsonValue>(config: {
     version: string;
     system?: string;
     explicitContext?: boolean;
+    includeLaneHistory?: boolean;
     toolSet?: string;
     state?: z.ZodType<TState>;
     historyCompaction?: HistoryCompactionOptions;