@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/runtime/channels/index.d.ts

@@ -1,7 +1,4 @@
 export type { ChannelDriver } from '../../types/channel.js';
 export { TextDriver, buildNodePrompt } from './TextDriver.js';
 export type { TextDriverConfig } from './TextDriver.js';
-export { VoiceDriver } from './VoiceDriver.js';
-export type { VoiceDriverConfig } from './VoiceDriver.js';
-export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/index.js

@@ -1,8 +1,2 @@
 export { TextDriver, buildNodePrompt } from './TextDriver.js';
-// PAUSED: the realtime VoiceDriver is not on the primary (text) path and is not
-// re-exported from the package's headline API. It stays here for the realtime
-// stack (`@kuralle-agents/realtime-audio`) via the `/runtime` subpath. Text is
-// the primary primitive; cascaded voice runs over text (see livekit-plugin).
-export { VoiceDriver } from './VoiceDriver.js';
-export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/inputBuffer.d.ts

@@ -7,3 +7,4 @@ export declare function consumePendingUserInput(session: Session): UserInputCont
 export declare function consumeAllPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function peekPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function hasPendingUserInput(session: Session): boolean;
+export declare function syncPendingUserInput(source: Session, target: Session): void;

package/dist/runtime/channels/inputBuffer.js

@@ -33,3 +33,12 @@ export function peekPendingUserInput(session) {
 export function hasPendingUserInput(session) {
     return queue(session).length > 0;
 }
+export function syncPendingUserInput(source, target) {
+    const pending = queue(source);
+    if (pending.length > 0) {
+        target.workingMemory[PENDING_INPUT_KEY] = [...pending];
+    }
+    else {
+        delete target.workingMemory[PENDING_INPUT_KEY];
+    }
+}

package/dist/runtime/channels/streaming/hostControlSpeak.js

@@ -72,7 +72,11 @@ export async function speakWithHostControl(args) {
     toolControl = getToolControl();
     if (toolControl) {
         if (spoken.text) {
-            ctx.emit({ type: 'text-cancel', id: turnId, reason: 'host-control' });
+            ctx.emit({
+                channel: 'client',
+                type: 'text-cancel',
+                payload: { id: turnId, reason: 'host-control' },
+            });
         }
         return { text: '', control: toolControl };
     }

package/dist/runtime/channels/streaming/speakGated.js

@@ -1,16 +1,16 @@
 import { randomUUID } from 'node:crypto';
 import { SentenceAggregator } from './SentenceAggregator.js';
 function emitMessage(ctx, id, text) {
-    ctx.emit({ type: 'text-start', id });
-    ctx.emit({ type: 'text-delta', id, delta: text });
-    ctx.emit({ type: 'text-end', id });
+    ctx.emit({ channel: 'client', type: 'text-start', payload: { id } });
+    ctx.emit({ channel: 'client', type: 'text-delta', payload: { id, delta: text } });
+    ctx.emit({ channel: 'client', type: 'text-end', payload: { id } });
 }
 async function emitBlockedSafeMessage(ctx, turnId, started, outcome) {
     if (started) {
         ctx.emit({
+            channel: 'client',
             type: 'text-cancel',
-            id: turnId,
-            reason: outcome.reason ?? 'blocked',
+            payload: { id: turnId, reason: outcome.reason ?? 'blocked' },
         });
     }
     const safeId = randomUUID();
@@ -32,7 +32,7 @@ export async function speakGated(args) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            ctx.emit({ type: 'error', error: message });
+            ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
             throw err instanceof Error ? err : new Error(message);
         }
         const decision = await runGate(full, true);
@@ -48,13 +48,17 @@ export async function speakGated(args) {
     let emitted = '';
     const openOnce = () => {
         if (!started) {
-            ctx.emit({ type: 'text-start', id: turnId });
+            ctx.emit({ channel: 'client', type: 'text-start', payload: { id: turnId } });
             started = true;
         }
     };
     const emitCleared = (chunk) => {
         openOnce();
-        ctx.emit({ type: 'text-delta', id: turnId, delta: chunk });
+        ctx.emit({
+            channel: 'client',
+            type: 'text-delta',
+            payload: { id: turnId, delta: chunk },
+        });
         emitted += chunk;
     };
     const gateSentence = async (sentence, final) => {
@@ -69,7 +73,11 @@ export async function speakGated(args) {
         for await (const { delta } of source) {
             if (mode === 'token') {
                 openOnce();
-                ctx.emit({ type: 'text-delta', id: turnId, delta });
+                ctx.emit({
+                    channel: 'client',
+                    type: 'text-delta',
+                    payload: { id: turnId, delta },
+                });
                 emitted += delta;
                 continue;
             }
@@ -88,15 +96,19 @@ export async function speakGated(args) {
             }
         }
         if (started) {
-            ctx.emit({ type: 'text-end', id: turnId });
+            ctx.emit({ channel: 'client', type: 'text-end', payload: { id: turnId } });
         }
         return { text: emitted };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        ctx.emit({ type: 'error', error: message });
+        ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
         if (started) {
-            ctx.emit({ type: 'text-cancel', id: turnId, reason: message });
+            ctx.emit({
+                channel: 'client',
+                type: 'text-cancel',
+                payload: { id: turnId, reason: message },
+            });
         }
         throw err instanceof Error ? err : new Error(message);
     }

package/dist/runtime/citations/index.d.ts

@@ -1,15 +1,15 @@
-import type { AgentKnowledgeOverrides, HarnessStreamPart, KnowledgeRetrievalResult, RetrievalCacheAdapter, SourceRef } from '../../types/index.js';
+import type { AgentKnowledgeOverrides, StreamPart, KnowledgeRetrievalResult, RetrievalCacheAdapter, SourceRef } from '../../types/index.js';
 export interface CitationRetrievalProvider {
     retrieve(query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<{
         results: KnowledgeRetrievalResult[];
         citations?: SourceRef[];
-        events: HarnessStreamPart[];
+        events: StreamPart[];
     }>;
 }
 export interface CitationRetrievalResult {
     results: KnowledgeRetrievalResult[];
     citations: SourceRef[];
-    events: HarnessStreamPart[];
+    events: StreamPart[];
 }
 export declare function retrieveWithCitations(provider: CitationRetrievalProvider, query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<CitationRetrievalResult>;
 export declare function normalizeCitations(results: KnowledgeRetrievalResult[], nativeCitations?: readonly SourceRef[]): SourceRef[];

package/dist/runtime/closeRun.js

@@ -1,4 +1,7 @@
 import { isTerminalOutcome, markSessionOutcome } from './outcomeMarking.js';
+import { mutateSessionWithRetry } from '../session/utils.js';
+import { syncPendingUserInput } from './channels/inputBuffer.js';
+import { runHookSafely } from './runHookSafely.js';
 export async function closeRun(options) {
     const { session, runState, runStore, sessionStore, hooks, ctx } = options;
     runState.updatedAt = Date.now();
@@ -14,17 +17,18 @@ export async function closeRun(options) {
         outcomeRecord = await markSessionOutcome(sessionStore, session, options.terminalOutcome, { reason: options.outcomeReason, markedBy: 'hook' }, ctx.emit);
     }
     if (outcomeRecord && isTerminalOutcome(outcomeRecord.outcome)) {
-        await hooks?.onConversationEnd?.({
+        await runHookSafely('onConversationEnd', () => hooks?.onConversationEnd?.({
             session,
             outcome: outcomeRecord,
-        });
+        }));
     }
-    const latest = (await sessionStore.get(session.id)) ?? session;
-    latest.currentAgent = runState.activeAgentId;
-    latest.activeAgentId = runState.activeAgentId;
-    // Sync the session-level message mirror to the canonical run record — it
-    // otherwise lacks assistant turns and keeps pre-guardrail (unredacted)
-    // user input written at openRun.
-    latest.messages = [...runState.messages];
-    await sessionStore.save(latest);
+    await mutateSessionWithRetry(sessionStore, session.id, (latest) => {
+        latest.currentAgent = runState.activeAgentId;
+        latest.activeAgentId = runState.activeAgentId;
+        // Sync the session-level message mirror to the canonical run record — it
+        // otherwise lacks assistant turns and keeps pre-guardrail (unredacted)
+        // user input written at openRun.
+        latest.messages = [...runState.messages];
+        syncPendingUserInput(ctx.session, latest);
+    });
 }

package/dist/runtime/compaction.d.ts

@@ -42,6 +42,8 @@ export interface CompactMessagesOptions {
     /** Skip the threshold check (overflow recovery). */
     force?: boolean;
     abortSignal?: AbortSignal;
+    /** Real last-turn prompt tokens when available (replaces chars/4 for threshold). */
+    lastPromptTokens?: number;
 }
 /**
  * Pure compaction step: returns a new message list when compaction applied.

package/dist/runtime/compaction.js

@@ -64,10 +64,11 @@ function truncate(text, max) {
  * pairs are never split across the summary boundary.
  */
 export async function compactMessages(options) {
-    const { messages, model, config, force, abortSignal } = options;
+    const { messages, model, config, force, abortSignal, lastPromptTokens } = options;
     const triggerTokens = config.triggerTokens ?? DEFAULT_COMPACTION_TRIGGER_TOKENS;
     const keepRecent = config.keepRecentMessages ?? DEFAULT_COMPACTION_KEEP_RECENT;
-    const beforeTokens = estimateMessagesTokens(messages);
+    const estimatedTokens = estimateMessagesTokens(messages);
+    const beforeTokens = lastPromptTokens ?? estimatedTokens;
     if (!force && beforeTokens < triggerTokens) {
         return { compacted: false, reason: 'under-threshold', beforeTokens };
     }

package/dist/runtime/controlFlowSignal.d.ts

@@ -0,0 +1,24 @@
+import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+/**
+ * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
+ * It unwinds the stack like an error but is not a failure, so it must never be reported to
+ * the model as a tool error, shown to the user as an error, or journaled as one.
+ *
+ * Only `SuspendError` qualifies. An approval *denial* is deliberately not a signal — see
+ * `isApprovalDenial`.
+ */
+export declare function isControlFlowSignal(error: unknown): boolean;
+/**
+ * A human answered "no". Neither a failure nor a suspend — the opposite of a suspend, in
+ * fact: a suspend defers the decision, a denial resolves it.
+ *
+ * Two rules follow, and they differ by who is driving the call:
+ *
+ * - It must never be degraded into "something went wrong on my side". Nothing went wrong;
+ *   saying so would be a lie to the user.
+ * - On the **model** path it becomes a tool result, because there is no author code to
+ *   catch it and the agent needs to be able to tell the user the request was declined.
+ *   On the **flow** path it keeps propagating, because an `action` node's author chose to
+ *   call the tool and can catch it or branch on `ctx.approve()` instead.
+ */
+export declare function isApprovalDenial(error: unknown): error is ToolApprovalDeniedError;

package/dist/runtime/controlFlowSignal.js

@@ -0,0 +1,29 @@
+import { SuspendError } from './durable/RunStore.js';
+import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+/**
+ * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
+ * It unwinds the stack like an error but is not a failure, so it must never be reported to
+ * the model as a tool error, shown to the user as an error, or journaled as one.
+ *
+ * Only `SuspendError` qualifies. An approval *denial* is deliberately not a signal — see
+ * `isApprovalDenial`.
+ */
+export function isControlFlowSignal(error) {
+    return error instanceof SuspendError;
+}
+/**
+ * A human answered "no". Neither a failure nor a suspend — the opposite of a suspend, in
+ * fact: a suspend defers the decision, a denial resolves it.
+ *
+ * Two rules follow, and they differ by who is driving the call:
+ *
+ * - It must never be degraded into "something went wrong on my side". Nothing went wrong;
+ *   saying so would be a lie to the user.
+ * - On the **model** path it becomes a tool result, because there is no author code to
+ *   catch it and the agent needs to be able to tell the user the request was declined.
+ *   On the **flow** path it keeps propagating, because an `action` node's author chose to
+ *   call the tool and can catch it or branch on `ctx.approve()` instead.
+ */
+export function isApprovalDenial(error) {
+    return error instanceof ToolApprovalDeniedError;
+}

package/dist/runtime/ctx.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel } from 'ai';
 import type { Session } from '../types/session.js';
-import type { EffectToolExecutor, HookRunner, MemoryService, AutoRetrieveProvider, RunContext } from '../types/run-context.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { EffectToolExecutor, MemoryService, AutoRetrieveProvider, RunContext } from '../types/run-context.js';
+import type { StreamPart } from '../types/stream.js';
 import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { InputProcessor, OutputProcessor } from '../types/processors.js';
@@ -19,7 +19,6 @@ export interface CtxDeps {
     runStore: RunStore;
     steps: StepRecord[];
     toolExecutor: EffectToolExecutor;
-    hookRunner?: HookRunner;
     model: LanguageModel;
     controlModel?: LanguageModel;
     outOfBandControl?: boolean;
@@ -34,7 +33,7 @@ export interface CtxDeps {
     bargeIn?: AbortSignal;
     abortSignal?: AbortSignal;
     clock?: EffectClock;
-    emit?: (part: HarnessStreamPart) => void;
+    emit?: (part: StreamPart) => void;
 }
 export declare function createRunContext(deps: CtxDeps): Promise<RunContext>;
 export {};

package/dist/runtime/ctx.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { SuspendError } from './durable/RunStore.js';
-import { clockEffectKey, pauseEffectKey, toolEffectKey, } from './durable/idempotency.js';
+import { clockEffectKey, idempotencyKey, logicalRunId, pauseEffectKey, } from './durable/idempotency.js';
 import { findStepByKey } from './durable/replay.js';
 import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
 const APPROVAL_SIGNAL = '__approval';
@@ -12,58 +12,149 @@ function makeCtx(deps) {
         uuid: () => randomUUID(),
     };
     const emit = deps.emit ?? (() => { });
+    // Mutable holder: handoff reassigns runCtx.toolExecutor; ctx.tool must see the swap.
+    const toolExecutorHolder = { executor: deps.toolExecutor };
+    let pendingAppendTail = Promise.resolve();
+    const serializePendingAppend = (operation) => {
+        const previous = pendingAppendTail;
+        let release;
+        pendingAppendTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        return previous.then(async () => {
+            try {
+                return await operation();
+            }
+            finally {
+                release();
+            }
+        });
+    };
     const consumeCallsite = () => {
         const site = String(effectOrdinal);
         effectOrdinal += 1;
         return site;
     };
-    const appendLiveStep = async (key, kind, name, result, signalId) => {
+    const isFinishedStep = (hit) => {
+        if (hit.status === 'finished') {
+            return true;
+        }
+        if (hit.status === 'running') {
+            return false;
+        }
+        if (hit.status === 'error' || hit.error) {
+            return false;
+        }
+        return hit.result !== undefined;
+    };
+    const updateLocalStep = (key, patch) => {
+        const idx = steps.findIndex((step) => step.key === key);
+        if (idx >= 0) {
+            steps[idx] = { ...steps[idx], ...patch };
+        }
+    };
+    const appendPendingStep = async (key, kind, name, index, signalId) => {
         const startedAt = Date.now();
         const record = {
-            index: steps.length,
+            index,
             key,
             kind,
             name,
             signalId,
-            result,
+            status: 'running',
             startedAt,
-            finishedAt: startedAt,
+            epoch: deps.runState.runEpoch ?? 0,
         };
         await deps.runStore.appendStep(deps.runState.runId, record);
-        steps.push(record);
-        deps.runState.updatedAt = startedAt;
-        await deps.runStore.putRunState(deps.runState);
+        const localIdx = steps.findIndex((step) => step.index === index);
+        if (localIdx >= 0) {
+            steps[localIdx] = record;
+        }
+        else {
+            while (steps.length < index) {
+                steps.push({
+                    index: steps.length,
+                    key: `__reserve:${deps.runState.runId}:${steps.length}`,
+                    kind: 'tool',
+                    name: '__reserve',
+                    status: 'running',
+                    startedAt,
+                    epoch: deps.runState.runEpoch ?? 0,
+                });
+            }
+            if (steps.length === index) {
+                steps.push(record);
+            }
+            else {
+                steps[index] = record;
+            }
+        }
     };
-    const replayOrExecute = async (key, kind, name, execute) => {
+    const replayOrExecute = async (key, kind, name, execute, options) => {
         const hit = findStepByKey(steps, key);
         if (hit) {
-            if (hit.error) {
+            if (hit.status === 'error' || hit.error) {
                 throw Object.assign(new Error(hit.error.message), { name: hit.error.name });
             }
-            return hit.result;
+            if (isFinishedStep(hit)) {
+                return hit.result;
+            }
         }
+        const isRetry = hit?.status === 'running';
+        const stepIndex = options?.index ?? hit?.index;
+        if (!isRetry) {
+            const append = async () => {
+                let index = stepIndex;
+                if (index === undefined) {
+                    if (deps.runStore.reserveSteps) {
+                        index = (await deps.runStore.reserveSteps(deps.runState.runId, 1))[0];
+                    }
+                    else {
+                        // ctx.tool owns ordinal assignment: use the store's atomic reservation when available,
+                        // and serialize legacy stores that do not expose reserveSteps within this context.
+                        index = steps.length;
+                    }
+                }
+                await appendPendingStep(key, kind, name, index);
+            };
+            if (stepIndex === undefined && !deps.runStore.reserveSteps) {
+                await serializePendingAppend(append);
+            }
+            else {
+                await append();
+            }
+        }
+        let result;
         try {
-            const result = await execute();
-            await appendLiveStep(key, kind, name, result);
-            return result;
+            result = await execute();
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
-            const startedAt = Date.now();
-            const record = {
-                index: steps.length,
-                key,
-                kind,
-                name,
+            const finishedAt = Date.now();
+            await deps.runStore.finalizeStep(deps.runState.runId, key, {
+                status: 'error',
                 error: { name: err.name, message: err.message },
-                startedAt,
-                finishedAt: startedAt,
-            };
-            await deps.runStore.appendStep(deps.runState.runId, record);
-            steps.push(record);
+                finishedAt,
+            });
+            updateLocalStep(key, {
+                status: 'error',
+                error: { name: err.name, message: err.message },
+                finishedAt,
+            });
             throw err;
         }
+        const finishedAt = Date.now();
+        await deps.runStore.finalizeStep(deps.runState.runId, key, {
+            status: 'finished',
+            result,
+            finishedAt,
+        });
+        updateLocalStep(key, { status: 'finished', result, finishedAt });
+        deps.runState.updatedAt = finishedAt;
+        await deps.runStore.putRunState(deps.runState);
+        return result;
     };
+    const effectRunId = () => logicalRunId(deps.runState.runId, deps.runState.runEpoch);
     const suspendForSignal = async (signalName, callsite, meta) => {
         deps.runState.waitingFor = {
             signalName,
@@ -75,18 +166,20 @@ function makeCtx(deps) {
         deps.runState.status = 'paused';
         deps.runState.updatedAt = Date.now();
         await deps.runStore.putRunState(deps.runState);
-        emit({ type: 'paused', waitingFor: signalName });
+        emit({ channel: 'internal', type: 'paused', payload: { waitingFor: signalName } });
         throw new SuspendError(signalName);
     };
     const pauseEffect = async (signalName, meta) => {
         const callsite = consumeCallsite();
-        const key = pauseEffectKey(deps.runState.runId, callsite, signalName);
+        const key = pauseEffectKey(effectRunId(), callsite, signalName);
         const hit = findStepByKey(steps, key);
         if (hit) {
-            if (hit.error) {
+            if (hit.status === 'error' || hit.error) {
                 throw Object.assign(new Error(hit.error.message), { name: hit.error.name });
             }
-            return hit.result;
+            if (hit.status === 'finished' || hit.result !== undefined) {
+                return hit.result;
+            }
         }
         await suspendForSignal(signalName, callsite, meta);
         throw new Error('unreachable');
@@ -96,8 +189,12 @@ function makeCtx(deps) {
         runState: deps.runState,
         runStore: deps.runStore,
         emit,
-        toolExecutor: deps.toolExecutor,
-        hookRunner: deps.hookRunner ?? {},
+        get toolExecutor() {
+            return toolExecutorHolder.executor;
+        },
+        set toolExecutor(executor) {
+            toolExecutorHolder.executor = executor;
+        },
         model: deps.model,
         controlModel: deps.controlModel ?? deps.model,
         outOfBandControl: deps.outOfBandControl ?? false,
@@ -121,6 +218,13 @@ function makeCtx(deps) {
         resetCallsites: () => {
             effectOrdinal = 0;
         },
+        reserveCallsites: (count) => {
+            const sites = [];
+            for (let i = 0; i < count; i++) {
+                sites.push(consumeCallsite());
+            }
+            return sites;
+        },
         tool: async (name, args, options) => {
             // needsApproval gate: a tool flagged `needsApproval` must be approved by a human
             // before it runs. Approval is a durable pause (the `__approval` signal); on resume
@@ -129,7 +233,7 @@ function makeCtx(deps) {
             // ordering is deterministic across replays. NOTE: the surrounding agent turn is not
             // itself a replayable effect — this is fully deterministic for flow `action` tools;
             // for model-issued tool calls, resume re-enters the agent turn.
-            const def = options?.def ?? deps.toolExecutor.getTool?.(name);
+            const def = options?.def ?? toolExecutorHolder.executor.getTool?.(name);
             if (def?.needsApproval) {
                 const decision = (await pauseEffect(APPROVAL_SIGNAL, {
                     approval: { title: `Approve tool: ${name}` },
@@ -138,9 +242,12 @@ function makeCtx(deps) {
                     throw new ToolApprovalDeniedError(name, decision.by);
                 }
             }
-            const callsite = consumeCallsite();
-            const key = toolEffectKey(deps.runState.runId, callsite, name, args);
-            const executeTool = () => deps.toolExecutor.execute({
+            const callsite = options?.callsite ?? consumeCallsite();
+            const logicalId = effectRunId();
+            const key = def?.idempotencyKey != null
+                ? def.idempotencyKey(args)
+                : idempotencyKey(logicalId, callsite, { name, args });
+            const executeTool = () => toolExecutorHolder.executor.execute({
                 name,
                 args,
                 session: deps.session,
@@ -150,30 +257,10 @@ function makeCtx(deps) {
                 toolCtx: options?.toolCtx,
             });
             if (def?.replay === false) {
-                const auditKey = `${key}:${steps.length}`;
-                try {
-                    const result = await executeTool();
-                    await appendLiveStep(auditKey, 'tool', name, result);
-                    return result;
-                }
-                catch (error) {
-                    const err = error instanceof Error ? error : new Error(String(error));
-                    const startedAt = Date.now();
-                    const record = {
-                        index: steps.length,
-                        key: auditKey,
-                        kind: 'tool',
-                        name,
-                        error: { name: err.name, message: err.message },
-                        startedAt,
-                        finishedAt: startedAt,
-                    };
-                    await deps.runStore.appendStep(deps.runState.runId, record);
-                    steps.push(record);
-                    throw err;
-                }
+                const auditKey = `${key}:${steps.length}:${options?.index ?? callsite}`;
+                return replayOrExecute(auditKey, 'tool', name, executeTool, { index: options?.index });
             }
-            return replayOrExecute(key, 'tool', name, executeTool);
+            return replayOrExecute(key, 'tool', name, executeTool, { index: options?.index });
         },
         approve: async (req) => {
             return pauseEffect(APPROVAL_SIGNAL, { approval: req });
@@ -186,12 +273,12 @@ function makeCtx(deps) {
         },
         now: async () => {
             const callsite = consumeCallsite();
-            const key = clockEffectKey(deps.runState.runId, callsite, 'now');
+            const key = clockEffectKey(effectRunId(), callsite, 'now');
             return replayOrExecute(key, 'now', 'now', async () => clock.now());
         },
         uuid: async () => {
             const callsite = consumeCallsite();
-            const key = clockEffectKey(deps.runState.runId, callsite, 'uuid');
+            const key = clockEffectKey(effectRunId(), callsite, 'uuid');
             return replayOrExecute(key, 'uuid', 'uuid', async () => clock.uuid());
         },
     };

package/dist/runtime/durable/RunStore.d.ts

@@ -12,9 +12,25 @@ export declare class SuspendError extends Error {
 export declare class RunNotFoundError extends Error {
     constructor(runId: string);
 }
+export declare class StepNotFoundError extends Error {
+    constructor(runId: string, key: string);
+}
+export interface StepFinalizePatch {
+    status: 'finished' | 'error';
+    result?: unknown;
+    error?: {
+        name: string;
+        message: string;
+    };
+    finishedAt?: number;
+}
 export interface RunStore {
     appendStep(runId: string, record: StepRecord): Promise<void>;
+    finalizeStep(runId: string, key: string, patch: StepFinalizePatch): Promise<void>;
     getSteps(runId: string): Promise<StepRecord[]>;
     getRunState(runId: string): Promise<RunState | null>;
     putRunState(state: RunState): Promise<void>;
+    initRun?(state: RunState): Promise<void>;
+    pruneStepsBeforeEpoch?(runId: string, keepEpoch: number): Promise<void>;
+    reserveSteps?(runId: string, count: number): Promise<number[]>;
 }

package/dist/runtime/durable/RunStore.js

@@ -3,7 +3,7 @@ export class LogConflictError extends Error {
     expectedIndex;
     actualIndex;
     constructor(runId, expectedIndex, actualIndex) {
-        super(`Log conflict for run ${runId}: expected append at index ${expectedIndex}, current length is ${actualIndex}`);
+        super(`Log conflict for run ${runId}: expected append at index ${expectedIndex}, current length is ${actualIndex}. For parallel durable effects, use ctx.tool directly or reserve callsites with ctx.reserveCallsites(count) before supplying explicit indices.`);
         this.name = 'LogConflictError';
         this.runId = runId;
         this.expectedIndex = expectedIndex;
@@ -24,3 +24,9 @@ export class RunNotFoundError extends Error {
         this.name = 'RunNotFoundError';
     }
 }
+export class StepNotFoundError extends Error {
+    constructor(runId, key) {
+        super(`Step not found for run ${runId}: ${key}`);
+        this.name = 'StepNotFoundError';
+    }
+}