@kuralle-agents/core 0.13.0 → 0.15.0

package/dist/types/knowledge.d.ts

@@ -0,0 +1,213 @@
+import type { StreamPart } from './stream.js';
+/**
+ * Runtime-level knowledge configuration. Configured once on the Runtime,
+ * inherited by all agents. Per-agent overrides via `AgentKnowledgeOverrides`
+ * can only reduce capabilities (e.g., disable compiled knowledge, restrict
+ * topK, filter by metadata).
+ */
+export interface KnowledgeProviderConfig {
+    /**
+     * Retriever for hybrid search (Layer 3). Any object implementing the
+     * Retriever interface from `@kuralle-agents/rag`. When not provided,
+     * only compiled knowledge and cache are available.
+     */
+    retriever?: KnowledgeRetrieverAdapter;
+    /**
+     * Embedder for cache similarity lookup. Required when `retriever` is
+     * provided (needed for cache population and query embedding).
+     */
+    embedder?: KnowledgeEmbedderAdapter;
+    /**
+     * Pre-compiled knowledge content (Layer 1). Injected into the system
+     * prompt every turn with zero search latency. Produced offline by
+     * KnowledgeCompiler.
+     */
+    compiled?: string;
+    /**
+     * Retrieval cache configuration. When omitted, a default configuration
+     * is used (maxEntries: 256, ttlMs: 300000, similarityThreshold: 0.85).
+     */
+    cache?: {
+        /** Maximum entries in the LRU cache. Default: 256. */
+        maxEntries?: number;
+        /** Cache entry TTL in milliseconds. Default: 300000 (5 minutes). */
+        ttlMs?: number;
+        /** Minimum cosine similarity for a cache hit. Default: 0.85. */
+        similarityThreshold?: number;
+    };
+    /**
+     * Predictive pre-fetch configuration. When enabled, the system
+     * predicts follow-up topics from the conversation window and
+     * pre-fetches relevant content into the session cache.
+     */
+    prefetch?: {
+        /** Enable predictive pre-fetching. Default: false. */
+        enabled?: boolean;
+        /** Number of keywords to extract per prediction. Default: 3. */
+        maxKeywords?: number;
+        /** Number of recent messages to analyze. Default: 5. */
+        conversationWindow?: number;
+    };
+    /**
+     * Default retrieval options applied to all agents unless overridden.
+     */
+    defaults?: {
+        /** Maximum results from Layer 3 search. Default: 5. */
+        topK?: number;
+        /** Maximum tokens for retrieval context in the system prompt. Default: 2000. */
+        maxOutputTokens?: number;
+        /** Whether to include embedding vectors in results (for cache writeback). Default: true. */
+        includeEmbeddings?: boolean;
+    };
+    /**
+     * Retrieval quality checking configuration. When configured, retrieval
+     * results are evaluated using score distribution (sub-millisecond).
+     * For text agents, low-quality results trigger inline reformulation.
+     * For voice agents, low-quality results trigger background reformulation
+     * via the pre-fetcher.
+     */
+    qualityCheck?: {
+        /** Minimum top-result score to consider quality "high". Default: 0.5. */
+        highThreshold?: number;
+        /** Minimum top-result score to consider quality "medium". Default: 0.3. */
+        mediumThreshold?: number;
+        /**
+         * Query reformulator callback. When provided and quality is "low",
+         * the system rewrites the query and re-retrieves.
+         */
+        reformulate?: (query: string, results: KnowledgeRetrievalResult[]) => Promise<string>;
+    };
+    /**
+     * How retrieved source references should be rendered into the model prompt.
+     * Defaults to 'footnotes'.
+     */
+    renderCitations?: 'inline' | 'footnotes' | 'off';
+}
+/**
+ * Per-agent knowledge overrides. Can only reduce capabilities — cannot
+ * add a retriever that doesn't exist at the Runtime level.
+ */
+export interface AgentKnowledgeOverrides {
+    /** Disable compiled knowledge injection for this agent. */
+    compiledEnabled?: boolean;
+    /** Disable retrieval tool for this agent. */
+    toolEnabled?: boolean;
+    /** Override topK (must be <= Runtime default). */
+    topK?: number;
+    /** Override max output tokens (must be <= Runtime default). */
+    maxOutputTokens?: number;
+    /** Metadata filter restricting which documents this agent can access. */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Adapter interface for retrievers used by KnowledgeProvider.
+ * Mirrors the Retriever interface from `@kuralle-agents/rag` without
+ * creating a dependency from core → rag.
+ */
+export interface KnowledgeRetrieverAdapter {
+    retrieve(query: string, options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+        queryEmbedding?: readonly number[];
+        includeEmbeddings?: boolean;
+    }): Promise<KnowledgeRetrievalResult[]>;
+}
+/**
+ * Adapter interface for embedders used by KnowledgeProvider.
+ * Mirrors the Embedder interface from `@kuralle-agents/rag`.
+ */
+export interface KnowledgeEmbedderAdapter {
+    embed(text: string): Promise<readonly number[]>;
+}
+export interface SourceRef {
+    readonly id: string;
+    readonly title?: string;
+    readonly url?: string;
+    readonly lastModified?: string;
+    readonly score?: number;
+}
+/**
+ * A single result from knowledge retrieval, used across the pipeline.
+ */
+export interface KnowledgeRetrievalResult {
+    id: string;
+    text: string;
+    sourceId: string;
+    score?: number;
+    relevanceScore?: number;
+    snippet?: string;
+    metadata?: Record<string, unknown>;
+    embedding?: readonly number[];
+}
+export type KnowledgeChunk = KnowledgeRetrievalResult;
+/**
+ * Interface for the session-level retrieval cache. Implemented by
+ * `RetrievalCache` from `@kuralle-agents/rag`. Defined here so
+ * `RunContext.retrievalCache` can be properly typed without core
+ * depending on rag.
+ */
+export interface RetrievalCacheAdapter {
+    lookup(queryEmbedding: readonly number[], topK?: number): KnowledgeRetrievalResult[];
+    populate(results: KnowledgeRetrievalResult[], queryEmbedding?: readonly number[]): void;
+    readonly size: number;
+}
+export interface HttpCallbackConfig {
+    url: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    allowList?: string[];
+    denyList?: string[];
+    includeFullText?: boolean;
+    timeoutMs?: number;
+}
+export interface StreamCallbackPayload {
+    sessionId: string;
+    agentId: string;
+    timestamp: string;
+    part: StreamPart;
+    fullText?: string;
+}
+export interface StreamCallbackSink {
+    name?: string;
+    write: (payload: StreamCallbackPayload) => Promise<void>;
+    close?: () => Promise<void>;
+}
+export interface StreamCallbackConfig {
+    sinks?: StreamCallbackSink[];
+    /**
+     * Events to emit when no explicit allowList is provided.
+     * - message: emit terminal events plus tool/transition events per toggles
+     * - all: emit every runtime event
+     * Default: message
+     */
+    eventMode?: 'message' | 'all';
+    /**
+     * Emit streaming text-delta events.
+     * Default: false (final text is emitted on terminal events via fullText)
+     */
+    emitTextDeltas?: boolean;
+    /**
+     * Emit tool lifecycle events (tool-call/tool-result) in message mode.
+     * Default: true
+     */
+    emitToolEvents?: boolean;
+    /**
+     * Emit transition lifecycle events (flow-transition/handoff) in message mode.
+     * Default: true
+     */
+    emitTransitionEvents?: boolean;
+    /**
+     * Attach accumulated assistant text as fullText on terminal events.
+     * Default: true
+     */
+    emitFinalText?: boolean;
+    allowList?: string[];
+    denyList?: string[];
+    includeFullText?: boolean;
+    maxQueueSize?: number;
+    dropPolicy?: 'drop_oldest' | 'drop_newest';
+    logDroppedEvents?: boolean;
+    /** If true, wait for sink queue drain when a stream call ends. Default: false. */
+    flushOnEnd?: boolean;
+    flushTimeoutMs?: number;
+}

package/dist/types/processors.d.ts

@@ -70,61 +70,3 @@ export interface AgentCapabilityDescriptor {
     handlesIntents?: string[];
     doesNotHandle?: string[];
 }
-export type AgentStreamPart = {
-    type: 'text-start';
-    id: string;
-} | {
-    type: 'text-delta';
-    id: string;
-    delta: string;
-} | {
-    type: 'text-end';
-    id: string;
-} | {
-    type: 'text-cancel';
-    id: string;
-    reason: string;
-} | {
-    type: 'tool-call';
-    toolName: string;
-    args: unknown;
-    toolCallId?: string;
-} | {
-    type: 'tool-result';
-    toolName: string;
-    result: unknown;
-    toolCallId?: string;
-} | {
-    type: 'tool-error';
-    toolName: string;
-    error: string;
-    toolCallId?: string;
-} | {
-    type: 'handoff';
-    targetAgent: string;
-    reason?: string;
-} | {
-    type: 'node-enter';
-    nodeName: string;
-} | {
-    type: 'node-exit';
-    nodeName: string;
-} | {
-    type: 'flow-transition';
-    from: string;
-    to: string;
-} | {
-    type: 'flow-end';
-    reason: string;
-} | {
-    type: 'custom';
-    name: string;
-    data: unknown;
-    timestamp?: Date;
-} | {
-    type: 'turn-end';
-    metadata?: Record<string, unknown>;
-} | {
-    type: 'error';
-    error: string;
-};

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

@@ -3,14 +3,14 @@ import type { Session } from './session.js';
 import type { InputProcessor, OutputProcessor } from './processors.js';
 import type { RunState } from '../runtime/durable/types.js';
 import type { RunStore } from '../runtime/durable/RunStore.js';
-import type { HarnessStreamPart } from './stream.js';
+import type { StreamPart } from './stream.js';
 import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 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, RetrievalCacheAdapter } from './voice.js';
+import type { AgentKnowledgeOverrides, SourceRef, RetrievalCacheAdapter } from './knowledge.js';
 export interface GatherScope {
     query?: string;
     knowledge?: AgentKnowledgeOverrides & {
@@ -45,16 +45,12 @@ export interface MemoryService {
     preload?(ctx: RunContext, scope?: GatherScope): Promise<string | undefined>;
     ingest?(ctx: RunContext): Promise<void>;
 }
-export interface HookRunner {
-    onStreamPart?(ctx: RunContext, part: HarnessStreamPart): void | Promise<void>;
-}
 export interface RunContext {
     session: Session;
     runState: RunState;
     runStore: RunStore;
-    emit: (part: HarnessStreamPart) => void;
+    emit: (part: StreamPart) => void;
     toolExecutor: EffectToolExecutor;
-    hookRunner: HookRunner;
     model: LanguageModel;
     /** Control-path model (routing, decide, extraction) at temperature 0. */
     controlModel: LanguageModel;

package/dist/types/runtime.d.ts

@@ -1,10 +1,6 @@
-import type { ModelMessage } from 'ai';
-import type { SessionEndMetadata, TurnUsage } from './telemetry.js';
-import type { AgentStreamPart } from './processors.js';
-import type { AgentContext, RunContext, Session, ToolCallRecord } from './session.js';
-import type { HarnessStreamPart } from './voice.js';
+import type { AgentContext, RunContext } from './session.js';
+import type { StreamPart } from './stream.js';
 import type { RefineDecision, ValidateDecision } from '../capabilities/index.js';
-import type { ConversationOutcome, ConversationOutcomeRecord } from '../outcomes/types.js';
 import type { ChannelId } from './session.js';
 export interface RefinementStageResult {
     proceed: boolean;
@@ -24,7 +20,7 @@ export interface Hook {
     name: string;
     onTurnStart?: (ctx: AgentContext, input: string) => Promise<void>;
     onTurnEnd?: (ctx: AgentContext) => Promise<void>;
-    onStreamPart?: (ctx: AgentContext, part: AgentStreamPart) => Promise<void>;
+    onStreamPart?: (ctx: AgentContext, part: StreamPart) => Promise<void>;
     onAgentSwitch?: (ctx: AgentContext, from: string, to: string) => Promise<void>;
     onError?: (ctx: AgentContext, error: Error) => Promise<void>;
 }
@@ -36,73 +32,6 @@ export interface StopCondition {
     name: string;
     check: (context: RunContext) => StopConditionResult;
 }
-export interface StepResult {
-    text?: string;
-    toolCalls: ToolCallRecord[];
-    finishReason: string;
-    tokensUsed: number;
-    handoffTo?: string;
-}
-export interface TurnSummary {
-    sessionId: string;
-    userId?: string;
-    agentId: string;
-    messageCount: number;
-    toolCallCount: number;
-    totalTokens: number;
-}
-export interface TurnEndHookResult {
-    outcome?: ConversationOutcome;
-    reason?: string;
-}
-export interface HarnessHooks {
-    onStart?: (context: RunContext) => Promise<void>;
-    onEnd?: (context: RunContext, result: {
-        success: boolean;
-        error?: Error;
-    }) => Promise<void>;
-    onStepStart?: (context: RunContext, step: number) => Promise<void>;
-    onStepEnd?: (context: RunContext, step: number, result: StepResult) => Promise<void>;
-    onToolCall?: (context: RunContext, call: ToolCallRecord) => Promise<void>;
-    onToolResult?: (context: RunContext, call: ToolCallRecord) => Promise<void>;
-    onToolError?: (context: RunContext, call: ToolCallRecord, error: Error) => Promise<void>;
-    onTurnEnd?: (context: RunContext, summary: TurnSummary) => Promise<TurnEndHookResult | void>;
-    onAgentStart?: (context: RunContext, agentId: string) => Promise<void>;
-    onAgentEnd?: (context: RunContext, agentId: string) => Promise<void>;
-    onHandoff?: (context: RunContext, from: string, to: string, reason: string) => Promise<void>;
-    onError?: (context: RunContext, error: Error) => Promise<void>;
-    onMessage?: (context: RunContext, message: ModelMessage) => Promise<void>;
-    onStreamPart?: (context: RunContext, part: HarnessStreamPart) => Promise<void>;
-    onPersistenceError?: (session: Session, error: Error) => Promise<void>;
-    onMemoryIngest?: (context: RunContext, session: Session) => Promise<boolean | void>;
-    onMemoryIngested?: (context: RunContext, session: Session) => Promise<void>;
-    onBeforeModelCall?: (context: RunContext, data: BeforeModelCallData) => Promise<BeforeModelCallResult | void>;
-    onSessionEnd?: (session: Session, metadata: SessionEndMetadata) => Promise<void>;
-    onConversationEnd?: (session: Session, outcome: ConversationOutcomeRecord) => Promise<{
-        csatInvited: boolean;
-        csatChannel?: 'email' | 'in-app' | 'sms';
-    } | void>;
-    onTokensUpdate?: (context: RunContext, turn: TurnUsage) => Promise<void> | void;
-}
-export interface BeforeModelCallData {
-    systemPrompt: string;
-    messages: ModelMessage[];
-    estimatedTokens: number;
-    agentId: string;
-    tokenBreakdown: {
-        basePrompt: number;
-        autoRetrieve: number;
-        workingMemory: number;
-        extraction: number;
-        longTermMemory: number;
-        policyInjections: number;
-        messageHistory: number;
-    };
-}
-export interface BeforeModelCallResult {
-    systemPrompt?: string;
-    messages?: ModelMessage[];
-}
 export interface StreamOptions {
     input: string;
     sessionId?: string;

package/dist/types/session.d.ts

@@ -1,5 +1,5 @@
 import type { ModelMessage } from 'ai';
-import type { RetrievalCacheAdapter } from './voice.js';
+import type { RetrievalCacheAdapter } from './knowledge.js';
 import type { RefinementStageResult } from './runtime.js';
 import type { EscalationReason, EscalationOutcome } from '../escalation/types.js';
 import type { ConversationOutcomeRecord, CsatRecord } from '../outcomes/types.js';

package/dist/types/skills.d.ts

@@ -16,4 +16,18 @@ export interface SkillStoreLike {
     getAllSkills?(): SkillLike[] | Promise<SkillLike[]>;
     loadAllSkills?(): Promise<SkillLike[]>;
 }
-export type SkillSource = SkillLike | SkillLike[] | SkillStoreLike;
+/**
+ * One way to supply skills. A `string` is a filesystem root scanned for
+ * `<dir>/SKILL.md`, resolved against the agent's `workspace` filesystem.
+ */
+export type SkillEntry = SkillLike | SkillStoreLike | string;
+/**
+ * Skills for an agent: one entry, or an ordered array mixing inline skills, stores, and
+ * workspace paths. **Later entries win** on a name collision, so layering reads in the
+ * order you write it:
+ *
+ * ```ts
+ * skills: ['/skills/org', '/skills/team', defineSkill({ name: 'override', … })]
+ * ```
+ */
+export type SkillSource = SkillEntry | ReadonlyArray<SkillEntry>;