@kuralle-agents/core 0.12.0 → 0.13.0

package/dist/types/run-context.d.ts

@@ -10,7 +10,7 @@ import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
 import type { FileSystem } from './filesystem.js';
 import type { Instructions } from './agentConfig.js';
-import type { AgentKnowledgeOverrides, SourceRef } from './voice.js';
+import type { AgentKnowledgeOverrides, SourceRef, RetrievalCacheAdapter } from './voice.js';
 export interface GatherScope {
     query?: string;
     knowledge?: AgentKnowledgeOverrides & {
@@ -80,6 +80,13 @@ export interface RunContext {
     turnInputConsumed?: boolean;
     /** Citations from the latest gather-phase retrieval on this turn. */
     lastRetrievalCitations?: SourceRef[];
+    /**
+     * Session retrieval cache (G6): created once per run by the KnowledgeProvider,
+     * persists across in-session agent handoffs (this RunContext survives the
+     * handoff branch). Keyed by query embedding; RAG-only, undefined without a
+     * configured knowledge provider + embedder.
+     */
+    retrievalCache?: RetrievalCacheAdapter;
     /** Agent base layer (ADR 0001), set when entering a flow. `baseInstructions`
      *  is composed as a prefix into every node turn's system prompt (persona /
      *  safety / grounding floor); `globalTools` are safe tools made model-visible
@@ -98,6 +105,10 @@ export interface RunContext {
         toolCallId?: string;
         def?: AnyTool;
         toolCtx?: ToolContext;
+        /** Pre-reserved callsite ordinal for parallel-safe tool batches (G9). */
+        callsite?: string;
+        /** Pre-reserved journal index for parallel-safe tool batches (G9). */
+        index?: number;
     }): Promise<unknown>;
     approve(req: {
         title: string;
@@ -116,6 +127,8 @@ export interface RunContext {
      *  a flow's durable callsites are anchored to the flow — identical on fresh entry
      *  (after an answering turn) and on resume (where that turn does not re-run). */
     resetCallsites(): void;
+    /** Reserve N contiguous effect callsite ordinals for parallel-safe tool batches (G9). */
+    reserveCallsites(count: number): string[];
 }
 export type ActionContext = Pick<RunContext, 'tool' | 'approve' | 'signal' | 'now' | 'uuid' | 'emit' | 'fs'>;
 export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit' | 'fs' | 'abortSignal'>;

package/dist/types/session.d.ts

@@ -6,6 +6,14 @@ import type { ConversationOutcomeRecord, CsatRecord } from '../outcomes/types.js
 import type { PersonaExperimentMetadata } from '../persona/types.js';
 import type { ConversationAuditEntry } from '../audit/types.js';
 export type ChannelId = 'web' | 'email' | 'sms' | 'voice' | 'api' | 'slack' | 'discord' | (string & {});
+/** Structured goal/thread entry on session.workingMemory.__goals (G5). */
+export type GoalStatus = 'open' | 'resolved';
+export interface TrackedGoal {
+    topic: string;
+    status: GoalStatus;
+    lastTurn: number;
+    note?: string;
+}
 export interface WorkingMemory {
     get<T>(key: string): T | undefined;
     set<T>(key: string, value: T): void;
@@ -42,6 +50,8 @@ export interface Session {
     pendingRefinement?: RefinementStageResult;
     /** @internal Pending key-facts extraction promises. Awaited before session save. */
     __pendingExtractions?: Promise<void>[];
+    /** Optimistic-concurrency version; must match the stored row on save (C2 CAS). */
+    version?: number;
 }
 export interface SessionMetadata {
     createdAt: Date;

package/dist/types/stream.d.ts

@@ -116,6 +116,14 @@ export type HarnessStreamPart = {
 } | {
     type: 'done';
     sessionId: string;
+    /** Per-turn token usage: `inputTokens`/`outputTokens` are THIS turn's
+     *  consumption (deltas, for cost attribution); `contextTokens` is the current
+     *  context-window occupancy (last prompt tokens, a snapshot). */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        contextTokens?: number;
+    };
 };
 export interface TurnHandle extends Promise<import('./channel.js').TurnResult> {
     readonly events: AsyncIterable<HarnessStreamPart>;

package/dist/types/trace.d.ts

@@ -0,0 +1,50 @@
+export type SpanKind = 'turn' | 'flow' | 'node' | 'tool' | 'handoff' | 'llm';
+export interface AgentSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    status: 'ok' | 'error';
+    events?: Array<{
+        name: string;
+        time: number;
+        attributes?: Record<string, unknown>;
+    }>;
+    attributes: {
+        sessionId: string;
+        activeFlow?: string;
+        nodeId?: string;
+        toolName?: string;
+        handoffFrom?: string;
+        handoffTo?: string;
+        input?: unknown;
+        output?: unknown;
+        error?: string;
+        /** Input tokens consumed by this turn (delta — for cost attribution). */
+        tokensIn?: number;
+        /** Output tokens generated by this turn (delta — for cost attribution). */
+        tokensOut?: number;
+        /** Context-window occupancy at this turn (last prompt tokens — a snapshot, not a delta). */
+        contextTokens?: number;
+    };
+}
+export interface AgentTrace {
+    traceId: string;
+    sessionId: string;
+    spans: AgentSpan[];
+    answer: string;
+    usedTool: boolean;
+    toolCalls: Array<{
+        name: string;
+        args: unknown;
+    }>;
+    toolResults: Array<{
+        name: string;
+        result: unknown;
+    }>;
+    startedAt: number;
+    endedAt?: number;
+}

package/dist/types/trace.js

@@ -0,0 +1 @@
+export {};

package/guides/EXAMPLE_VERIFICATION.md

@@ -8,8 +8,8 @@ This verification was run after runtime policy-profile changes to check for regr
 
 Covered suites:
 
-1. `packages/kuralle-core/examples/agents` (Line parity set)
-2. `packages/kuralle-core/examples/flows` (Pipecat parity set)
+1. `packages/core/examples/agents` (Line parity set)
+2. `packages/core/examples/flows` (Pipecat parity set)
 3. Extended package examples (`kuralle-tools`, `kuralle-redis-store`)
 
 ## Results
@@ -30,8 +30,8 @@ Interpretation:
 
 Non-pass items:
 
-1. `packages/kuralle-redis-store/examples/local-redis/test.ts` -> `SKIPPED`
-2. `packages/kuralle-redis-store/examples/local-redis/multi-turn.ts` -> `SKIPPED`
+1. `packages/redis-store/examples/local-redis/test.ts` -> `SKIPPED`
+2. `packages/redis-store/examples/local-redis/multi-turn.ts` -> `SKIPPED`
    - Cause: local Redis was not started.
 
 ## Verdict

package/package.json

@@ -4,9 +4,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
-    "directory": "packages/kuralle-core"
+    "directory": "packages/core"
   },
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -48,6 +48,14 @@
       "types": "./dist/session/testing.d.ts",
       "default": "./dist/session/testing.js"
     },
+    "./tracing": {
+      "types": "./dist/tracing/index.d.ts",
+      "default": "./dist/tracing/index.js"
+    },
+    "./tracing/testing": {
+      "types": "./dist/tracing/testing.d.ts",
+      "default": "./dist/tracing/testing.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -94,8 +102,8 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "^0.12.7",
     "@ai-sdk/openai": "^3.0.0",
+    "@cloudflare/vitest-pool-workers": "^0.12.7",
     "@types/node": "^20.11.0",
     "ai": "^6.0.0",
     "bun-types": "^1.3.0",
@@ -103,7 +111,8 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/realtime-audio": "0.12.0"
+    "@kuralle-agents/fs": "0.13.0",
+    "@kuralle-agents/realtime-audio": "0.13.0"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"