@soulcraft/sdk 1.7.0 → 2.0.1

package/dist/server/handlers/chat/delegator.js

@@ -0,0 +1,431 @@
+/**
+ * @module server/handlers/chat/delegator
+ * @description Tiered model delegation: Sonnet triage → Haiku execute → Sonnet synthesize.
+ *
+ * The delegator handles normal (non-plan-mode) chat by:
+ * 1. **Triage** — Sonnet analyzes the user message and decides: answer directly,
+ *    delegate specific tasks to Haiku, or recommend Plan Mode for complex work.
+ * 2. **Execute** — Haiku runs each delegated task (tool calls). If a task fails,
+ *    auto-escalates to Sonnet (the fallback model).
+ * 3. **Synthesize** — Sonnet combines task results into a coherent response.
+ *
+ * The delegator uses the injected {@link ChatAIClient} and {@link ToolExecutor},
+ * so it works with any product's tool set (Workshop, Venue, Academy).
+ */
+import { DEFAULT_MODEL_TIERS } from './models.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// System Prompts
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Build the triage system prompt dynamically from available tool definitions.
+ *
+ * @param tools - Available tool definitions.
+ * @returns Complete triage system prompt.
+ */
+function buildTriagePrompt(tools) {
+    const toolList = tools.map(t => `- ${t.name}: ${t.description}`).join('\n');
+    return `You are an AI assistant that routes and triages user requests.
+Your job is to analyze the user's message and decide how to handle it most efficiently.
+
+You MUST respond with a JSON object in one of these three formats:
+
+## 1. DIRECT - Answer directly (for questions, explanations, simple reasoning)
+Use this when you can answer completely without any tool calls.
+{
+  "decision": "direct",
+  "reasoning": "Why this can be answered directly",
+  "directResponse": "Your complete response to the user"
+}
+
+## 2. DELEGATE_TASKS - Delegate specific tasks to be executed
+Use this when the request requires tool operations with clear inputs/outputs.
+{
+  "decision": "delegate_tasks",
+  "reasoning": "Why this needs task delegation",
+  "tasks": [
+    {
+      "id": "task_1",
+      "description": "What this task does",
+      "tool": "tool_name",
+      "input": { "param": "value" },
+      "purpose": "Why this task is needed"
+    }
+  ]
+}
+
+## 3. RECOMMEND_PLAN - Recommend enabling Plan Mode
+Use this for complex, multi-step tasks with dependencies.
+{
+  "decision": "recommend_plan",
+  "reasoning": "Why this task is complex",
+  "recommendPlanReason": "User-friendly explanation of why Plan Mode would help"
+}
+
+## Available Tools
+${toolList}
+
+## Guidelines
+- Use DIRECT for: questions, explanations, analysis, reasoning
+- Use DELEGATE_TASKS for: search operations, file reads, entity lookups, simple CRUD
+- Use RECOMMEND_PLAN for: multi-file changes, architectural changes, complex workflows
+
+Always respond with valid JSON only.`;
+}
+/** System prompt template for task execution. */
+const TASK_EXECUTION_PROMPT = `You are an AI assistant executing a specific task.
+
+Your task: {task_description}
+Purpose: {task_purpose}
+
+Execute this task using the available tools. Be efficient and focused.
+Only do what this specific task requires.`;
+/** System prompt template for result synthesis. */
+const SYNTHESIS_PROMPT = `You are an AI assistant synthesizing results from multiple tasks.
+
+The user asked: {user_message}
+
+Tasks were executed to answer this request. Here are the results:
+{task_results}
+
+Synthesize these results into a clear, helpful response for the user.
+Be concise and directly address what the user asked.`;
+/**
+ * Triage a user message — Sonnet decides how to handle it.
+ *
+ * Parses Claude's JSON response into a {@link RoutingDecision}. If parsing
+ * fails, falls back to treating the response as a direct answer.
+ *
+ * @param options - Triage configuration.
+ * @returns The routing decision and token usage.
+ */
+export async function triageMessage(options) {
+    const { message, conversationHistory, aiClient, tools, triageModel = DEFAULT_MODEL_TIERS.triage, } = options;
+    try {
+        const response = await aiClient.create({
+            model: triageModel,
+            maxTokens: 4096,
+            system: buildTriagePrompt(tools),
+            messages: [
+                ...conversationHistory.map(msg => ({
+                    role: msg.role,
+                    content: msg.content,
+                })),
+                { role: 'user', content: message },
+            ],
+        });
+        const inputTokens = response.usage?.input_tokens || 0;
+        const outputTokens = response.usage?.output_tokens || 0;
+        // Extract text content
+        let responseText = '';
+        for (const block of response.content) {
+            if (block.type === 'text' && block.text) {
+                responseText += block.text;
+            }
+        }
+        // Parse JSON response (handle markdown code blocks)
+        let decision;
+        try {
+            const jsonMatch = responseText.match(/```(?:json)?\s*([\s\S]*?)```/) || [null, responseText];
+            const cleanJson = (jsonMatch[1] || responseText).trim();
+            decision = JSON.parse(cleanJson);
+        }
+        catch {
+            decision = {
+                decision: 'direct',
+                reasoning: 'Failed to parse structured decision',
+                directResponse: responseText,
+            };
+        }
+        // Normalize task statuses
+        if (decision.decision === 'delegate_tasks' && decision.tasks) {
+            decision.tasks = decision.tasks.map((task, idx) => ({
+                ...task,
+                id: task.id || `task_${idx + 1}`,
+                status: 'pending',
+                purpose: task.purpose || task.description,
+            }));
+        }
+        return { decision, inputTokens, outputTokens };
+    }
+    catch (error) {
+        const message_ = error instanceof Error ? error.message : String(error);
+        return {
+            decision: {
+                decision: 'direct',
+                reasoning: 'Error during triage',
+                directResponse: `I encountered an error processing your request: ${message_}`,
+            },
+            inputTokens: 0,
+            outputTokens: 0,
+        };
+    }
+}
+/**
+ * Execute a single delegated task using the executor model.
+ *
+ * If the task has explicit `tool` and `input` fields (from triage), executes
+ * the tool directly without an AI call. Otherwise, sends the task description
+ * to the executor model and lets it choose tools.
+ *
+ * Auto-escalates to the fallback model on failure.
+ *
+ * @param options - Task execution configuration.
+ * @returns Execution result with token usage.
+ */
+export async function executeTask(options) {
+    const { task, aiClient, toolExecutor, tools, toolContext, executeModel = DEFAULT_MODEL_TIERS.executor, fallbackModel = DEFAULT_MODEL_TIERS.fallback, } = options;
+    // Direct tool execution (triage provided explicit tool + input)
+    if (task.tool && task.input) {
+        try {
+            const result = await toolExecutor.execute(task.tool, task.input, toolContext);
+            return {
+                taskId: task.id,
+                success: true,
+                result,
+                model: executeModel,
+                escalated: false,
+                inputTokens: 0,
+                outputTokens: 0,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                taskId: task.id,
+                success: false,
+                error: message,
+                model: executeModel,
+                escalated: false,
+                inputTokens: 0,
+                outputTokens: 0,
+            };
+        }
+    }
+    // AI-driven execution with the executor model
+    const prompt = TASK_EXECUTION_PROMPT
+        .replace('{task_description}', task.description)
+        .replace('{task_purpose}', task.purpose);
+    let result = await executeTaskWithModel(task, executeModel, prompt, aiClient, toolExecutor, tools, toolContext);
+    // Auto-escalate on failure
+    if (!result.success && fallbackModel !== executeModel) {
+        result = await executeTaskWithModel(task, fallbackModel, prompt, aiClient, toolExecutor, tools, toolContext);
+        result.escalated = true;
+    }
+    return result;
+}
+/**
+ * Execute a task using a specific model — internal helper.
+ *
+ * @param task - The delegated task.
+ * @param model - Model to use.
+ * @param systemPrompt - Task-specific system prompt.
+ * @param aiClient - AI client.
+ * @param toolExecutor - Tool executor.
+ * @param tools - Available tool definitions.
+ * @param toolContext - Execution context.
+ * @returns Task execution result.
+ */
+async function executeTaskWithModel(task, model, systemPrompt, aiClient, toolExecutor, tools, toolContext) {
+    try {
+        const response = await aiClient.create({
+            model,
+            maxTokens: 8192,
+            system: systemPrompt,
+            messages: [{ role: 'user', content: `Execute task: ${task.description}` }],
+            tools,
+        });
+        const inputTokens = response.usage?.input_tokens || 0;
+        const outputTokens = response.usage?.output_tokens || 0;
+        let result = null;
+        let textResponse = '';
+        for (const block of response.content) {
+            if (block.type === 'text' && block.text) {
+                textResponse += block.text;
+            }
+            else if (block.type === 'tool_use' && block.name) {
+                try {
+                    result = await toolExecutor.execute(block.name, (block.input || {}), toolContext);
+                }
+                catch (toolError) {
+                    const message = toolError instanceof Error ? toolError.message : String(toolError);
+                    return {
+                        taskId: task.id,
+                        success: false,
+                        error: `Tool error: ${message}`,
+                        model,
+                        escalated: false,
+                        inputTokens,
+                        outputTokens,
+                    };
+                }
+            }
+        }
+        return {
+            taskId: task.id,
+            success: true,
+            result: result ?? textResponse,
+            model,
+            escalated: false,
+            inputTokens,
+            outputTokens,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            taskId: task.id,
+            success: false,
+            error: message,
+            model,
+            escalated: false,
+            inputTokens: 0,
+            outputTokens: 0,
+        };
+    }
+}
+/**
+ * Synthesize task results into a coherent response using Sonnet.
+ *
+ * Takes the raw task outputs and composes a user-facing answer that
+ * addresses the original request.
+ *
+ * @param options - Synthesis configuration.
+ * @returns The synthesized response text and token usage.
+ */
+export async function synthesizeResults(options) {
+    const { userMessage, taskResults, aiClient, synthesizeModel = DEFAULT_MODEL_TIERS.triage, } = options;
+    const taskResultsStr = taskResults.map(tr => {
+        if (tr.success) {
+            return `Task ${tr.taskId}: SUCCESS\nResult: ${JSON.stringify(tr.result, null, 2)}`;
+        }
+        return `Task ${tr.taskId}: FAILED\nError: ${tr.error}`;
+    }).join('\n\n');
+    const prompt = SYNTHESIS_PROMPT
+        .replace('{user_message}', userMessage)
+        .replace('{task_results}', taskResultsStr);
+    try {
+        const response = await aiClient.create({
+            model: synthesizeModel,
+            maxTokens: 4096,
+            system: prompt,
+            messages: [{ role: 'user', content: 'Synthesize the task results into a response.' }],
+        });
+        let responseText = '';
+        for (const block of response.content) {
+            if (block.type === 'text' && block.text) {
+                responseText += block.text;
+            }
+        }
+        return {
+            response: responseText,
+            inputTokens: response.usage?.input_tokens || 0,
+            outputTokens: response.usage?.output_tokens || 0,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            response: `I completed some tasks but had trouble summarizing the results: ${message}`,
+            inputTokens: 0,
+            outputTokens: 0,
+        };
+    }
+}
+/**
+ * Execute the full Sonnet → Haiku → Sonnet delegation flow.
+ *
+ * 1. Triage with Sonnet → routing decision
+ * 2. Execute tasks with Haiku (auto-escalate on failure)
+ * 3. Synthesize with Sonnet
+ *
+ * @param options - Delegation configuration.
+ * @returns The delegation result with synthesized response.
+ */
+export async function delegateAndExecute(options) {
+    const { message, conversationHistory, aiClient, tools, toolExecutor, toolContext, triageModel, executeModel, fallbackModel, onTaskStart, onTaskComplete, } = options;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let escalationCount = 0;
+    // Step 1: Triage
+    const triageResult = await triageMessage({
+        message,
+        conversationHistory,
+        aiClient,
+        tools,
+        ...(triageModel != null ? { triageModel } : {}),
+    });
+    totalInputTokens += triageResult.inputTokens;
+    totalOutputTokens += triageResult.outputTokens;
+    const { decision } = triageResult;
+    // Direct response — no delegation needed
+    if (decision.decision === 'direct') {
+        return {
+            success: true,
+            taskResults: [],
+            ...(decision.directResponse != null ? { synthesizedResponse: decision.directResponse } : {}),
+            totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+            escalationCount: 0,
+        };
+    }
+    // Recommend plan mode
+    if (decision.decision === 'recommend_plan') {
+        return {
+            success: true,
+            taskResults: [],
+            synthesizedResponse: decision.recommendPlanReason ||
+                'This is a complex task. I recommend enabling Plan Mode for better results.',
+            totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+            escalationCount: 0,
+        };
+    }
+    // Delegate tasks
+    if (decision.decision === 'delegate_tasks' && decision.tasks) {
+        const taskResults = [];
+        // Step 2: Execute tasks sequentially
+        for (const task of decision.tasks) {
+            if (onTaskStart)
+                await onTaskStart(task);
+            const result = await executeTask({
+                task,
+                aiClient,
+                toolExecutor,
+                tools,
+                toolContext,
+                ...(executeModel != null ? { executeModel } : {}),
+                ...(fallbackModel != null ? { fallbackModel } : {}),
+            });
+            taskResults.push(result);
+            totalInputTokens += result.inputTokens;
+            totalOutputTokens += result.outputTokens;
+            if (result.escalated)
+                escalationCount++;
+            if (onTaskComplete)
+                await onTaskComplete(result);
+        }
+        // Step 3: Synthesize
+        const synthesisResult = await synthesizeResults({
+            userMessage: message,
+            taskResults,
+            aiClient,
+            ...(triageModel != null ? { synthesizeModel: triageModel } : {}),
+        });
+        totalInputTokens += synthesisResult.inputTokens;
+        totalOutputTokens += synthesisResult.outputTokens;
+        return {
+            success: taskResults.every(r => r.success),
+            taskResults,
+            synthesizedResponse: synthesisResult.response,
+            totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+            escalationCount,
+        };
+    }
+    // Fallback — should not reach here
+    return {
+        success: false,
+        taskResults: [],
+        synthesizedResponse: 'Unable to process your request.',
+        totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+        escalationCount: 0,
+    };
+}
+//# sourceMappingURL=delegator.js.map

package/dist/server/handlers/chat/delegator.js.map

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

package/dist/server/handlers/chat/engine.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module server/handlers/chat/engine
+ * @description The core streaming chat engine — agentic tool-use loop with
+ * stuck detection, timeout protection, and fire-and-forget persistence.
+ *
+ * The engine is transport-agnostic: it yields `ChatStreamChunk` frames via
+ * an `AsyncGenerator`. The transport layer (SSE, WebSocket, PostMessage)
+ * delivers those chunks to the client.
+ *
+ * ## Agentic Loop
+ *
+ * When Claude calls a tool, the engine:
+ * 1. Executes the tool via the injected {@link ToolExecutor}
+ * 2. Feeds the result back to Claude as a `tool_result` message
+ * 3. Claude continues (more text, more tool calls, or `message_stop`)
+ * 4. Repeat until no more tool calls, max iterations, or timeout
+ *
+ * ## Stuck Detection
+ *
+ * If the same tool with the same input is called 3 times consecutively,
+ * the engine breaks the loop to prevent infinite spinning.
+ *
+ * ## Fire-and-Forget
+ *
+ * Message storage, auto-titling, and background learning happen async
+ * without blocking the stream.
+ */
+import type { ChatHandlerOptions } from './types.js';
+import type { ChatStreamChunk } from '../../../namespaces.js';
+import type { HandlerContext } from '../../namespace-router.js';
+/**
+ * Options for a single streaming chat message.
+ */
+export interface StreamMessageOptions {
+    /** The user's message text. */
+    message: string;
+    /** Existing conversation ID, or undefined to create a new one. */
+    conversationId?: string;
+    /** Forced model override. */
+    model?: string;
+    /** Whether Plan Mode is enabled. */
+    planModeEnabled?: boolean;
+    /** Product-specific context (e.g. ChatContext, KitAIContext). */
+    productContext?: Record<string, unknown>;
+}
+/**
+ * Run the streaming chat engine for a single message.
+ *
+ * Yields {@link ChatStreamChunk} frames: `text`, `tool_use`, `tool_result`,
+ * `status`, `thinking_start`, `thinking_delta`, `thinking_end`, and
+ * terminal `done` or `error`.
+ *
+ * This is the core of the chat system — the full agentic loop with
+ * tool use, stuck detection, timeout, and fire-and-forget persistence.
+ *
+ * @param opts - Message options.
+ * @param handlerCtx - Handler context with brain, user, workspace.
+ * @param config - Chat handler configuration (injected dependencies).
+ * @yields ChatStreamChunk frames.
+ */
+export declare function streamMessage(opts: StreamMessageOptions, handlerCtx: HandlerContext, config: ChatHandlerOptions): AsyncGenerator<ChatStreamChunk>;
+/**
+ * Send a message and collect the full response (non-streaming).
+ *
+ * Internally uses the streaming engine and collects all text chunks.
+ *
+ * @param opts - Message options.
+ * @param handlerCtx - Handler context.
+ * @param config - Chat handler configuration.
+ * @returns Complete response with conversation ID and usage.
+ */
+export declare function sendMessage(opts: StreamMessageOptions, handlerCtx: HandlerContext, config: ChatHandlerOptions): Promise<{
+    response: string;
+    conversationId: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        model: string;
+    };
+}>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/server/handlers/chat/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/chat/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAUV,kBAAkB,EAGnB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AA6B/D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAuB,aAAa,CAClC,IAAI,EAAE,oBAAoB,EAC1B,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,kBAAkB,GACzB,cAAc,CAAC,eAAe,CAAC,CAgVjC;AAMD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,oBAAoB,EAC1B,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC;IACT,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CACpE,CAAC,CAeD"}