@ariaflowagents/core 0.7.0 → 0.8.1

package/dist/memory/MemoryService.d.ts

@@ -0,0 +1,40 @@
+import type { Session } from '../types/index.js';
+import type { MemoryIngestionOptions, SearchMemoryRequest, SearchMemoryResponse } from './types.js';
+/**
+ * Interface for cross-session long-term memory.
+ *
+ * MemoryService is the counterpart to SessionStore:
+ * - SessionStore manages per-session state (messages, workingMemory, agentStates)
+ * - MemoryService manages cross-session knowledge (facts, summaries, preferences)
+ *
+ * The service has two responsibilities:
+ * 1. Ingestion — converting session data into searchable memories
+ * 2. Retrieval — finding relevant memories for a given query
+ */
+export interface MemoryService {
+    /**
+     * Ingest a session into long-term memory.
+     *
+     * Typically called when a session ends or reaches a meaningful checkpoint.
+     * Implementations may store raw events, extract facts via LLM, or summarize.
+     * A session may be ingested multiple times (implementations must handle idempotency).
+     *
+     * @param session - The session to ingest
+     * @param options - Optional ingestion configuration
+     */
+    addSessionToMemory(session: Session, options?: MemoryIngestionOptions): Promise<void>;
+    /**
+     * Search long-term memory for relevant context.
+     *
+     * Returns memories scoped to a specific user within an application context.
+     * Implementations may use keyword matching, semantic search, or hybrid approaches.
+     *
+     * @param request - Search parameters (userId, query, optional filters)
+     */
+    searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+    /**
+     * Delete all memories for a user. Used for GDPR compliance / data cleanup.
+     */
+    deleteMemories?(userId: string): Promise<void>;
+}
+//# sourceMappingURL=MemoryService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryService.d.ts","sourceRoot":"","sources":["../../src/memory/MemoryService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEpG;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;OASG;IACH,kBAAkB,CAChB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE1E;;OAEG;IACH,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD"}

package/dist/memory/MemoryService.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=MemoryService.js.map

package/dist/memory/MemoryService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryService.js","sourceRoot":"","sources":["../../src/memory/MemoryService.ts"],"names":[],"mappings":""}

package/dist/memory/index.d.ts

@@ -0,0 +1,5 @@
+export type { MemoryService } from './MemoryService.js';
+export type { MemoryEntry, SearchMemoryRequest, SearchMemoryResponse, MemoryIngestionOptions, } from './types.js';
+export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
+export { preloadMemoryContext } from './preloadMemory.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/memory/index.js

@@ -0,0 +1,3 @@
+export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
+export { preloadMemoryContext } from './preloadMemory.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/memory/preloadMemory.d.ts

@@ -0,0 +1,17 @@
+import type { Session } from '../types/index.js';
+import type { MemoryService } from './MemoryService.js';
+/**
+ * Preloads relevant memories into the system prompt before each LLM call.
+ *
+ * This is NOT a tool the LLM calls. It is a Runtime-level middleware that:
+ * 1. Takes the user's latest message as a search query
+ * 2. Searches long-term memory for relevant context
+ * 3. Formats matching memories as a markdown section
+ * 4. Truncates the output to fit within the allocated token budget
+ *
+ * The maxTokens parameter is mandatory. If the formatted output exceeds
+ * maxTokens, memories are dropped in lowest-relevance-first order until
+ * the output fits.
+ */
+export declare function preloadMemoryContext(memoryService: MemoryService, session: Session, userInput: string, maxTokens: number): Promise<string | null>;
+//# sourceMappingURL=preloadMemory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preloadMemory.d.ts","sourceRoot":"","sources":["../../src/memory/preloadMemory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAWxD;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA2CxB"}

package/dist/memory/preloadMemory.js

@@ -0,0 +1,62 @@
+/**
+ * Token estimation function. Matches the estimator used in ContextManager.ts:
+ * Math.ceil(text.length / 4).
+ */
+function estimateTokenCount(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Preloads relevant memories into the system prompt before each LLM call.
+ *
+ * This is NOT a tool the LLM calls. It is a Runtime-level middleware that:
+ * 1. Takes the user's latest message as a search query
+ * 2. Searches long-term memory for relevant context
+ * 3. Formats matching memories as a markdown section
+ * 4. Truncates the output to fit within the allocated token budget
+ *
+ * The maxTokens parameter is mandatory. If the formatted output exceeds
+ * maxTokens, memories are dropped in lowest-relevance-first order until
+ * the output fits.
+ */
+export async function preloadMemoryContext(memoryService, session, userInput, maxTokens) {
+    if (!session.userId)
+        return null;
+    if (maxTokens <= 0)
+        return null;
+    const result = await memoryService.searchMemory({
+        userId: session.userId,
+        query: userInput,
+        limit: 10,
+    });
+    if (result.memories.length === 0)
+        return null;
+    const headerLines = [
+        '## Context from Past Conversations',
+        '',
+        'The following is from previous conversations with this user.',
+        'Use this context to provide continuity and avoid asking for information the user has already provided.',
+        '',
+    ];
+    const header = headerLines.join('\n');
+    let estimatedTokens = estimateTokenCount(header);
+    const includedLines = [];
+    for (const m of result.memories) {
+        const author = m.author ? `${m.author}: ` : '';
+        const date = m.createdAt
+            ? `[${m.createdAt.toISOString().split('T')[0]}] `
+            : '';
+        const line = `${date}${author}${m.content}`;
+        const lineTokens = estimateTokenCount(line);
+        if (estimatedTokens + lineTokens > maxTokens) {
+            break;
+        }
+        includedLines.push(line);
+        estimatedTokens += lineTokens;
+    }
+    if (includedLines.length === 0)
+        return null;
+    return header + includedLines.join('\n');
+}
+//# sourceMappingURL=preloadMemory.js.map

package/dist/memory/preloadMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preloadMemory.js","sourceRoot":"","sources":["../../src/memory/preloadMemory.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,aAA4B,EAC5B,OAAgB,EAChB,SAAiB,EACjB,SAAiB;IAEjB,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC;QAC9C,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,EAAE;KACV,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,MAAM,WAAW,GAAG;QAClB,oCAAoC;QACpC,EAAE;QACF,8DAA8D;QAC9D,wGAAwG;QACxG,EAAE;KACH,CAAC;IACF,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,eAAe,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAEjD,MAAM,aAAa,GAAa,EAAE,CAAC;IAEnC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,CAAC,CAAC,SAAS;YACtB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;YACjD,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,GAAG,GAAG,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;QAC5C,MAAM,UAAU,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QAE5C,IAAI,eAAe,GAAG,UAAU,GAAG,SAAS,EAAE,CAAC;YAC7C,MAAM;QACR,CAAC;QAED,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,eAAe,IAAI,UAAU,CAAC;IAChC,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,OAAO,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC"}

package/dist/memory/stores/InMemoryMemoryService.d.ts

@@ -0,0 +1,20 @@
+import type { Session } from '../../types/index.js';
+import type { MemoryService } from '../MemoryService.js';
+import type { MemoryIngestionOptions, SearchMemoryRequest, SearchMemoryResponse } from '../types.js';
+/**
+ * In-memory implementation of MemoryService for development and testing.
+ *
+ * Uses keyword-based search with term overlap scoring.
+ * All data is stored in-process and lost on restart.
+ */
+export declare class InMemoryMemoryService implements MemoryService {
+    /**
+     * In-memory storage indexed by userId.
+     * Each user has a map of sessionId → MemoryEntry[].
+     */
+    private memories;
+    addSessionToMemory(session: Session, options?: MemoryIngestionOptions): Promise<void>;
+    searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+    deleteMemories(userId: string): Promise<void>;
+}
+//# sourceMappingURL=InMemoryMemoryService.d.ts.map

package/dist/memory/stores/InMemoryMemoryService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryMemoryService.d.ts","sourceRoot":"","sources":["../../../src/memory/stores/InMemoryMemoryService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAEV,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AA6BrB;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAsD;IAEhE,kBAAkB,CACtB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC;IA2BV,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA2BzE,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGpD"}

package/dist/memory/stores/InMemoryMemoryService.js

@@ -0,0 +1,92 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Extracts plain text from a message content field.
+ * Handles both string content and array content parts.
+ */
+function extractTextFromMessage(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    if (Array.isArray(message.content)) {
+        return message.content
+            .filter((part) => part.type === 'text')
+            .map((part) => part.text)
+            .join('\n');
+    }
+    return '';
+}
+/**
+ * Extracts lowercase words from text as a Set for fast lookup.
+ */
+function extractWordsLower(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean));
+}
+/**
+ * In-memory implementation of MemoryService for development and testing.
+ *
+ * Uses keyword-based search with term overlap scoring.
+ * All data is stored in-process and lost on restart.
+ */
+export class InMemoryMemoryService {
+    /**
+     * In-memory storage indexed by userId.
+     * Each user has a map of sessionId → MemoryEntry[].
+     */
+    memories = new Map();
+    async addSessionToMemory(session, options) {
+        if (!session.userId)
+            return;
+        const entries = [];
+        for (const message of session.messages) {
+            if (message.role !== 'user' && message.role !== 'assistant')
+                continue;
+            const text = extractTextFromMessage(message);
+            if (!text.trim())
+                continue;
+            entries.push({
+                id: randomUUID(),
+                sessionId: session.id,
+                userId: session.userId,
+                content: text,
+                author: message.role === 'user' ? 'user' : 'assistant',
+                metadata: options?.metadata,
+                createdAt: new Date(),
+            });
+        }
+        // Idempotency: delete existing entries for this session before re-ingesting
+        const userMemories = this.memories.get(session.userId) ?? new Map();
+        userMemories.set(session.id, entries);
+        this.memories.set(session.userId, userMemories);
+    }
+    async searchMemory(request) {
+        const userMemories = this.memories.get(request.userId);
+        if (!userMemories)
+            return { memories: [] };
+        const queryWords = extractWordsLower(request.query);
+        if (queryWords.size === 0)
+            return { memories: [] };
+        const matches = [];
+        for (const entries of userMemories.values()) {
+            for (const entry of entries) {
+                const entryWords = extractWordsLower(entry.content);
+                let matchCount = 0;
+                for (const w of queryWords) {
+                    if (entryWords.has(w))
+                        matchCount++;
+                }
+                if (matchCount > 0) {
+                    matches.push({ ...entry, score: matchCount / queryWords.size });
+                }
+            }
+        }
+        // Sort by relevance score descending
+        matches.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+        return { memories: matches.slice(0, request.limit ?? 10) };
+    }
+    async deleteMemories(userId) {
+        this.memories.delete(userId);
+    }
+}
+//# sourceMappingURL=InMemoryMemoryService.js.map

package/dist/memory/stores/InMemoryMemoryService.js.map

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

package/dist/memory/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Types for the cross-session long-term memory system.
+ *
+ * These types define the data structures used by MemoryService implementations
+ * for storing, searching, and managing cross-session knowledge.
+ */
+export interface MemoryEntry {
+    /** Unique identifier for this memory */
+    id: string;
+    /** The session this memory was derived from */
+    sessionId: string;
+    /** The user this memory belongs to */
+    userId: string;
+    /** The memory content (extracted fact, summary, or raw text) */
+    content: string;
+    /** Who authored the original content: 'user' | 'assistant' | agent name */
+    author?: string;
+    /** Structured metadata for filtering */
+    metadata?: Record<string, unknown>;
+    /** When the memory was created */
+    createdAt: Date;
+    /** Relevance score (populated by search, not storage) */
+    score?: number;
+}
+export interface SearchMemoryRequest {
+    /** Required: whose memories to search */
+    userId: string;
+    /** The search query */
+    query: string;
+    /** Max results to return (default: 10) */
+    limit?: number;
+    /** Optional metadata filters */
+    filter?: Record<string, unknown>;
+}
+export interface SearchMemoryResponse {
+    memories: MemoryEntry[];
+}
+export interface MemoryIngestionOptions {
+    /** Custom metadata to attach to all memories from this session */
+    metadata?: Record<string, unknown>;
+    /**
+     * Ingestion strategy:
+     * - 'raw': Store message content as-is (default for InMemoryMemoryService)
+     * - 'summarize': Use LLM to summarize the session before storing
+     * - 'extract': Use LLM to extract individual facts/entities
+     */
+    strategy?: 'raw' | 'summarize' | 'extract';
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IAEX,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAElB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IAEf,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAEhB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,kCAAkC;IAClC,SAAS,EAAE,IAAI,CAAC;IAEhB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IAEf,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IAEd,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC;CAC5C"}

package/dist/memory/types.js

@@ -0,0 +1,8 @@
+/**
+ * Types for the cross-session long-term memory system.
+ *
+ * These types define the data structures used by MemoryService implementations
+ * for storing, searching, and managing cross-session knowledge.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/prompts/AgentPrompt.d.ts

@@ -0,0 +1,110 @@
+/**
+ * AgentPrompt — Developer-facing class for structured prompt assembly.
+ *
+ * Provides a chainable API for composing agent prompts with automatic
+ * security sandwiching, priority-based ordering, and XML-tagged rendering.
+ *
+ * @example
+ * ```ts
+ * const prompt = new AgentPrompt()
+ *   .role('You are a helpful customer support agent.')
+ *   .instructions('Help customers with billing and account issues.')
+ *   .guardrails('Never share internal pricing or discount formulas.')
+ *   .knowledge(async () => fetchKnowledgeBase())
+ *   .tools(myToolSet);
+ *
+ * const systemPrompt = await prompt.render();
+ * ```
+ *
+ * @module
+ */
+import type { ToolSet } from '../tools/Tool.js';
+import type { GlossaryTerm, VoiceRulesConfig, PolicyProfile } from './types.js';
+import { PromptAssembly } from './PromptAssembly.js';
+import type { AssemblyDebugInfo } from './PromptAssembly.js';
+/**
+ * Configuration for the AgentPrompt constructor.
+ */
+export interface AgentPromptConfig {
+    /** Security policy profile. Defaults to 'minimal'. */
+    policy?: PolicyProfile;
+    /** Whether to wrap sections in XML tags. Defaults to true. */
+    xmlTags?: boolean;
+    /** Maximum token budget for the rendered prompt. */
+    maxTokens?: number;
+    /** Disable automatic security core and reminder sections. Defaults to false. */
+    disableSecurity?: boolean;
+}
+/**
+ * Developer-facing prompt builder with a chainable API.
+ *
+ * Internally creates a {@link PromptAssembly}, injects security core (priority 0)
+ * and security reminder (priority 1000), then freezes security bands.
+ *
+ * All chainable methods accept either a static string or an async function
+ * that resolves to a string.
+ */
+export declare class AgentPrompt {
+    private readonly _assembly;
+    private readonly renderOptions;
+    constructor(config?: AgentPromptConfig);
+    /**
+     * Sets the agent's role description. Priority 10, non-shrinkable.
+     */
+    role(content: string | (() => Promise<string>)): this;
+    /**
+     * Sets the agent's instructions. Priority 15, non-shrinkable.
+     */
+    instructions(content: string | (() => Promise<string>)): this;
+    /**
+     * Sets guardrail rules. Priority 20, non-shrinkable.
+     */
+    guardrails(content: string | (() => Promise<string>)): this;
+    /**
+     * Sets voice/personality description. Priority 25, shrinkable.
+     */
+    voice(content: string | (() => Promise<string>)): this;
+    /**
+     * Injects knowledge context. Priority 30, shrinkable.
+     */
+    knowledge(content: string | (() => Promise<string>)): this;
+    /**
+     * Sets business/domain rules. Priority 35, shrinkable.
+     */
+    rules(content: string | (() => Promise<string>)): this;
+    /**
+     * Adds a glossary of domain terms. Priority 38, shrinkable.
+     * Terms are auto-formatted into a structured list.
+     */
+    glossary(terms: GlossaryTerm[]): this;
+    /**
+     * Generates tool descriptions from a ToolSet. Priority 40, shrinkable.
+     */
+    tools(toolSet: ToolSet): this;
+    /**
+     * Sets voice/TTS output rules. Priority 45, shrinkable.
+     * Uses the same formatting logic as PromptTemplateBuilder.formatVoiceRules.
+     */
+    voiceRules(config: VoiceRulesConfig): this;
+    /**
+     * Adds example interactions or few-shot prompts. Priority 50, shrinkable.
+     */
+    examples(content: string | (() => Promise<string>)): this;
+    /**
+     * Adds an arbitrary named section. Defaults to priority 60, shrinkable.
+     */
+    section(type: string, content: string | (() => Promise<string>), priority?: number): this;
+    /**
+     * Resolves all sections and renders the prompt to a string.
+     */
+    render(): Promise<string>;
+    /**
+     * Returns debug information about the assembly's current state.
+     */
+    debug(): Promise<AssemblyDebugInfo>;
+    /**
+     * Exposes the underlying PromptAssembly for runtime injection.
+     */
+    get assembly(): PromptAssembly;
+}
+//# sourceMappingURL=AgentPrompt.d.ts.map

package/dist/prompts/AgentPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentPrompt.d.ts","sourceRoot":"","sources":["../../src/prompts/AgentPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAQ7D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAMD;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAElC,MAAM,GAAE,iBAAsB;IA0C1C;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAYrD;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAY7D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAY3D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAYtD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAY1D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAYtD;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI;IAarC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAa7B;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAa1C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAYzD;;OAEG;IACH,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,EACzC,QAAQ,SAAK,GACZ,IAAI;IAgBP;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAK/B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIzC;;OAEG;IACH,IAAI,QAAQ,IAAI,cAAc,CAE7B;CACF"}