@ariaflowagents/core 0.7.1 → 0.9.0

package/dist/runtime/pipeline/sessionUtils.js

@@ -0,0 +1,73 @@
+import { normalizeModelMessage } from '../../utils/messageNormalization.js';
+import { SessionWorkingMemory } from '../WorkingMemory.js';
+export function getFlowState(session, agentId) {
+    const stored = session.agentStates?.[agentId]?.state;
+    if (!stored)
+        return undefined;
+    return stored;
+}
+export function setFlowState(session, agentId, state, conversationState) {
+    session.agentStates[agentId] = {
+        agentId,
+        state: state,
+        lastActive: new Date(),
+    };
+    updateFlowStateSnapshot(session, agentId, state);
+    conversationState.touchSession(session);
+}
+export function clearFlowState(session, agentId, conversationState) {
+    delete session.agentStates[agentId];
+    conversationState.touchSession(session);
+}
+export function updateFlowStateSnapshot(session, agentId, state) {
+    const existing = session.workingMemory.flowStateByAgent;
+    const byAgent = typeof existing === 'object' && existing !== null
+        ? { ...existing }
+        : {};
+    byAgent[agentId] = {
+        currentNode: state.context.currentNode,
+        collectedData: state.context.collectedData,
+        nodeHistory: state.context.nodeHistory,
+        initialized: state.initialized,
+        flowEnded: state.flowEnded,
+        updatedAt: new Date().toISOString(),
+    };
+    session.workingMemory.flowStateByAgent = byAgent;
+}
+function normalizeSessionMessage(message) {
+    return normalizeModelMessage(message);
+}
+export function normalizeSessionHistory(messages) {
+    const normalized = [];
+    for (const message of messages) {
+        const next = normalizeSessionMessage(message);
+        if (next) {
+            normalized.push(next);
+        }
+    }
+    return normalized;
+}
+export function appendSessionMessage(session, message, conversationState) {
+    const normalized = normalizeSessionMessage(message);
+    if (!normalized)
+        return;
+    session.messages.push(normalized);
+    conversationState.touchSession(session);
+}
+export function appendSessionMessages(session, messages, conversationState) {
+    for (const message of messages) {
+        appendSessionMessage(session, message, conversationState);
+    }
+}
+export function buildAgentContext(input, context, conversationState, abortSignal) {
+    return {
+        session: context.session,
+        messages: context.session.messages,
+        workingMemory: new SessionWorkingMemory(context.session),
+        currentAgent: context.agentId,
+        turnCount: conversationState.getSessionTurn(context.session),
+        metadata: (context.session.metadata ?? {}),
+        abortSignal,
+    };
+}
+//# sourceMappingURL=sessionUtils.js.map

package/dist/runtime/pipeline/sessionUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionUtils.js","sourceRoot":"","sources":["../../../src/runtime/pipeline/sessionUtils.ts"],"names":[],"mappings":"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"}

package/dist/tools/Tool.d.ts

@@ -1,4 +1,5 @@
 import type { Tool as AiTool, ToolSet as AiToolSet } from 'ai';
+import type { Runtime } from '../runtime/Runtime.js';
 import type { ZodTypeAny } from 'zod';
 export type Tool<TInput = unknown, TResult = unknown> = AiTool<TInput, TResult>;
 export type ToolSet = AiToolSet;
@@ -11,6 +12,7 @@ export interface ToolExecutionContext {
     toolName?: string;
     toolCallId?: string;
     idempotencyKey?: string;
+    runtime?: unknown;
     [key: string]: unknown;
 }
 export interface ToolExecutionOptions {
@@ -20,6 +22,11 @@ export interface ToolExecutionOptions {
     experimental_context?: ToolExecutionContext;
     [key: string]: unknown;
 }
+export type ToolExecutionContextWithRuntime = ToolExecutionContext & {
+    runtime: Runtime;
+};
+export declare function isAgentContext(value: unknown): value is ToolExecutionContextWithRuntime;
+export declare function getRuntimeFromContext(context: ToolExecutionContext | undefined): Runtime | undefined;
 export interface ToolDefinition<TInput = unknown, TResult = unknown> {
     description: string;
     inputSchema: ZodTypeAny;

package/dist/tools/Tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/tools/Tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,IAAI,MAAM,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEtC,MAAM,MAAM,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAChF,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC;AAEhC,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACvF,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,CAAE,SAAQ,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1G,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC5D,UAAU,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzD;AAED,wBAAgB,oBAAoB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACtE,UAAU,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzD"}
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/tools/Tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,IAAI,MAAM,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEtC,MAAM,MAAM,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAChF,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC;AAEhC,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1F,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,+BAA+B,CAMvF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAEpG;AAED,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACvF,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,CAAE,SAAQ,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1G,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC5D,UAAU,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzD;AAED,wBAAgB,oBAAoB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACtE,UAAU,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzD"}

package/dist/tools/Tool.js

@@ -1,4 +1,12 @@
 import { tool as aiTool } from 'ai';
+export function isAgentContext(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'runtime' in value);
+}
+export function getRuntimeFromContext(context) {
+    return context?.runtime;
+}
 export function createTool(definition) {
     // NOTE: We intentionally return the tool typed as ToolDefinition for a stable,
     // portable public API surface. Internally the returned object is a Vercel AI SDK tool.
@@ -7,10 +15,11 @@ export function createTool(definition) {
 export function createToolWithFiller(definition) {
     const t = aiTool(definition);
     // Preserve non-standard UX hints for AriaFlow (used by Runtime tool-start filler).
+    const extended = t;
     if (definition.filler)
-        t.filler = definition.filler;
+        extended.filler = definition.filler;
     if (definition.estimatedDurationMs)
-        t.estimatedDurationMs = definition.estimatedDurationMs;
-    return t;
+        extended.estimatedDurationMs = definition.estimatedDurationMs;
+    return extended;
 }
 //# sourceMappingURL=Tool.js.map

package/dist/tools/Tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../src/tools/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,IAAI,CAAC;AA4CpC,MAAM,UAAU,UAAU,CACxB,UAA2C;IAE3C,+EAA+E;IAC/E,uFAAuF;IACvF,OAAO,MAAM,CAAC,UAAiB,CAAQ,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,UAA2C;IAE3C,MAAM,CAAC,GAAG,MAAM,CAAC,UAAiB,CAAC,CAAC;IACpC,mFAAmF;IACnF,IAAI,UAAU,CAAC,MAAM;QAAG,CAAS,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;IAC7D,IAAI,UAAU,CAAC,mBAAmB;QAAG,CAAS,CAAC,mBAAmB,GAAG,UAAU,CAAC,mBAAmB,CAAC;IACpG,OAAO,CAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../src/tools/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,IAAI,CAAC;AA+BpC,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK,CACnB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAyC;IAC7E,OAAO,OAAO,EAAE,OAA8B,CAAC;AACjD,CAAC;AAmBD,MAAM,UAAU,UAAU,CACxB,UAA2C;IAE3C,+EAA+E;IAC/E,uFAAuF;IACvF,OAAO,MAAM,CAAC,UAAqD,CAAuE,CAAC;AAC7I,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,UAA2C;IAE3C,MAAM,CAAC,GAAG,MAAM,CAAC,UAAqD,CAAC,CAAC;IACxE,mFAAmF;IACnF,MAAM,QAAQ,GAAG,CAAuE,CAAC;IACzF,IAAI,UAAU,CAAC,MAAM;QAAE,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;IAC3D,IAAI,UAAU,CAAC,mBAAmB;QAAE,QAAQ,CAAC,mBAAmB,GAAG,UAAU,CAAC,mBAAmB,CAAC;IAClG,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/tools/memory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates a tool that lets the agent search long-term memory.
+ * The LLM decides when to call this based on the conversation.
+ *
+ * The tool accesses memoryService and session via experimental_context
+ * injected by Runtime.wrapToolsWithEnforcement / withToolExecutionMetadata.
+ *
+ * Usage:
+ *   const agent: AgentConfig = {
+ *     tools: { ...otherTools, loadMemory: createLoadMemoryTool() },
+ *   };
+ */
+export declare function createLoadMemoryTool(): import("ai").Tool<{
+    query: string;
+}, {
+    memories: never[];
+    note: string;
+} | {
+    memories: {
+        content: string;
+        author: string | undefined;
+        date: string;
+    }[];
+    note?: undefined;
+}>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/tools/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/tools/memory.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB;;;;;;;;;;;;GAuCnC"}

package/dist/tools/memory.js

@@ -0,0 +1,51 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+/**
+ * Creates a tool that lets the agent search long-term memory.
+ * The LLM decides when to call this based on the conversation.
+ *
+ * The tool accesses memoryService and session via experimental_context
+ * injected by Runtime.wrapToolsWithEnforcement / withToolExecutionMetadata.
+ *
+ * Usage:
+ *   const agent: AgentConfig = {
+ *     tools: { ...otherTools, loadMemory: createLoadMemoryTool() },
+ *   };
+ */
+export function createLoadMemoryTool() {
+    return tool({
+        description: 'Search long-term memory for relevant information from past conversations with this user. ' +
+            'Use this when the user refers to something discussed previously, or when you need context ' +
+            'about their preferences, history, or past interactions.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe('What to search for in past conversations'),
+        }),
+        execute: async ({ query }, { experimental_context }) => {
+            const ctx = experimental_context;
+            const memoryService = ctx?.memoryService;
+            const session = ctx?.session;
+            const userId = session?.userId;
+            if (!memoryService) {
+                return { memories: [], note: 'Memory service not configured.' };
+            }
+            if (!userId) {
+                return { memories: [], note: 'No userId on session.' };
+            }
+            const result = await memoryService.searchMemory({
+                userId,
+                query,
+                limit: 10,
+            });
+            return {
+                memories: result.memories.map((m) => ({
+                    content: m.content,
+                    author: m.author,
+                    date: m.createdAt.toISOString(),
+                })),
+            };
+        },
+    });
+}
+//# sourceMappingURL=memory.js.map

package/dist/tools/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/tools/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC;QACV,WAAW,EACT,2FAA2F;YAC3F,4FAA4F;YAC5F,yDAAyD;QAC3D,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,CAAC,0CAA0C,CAAC;SACxD,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE;YACrD,MAAM,GAAG,GAAG,oBAA2D,CAAC;YACxE,MAAM,aAAa,GAAG,GAAG,EAAE,aAA8L,CAAC;YAC1N,MAAM,OAAO,GAAG,GAAG,EAAE,OAA0C,CAAC;YAChE,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;YAE/B,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnB,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAAC;YAClE,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;YACzD,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC;gBAC9C,MAAM;gBACN,KAAK;gBACL,KAAK,EAAE,EAAE;aACV,CAAC,CAAC;YAEH,OAAO;gBACL,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACpC,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE;iBAChC,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/types/index.d.ts

@@ -1,9 +1,20 @@
 import type { LanguageModel, ModelMessage, ToolSet, TelemetrySettings } from 'ai';
+export type { ToolSet } from 'ai';
 import type { ZodTypeAny } from 'zod';
 import type { SessionStore } from '../session/SessionStore.js';
 import type { ContextManager } from '../runtime/ContextManager.js';
-import type { PromptTemplate } from '../prompts/types.js';
+import type { MemoryService } from '../memory/MemoryService.js';
+import type { ContextBudgetConfig } from '../runtime/ContextBudget.js';
+import type { AgentDefinition } from '../foundation/AgentDefinition.js';
+import type { AgentPrompt } from '../prompts/AgentPrompt.js';
+import type { SessionEndMetadata } from './telemetry.js';
 export * from './telemetry.js';
+export interface SessionCacheConfig {
+    /** Maximum number of sessions to cache. Default: 100. */
+    maxEntries?: number;
+    /** Cache entry TTL in milliseconds. Default: 30000 (30s). */
+    ttlMs?: number;
+}
 export type ProcessorAction = 'allow' | 'modify' | 'block';
 export interface ProcessorContext {
     /** Session + agent info (when available). */
@@ -60,13 +71,13 @@ export interface ExtractionSnapshot {
     updatedAt: string;
     lastInput: string;
 }
-export interface AgentConfig {
-    id: string;
-    name: string;
-    description?: string;
-    systemPrompt: string | PromptTemplate;
+export interface AgentConfig extends AgentDefinition {
     model?: LanguageModel;
     tools?: ToolSet;
+    /**
+     * Agent prompt — a plain string or a structured AgentPrompt.
+     */
+    prompt?: string | AgentPrompt;
     /**
      * Optional manual overrides for tool criticality.
      * By default, all tools are considered critical unless specified here.
@@ -94,6 +105,8 @@ export interface AgentConfig {
     promptMemoryAllowlist?: string[];
     type?: string;
     telemetry?: TelemetrySettings;
+    /** Optional capability descriptor for agent routing. */
+    capability?: AgentCapabilityDescriptor;
 }
 export interface ExtractionConfig {
     /**
@@ -153,6 +166,8 @@ export interface FlowDetourRules {
     emergencyHandoffAgent?: string;
     allowShortAffirmations?: boolean;
     allowDateTime?: boolean;
+    /** Regex patterns matching expected on-flow inputs (e.g., phone numbers, emails). Skips LLM routing when matched. */
+    expectedInputPatterns?: string[];
 }
 export interface FlowAgentConfig extends AgentConfig {
     type: 'flow';
@@ -160,17 +175,46 @@ export interface FlowAgentConfig extends AgentConfig {
     initialNode: string;
     mode?: FlowAgentMode;
     detourRules?: FlowDetourRules;
+    /** Optional smaller/faster model for hybrid mode flow-vs-detour routing. Falls back to agent model. */
+    routingModel?: LanguageModel;
 }
 export interface TriageAgentConfig extends AgentConfig {
     type: 'triage';
     routes: AgentRoute[];
     defaultAgent?: string;
     triageMode?: 'llm' | 'structured';
+    /** Optional smaller/faster model for triage routing decisions. Falls back to agent model. */
+    routingModel?: LanguageModel;
+}
+export interface HandoffInputData {
+    /** The full message history at the point of handoff. */
+    messages: ModelMessage[];
+    /** The workingMemory state at the point of handoff. */
+    workingMemory: Record<string, unknown>;
+    /** The agent that initiated the handoff. */
+    sourceAgentId: string;
+    /** The agent that will receive the handoff. */
+    targetAgentId: string;
+    /** The reason provided by the LLM for the handoff, if any. */
+    reason?: string;
+}
+export interface HandoffInputResult {
+    /** The filtered message history to pass to the target agent. */
+    messages: ModelMessage[];
+    /** The filtered workingMemory to pass to the target agent. */
+    workingMemory: Record<string, unknown>;
 }
+export type HandoffInputFilter = (data: HandoffInputData) => Promise<HandoffInputResult> | HandoffInputResult;
 export interface AgentRoute {
     agentId: string;
     description: string;
     condition?: RouteCondition;
+    /**
+     * Optional filter applied to the session context before the target agent
+     * receives it. Use this to remove irrelevant tool history, trim messages,
+     * or summarize the prior conversation.
+     */
+    inputFilter?: HandoffInputFilter;
 }
 export type RouteCondition = (input: string, context: AgentContext) => Promise<boolean>;
 export interface AgentContext {
@@ -210,6 +254,8 @@ export interface SessionMetadata {
     totalTokens: number;
     totalSteps: number;
     handoffHistory: HandoffRecord[];
+    /** Whether the previous turn involved at least one tool call. */
+    lastTurnHadToolCalls?: boolean;
 }
 export interface AgentState {
     agentId: string;
@@ -292,7 +338,7 @@ export type AgentStreamPart = {
     error: string;
 };
 export interface FlowConfig {
-    nodes: FlowNodeConfig[];
+    nodes: (FlowNodeConfig | ExtractionNodeConfig)[];
     transitions?: FlowTransitionConfig[];
     defaultRolePrompt?: string;
     contextStrategy?: ContextStrategy;
@@ -304,8 +350,19 @@ export interface FlowConfig {
     summaryTimeoutMs?: number;
     /** Default maxSteps for tool loop / function calling in a node. */
     maxSteps?: number;
+    /**
+     * Max times the same from->to transition edge can fire within a single user turn
+     * before being blocked as oscillation. Prevents infinite ping-pong loops
+     * (e.g., triage->services->triage->services).
+     *
+     * When the limit is hit, the transition is blocked and the flow stays on the
+     * current node, allowing the LLM to respond directly instead of routing.
+     *
+     * Default: 2.
+     */
+    maxOscillations?: number;
 }
-export type FlowNodeType = 'start' | 'agent' | 'end' | 'global';
+export type FlowNodeType = 'start' | 'agent' | 'end' | 'global' | 'extraction';
 export interface FlowNodeConfig {
     id: string;
     name?: string;
@@ -351,7 +408,46 @@ export interface FlowNodeConfig {
      * Overrides agent-level extraction while this node is active.
      */
     extraction?: ExtractionConfig;
-}
+    /** Only include these keys from collectedData in the system prompt. Omit to include all (default). */
+    relevantFields?: string[];
+    /**
+     * Per-tool voice hints for realtime sessions.
+     * Appended to tool descriptions to guide the model on when/how to call each tool.
+     * Only used by FlowCapability for realtime prompt assembly — no effect on text mode.
+     */
+    toolHints?: Record<string, {
+        /** When to call this tool (e.g., "Call when the customer asks about products or prices.") */
+        invocationCondition?: string;
+        /** What to do after receiving the tool result (e.g., "Summarize matching products briefly.") */
+        afterResult?: string;
+    }>;
+    /** Optional Zod schema validating collectedData on node entry. Blocks transition if validation fails. */
+    inputSchema?: ZodTypeAny;
+    /** Optional Zod schema validating collectedData on node exit. Blocks transition if validation fails. */
+    outputSchema?: ZodTypeAny;
+}
+/**
+ * ExtractionNode: a first-class loop primitive that collects structured data
+ * across multiple turns until a Zod schema is fully satisfied.
+ * The schema IS the node definition -- no manual tool wiring needed.
+ */
+export interface ExtractionNodeConfig extends FlowNodeConfig {
+    nodeType: 'extraction';
+    /** Zod schema defining the data to collect. The node loops until safeParse() succeeds. */
+    extractionSchema: ZodTypeAny;
+    /** Subset of schema fields that must be present for completion. Defaults to all top-level keys. */
+    extractionRequiredFields?: string[];
+    /** Max turns before auto-transitioning with partial data. Default: 10. */
+    extractionMaxTurns?: number;
+    /** Node ID to auto-transition to when extraction is complete. */
+    extractionCompleteTransition?: string;
+    /** How to generate follow-up prompts. 'template' = zero LLM cost, 'llm' = natural language. Default: 'llm'. */
+    extractionPromptMode?: 'llm' | 'template';
+    /** Per-field prompt templates for template mode. Key = field name, value = prompt text. */
+    extractionFieldPrompts?: Record<string, string>;
+}
+/** Type guard for extraction nodes. */
+export declare function isExtractionNode(node: FlowNodeConfig): node is ExtractionNodeConfig;
 export interface FlowTransitionConfig {
     from: string;
     to: string;
@@ -459,6 +555,69 @@ export interface HarnessHooks {
      *
      */
     onStreamPart?: (context: RunContext, part: HarnessStreamPart) => Promise<void>;
+    /**
+     * Called when deferred persistence fails after all retry attempts.
+     *
+     * This hook is the safety net for `deferPersistence: true`. When the session
+     * store is unreachable (database down, network timeout), the session snapshot
+     * is passed to this hook so the caller can implement recovery (e.g., write to
+     * a dead-letter queue, log to a file, retry with a different store, alert ops).
+     *
+     * If this hook is not set, the error is logged to console.error and discarded.
+     *
+     * @param session - The session snapshot that failed to persist.
+     * @param error - The final error after all retries were exhausted.
+     */
+    onPersistenceError?: (session: Session, error: Error) => Promise<void>;
+    /**
+     * Called before a session is ingested into long-term memory.
+     * Return false to skip ingestion for this session.
+     */
+    onMemoryIngest?: (context: RunContext, session: Session) => Promise<boolean | void>;
+    /**
+     * Called after memory ingestion completes.
+     */
+    onMemoryIngested?: (context: RunContext, session: Session) => Promise<void>;
+    /**
+     * Called after the system prompt is fully assembled and messages are
+     * pruned, but before the LLM call is dispatched. The hook can inspect
+     * the complete request payload and optionally modify it.
+     *
+     * Return an object with systemPrompt and/or messages to override them.
+     * Return void or undefined to use the originals unchanged.
+     */
+    onBeforeModelCall?: (context: RunContext, data: BeforeModelCallData) => Promise<BeforeModelCallResult | void>;
+    /**
+     * Fires once after a session ends and has been persisted (e.g. OrchestrationAuthority.closeSession).
+     * Not invoked per chat turn for text Runtime — only when the session handle is closed.
+     */
+    onSessionEnd?: (session: Session, metadata: SessionEndMetadata) => Promise<void>;
+}
+export interface BeforeModelCallData {
+    /** The fully assembled system prompt string. */
+    systemPrompt: string;
+    /** The post-ContextManager pruned message history. */
+    messages: ModelMessage[];
+    /** Estimated total token count of systemPrompt + messages. */
+    estimatedTokens: number;
+    /** The agent that will receive this LLM call. */
+    agentId: string;
+    /** Breakdown of token usage by section. */
+    tokenBreakdown: {
+        basePrompt: number;
+        autoRetrieve: number;
+        workingMemory: number;
+        extraction: number;
+        longTermMemory: number;
+        policyInjections: number;
+        messageHistory: number;
+    };
+}
+export interface BeforeModelCallResult {
+    /** Modified system prompt. If omitted, the original is used. */
+    systemPrompt?: string;
+    /** Modified message history. If omitted, the original is used. */
+    messages?: ModelMessage[];
 }
 export type InjectionPriority = 'critical' | 'high' | 'medium' | 'low';
 export type InjectionLevel = 'system' | 'message' | 'tool';
@@ -565,6 +724,12 @@ export interface HarnessConfig {
     agents: AgentConfig[];
     defaultAgentId: string;
     defaultModel?: LanguageModel;
+    /**
+     * Optional dedicated text model used to verify realtime extraction-node data.
+     * When omitted, realtime falls back to a conservative guard instead of full
+     * extraction-model parity.
+     */
+    extractionModel?: LanguageModel;
     maxSteps?: number;
     maxHandoffs?: number;
     /**
@@ -629,12 +794,69 @@ export interface HarnessConfig {
     /** Number of suggestions to generate. Default is 3. */
     suggestionCount?: number;
     telemetry?: TelemetrySettings;
+    /**
+     * Enable layered prompting with PromptBuilder.
+     * When true, system prompts are built using PromptBuilder with automatic layers:
+     * - Security Core (immutable)
+     * - Identity & Role (from agent)
+     * - Tools (auto from agent)
+     * - Session Memory (auto)
+     * - Security Reminder (immutable)
+     * Default: false (backward compatible)
+     */
+    layeredPrompting?: boolean;
+    /**
+     * Optional memory service for cross-session long-term memory.
+     * When provided, enables memory tools and session-end ingestion.
+     * Requires userId to be passed via stream() for memory to function.
+     */
+    memoryService?: MemoryService;
+    /**
+     * Controls automatic memory ingestion behavior.
+     * Only applies when memoryService is configured.
+     * - 'onEnd': Ingest session into memory when stream() completes (default)
+     * - 'manual': Developer must call memoryService.addSessionToMemory() explicitly
+     * - 'hook': Fires onMemoryIngest hook, letting the developer decide
+     */
+    memoryIngestion?: 'onEnd' | 'manual' | 'hook';
+    /**
+     * Whether to automatically preload relevant memories into system prompt.
+     * Default: true (when memoryService is provided)
+     */
+    preloadMemory?: boolean;
+    /**
+     * Context budget configuration. Controls how the finite LLM context window
+     * is allocated across the multiple content sources that compose the system
+     * prompt and message history.
+     */
+    contextBudget?: Partial<ContextBudgetConfig>;
+    /**
+     * Optional LRU session cache. Reduces repeated SessionStore lookups
+     * for same-process reads (~10-90ms per warm turn).
+     * When provided, sessions are cached in-memory and invalidated by TTL.
+     */
+    sessionCache?: SessionCacheConfig;
+    /**
+     * When true, the 'done' event is emitted before session persistence completes.
+     * Persistence runs in the background on a cloned session snapshot with retry
+     * (3 attempts, exponential backoff). On final failure, the onPersistenceError
+     * hook is called if configured.
+     *
+     * When false, the 'done' event is blocked until persistence completes. This
+     * adds 10-200ms latency per turn but guarantees the session is saved before
+     * the client receives the done signal.
+     *
+     * Default: true.
+     */
+    deferPersistence?: boolean;
 }
 export interface StreamOptions {
     input: string;
     sessionId?: string;
     userId?: string;
     abortSignal?: AbortSignal;
+    /** Force a specific agent ID, bypassing triage routing */
+    agentId?: string;
 }
 export interface AbortOptions {
     reason?: string;
@@ -649,6 +871,12 @@ export interface InterruptionEvent {
     lastStep?: number;
 }
 export type CancellationReason = 'user_interrupt' | 'timeout' | 'shutdown' | 'custom';
+export interface AgentCapabilityDescriptor {
+    summary: string;
+    keywords: string[];
+    handlesIntents?: string[];
+    doesNotHandle?: string[];
+}
 export declare function isAbortSignal(signal: unknown): signal is AbortSignal;
 export type HarnessStreamPart = {
     type: 'input';
@@ -752,5 +980,6 @@ export type HarnessStreamPart = {
 } | {
     type: 'done';
     sessionId: string;
+    userId?: string;
 };
 //# sourceMappingURL=index.d.ts.map