@revealui/ai 0.1.0

package/dist/orchestration/streaming-runtime.js

@@ -0,0 +1,175 @@
+/**
+ * Streaming Agent Runtime
+ *
+ * Extends AgentRuntime with SSE-compatible streaming via LLMClient.stream().
+ * Each yielded AgentStreamChunk maps to one SSE event.
+ *
+ * AnythingLLM lesson: SSE is the correct approach for unidirectional LLM output.
+ * EventSource is not used client-side because it doesn't support POST — use fetch + ReadableStream.
+ */
+import { z } from 'zod/v4';
+import { ToolCallDeduplicator } from '../tools/deduplicator.js';
+import { AgentRuntime } from './runtime.js';
+export class StreamingAgentRuntime extends AgentRuntime {
+    constructor(config = {}) {
+        super(config);
+    }
+    /**
+     * Stream a task execution, yielding typed events as they occur.
+     * Accepts an AbortSignal — on abort, emits an error event and stops.
+     */
+    async *streamTask(agent, task, llmClient, signal) {
+        const startTime = Date.now();
+        const toolResults = [];
+        const deduplicator = new ToolCallDeduplicator();
+        let iterations = 0;
+        const maxIterations = this.config.maxIterations ?? 10;
+        const timeout = this.config.timeout ?? 60_000;
+        const messages = [
+            {
+                role: 'system',
+                content: agent.instructions,
+                cacheControl: { type: 'ephemeral' },
+            },
+            {
+                role: 'user',
+                content: task.description,
+            },
+        ];
+        try {
+            while (iterations < maxIterations) {
+                iterations++;
+                if (signal?.aborted) {
+                    yield { type: 'error', error: 'interrupted' };
+                    return;
+                }
+                if (Date.now() - startTime > timeout) {
+                    yield { type: 'error', error: 'Task execution timeout' };
+                    return;
+                }
+                // Accumulate streamed text and all tool calls
+                let accumulatedContent = '';
+                let pendingToolCalls = [];
+                try {
+                    for await (const chunk of llmClient.stream(messages, {
+                        tools: agent.tools.map((tool) => ({
+                            type: 'function',
+                            function: {
+                                name: tool.name,
+                                description: tool.description,
+                                parameters: z.toJSONSchema(tool.parameters),
+                            },
+                        })),
+                    })) {
+                        if (signal?.aborted) {
+                            yield { type: 'error', error: 'interrupted' };
+                            return;
+                        }
+                        // Stream text content
+                        if (chunk.content) {
+                            accumulatedContent += chunk.content;
+                            yield { type: 'text', content: chunk.content };
+                        }
+                        // Collect all tool calls when streaming is complete
+                        if (chunk.toolCalls && chunk.toolCalls.length > 0 && chunk.done) {
+                            pendingToolCalls = chunk.toolCalls.map((tc) => ({
+                                name: tc.function.name,
+                                arguments: tc.function.arguments,
+                                id: tc.id,
+                            }));
+                        }
+                    }
+                }
+                catch (streamError) {
+                    yield {
+                        type: 'error',
+                        error: streamError instanceof Error ? streamError.message : String(streamError),
+                    };
+                    return;
+                }
+                // If no tool calls, task is complete
+                if (pendingToolCalls.length === 0) {
+                    yield {
+                        type: 'done',
+                        content: accumulatedContent,
+                        metadata: { executionTime: Date.now() - startTime },
+                    };
+                    return;
+                }
+                // Push the assistant message with all tool calls
+                messages.push({
+                    role: 'assistant',
+                    content: accumulatedContent,
+                    toolCalls: pendingToolCalls,
+                });
+                // Execute all tool calls in this response
+                for (const tc of pendingToolCalls) {
+                    yield { type: 'tool_call_start', toolCall: { name: tc.name, arguments: tc.arguments } };
+                    const tool = agent.tools.find((t) => t.name === tc.name);
+                    if (!tool) {
+                        const result = { success: false, error: `Tool "${tc.name}" not found` };
+                        toolResults.push(result);
+                        yield { type: 'tool_call_result', toolResult: result };
+                        messages.push({
+                            role: 'tool',
+                            content: result.content ?? JSON.stringify(result.data ?? result),
+                            toolCallId: tc.id,
+                        });
+                        continue;
+                    }
+                    let params;
+                    try {
+                        params = JSON.parse(tc.arguments || '{}');
+                    }
+                    catch {
+                        params = {};
+                    }
+                    // Deduplication check
+                    if (deduplicator.isDuplicate(tc.name, params)) {
+                        const cached = deduplicator.getResult(tc.name, params);
+                        toolResults.push(cached);
+                        yield { type: 'tool_call_result', toolResult: cached };
+                        messages.push({
+                            role: 'tool',
+                            content: cached.content ?? JSON.stringify(cached.data ?? cached),
+                            toolCallId: tc.id,
+                        });
+                        continue;
+                    }
+                    try {
+                        const result = await tool.execute(params);
+                        deduplicator.record(tc.name, params, result);
+                        toolResults.push(result);
+                        yield { type: 'tool_call_result', toolResult: result };
+                        messages.push({
+                            role: 'tool',
+                            content: result.content ?? JSON.stringify(result.data ?? result),
+                            toolCallId: tc.id,
+                        });
+                    }
+                    catch (toolError) {
+                        const result = {
+                            success: false,
+                            error: toolError instanceof Error ? toolError.message : String(toolError),
+                        };
+                        toolResults.push(result);
+                        yield { type: 'tool_call_result', toolResult: result };
+                        messages.push({
+                            role: 'tool',
+                            content: result.content ?? JSON.stringify(result.data ?? result),
+                            toolCallId: tc.id,
+                        });
+                    }
+                }
+            }
+            yield { type: 'error', error: 'Maximum iterations reached' };
+        }
+        catch (error) {
+            yield {
+                type: 'error',
+                error: error instanceof Error ? error.message : String(error),
+                metadata: { executionTime: Date.now() - startTime },
+            };
+        }
+    }
+}

package/dist/orchestration/ticket-agent.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Ticket Agent Bridge
+ *
+ * Closes the loop between the ticketing system and the AI agent system.
+ *
+ * Flow:
+ *   Ticket (title + description) → Task → Agent (CMS tools + ticket tools)
+ *   → agentic loop → CMS mutations + ticket status updated + comment written
+ *
+ * Usage:
+ *   const dispatcher = new TicketAgentDispatcher({ llmClient, apiClient, ticketClient })
+ *   const result = await dispatcher.dispatch(ticket)
+ */
+import type { Database } from '@revealui/db/client';
+import type { LLMClient } from '../llm/client.js';
+import type { EpisodicMemory } from '../memory/stores/episodic-memory.js';
+import type { CMSAPIClient, CollectionMetadata, GlobalMetadata } from '../tools/cms/factory.js';
+import type { TicketMutationClient } from '../tools/ticket-tools.js';
+import type { AgentResult } from './agent.js';
+export interface TicketInput {
+    id: string;
+    title: string;
+    /** Rich text or plain text description. Plain strings are used directly; objects are JSON-stringified. */
+    description: unknown;
+    type?: string;
+    priority?: string;
+}
+export interface TicketAgentConfig {
+    /** LLM client (Anthropic, OpenAI, etc.) */
+    llmClient: LLMClient;
+    /** CMS API client — used to inject into CMS tools */
+    apiClient: CMSAPIClient;
+    /** Ticket mutation client — used to update status and add comments */
+    ticketClient: TicketMutationClient;
+    /** Available CMS collections (optional, improves tool descriptions) */
+    collections?: CollectionMetadata[];
+    /** Available CMS globals (optional) */
+    globals?: GlobalMetadata[];
+    /**
+     * Memory instance to share across dispatches (optional).
+     * If omitted, each dispatch uses a no-op stub — the runtime does not
+     * call agent.memory directly, so this is safe for stateless dispatch.
+     */
+    memory?: EpisodicMemory;
+    /**
+     * Database client — enables the document_summarize tool.
+     * If omitted, the summarizer tool is not included in the agent's toolset.
+     */
+    db?: Database;
+    /** Max iterations for the agentic loop (default: 10) */
+    maxIterations?: number;
+    /** Timeout in ms (default: 120_000) */
+    timeout?: number;
+}
+export declare class TicketAgentDispatcher {
+    private config;
+    private orchestrator;
+    constructor(config: TicketAgentConfig);
+    /**
+     * Dispatch a ticket to the agent and await the result.
+     *
+     * The agent will:
+     * - Receive the ticket as its task description
+     * - Have access to all CMS tools (create/update/delete content, globals, media, users)
+     * - Have access to ticket mutation tools (update status, add comment)
+     * - Run the agentic loop until done or max iterations
+     */
+    dispatch(ticket: TicketInput): Promise<AgentResult>;
+}
+//# sourceMappingURL=ticket-agent.d.ts.map

package/dist/orchestration/ticket-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket-agent.d.ts","sourceRoot":"","sources":["../../src/orchestration/ticket-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAA;AACzE,OAAO,KAAK,EACV,YAAY,EAEZ,kBAAkB,EAClB,cAAc,EACf,MAAM,yBAAyB,CAAA;AAGhC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAGpE,OAAO,KAAK,EAAS,WAAW,EAAQ,MAAM,YAAY,CAAA;AAG1D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,0GAA0G;IAC1G,WAAW,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,SAAS,EAAE,SAAS,CAAA;IAEpB,qDAAqD;IACrD,SAAS,EAAE,YAAY,CAAA;IAEvB,sEAAsE;IACtE,YAAY,EAAE,oBAAoB,CAAA;IAElC,uEAAuE;IACvE,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAElC,uCAAuC;IACvC,OAAO,CAAC,EAAE,cAAc,EAAE,CAAA;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;IAEvB;;;OAGG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAA;IAEb,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAwDD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,YAAY,CAAmB;gBAE3B,MAAM,EAAE,iBAAiB;IAUrC;;;;;;;;OAQG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAsD1D"}

package/dist/orchestration/ticket-agent.js

@@ -0,0 +1,146 @@
+/**
+ * Ticket Agent Bridge
+ *
+ * Closes the loop between the ticketing system and the AI agent system.
+ *
+ * Flow:
+ *   Ticket (title + description) → Task → Agent (CMS tools + ticket tools)
+ *   → agentic loop → CMS mutations + ticket status updated + comment written
+ *
+ * Usage:
+ *   const dispatcher = new TicketAgentDispatcher({ llmClient, apiClient, ticketClient })
+ *   const result = await dispatcher.dispatch(ticket)
+ */
+import { createCMSTools } from '../tools/cms/factory.js';
+import { createDocumentSummarizerTool } from '../tools/document-summarizer.js';
+import { createTicketTools } from '../tools/ticket-tools.js';
+import { webScraperTool } from '../tools/web/scraper.js';
+import { AgentOrchestrator } from './orchestrator.js';
+/**
+ * Converts a ticket's description field to a plain string the LLM can use.
+ * Handles: string, Lexical/Slate rich text JSON objects, null, undefined.
+ */
+function descriptionToString(description) {
+    if (!description)
+        return '';
+    if (typeof description === 'string')
+        return description;
+    if (typeof description === 'object') {
+        // Extract text nodes from a simple Lexical-style document
+        try {
+            const json = description;
+            if (json.root && typeof json.root === 'object') {
+                const root = json.root;
+                const texts = [];
+                const walk = (nodes) => {
+                    for (const node of nodes) {
+                        const n = node;
+                        if (typeof n.text === 'string')
+                            texts.push(n.text);
+                        if (Array.isArray(n.children))
+                            walk(n.children);
+                    }
+                };
+                if (Array.isArray(root.children))
+                    walk(root.children);
+                return texts.join(' ').trim();
+            }
+        }
+        catch {
+            // fall through
+        }
+        return JSON.stringify(description);
+    }
+    return String(description);
+}
+/**
+ * Build the agent system prompt from a ticket.
+ */
+function buildInstructions(ticket) {
+    return `You are a RevealUI content agent. You have been assigned a ticket and must complete it.
+
+Your job is to:
+1. Understand the intent of the ticket
+2. Use the available CMS tools to take the necessary actions (create, update, or delete content)
+3. When your work is done, call add_ticket_comment to summarize what you did
+4. Finally, call update_ticket_status with status="done"
+5. If you cannot complete the task, call add_ticket_comment to explain why, then update_ticket_status with status="blocked"
+
+Always prefer taking action over asking questions. If you are uncertain about details, make reasonable assumptions and document them in your comment.
+
+Ticket: #${ticket.id}
+Title: ${ticket.title}
+Type: ${ticket.type ?? 'task'}
+Priority: ${ticket.priority ?? 'medium'}
+`.trim();
+}
+export class TicketAgentDispatcher {
+    config;
+    orchestrator;
+    constructor(config) {
+        this.config = config;
+        this.orchestrator = new AgentOrchestrator({
+            maxConcurrentAgents: 1,
+            taskTimeout: config.timeout ?? 120_000,
+            retryOnFailure: false,
+        });
+        this.orchestrator.setLLMClient(config.llmClient);
+    }
+    /**
+     * Dispatch a ticket to the agent and await the result.
+     *
+     * The agent will:
+     * - Receive the ticket as its task description
+     * - Have access to all CMS tools (create/update/delete content, globals, media, users)
+     * - Have access to ticket mutation tools (update status, add comment)
+     * - Run the agentic loop until done or max iterations
+     */
+    async dispatch(ticket) {
+        const { apiClient, ticketClient, collections, globals, memory: sharedMemory, db } = this.config;
+        // Build tool set: CMS tools + ticket mutation tools + web scraper + optional summarizer
+        const cmsConfig = { apiClient, collections, globals };
+        const cmsTools = createCMSTools(cmsConfig);
+        const ticketTools = createTicketTools(ticket.id, ticketClient);
+        const extraTools = db
+            ? [webScraperTool, createDocumentSummarizerTool(db, this.config.llmClient)]
+            : [webScraperTool];
+        const tools = [...cmsTools, ...ticketTools, ...extraTools];
+        // The runtime does not call agent.memory — satisfy the interface with a stub when no
+        // shared memory instance is provided. Cast is safe: only runtime touches this field.
+        const memory = (sharedMemory ?? {});
+        const agent = {
+            id: `ticket-agent-${ticket.id}`,
+            name: 'Ticket Agent',
+            instructions: buildInstructions(ticket),
+            tools,
+            memory,
+            getContext() {
+                return {
+                    agentId: `ticket-agent-${ticket.id}`,
+                    currentTask: {
+                        id: ticket.id,
+                        type: ticket.type ?? 'cms',
+                        description: descriptionToString(ticket.description),
+                    },
+                };
+            },
+        };
+        // Register the agent (fresh orchestrator per dispatch is fine for now)
+        this.orchestrator.registerAgent(agent);
+        const descriptionText = descriptionToString(ticket.description);
+        const taskDescription = descriptionText ? `${ticket.title}\n\n${descriptionText}` : ticket.title;
+        const task = {
+            id: ticket.id,
+            type: ticket.type ?? 'cms',
+            description: taskDescription,
+            priority: ticket.priority === 'critical' ? 1 : ticket.priority === 'high' ? 2 : 3,
+        };
+        try {
+            return await this.orchestrator.delegateTask(task, agent.id);
+        }
+        finally {
+            // Clean up so this orchestrator can be reused or GC'd cleanly
+            this.orchestrator.unregisterAgent(agent.id);
+        }
+    }
+}

package/dist/skills/activation/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Skill Activation
+ *
+ * Context-based skill activation for agents.
+ */
+export { SkillActivator, type SkillActivatorConfig } from './skill-activator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/activation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skills/activation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/skills/activation/index.js

@@ -0,0 +1,6 @@
+/**
+ * Skill Activation
+ *
+ * Context-based skill activation for agents.
+ */
+export { SkillActivator } from './skill-activator.js';

package/dist/skills/activation/skill-activator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Skill Activator
+ *
+ * Determines which skills to activate based on context.
+ */
+import type { SkillRegistry } from '../registry/index.js';
+import type { SkillActivationContext, SkillActivationResult } from '../types.js';
+/**
+ * Configuration for skill activation.
+ */
+export interface SkillActivatorConfig {
+    /** Registry to get skills from */
+    registry: SkillRegistry;
+    /** Minimum similarity score for semantic activation (0-1) */
+    semanticThreshold?: number;
+    /** Maximum number of skills to activate automatically */
+    maxAutoActivate?: number;
+    /** Enable semantic (embedding-based) activation */
+    enableSemantic?: boolean;
+}
+/**
+ * Skill activator for context-based skill activation.
+ */
+export declare class SkillActivator {
+    private registry;
+    private semanticThreshold;
+    private maxAutoActivate;
+    private enableSemantic;
+    constructor(config: SkillActivatorConfig);
+    /**
+     * Activate skills based on context.
+     *
+     * Activation methods (in priority order):
+     * 1. Explicit: /skill-name syntax
+     * 2. Semantic: Embedding similarity match
+     * 3. File-match: Based on current file types
+     * 4. Project-type: Based on project configuration
+     */
+    activate(context: SkillActivationContext): Promise<SkillActivationResult>;
+    /**
+     * Find skills by semantic similarity to a query.
+     */
+    private findSemanticMatches;
+    /**
+     * Find skills that match file types.
+     */
+    private findFileTypeMatches;
+    /**
+     * Find skills that match project type.
+     */
+    private findProjectTypeMatches;
+    /**
+     * Parse explicit skill references from user input.
+     *
+     * @example
+     * parseExplicitSkills("Please /react-best-practices fix this component")
+     * // ["react-best-practices"]
+     */
+    static parseExplicitSkills(input: string): string[];
+    /**
+     * Get all available skills for auto-completion.
+     */
+    getAvailableSkills(): Array<{
+        name: string;
+        description: string;
+    }>;
+}
+//# sourceMappingURL=skill-activator.d.ts.map

package/dist/skills/activation/skill-activator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-activator.d.ts","sourceRoot":"","sources":["../../../src/skills/activation/skill-activator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAS,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEvF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,QAAQ,EAAE,aAAa,CAAA;IAEvB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB,mDAAmD;IACnD,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AA0BD;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,EAAE,oBAAoB;IAOxC;;;;;;;;OAQG;IACG,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4E/E;;OAEG;YACW,mBAAmB;IA4BjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2D3B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAOnD;;OAEG;IACH,kBAAkB,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAMnE"}