agent-world 0.11.1 → 0.12.0

package/dist/core/google-direct.js

@@ -0,0 +1,298 @@
+/**
+ * Google Direct Integration Module - Pure Client (LLM Provider Refactoring Phase 4)
+ *
+ * Features:
+ * - Direct Google Generative AI API integration
+ * - Streaming and non-streaming responses returning LLMResponse
+ * - Function/tool calling detection (NO execution)
+ * - Proper error handling and retry logic
+ * - Browser-safe configuration injection
+ * - Pure client: only calls APIs and returns structured data
+ *
+ * Implementation Details:
+ * - Uses official @google/generative-ai package for reliable API access
+ * - Converts AI SDK message format to Google Generative AI format
+ * - Returns LLMResponse with type='text' or type='tool_calls'
+ * - Streaming support with chunk-by-chunk processing via onChunk callback
+ * - Error handling with descriptive messages
+ * - Configuration injection from llm-config module
+ * - NO event emission, NO storage, NO tool execution
+ *
+ * Recent Changes:
+ * - 2026-02-15: Stopped replaying historical tool call/response parts as Google `functionCall`/`functionResponse` in conversation conversion to avoid 400 errors requiring `thought_signature` on replayed calls.
+ * - 2026-02-13: Added transport-level AbortSignal wiring to Google SDK request options where supported.
+ * - 2026-02-13: Added abort-signal checks for streaming and non-streaming execution paths.
+ * - 2025-11-09: Phase 4 - Removed ALL tool execution logic (~200 lines)
+ * - Provider is now a pure client - only API calls and data transformation
+ * - Returns LLMResponse interface with type discriminator
+ * - Filters invalid function calls (empty/missing names) and logs warnings
+ * - Note: Google API doesn't provide usage information in response
+ * - 2025-11-08: Removed ALL event emission from provider
+ * - Streaming uses onChunk callback instead of direct SSE emission
+ */
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { getLLMProviderConfig } from './llm-config.js';
+import { createCategoryLogger } from './logger.js';
+import { generateId } from './utils.js';
+const logger = createCategoryLogger('llm.google');
+const mcpLogger = createCategoryLogger('mcp.execution');
+/**
+ * Google client factory
+ */
+export function createGoogleClient(config) {
+    return new GoogleGenerativeAI(config.apiKey);
+}
+/**
+ * Create Google model instance
+ */
+export function createGoogleModel(client, modelName, tools) {
+    return client.getGenerativeModel({
+        model: modelName,
+        ...(tools && tools.length > 0 && { tools: [{ functionDeclarations: tools }] })
+    });
+}
+/**
+ * Convert AI SDK messages to Google format
+ */
+function convertMessagesToGoogle(messages) {
+    const googleMessages = [];
+    let systemInstruction = '';
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            systemInstruction = msg.content || '';
+            continue;
+        }
+        if (msg.role === 'tool') {
+            // Replay compatibility: avoid functionResponse replay because Gemini
+            // expects metadata coupling with prior functionCall traces.
+            // Keep tool outcomes as plain text context.
+            if (!msg.content?.trim()) {
+                continue;
+            }
+            googleMessages.push({
+                role: 'user',
+                parts: [{ text: `[Tool result]\n${msg.content}` }]
+            });
+            continue;
+        }
+        if (msg.role === 'assistant' && msg.tool_calls) {
+            // Replay compatibility: do NOT replay historical functionCall parts.
+            // Gemini may reject replayed calls without provider-issued thought_signature.
+            const parts = [];
+            if (msg.content) {
+                parts.push({ text: msg.content });
+            }
+            if (parts.length === 0) {
+                parts.push({ text: '[Tool call history omitted for Google replay compatibility]' });
+            }
+            googleMessages.push({
+                role: 'model',
+                parts
+            });
+            continue;
+        }
+        // Regular user/assistant messages
+        googleMessages.push({
+            role: msg.role === 'assistant' ? 'model' : 'user',
+            parts: [{ text: msg.content || '' }]
+        });
+    }
+    return { messages: googleMessages, systemInstruction };
+}
+/**
+ * Convert MCP tools to Google format
+ */
+function convertMCPToolsToGoogle(mcpTools) {
+    return Object.entries(mcpTools).map(([name, tool]) => ({
+        name,
+        description: tool.description || '',
+        parameters: tool.inputSchema || { type: 'object', properties: {} },
+    }));
+}
+/**
+ * Streaming Google response handler - Pure client (no tool execution)
+ * Returns LLMResponse with type='text' or type='tool_calls'
+ */
+export async function streamGoogleResponse(client, model, messages, agent, mcpTools, world, onChunk, messageId, abortSignal) {
+    const googleTools = Object.keys(mcpTools).length > 0 ? convertMCPToolsToGoogle(mcpTools) : undefined;
+    const { messages: googleMessages, systemInstruction } = convertMessagesToGoogle(messages);
+    const generativeModel = client.getGenerativeModel({
+        model,
+        systemInstruction: systemInstruction || undefined,
+        ...(googleTools && googleTools.length > 0 && { tools: [{ functionDeclarations: googleTools }] })
+    });
+    logger.debug(`Google Direct: Starting streaming request for agent=${agent.id}, model=${model}`, {
+        messageCount: messages.length,
+        hasTools: !!googleTools,
+        toolCount: googleTools?.length || 0,
+    });
+    let fullResponse = '';
+    let functionCalls = [];
+    try {
+        if (abortSignal?.aborted) {
+            throw new DOMException('Google stream aborted before start', 'AbortError');
+        }
+        const result = await generativeModel.generateContentStream({ contents: googleMessages }, abortSignal ? { signal: abortSignal } : undefined);
+        for await (const chunk of result.stream) {
+            if (abortSignal?.aborted) {
+                throw new DOMException('Google stream aborted', 'AbortError');
+            }
+            const chunkText = chunk.text();
+            if (chunkText) {
+                fullResponse += chunkText;
+                onChunk(chunkText);
+            }
+            // Check for function calls in the chunk
+            if (chunk.candidates?.[0]?.content?.parts) {
+                for (const part of chunk.candidates[0].content.parts) {
+                    if (part.functionCall) {
+                        functionCalls.push({
+                            id: generateId(),
+                            type: 'function',
+                            function: {
+                                name: part.functionCall.name,
+                                arguments: JSON.stringify(part.functionCall.args || {}),
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        // Return LLMResponse based on whether we have function calls or text
+        if (functionCalls.length > 0) {
+            // Filter out invalid function calls (empty or missing names)
+            const validCalls = functionCalls.filter(fc => fc.function?.name && fc.function.name.trim() !== '');
+            const invalidCount = functionCalls.length - validCalls.length;
+            if (invalidCount > 0) {
+                logger.warn(`Google Direct: Filtered ${invalidCount} invalid function calls (streaming)`, {
+                    agentId: agent.id,
+                    totalCalls: functionCalls.length
+                });
+            }
+            logger.debug(`Google Direct: Completed streaming request with function calls for agent=${agent.id}`, {
+                toolCount: validCalls.length,
+                toolNames: validCalls.map(fc => fc.function?.name)
+            });
+            return {
+                type: 'tool_calls',
+                content: fullResponse,
+                tool_calls: validCalls,
+                assistantMessage: {
+                    role: 'assistant',
+                    content: fullResponse || '',
+                    tool_calls: validCalls,
+                },
+                usage: undefined, // Google streaming doesn't provide usage in final chunk
+            };
+        }
+        logger.debug(`Google Direct: Completed streaming request for agent=${agent.id}, responseLength=${fullResponse.length}`);
+        return {
+            type: 'text',
+            content: fullResponse,
+            assistantMessage: {
+                role: 'assistant',
+                content: fullResponse,
+            },
+            usage: undefined, // Google streaming doesn't provide usage in final chunk
+        };
+    }
+    catch (error) {
+        logger.error(`Google Direct: Streaming error for agent=${agent.id}:`, error);
+        throw error;
+    }
+}
+/**
+ * Non-streaming Google response handler - Pure client (no tool execution)
+ * Returns LLMResponse with type='text' or type='tool_calls'
+ */
+export async function generateGoogleResponse(client, model, messages, agent, mcpTools, world, abortSignal) {
+    const googleTools = Object.keys(mcpTools).length > 0 ? convertMCPToolsToGoogle(mcpTools) : undefined;
+    const { messages: googleMessages, systemInstruction } = convertMessagesToGoogle(messages);
+    const generativeModel = client.getGenerativeModel({
+        model,
+        systemInstruction: systemInstruction || undefined,
+        ...(googleTools && googleTools.length > 0 && { tools: [{ functionDeclarations: googleTools }] }),
+        generationConfig: {
+            temperature: agent.temperature,
+            maxOutputTokens: agent.maxTokens,
+        }
+    });
+    logger.debug(`Google Direct: Starting non-streaming request for agent=${agent.id}, model=${model}`, {
+        messageCount: messages.length,
+        hasTools: !!googleTools,
+        toolCount: googleTools?.length || 0,
+    });
+    try {
+        if (abortSignal?.aborted) {
+            throw new DOMException('Google generation aborted before start', 'AbortError');
+        }
+        const result = await generativeModel.generateContent({ contents: googleMessages }, abortSignal ? { signal: abortSignal } : undefined);
+        const response = result.response;
+        let content = response.text() || '';
+        let functionCalls = [];
+        // Check for function calls in the response
+        if (response.candidates?.[0]?.content?.parts) {
+            for (const part of response.candidates[0].content.parts) {
+                if (part.functionCall) {
+                    functionCalls.push({
+                        id: generateId(),
+                        type: 'function',
+                        function: {
+                            name: part.functionCall.name,
+                            arguments: JSON.stringify(part.functionCall.args || {}),
+                        },
+                    });
+                }
+            }
+        }
+        // Return LLMResponse based on whether we have function calls or text
+        if (functionCalls.length > 0) {
+            // Filter out invalid function calls (empty or missing names)
+            const validCalls = functionCalls.filter(fc => fc.function?.name && fc.function.name.trim() !== '');
+            const invalidCount = functionCalls.length - validCalls.length;
+            if (invalidCount > 0) {
+                logger.warn(`Google Direct: Filtered ${invalidCount} invalid function calls (non-streaming)`, {
+                    agentId: agent.id,
+                    totalCalls: functionCalls.length
+                });
+            }
+            logger.debug(`Google Direct: Completed non-streaming request with function calls for agent=${agent.id}`, {
+                toolCount: validCalls.length,
+                toolNames: validCalls.map(fc => fc.function?.name)
+            });
+            return {
+                type: 'tool_calls',
+                content: content,
+                tool_calls: validCalls,
+                assistantMessage: {
+                    role: 'assistant',
+                    content: content,
+                    tool_calls: validCalls,
+                },
+                usage: undefined, // Google doesn't provide usage information in response
+            };
+        }
+        logger.debug(`Google Direct: Completed non-streaming request for agent=${agent.id}, responseLength=${content.length}`);
+        return {
+            type: 'text',
+            content: content,
+            assistantMessage: {
+                role: 'assistant',
+                content: content,
+            },
+            usage: undefined, // Google doesn't provide usage information in response
+        };
+    }
+    catch (error) {
+        logger.error(`Google Direct: Generation error for agent=${agent.id}:`, error);
+        throw error;
+    }
+}
+/**
+ * Factory function to create Google client for agent
+ */
+export function createGoogleClientForAgent(agent) {
+    const config = getLLMProviderConfig(agent.provider);
+    return createGoogleClient(config);
+}
+//# sourceMappingURL=google-direct.js.map

package/dist/core/google-direct.js.map

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

package/dist/core/hitl.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Human-in-the-Loop (HITL) Option Runtime
+ *
+ * Purpose:
+ * - Provide a generic world-scoped request/response flow for option-based user approvals.
+ *
+ * Key Features:
+ * - Emits structured system events for option prompts (`hitl-option-request`)
+ * - Resolves pending requests when renderer/API submits a response
+ * - Supports timeout fallback with deterministic default option
+ * - Maintains pending request map for validation and lifecycle cleanup
+ *
+ * Implementation Notes:
+ * - Requests are keyed by `(worldId, requestId)` to avoid cross-world collisions.
+ * - Timeout fallback defaults to `no` when available, otherwise first option.
+ * - Runtime is in-memory and process-local by design.
+ *
+ * Recent Changes:
+ * - 2026-02-14: Added initial generic HITL option request/response runtime.
+ */
+import { type World } from './types.js';
+export interface HitlOption {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface HitlOptionRequest {
+    requestId?: string;
+    title: string;
+    message: string;
+    options: HitlOption[];
+    chatId?: string | null;
+    timeoutMs?: number;
+    defaultOptionId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface HitlOptionResolution {
+    requestId: string;
+    worldId: string;
+    chatId: string | null;
+    optionId: string;
+    source: 'user' | 'timeout';
+}
+export declare function requestWorldOption(world: World, request: HitlOptionRequest): Promise<HitlOptionResolution>;
+export declare function submitWorldOptionResponse(params: {
+    worldId: string;
+    requestId: string;
+    optionId: string;
+}): {
+    accepted: boolean;
+    reason?: string;
+};
+export declare function clearHitlStateForTests(): void;
+//# sourceMappingURL=hitl.d.ts.map

package/dist/core/hitl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","sourceRoot":"","sources":["../../core/hitl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,KAAK,EAAyB,MAAM,YAAY,CAAC;AAG/D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAoDD,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAmE/B;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAiCzC;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAO7C"}

package/dist/core/hitl.js

@@ -0,0 +1,153 @@
+/**
+ * Human-in-the-Loop (HITL) Option Runtime
+ *
+ * Purpose:
+ * - Provide a generic world-scoped request/response flow for option-based user approvals.
+ *
+ * Key Features:
+ * - Emits structured system events for option prompts (`hitl-option-request`)
+ * - Resolves pending requests when renderer/API submits a response
+ * - Supports timeout fallback with deterministic default option
+ * - Maintains pending request map for validation and lifecycle cleanup
+ *
+ * Implementation Notes:
+ * - Requests are keyed by `(worldId, requestId)` to avoid cross-world collisions.
+ * - Timeout fallback defaults to `no` when available, otherwise first option.
+ * - Runtime is in-memory and process-local by design.
+ *
+ * Recent Changes:
+ * - 2026-02-14: Added initial generic HITL option request/response runtime.
+ */
+import { generateId } from './utils.js';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const pendingHitlRequests = new Map();
+function getPendingKey(worldId, requestId) {
+    return `${worldId}::${requestId}`;
+}
+function normalizeOptions(options) {
+    const seen = new Set();
+    const normalized = [];
+    for (const option of options) {
+        const id = String(option?.id || '').trim();
+        const label = String(option?.label || '').trim();
+        if (!id || !label || seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        normalized.push({
+            id,
+            label,
+            description: option?.description ? String(option.description) : undefined,
+        });
+    }
+    return normalized;
+}
+function resolveDefaultOptionId(options, preferredDefaultOptionId) {
+    const preferred = String(preferredDefaultOptionId || '').trim();
+    if (preferred && options.some((option) => option.id === preferred)) {
+        return preferred;
+    }
+    const explicitNo = options.find((option) => option.id === 'no');
+    if (explicitNo) {
+        return explicitNo.id;
+    }
+    return options[0]?.id || 'no';
+}
+export async function requestWorldOption(world, request) {
+    const normalizedOptions = normalizeOptions(Array.isArray(request.options) ? request.options : []);
+    if (normalizedOptions.length === 0) {
+        throw new Error('HITL option request requires at least one valid option.');
+    }
+    const worldId = String(world.id || '').trim();
+    if (!worldId) {
+        throw new Error('Cannot request HITL option without a valid world ID.');
+    }
+    const requestId = String(request.requestId || '').trim() || generateId();
+    const chatId = request.chatId !== undefined
+        ? (request.chatId ? String(request.chatId) : null)
+        : (world.currentChatId ?? null);
+    const timeoutMsRaw = Number(request.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0
+        ? Math.floor(timeoutMsRaw)
+        : DEFAULT_TIMEOUT_MS;
+    const defaultOptionId = resolveDefaultOptionId(normalizedOptions, request.defaultOptionId);
+    const pendingKey = getPendingKey(worldId, requestId);
+    return await new Promise((resolve) => {
+        const pending = {
+            worldId,
+            requestId,
+            chatId,
+            optionIds: new Set(normalizedOptions.map((option) => option.id)),
+            timeoutHandle: null,
+            resolve: (resolution) => resolve(resolution),
+        };
+        pending.timeoutHandle = setTimeout(() => {
+            const timeoutPending = pendingHitlRequests.get(pendingKey);
+            if (!timeoutPending) {
+                return;
+            }
+            pendingHitlRequests.delete(pendingKey);
+            timeoutPending.resolve({
+                requestId,
+                worldId,
+                chatId,
+                optionId: defaultOptionId,
+                source: 'timeout',
+            });
+        }, timeoutMs);
+        pendingHitlRequests.set(pendingKey, pending);
+        const event = {
+            messageId: generateId(),
+            timestamp: new Date(),
+            chatId,
+            content: {
+                eventType: 'hitl-option-request',
+                requestId,
+                title: String(request.title || '').trim(),
+                message: String(request.message || '').trim(),
+                options: normalizedOptions,
+                defaultOptionId,
+                timeoutMs,
+                metadata: request.metadata || null,
+            },
+        };
+        world.eventEmitter.emit('system', event);
+    });
+}
+export function submitWorldOptionResponse(params) {
+    const worldId = String(params.worldId || '').trim();
+    const requestId = String(params.requestId || '').trim();
+    const optionId = String(params.optionId || '').trim();
+    if (!worldId || !requestId || !optionId) {
+        return { accepted: false, reason: 'worldId, requestId, and optionId are required.' };
+    }
+    const pendingKey = getPendingKey(worldId, requestId);
+    const pending = pendingHitlRequests.get(pendingKey);
+    if (!pending) {
+        return { accepted: false, reason: `No pending HITL request found for requestId '${requestId}'.` };
+    }
+    if (!pending.optionIds.has(optionId)) {
+        return { accepted: false, reason: `Invalid option '${optionId}' for requestId '${requestId}'.` };
+    }
+    pendingHitlRequests.delete(pendingKey);
+    if (pending.timeoutHandle) {
+        clearTimeout(pending.timeoutHandle);
+    }
+    pending.resolve({
+        requestId,
+        worldId,
+        chatId: pending.chatId,
+        optionId,
+        source: 'user',
+    });
+    return { accepted: true };
+}
+export function clearHitlStateForTests() {
+    for (const pending of pendingHitlRequests.values()) {
+        if (pending.timeoutHandle) {
+            clearTimeout(pending.timeoutHandle);
+        }
+    }
+    pendingHitlRequests.clear();
+}
+//# sourceMappingURL=hitl.js.map

package/dist/core/hitl.js.map

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

package/dist/core/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Core Module - Curated Public API
+ *
+ * Features:
+ * - Essential world/agent/chat management functions for client applications
+ * - Event-driven messaging with clean subscription interface
+ * - Category-based logging system
+ * - Core types and utility functions
+ *
+ * Architecture:
+ * - Public API limited to client-facing functionality (~25 exports vs previous 60+)
+ * - Internal implementation details kept private
+ * - Clear separation between public and private interfaces
+ * - Tests can import from internal modules directly
+ *
+ * Public API Categories:
+ * - World Management: createWorld, getWorld, updateWorld, deleteWorld, listWorlds, getWorldConfig, exportWorldToMarkdown
+ * - Agent Management: getAgent, updateAgent, deleteAgent, listAgents, clearAgentMemory
+ * - Chat Management: createChatData, getChatData, restoreWorldChat
+ * - Event System: publishMessage, enableStreaming, disableStreaming
+ * - Core Types: World, Agent, AgentMessage, WorldChat, ChatData, WorldInfo, LLMProvider, LoggerConfig, LogLevel
+ * - Utilities: logger, createCategoryLogger, loggers, generateId, toKebabCase
+ * - Subscription System: subscribeWorld, ClientConnection (for server API)
+ *
+ * Private APIs (not exported):
+ * - Internal agent functions: createAgent (via world instance), updateAgentMemory, loadAgentsIntoWorld, syncWorldAgents, etc.
+ * - Internal chat functions: createChat, getChat, createWorldChat
+ * - Internal event functions: subscribeAgentToMessages, processAgentMessage, SSE functions
+ * - Parameter types: CreateAgentParams, UpdateAgentParams, etc.
+ * - Storage implementation: StorageAPI, storage factory functions
+ * - Internal utilities: initializeLogger, getCategoryLogLevel
+ *
+ * Recent Changes:
+ * - 2026-02-14: Exported generic HITL option request/response APIs for world-scoped user approval flows.
+ * - 2026-02-14: Exported `waitForInitialSkillSync` to allow callers to await startup skill-registry auto-sync completion.
+ * - 2026-02-13: Exported chat-scoped stop-message processing controls for Electron IPC stop action.
+ * - 2026-02-08: Exported LLM provider configuration helpers for npm core library consumers
+ *
+ * Version: 3.1.0
+ */
+export { createWorld, getWorld, updateWorld, setWorldVariablesText, getWorldVariablesText, getWorldEnvMap, getWorldEnvValue, deleteWorld, listWorlds, getMemory, migrateMessageIds, removeMessagesFrom, editUserMessage, logEditError, getEditErrors } from './managers.js';
+export { exportWorldToMarkdown, exportChatToMarkdown, } from './export.js';
+export { createAgent, getAgent, updateAgent, deleteAgent, listAgents, clearAgentMemory, } from './managers.js';
+export { clearToolsCache } from './mcp-server-registry.js';
+export { skillRegistry, syncSkills, waitForInitialSkillSync, getSkills, getSkillsForSystemPrompt, getSkill, getSkillSourceScope, clearSkillsForTests, type SkillRegistryEntry, type SkillSourceScope, type SkillScopeFilterOptions, type SyncSkillsOptions, type SyncSkillsResult, } from './skill-registry.js';
+export { requestWorldOption, submitWorldOptionResponse, clearHitlStateForTests, type HitlOption, type HitlOptionRequest, type HitlOptionResolution, } from './hitl.js';
+export { executeShellCommand, getExecutionHistory, clearExecutionHistory, stopShellCommandsForChat, getProcessExecution, listProcessExecutions, cancelProcessExecution, deleteProcessExecution, subscribeProcessExecutionStatus, clearProcessExecutionStateForTests, type CommandExecutionResult } from './shell-cmd-tool.js';
+export { stopMessageProcessing, type StopMessageProcessingResult } from './message-processing-control.js';
+export { newChat, branchChatFromMessage, listChats, updateChat, deleteChat, restoreChat } from './managers.js';
+export { enableStreaming, disableStreaming, publishMessage, publishMessageWithId, } from './events/index.js';
+export { beginWorldActivity, trackWorldActivity, type WorldActivityEventPayload, type WorldActivityEventType, } from './activity-tracker.js';
+export { type World, type Agent, type Chat, type AgentMessage, type RemovalResult, type EditErrorLog, LLMProvider, EventType, type LLMResponse } from './types.js';
+export { configureLLMProvider, validateProviderConfig, isProviderConfigured, getConfiguredProviders, clearAllConfiguration, getConfigurationStatus, type BaseLLMConfig, type OpenAIConfig, type AnthropicConfig, type GoogleConfig, type AzureConfig, type XAIConfig, type OpenAICompatibleConfig, type OllamaConfig, type ProviderConfigMap, type ProviderConfig, } from './llm-config.js';
+export { type LoggerConfig, type LogLevel, logger, createCategoryLogger, loggers, addLogStreamCallback } from './logger.js';
+export { type ClientConnection, subscribeWorld } from './subscription.js';
+export { getDefaultRootPath } from './storage/storage-factory.js';
+export { runMigrations, getMigrationStatus, needsMigration, type MigrationContext, type MigrationFile } from './storage/migration-runner.js';
+export declare const VERSION = "0.5.0";
+//# sourceMappingURL=index.d.ts.map

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

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