@kuralle-agents/core 0.12.0 → 0.13.0

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,114 @@ 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 };
     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 ?? steps.length;
+        if (!isRetry) {
+            await appendPendingStep(key, kind, name, stepIndex);
         }
+        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 },
+                finishedAt,
+            });
+            updateLocalStep(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,
+            });
             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,
@@ -80,13 +136,15 @@ function makeCtx(deps) {
     };
     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,7 +154,12 @@ function makeCtx(deps) {
         runState: deps.runState,
         runStore: deps.runStore,
         emit,
-        toolExecutor: deps.toolExecutor,
+        get toolExecutor() {
+            return toolExecutorHolder.executor;
+        },
+        set toolExecutor(executor) {
+            toolExecutorHolder.executor = executor;
+        },
         hookRunner: deps.hookRunner ?? {},
         model: deps.model,
         controlModel: deps.controlModel ?? deps.model,
@@ -121,6 +184,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 +199,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 +208,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,
@@ -151,29 +224,9 @@ function makeCtx(deps) {
             });
             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;
-                }
+                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 +239,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

@@ -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';
+    }
+}

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

@@ -1,14 +1,19 @@
-import type { SessionStore } from '../../session/SessionStore.js';
+import { type SessionStore } from '../../session/SessionStore.js';
 import type { RunState, StepRecord } from './types.js';
-import { type RunStore } from './RunStore.js';
+import { type RunStore, type StepFinalizePatch } from './RunStore.js';
 export declare class SessionRunStore implements RunStore {
     private readonly sessionStore;
     private readonly sessionId;
+    private static readonly CAS_RETRIES;
     constructor(sessionStore: SessionStore, sessionId: string);
+    private mutateSession;
     appendStep(runId: string, record: StepRecord): Promise<void>;
+    finalizeStep(runId: string, key: string, patch: StepFinalizePatch): Promise<void>;
+    reserveSteps(runId: string, count: number): Promise<number[]>;
     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>;
     private requireSession;
 }

package/dist/runtime/durable/SessionRunStore.js

@@ -1,5 +1,6 @@
+import { StaleWriteError } from '../../session/SessionStore.js';
 import { DURABLE_RUNS_KEY } from './types.js';
-import { LogConflictError, RunNotFoundError } from './RunStore.js';
+import { LogConflictError, RunNotFoundError, StepNotFoundError, } from './RunStore.js';
 function cloneSession(value) {
     try {
         return structuredClone(value);
@@ -21,28 +22,115 @@ function getPersistedRun(session, runId) {
 export class SessionRunStore {
     sessionStore;
     sessionId;
+    static CAS_RETRIES = 8;
     constructor(sessionStore, sessionId) {
         this.sessionStore = sessionStore;
         this.sessionId = sessionId;
     }
-    async appendStep(runId, record) {
-        const session = await this.requireSession();
-        const runs = readRuns(session);
-        const persisted = runs[runId];
-        if (!persisted) {
-            throw new RunNotFoundError(runId);
+    async mutateSession(mutator) {
+        for (let attempt = 0; attempt < SessionRunStore.CAS_RETRIES; attempt++) {
+            const session = await this.requireSession();
+            await mutator(session);
+            try {
+                await this.sessionStore.save(session);
+                return;
+            }
+            catch (error) {
+                if (error instanceof StaleWriteError && attempt < SessionRunStore.CAS_RETRIES - 1) {
+                    continue;
+                }
+                throw error;
+            }
         }
-        if (persisted.steps.length !== record.index) {
-            throw new LogConflictError(runId, record.index, persisted.steps.length);
-        }
-        if (persisted.steps.some((step) => step.key === record.key)) {
-            throw new LogConflictError(runId, record.index, persisted.steps.length);
+    }
+    async appendStep(runId, record) {
+        await this.mutateSession((session) => {
+            const runs = readRuns(session);
+            const persisted = runs[runId];
+            if (!persisted) {
+                throw new RunNotFoundError(runId);
+            }
+            const existingAtIndex = persisted.steps[record.index];
+            if (existingAtIndex?.name === '__reserve') {
+                if (persisted.steps.some((step) => step.key === record.key && step.index !== record.index)) {
+                    throw new LogConflictError(runId, record.index, persisted.steps.length);
+                }
+                persisted.steps[record.index] = cloneSession(record);
+            }
+            else if (persisted.steps.length !== record.index) {
+                throw new LogConflictError(runId, record.index, persisted.steps.length);
+            }
+            else if (persisted.steps.some((step) => step.key === record.key)) {
+                throw new LogConflictError(runId, record.index, persisted.steps.length);
+            }
+            else {
+                persisted.steps.push(cloneSession(record));
+            }
+            persisted.runState.updatedAt = Date.now();
+            runs[runId] = persisted;
+            writeRuns(session, runs);
+        });
+    }
+    async finalizeStep(runId, key, patch) {
+        await this.mutateSession((session) => {
+            const runs = readRuns(session);
+            const persisted = runs[runId];
+            if (!persisted) {
+                throw new RunNotFoundError(runId);
+            }
+            const stepIndex = persisted.steps.findIndex((step) => step.key === key);
+            if (stepIndex === -1) {
+                throw new StepNotFoundError(runId, key);
+            }
+            const existing = persisted.steps[stepIndex];
+            persisted.steps[stepIndex] = cloneSession({
+                ...existing,
+                ...patch,
+                index: existing.index,
+                key: existing.key,
+                kind: existing.kind,
+                name: existing.name,
+                startedAt: existing.startedAt,
+                epoch: existing.epoch,
+            });
+            persisted.runState.updatedAt = Date.now();
+            runs[runId] = persisted;
+            writeRuns(session, runs);
+        });
+    }
+    async reserveSteps(runId, count) {
+        if (count <= 0) {
+            return [];
         }
-        persisted.steps.push(cloneSession(record));
-        persisted.runState.updatedAt = Date.now();
-        runs[runId] = persisted;
-        writeRuns(session, runs);
-        await this.sessionStore.save(session);
+        let indices = [];
+        await this.mutateSession((session) => {
+            const runs = readRuns(session);
+            const persisted = runs[runId];
+            if (!persisted) {
+                throw new RunNotFoundError(runId);
+            }
+            const start = persisted.steps.length;
+            const now = Date.now();
+            const epoch = persisted.runState.runEpoch ?? 0;
+            indices = [];
+            for (let i = 0; i < count; i++) {
+                const index = start + i;
+                indices.push(index);
+                persisted.steps.push({
+                    index,
+                    key: `__reserve:${runId}:${index}`,
+                    kind: 'tool',
+                    name: '__reserve',
+                    status: 'running',
+                    startedAt: now,
+                    epoch,
+                });
+            }
+            persisted.runState.updatedAt = now;
+            runs[runId] = persisted;
+            writeRuns(session, runs);
+        });
+        return indices;
     }
     async getSteps(runId) {
         const session = await this.requireSession();
@@ -58,25 +146,39 @@ export class SessionRunStore {
         return persisted ? cloneSession(persisted.runState) : null;
     }
     async putRunState(state) {
-        const session = await this.requireSession();
-        const runs = readRuns(session);
-        const existing = runs[state.runId];
-        runs[state.runId] = {
-            runState: cloneSession({ ...state, updatedAt: Date.now() }),
-            steps: existing?.steps.map((step) => cloneSession(step)) ?? [],
-        };
-        writeRuns(session, runs);
-        await this.sessionStore.save(session);
+        await this.mutateSession((session) => {
+            const runs = readRuns(session);
+            const existing = runs[state.runId];
+            runs[state.runId] = {
+                runState: cloneSession({ ...state, updatedAt: Date.now() }),
+                steps: existing?.steps.map((step) => cloneSession(step)) ?? [],
+            };
+            writeRuns(session, runs);
+        });
     }
     async initRun(state) {
-        const session = await this.requireSession();
-        const runs = readRuns(session);
-        runs[state.runId] = {
-            runState: cloneSession(state),
-            steps: [],
-        };
-        writeRuns(session, runs);
-        await this.sessionStore.save(session);
+        await this.mutateSession((session) => {
+            const runs = readRuns(session);
+            runs[state.runId] = {
+                runState: cloneSession(state),
+                steps: [],
+            };
+            writeRuns(session, runs);
+        });
+    }
+    async pruneStepsBeforeEpoch(runId, keepEpoch) {
+        await this.mutateSession((session) => {
+            const runs = readRuns(session);
+            const persisted = runs[runId];
+            if (!persisted) {
+                return;
+            }
+            const kept = persisted.steps.filter((step) => step.epoch === undefined || step.epoch >= keepEpoch);
+            persisted.steps = kept.map((step, index) => ({ ...cloneSession(step), index }));
+            persisted.runState.updatedAt = Date.now();
+            runs[runId] = persisted;
+            writeRuns(session, runs);
+        });
     }
     async requireSession() {
         const session = await this.sessionStore.get(this.sessionId);

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

@@ -1,3 +1,4 @@
+export declare function logicalRunId(runId: string, runEpoch: number | undefined): string;
 export declare function idempotencyKey(runId: string, callsite: string, payload: unknown): string;
 export declare function toolEffectKey(runId: string, callsite: string, name: string, args: unknown): string;
 export declare function pauseEffectKey(runId: string, callsite: string, name: string): string;

package/dist/runtime/durable/idempotency.js

@@ -12,6 +12,9 @@ function stableStringify(value) {
         return val;
     });
 }
+export function logicalRunId(runId, runEpoch) {
+    return `${runId}#${runEpoch ?? 0}`;
+}
 export function idempotencyKey(runId, callsite, payload) {
     const material = stableStringify({ runId, callsite, payload });
     return createHash('sha256').update(material).digest('hex');

package/dist/runtime/durable/replay.js

@@ -1,4 +1,4 @@
-import { pauseEffectKey } from './idempotency.js';
+import { pauseEffectKey, logicalRunId } from './idempotency.js';
 export function findStepByKey(steps, key) {
     return steps.find((step) => step.key === key);
 }
@@ -14,7 +14,10 @@ export async function recordSignalDelivery(runStore, runState, delivery) {
     if (!waitingFor || waitingFor.signalName !== delivery.name) {
         throw new Error(`Signal ${delivery.name} does not match waitingFor ${waitingFor?.signalName ?? 'none'}`);
     }
-    const key = pauseEffectKey(runState.runId, waitingFor.callsite, delivery.name);
+    // Must match the key pauseEffect used when it suspended: the keystone scopes the
+    // effect-key namespace by logical run (runId#epoch), so the resume-side delivery
+    // key has to use logicalRunId too, else the pause never finds its own decision.
+    const key = pauseEffectKey(logicalRunId(runState.runId, runState.runEpoch), waitingFor.callsite, delivery.name);
     if (findStepByKey(steps, key)) {
         return false;
     }
@@ -25,9 +28,11 @@ export async function recordSignalDelivery(runStore, runState, delivery) {
         kind: waitingFor.approval ? 'approval' : 'signal',
         name: delivery.name,
         signalId: delivery.signalId,
+        status: 'finished',
         result: delivery.payload,
         startedAt: now,
         finishedAt: now,
+        epoch: runState.runEpoch ?? 0,
     };
     await runStore.appendStep(runState.runId, record);
     runState.waitingFor = undefined;

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

@@ -1,5 +1,6 @@
 import type { ModelMessage } from 'ai';
 export type StepKind = 'tool' | 'approval' | 'signal' | 'now' | 'uuid';
+export type StepStatus = 'running' | 'paused' | 'finished' | 'error' | 'aborted';
 export interface StepRecord {
     index: number;
     key: string;
@@ -11,8 +12,12 @@ export interface StepRecord {
         name: string;
         message: string;
     };
+    /** Intent lifecycle: `running` = pending execute; `finished`/`error` = finalized. Legacy steps omit status. */
+    status?: StepStatus;
     startedAt: number;
     finishedAt?: number;
+    /** Logical-run epoch when this step was recorded. Absent on legacy steps → prune keeps them until superseded. */
+    epoch?: number;
 }
 interface WaitingFor {
     signalName: string;
@@ -36,6 +41,12 @@ export interface RunState {
     messages: ModelMessage[];
     createdAt: number;
     updatedAt: number;
+    /** Monotonic logical-run counter. Increments on each fresh turn; stable across suspend/resume.
+     *  Scopes the durable effect-key namespace so a new turn re-executes rather than replaying a
+     *  prior turn's cached result (F6/G8). Absent on legacy runs → treat as 0. */
+    runEpoch?: number;
+    /** Inbound message idempotency keys already accepted (H2 webhook-retry dedup). */
+    processedInboundKeys?: string[];
 }
 export interface SignalDelivery {
     signalId: string;

package/dist/runtime/goals.d.ts

@@ -0,0 +1,18 @@
+import type { LanguageModel } from 'ai';
+import type { RunContext } from '../types/run-context.js';
+export declare const GOALS_KEY = "__goals";
+export type GoalStatus = 'open' | 'resolved';
+export interface TrackedGoal {
+    topic: string;
+    status: GoalStatus;
+    lastTurn: number;
+    note?: string;
+}
+export type GoalsState = Record<string, unknown>;
+export declare function getGoals(state: GoalsState): TrackedGoal[];
+export declare function addGoal(state: GoalsState, topic: string, lastTurn?: number, note?: string): GoalsState;
+export declare function resolveGoal(state: GoalsState, topic: string, lastTurn?: number): GoalsState;
+export declare function listOpenGoals(state: GoalsState): string[];
+export declare function projectGoalsPrompt(goals: TrackedGoal[]): string;
+export declare function projectGoalsPromptFromState(state: GoalsState): string;
+export declare function updateGoalsFromTurn(ctx: RunContext, model: LanguageModel): Promise<void>;