@soulcraft/sdk 1.6.2 → 2.0.0

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

@@ -0,0 +1,500 @@
+/**
+ * @module server/handlers/chat/types
+ * @description Shared types and dependency interfaces for the chat engine.
+ *
+ * Products inject implementations of these interfaces when creating the chat
+ * handler. The SDK provides the universal engine (streaming loop, conversation
+ * CRUD, memory, model routing, delegator, planner); products supply their
+ * own tools, system prompts, and billing checks.
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { HandlerContext } from '../../namespace-router.js';
+/**
+ * Abstraction over the Anthropic SDK `messages.create()` call.
+ *
+ * Products inject their own client (which may use a personal API key, a
+ * platform key, or a BYOK key). The chat engine calls `createStream()` and
+ * iterates over the events.
+ */
+export interface ChatAIClient {
+    /**
+     * Create a streaming message completion.
+     *
+     * @param options - Anthropic-compatible request options.
+     * @returns An async iterable of raw Anthropic stream events.
+     */
+    createStream(options: {
+        model: string;
+        maxTokens: number;
+        system: Array<{
+            type: 'text';
+            text: string;
+            cache_control?: {
+                type: 'ephemeral';
+            };
+        }>;
+        messages: Array<{
+            role: string;
+            content: any;
+        }>;
+        tools?: ToolDefinition[];
+        thinking?: {
+            type: 'enabled';
+            budget_tokens: number;
+        };
+    }): Promise<AsyncIterable<AnthropicStreamEvent>>;
+    /**
+     * Create a non-streaming message completion.
+     *
+     * Used by the delegator for triage and synthesis (no streaming needed).
+     *
+     * @param options - Request options.
+     * @returns The completion response.
+     */
+    create(options: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        messages: Array<{
+            role: string;
+            content: any;
+        }>;
+        tools?: ToolDefinition[];
+    }): Promise<{
+        content: Array<{
+            type: string;
+            text?: string;
+            id?: string;
+            name?: string;
+            input?: any;
+        }>;
+        usage: {
+            input_tokens: number;
+            output_tokens: number;
+        };
+    }>;
+}
+/**
+ * Raw Anthropic stream event — subset of the events the chat engine processes.
+ *
+ * The engine handles: content_block_start, content_block_delta,
+ * content_block_stop, message_start, message_delta, message_stop.
+ */
+export interface AnthropicStreamEvent {
+    type: string;
+    content_block?: {
+        type: string;
+        id?: string;
+        name?: string;
+    };
+    delta?: {
+        type: string;
+        text?: string;
+        thinking?: string;
+        partial_json?: string;
+    };
+    message?: {
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cache_creation_input_tokens?: number;
+            cache_read_input_tokens?: number;
+        };
+    };
+    usage?: {
+        output_tokens?: number;
+    };
+}
+/**
+ * Tool definition in Anthropic's format — passed to `messages.create()`.
+ *
+ * Products register their own tool sets. Workshop has 31 tools (entity CRUD,
+ * VFS, search, UI actions). Venue has different tools. Academy has tutor tools.
+ */
+export interface ToolDefinition {
+    /** Tool name (e.g. 'advanced_search', 'create_entity'). */
+    name: string;
+    /** Human-readable description shown to Claude. */
+    description: string;
+    /** JSON Schema for the tool's input parameters. */
+    input_schema: Record<string, unknown>;
+}
+/**
+ * Tool executor — dispatches tool calls to product-specific implementations.
+ *
+ * The chat engine calls this when Claude invokes a tool. Products implement
+ * the actual logic (e.g. Workshop's `executeTool()` with 55-case switch).
+ */
+export interface ToolExecutor {
+    /**
+     * Execute a tool call.
+     *
+     * @param name - Tool name from Claude's response.
+     * @param input - Tool input parameters.
+     * @param ctx - Execution context with brain, user, and conversation info.
+     * @returns Tool result (serialized as JSON for Claude's next turn).
+     */
+    execute(name: string, input: Record<string, unknown>, ctx: ToolExecutionContext): Promise<unknown>;
+}
+/**
+ * Context passed to tool execution.
+ *
+ * Provides the tool with everything it needs to operate — brain instance,
+ * conversation state, and product-specific context.
+ */
+export interface ToolExecutionContext {
+    /** Brainy instance for the current workspace. */
+    brain: Brainy;
+    /** Conversation ID the tool is executing within. */
+    conversationId: string;
+    /** Message ID of the assistant message that triggered this tool call. */
+    assistantMessageId: string;
+    /** Handler context with user and workspace info. */
+    handlerCtx: HandlerContext;
+    /** Product-specific context (e.g. Workshop's ChatContext, kit config). */
+    productContext?: Record<string, unknown>;
+}
+/**
+ * System prompt builder — products provide their own prompt logic.
+ *
+ * Workshop builds a prompt with kit context, skills, memory, expertise.
+ * Venue uses the kit's AI persona. Academy uses a Socratic tutor prompt.
+ */
+export interface SystemPromptBuilder {
+    /**
+     * Build the system prompt for a chat message.
+     *
+     * @param ctx - Context for prompt building.
+     * @returns Static part (cacheable) and dynamic part (per-request).
+     */
+    build(ctx: SystemPromptContext): Promise<{
+        staticPart: string;
+        dynamicPart: string;
+    }>;
+}
+/**
+ * Context provided to the system prompt builder.
+ */
+export interface SystemPromptContext {
+    /** Brainy instance. */
+    brain: Brainy;
+    /** Handler context. */
+    handlerCtx: HandlerContext;
+    /** Conversation history for context. */
+    conversationHistory: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Retrieved memory items. */
+    memory: RetrievedMemory | null;
+    /** User expertise profile. */
+    expertise: UserExpertiseProfile | null;
+    /** Product-specific context passed through from send options. */
+    productContext?: Record<string, unknown>;
+}
+/**
+ * Model selector — chooses the right Claude model for each request.
+ *
+ * The default implementation provides tiered routing (Opus for planning,
+ * Sonnet for triage, Haiku for execution). Products can override for
+ * simpler routing or cost control.
+ */
+export interface ModelSelector {
+    /**
+     * Select the routing strategy for a message.
+     *
+     * @param message - The user's message.
+     * @param options - Routing options.
+     * @returns The routing decision with model assignments.
+     */
+    selectRouting(message: string, options: {
+        planModeEnabled?: boolean;
+        forcedModel?: string;
+    }): TieredRouting;
+}
+/** Model role in the tiered strategy. */
+export type ModelRole = 'planner' | 'triage' | 'executor' | 'fallback';
+/**
+ * Tiered routing decision — which models to use for each phase.
+ */
+export interface TieredRouting {
+    /** Whether plan mode is active. */
+    planModeEnabled: boolean;
+    /** Model for triage/planning phase. */
+    triageModel: string;
+    /** Model for task execution phase. */
+    executeModel: string;
+    /** Complexity score (0-10) from message analysis. */
+    complexityScore: number;
+    /** Whether the engine should recommend switching to plan mode. */
+    shouldRecommendPlan: boolean;
+    /** Human-readable routing reason. */
+    reason: string;
+}
+/**
+ * Billing check interface — products enforce their own limits.
+ *
+ * Called before streaming starts. If the check fails, the chat handler
+ * returns an error without calling Claude.
+ */
+export interface ChatBillingCheck {
+    /**
+     * Check if the user can send a message.
+     *
+     * @param userId - The billing identity (email or hash).
+     * @param ctx - Handler context.
+     * @returns Whether the user can proceed, and tier info.
+     */
+    checkLimit(userId: string, ctx: HandlerContext): Promise<{
+        ok: boolean;
+        tier: 'free' | 'subscriber' | 'byok';
+        remaining: number;
+        useTopUp?: boolean;
+    }>;
+    /**
+     * Record token usage after a message completes. Fire-and-forget.
+     *
+     * @param userId - The billing identity.
+     * @param inputTokens - Input tokens consumed.
+     * @param outputTokens - Output tokens consumed.
+     * @param model - Model used.
+     */
+    recordUsage(userId: string, inputTokens: number, outputTokens: number, model: string): void;
+}
+/**
+ * Optional event emitter for real-time UI updates (data changes, activity feed).
+ */
+export interface ChatEventEmitter {
+    /** Emit an event. */
+    emit(event: string, data: unknown): void;
+}
+/**
+ * Memory retrieved by the proactive memory system for context enrichment.
+ */
+export interface RetrievedMemory {
+    /** Past conversation fragments relevant to the current message. */
+    conversations: Array<{
+        content: string;
+        timestamp: string;
+    }>;
+    /** User preferences learned from past interactions. */
+    preferences: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** Entities in the knowledge graph related to the message. */
+    relatedEntities: Array<{
+        id: string;
+        name: string;
+        type: string;
+    }>;
+    /** Insights the AI has derived from past conversations. */
+    insights: Array<{
+        content: string;
+        confidence: number;
+    }>;
+}
+/**
+ * User expertise profile — accumulated over time from conversations.
+ *
+ * The AI adapts its communication style based on the user's demonstrated
+ * knowledge level in various domains.
+ */
+export interface UserExpertiseProfile {
+    /** Domains where the user has demonstrated strong knowledge. */
+    strongAreas: string[];
+    /** Domains where the user is learning or has asked basic questions. */
+    growthAreas: string[];
+    /** Overall technical sophistication (1-5 scale). */
+    technicalLevel: number;
+    /** How much detail the user prefers (1-5 scale). */
+    preferredDetailLevel: number;
+    /** User's preferred communication style. */
+    communicationStyle: string;
+    /** Specific domain expertise entries. */
+    domainExpertise: Array<{
+        domain: string;
+        level: number;
+        lastSeen: string;
+    }>;
+}
+/** Routing decision from triage. */
+export type RoutingDecisionType = 'direct' | 'delegate_tasks' | 'recommend_plan';
+/** A task delegated by the triage model to the executor model. */
+export interface DelegatedTask {
+    id: string;
+    description: string;
+    tool?: string;
+    input?: Record<string, unknown>;
+    purpose: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    result?: unknown;
+    error?: string;
+}
+/** Triage routing decision. */
+export interface RoutingDecision {
+    decision: RoutingDecisionType;
+    reasoning: string;
+    tasks?: DelegatedTask[];
+    directResponse?: string;
+    recommendPlanReason?: string;
+}
+/** Result of the triage phase. */
+export interface TriageResult {
+    decision: RoutingDecision;
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Result of executing a single delegated task. */
+export interface TaskExecutionResult {
+    taskId: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    model: string;
+    escalated: boolean;
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Result of the full delegation flow. */
+export interface DelegationResult {
+    success: boolean;
+    taskResults: TaskExecutionResult[];
+    synthesizedResponse?: string;
+    totalTokens: {
+        input: number;
+        output: number;
+    };
+    escalationCount: number;
+}
+/** A step in an AI-generated execution plan. */
+export interface PlanStep {
+    id: string;
+    description: string;
+    activeDescription: string;
+    tools: string[];
+    dependencies: string[];
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+    result?: unknown;
+    error?: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+/** An AI-generated plan for complex multi-step operations. */
+export interface AIPlan {
+    id: string;
+    conversationId: string;
+    userMessage: string;
+    status: 'draft' | 'pending' | 'approved' | 'executing' | 'completed' | 'failed' | 'cancelled';
+    analysis: string;
+    approach: string;
+    steps: PlanStep[];
+    executionContext: {
+        relevantFiles: string[];
+        entities: string[];
+        tools: string[];
+        skills: string[];
+    };
+    planModel: string;
+    executeModel: string;
+    createdAt: string;
+    approvedAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    estimatedCost: {
+        planTokens: number;
+        executeTokens: number;
+        totalUSD: number;
+    };
+    actualCost?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalUSD: number;
+    };
+}
+/** Progress event emitted during plan execution. */
+export interface StepProgress {
+    type: 'step_start' | 'step_complete' | 'step_error' | 'escalating';
+    stepId: string;
+    stepIndex: number;
+    totalSteps: number;
+    description: string;
+    model?: string;
+    result?: unknown;
+    error?: string;
+}
+/** Result of executing a plan. */
+export interface PlanExecutionResult {
+    success: boolean;
+    stepResults: Array<{
+        stepId: string;
+        status: string;
+        result?: unknown;
+        error?: string;
+        model: string;
+        tokens: {
+            input: number;
+            output: number;
+        };
+        escalated: boolean;
+    }>;
+    totalTokens: {
+        input: number;
+        output: number;
+    };
+    actualCost: number;
+    escalationCount: number;
+}
+/**
+ * Options for {@link createChatHandler}.
+ *
+ * The AI client and tool executor are required — the chat engine can't
+ * function without them. All other dependencies have sensible defaults.
+ */
+export interface ChatHandlerOptions {
+    /** AI client for calling Claude. Required. */
+    aiClient: ChatAIClient;
+    /** Tool definitions available to Claude. Required. */
+    tools: ToolDefinition[];
+    /** Tool executor for running tool calls. Required. */
+    toolExecutor: ToolExecutor;
+    /** System prompt builder. If omitted, uses a minimal default prompt. */
+    systemPromptBuilder?: SystemPromptBuilder;
+    /** Model selector for tiered routing. If omitted, uses default tiers. */
+    modelSelector?: ModelSelector;
+    /** Billing check. If omitted, all messages are allowed. */
+    billing?: ChatBillingCheck;
+    /** Event emitter for real-time updates. Optional. */
+    events?: ChatEventEmitter;
+    /**
+     * Maximum agentic loop iterations (tool use → Claude → tool use → ...).
+     * @default 100
+     */
+    maxIterations?: number;
+    /**
+     * Maximum agentic loop duration in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    maxDurationMs?: number;
+    /**
+     * Default model for non-tiered requests.
+     * @default 'claude-3-5-haiku-latest'
+     */
+    defaultModel?: string;
+    /**
+     * Free-tier model override. Used when billing reports `tier: 'free'`.
+     * @default 'claude-3-5-haiku-latest'
+     */
+    freeTierModel?: string;
+    /**
+     * Enable extended thinking for supported models.
+     * @default true
+     */
+    enableThinking?: boolean;
+    /**
+     * Thinking budget in tokens.
+     * @default 8000
+     */
+    thinkingBudget?: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * @module server/handlers/chat/types
+ * @description Shared types and dependency interfaces for the chat engine.
+ *
+ * Products inject implementations of these interfaces when creating the chat
+ * handler. The SDK provides the universal engine (streaming loop, conversation
+ * CRUD, memory, model routing, delegator, planner); products supply their
+ * own tools, system prompts, and billing checks.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/dist/server/handlers/collections.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @module server/handlers/collections
+ * @description Collections namespace handler — view collection CRUD, member
+ * management, and sample data seeding.
+ *
+ * Absorbs Workshop `routes/collections.ts`. Collections are Brainy entities
+ * of type `Collection` with `isViewCollection: true` metadata. Members are
+ * linked via `Contains` relationships. Virtual collections (Everything,
+ * Uncategorized) are computed dynamically.
+ *
+ * Methods:
+ * - `list` — List all view collections (real + virtual)
+ * - `get` — Get a single collection by ID
+ * - `create` — Create a new collection (optionally with sample data)
+ * - `update` — Update collection name/metadata
+ * - `delete` — Delete a collection (members are NOT deleted)
+ * - `getMembers` — Get entities belonging to a collection
+ * - `addMember` — Add an entity to a collection
+ * - `removeMember` — Remove an entity from a collection
+ * - `loadSampleData` — Seed sample data for a kit
+ * - `clearSampleData` — Remove all sample data entities
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Sample data provider for seeding collections with demo content.
+ *
+ * Products inject their own sample data definitions — Workshop uses
+ * `VIEW_SAMPLE_DATA` keyed by view type; Venue might have different samples.
+ */
+export interface SampleDataProvider {
+    /**
+     * Get sample data for a given key (view type or kit ID).
+     *
+     * @returns Entity and relationship definitions, or `null` if no sample data.
+     */
+    getSampleData(key: string): {
+        entities: Array<{
+            name: string;
+            type: string;
+            description?: string;
+            properties?: Record<string, unknown>;
+        }>;
+        relationships?: Array<{
+            from: string;
+            to: string;
+            type: string;
+        }>;
+    } | null;
+}
+/**
+ * Options for {@link createCollectionsHandler}.
+ */
+export interface CollectionsHandlerOptions {
+    /**
+     * Sample data provider for the `loadSampleData` method.
+     * If not provided, sample data methods return no-ops.
+     */
+    sampleData?: SampleDataProvider;
+}
+/**
+ * Creates the `collections` namespace handler.
+ *
+ * @param options - Optional collections handler configuration.
+ * @returns A {@link NamespaceProvider} implementing {@link CollectionsNamespace}.
+ */
+export declare function createCollectionsHandler(options?: CollectionsHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=collections.d.ts.map

package/dist/server/handlers/collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/collections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAO/E;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;QAC1B,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,CAAA;YACZ,IAAI,EAAE,MAAM,CAAA;YACZ,WAAW,CAAC,EAAE,MAAM,CAAA;YACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SACrC,CAAC,CAAA;QACF,aAAa,CAAC,EAAE,KAAK,CAAC;YACpB,IAAI,EAAE,MAAM,CAAA;YACZ,EAAE,EAAE,MAAM,CAAA;YACV,IAAI,EAAE,MAAM,CAAA;SACb,CAAC,CAAA;KACH,GAAG,IAAI,CAAA;CACT;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAChC;AAsED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,iBAAiB,CAwc/F"}