@kuralle-agents/core 0.12.0 → 0.14.0

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>;

package/dist/runtime/goals.js

@@ -0,0 +1,158 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+export const GOALS_KEY = '__goals';
+const goalPatchSchema = z.object({
+    add: z
+        .array(z.object({
+        topic: z.string(),
+        note: z.union([z.string(), z.null()]),
+    }))
+        .default([]),
+    resolve: z.array(z.string()).default([]),
+});
+function isTrackedGoal(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const goal = value;
+    return (typeof goal.topic === 'string' &&
+        (goal.status === 'open' || goal.status === 'resolved') &&
+        typeof goal.lastTurn === 'number');
+}
+function normalizeTopic(topic) {
+    return topic.trim().toLowerCase();
+}
+export function getGoals(state) {
+    const raw = state[GOALS_KEY];
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter(isTrackedGoal);
+}
+export function addGoal(state, topic, lastTurn = 0, note) {
+    const trimmed = topic.trim();
+    if (!trimmed) {
+        return state;
+    }
+    const goals = getGoals(state);
+    const key = normalizeTopic(trimmed);
+    const existingIndex = goals.findIndex((goal) => normalizeTopic(goal.topic) === key);
+    if (existingIndex >= 0) {
+        const next = [...goals];
+        const existing = next[existingIndex];
+        next[existingIndex] = {
+            ...existing,
+            topic: trimmed,
+            status: 'open',
+            lastTurn,
+            note: note ?? existing.note,
+        };
+        return { ...state, [GOALS_KEY]: next };
+    }
+    const entry = { topic: trimmed, status: 'open', lastTurn };
+    if (note) {
+        entry.note = note;
+    }
+    return { ...state, [GOALS_KEY]: [...goals, entry] };
+}
+export function resolveGoal(state, topic, lastTurn = 0) {
+    const trimmed = topic.trim();
+    if (!trimmed) {
+        return state;
+    }
+    const key = normalizeTopic(trimmed);
+    const goals = getGoals(state);
+    let changed = false;
+    const next = goals.map((goal) => {
+        if (normalizeTopic(goal.topic) !== key) {
+            return goal;
+        }
+        changed = true;
+        return { ...goal, status: 'resolved', lastTurn };
+    });
+    if (!changed) {
+        return state;
+    }
+    return { ...state, [GOALS_KEY]: next };
+}
+export function listOpenGoals(state) {
+    return getGoals(state)
+        .filter((goal) => goal.status === 'open')
+        .map((goal) => goal.topic);
+}
+export function projectGoalsPrompt(goals) {
+    const open = goals.filter((goal) => goal.status === 'open');
+    if (open.length === 0) {
+        return '';
+    }
+    const parts = open.map((goal) => goal.note ? `${goal.topic} (${goal.status}, ${goal.note})` : `${goal.topic} (${goal.status})`);
+    return `Open threads: ${parts.join('; ')}`;
+}
+export function projectGoalsPromptFromState(state) {
+    return projectGoalsPrompt(getGoals(state));
+}
+function readSessionTurn(state) {
+    const value = state['__ariaSessionTurn'];
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function latestExchange(messages) {
+    let assistant = '';
+    let user = '';
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!assistant && message?.role === 'assistant' && typeof message.content === 'string') {
+            assistant = message.content;
+            continue;
+        }
+        if (assistant && message?.role === 'user' && typeof message.content === 'string') {
+            user = message.content;
+            break;
+        }
+    }
+    if (!user || !assistant) {
+        return null;
+    }
+    return { user, assistant };
+}
+function applyGoalPatch(state, patch) {
+    let next = state;
+    const turn = readSessionTurn(state);
+    for (const topic of patch.resolve) {
+        next = resolveGoal(next, topic, turn);
+    }
+    for (const entry of patch.add) {
+        const note = entry.note ?? undefined;
+        next = addGoal(next, entry.topic, turn, note);
+    }
+    return next;
+}
+export async function updateGoalsFromTurn(ctx, model) {
+    const exchange = latestExchange(ctx.runState.messages);
+    if (!exchange) {
+        return;
+    }
+    const currentGoals = getGoals(ctx.session.workingMemory);
+    const goalsSummary = currentGoals.length === 0
+        ? 'none'
+        : currentGoals
+            .map((goal) => goal.note
+            ? `${goal.topic} [${goal.status}] — ${goal.note}`
+            : `${goal.topic} [${goal.status}]`)
+            .join('\n');
+    const { object } = await generateObject({
+        model,
+        schema: goalPatchSchema,
+        temperature: 0,
+        system: 'You track conversational threads (goals/topics the user may circle back to). ' +
+            'Given the latest exchange and current tracked threads, return only schema fields. ' +
+            'Add a topic when the user opens a new thread or revisits one not yet tracked. ' +
+            'Resolve a topic when the exchange clearly completes or abandons it. ' +
+            'Keep topics short labels (1-4 words). Do not invent threads unrelated to the exchange.',
+        prompt: `Current tracked threads:\n${goalsSummary}\n\n` +
+            `Latest user message:\n${exchange.user}\n\n` +
+            `Latest assistant message:\n${exchange.assistant}\n\n` +
+            'Return add[] for new/reopened open topics and resolve[] for completed topics.',
+    });
+    const patched = applyGoalPatch(ctx.session.workingMemory, object);
+    ctx.session.workingMemory = patched;
+}

package/dist/runtime/grounding/gather.d.ts

@@ -1,4 +1,4 @@
-import type { SourceRef } from '../../types/voice.js';
+import type { SourceRef } from '../../types/knowledge.js';
 import type { GatherScope, RunContext } from '../../types/run-context.js';
 export type { GatherScope } from '../../types/run-context.js';
 export interface GatherResult {

package/dist/runtime/grounding/inMemoryKnowledge.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeProviderConfig, KnowledgeRetrieverAdapter } from '../../types/voice.js';
+import type { KnowledgeProviderConfig, KnowledgeRetrieverAdapter } from '../../types/knowledge.js';
 export interface InMemoryKnowledgeDocument {
     id?: string;
     text: string;

package/dist/runtime/grounding/knowledge.d.ts

@@ -1,7 +1,7 @@
 import type { AgentConfig } from '../../types/agentConfig.js';
 import type { AutoRetrieveProvider } from '../../types/run-context.js';
 import type { AnyTool } from '../../types/effectTool.js';
-import type { KnowledgeProviderConfig } from '../../types/voice.js';
+import type { KnowledgeProviderConfig } from '../../types/knowledge.js';
 import { KnowledgeProvider } from '../KnowledgeProvider.js';
 export declare function buildKnowledgeProvider(config: KnowledgeProviderConfig): KnowledgeProvider;
 export declare function buildAutoRetrieveProvider(provider: KnowledgeProvider, agent: AgentConfig): AutoRetrieveProvider | undefined;

package/dist/runtime/grounding/knowledge.js

@@ -42,7 +42,7 @@ export function buildAutoRetrieveProvider(provider, agent) {
         retrieve: async (ctx, scope) => {
             const query = scope?.query ?? latestUserMessage(ctx);
             const merged = scope?.knowledge ? { ...overrides, ...scope.knowledge } : overrides;
-            const cache = undefined;
+            const cache = ctx.retrievalCache;
             const { results, events } = await provider.retrieve(query || ' ', cache, merged, false);
             for (const event of events) {
                 ctx.emit(event);

package/dist/runtime/handoffContinuation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Silent handoff: a transfer between agents should read as one continuous
+ * assistant to the user. The transfer itself is already a silent control tool
+ * call, but the TARGET agent's own instructions may tell it to introduce itself
+ * ("Bill here"), which leaks the switch. On a silent handoff we append a strong
+ * continuation directive to the target's system prompt so it does not greet or
+ * re-introduce — mirroring the OpenAI Agents SDK's `nest_handoff_history`
+ * context-note approach. Off (visible handoff) leaves the target's instructions
+ * untouched.
+ */
+import type { Instructions } from '../types/agentConfig.js';
+export declare const HANDOFF_CONTINUATION_DIRECTIVE: string;
+/**
+ * Append the continuation directive to a target agent's instructions on a silent
+ * handoff. Handles every `Instructions` form: a string is suffixed; a (sync)
+ * function is wrapped so the directive is appended to its resolved text; an
+ * `AgentPrompt` object is left untouched (it cannot be safely suffixed, and is
+ * rare as a base layer); `undefined` yields the directive alone.
+ */
+export declare function applyHandoffContinuation(base: Instructions | undefined): Instructions;

package/dist/runtime/handoffContinuation.js

@@ -0,0 +1,30 @@
+export const HANDOFF_CONTINUATION_DIRECTIVE = 'You are seamlessly continuing an ongoing conversation with the same user — this is ' +
+    'not a new conversation. Do NOT greet the user, introduce yourself, state your name ' +
+    'or role, say "hello", or mention any transfer, connection, or that a different ' +
+    'assistant is now helping. Ignore any earlier instruction to open with a greeting or ' +
+    'self-introduction. Continue as one uninterrupted assistant and answer the request directly.';
+const SUFFIX = `\n\n[Handoff continuation]\n${HANDOFF_CONTINUATION_DIRECTIVE}`;
+/**
+ * Append the continuation directive to a target agent's instructions on a silent
+ * handoff. Handles every `Instructions` form: a string is suffixed; a (sync)
+ * function is wrapped so the directive is appended to its resolved text; an
+ * `AgentPrompt` object is left untouched (it cannot be safely suffixed, and is
+ * rare as a base layer); `undefined` yields the directive alone.
+ */
+export function applyHandoffContinuation(base) {
+    if (typeof base === 'string') {
+        return `${base}${SUFFIX}`;
+    }
+    if (typeof base === 'function') {
+        return (ctx) => {
+            const inner = base(ctx);
+            if (typeof inner !== 'string') {
+                // resolveInstructions only supports sync-string functions; match that contract.
+                throw new Error('handoff continuation: instructions function must return a string synchronously');
+            }
+            return `${inner}${SUFFIX}`;
+        };
+    }
+    // AgentPrompt object → preserve as-is (do not drop the persona); undefined → directive only.
+    return base ?? HANDOFF_CONTINUATION_DIRECTIVE;
+}

package/dist/runtime/handoffOscillation.d.ts

@@ -0,0 +1,6 @@
+/** True when the recent handoff history shows A↔B oscillation at/above `threshold` hops
+ *  between the same unordered pair, counting the pending from→to as the latest hop. */
+export declare function isHandoffOscillating(history: Array<{
+    from: string;
+    to: string;
+}>, pendingFrom: string, pendingTo: string, threshold: number): boolean;

package/dist/runtime/handoffOscillation.js

@@ -0,0 +1,17 @@
+/** True when the recent handoff history shows A↔B oscillation at/above `threshold` hops
+ *  between the same unordered pair, counting the pending from→to as the latest hop. */
+export function isHandoffOscillating(history, pendingFrom, pendingTo, threshold) {
+    const pairKey = (a, b) => [a, b].sort().join('\0');
+    const target = pairKey(pendingFrom, pendingTo);
+    let count = 1; // the pending hop
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const h = history[i];
+        if (!h)
+            break;
+        if (pairKey(h.from, h.to) === target)
+            count += 1;
+        else
+            break; // only CONSECUTIVE same-pair hops count as oscillation
+    }
+    return count >= threshold;
+}