@pellux/goodvibes-sdk 0.18.13 → 0.18.15

package/dist/_internal/platform/mcp/registry.js

@@ -0,0 +1,427 @@
+/**
+ * McpRegistry — manages all connected MCP servers.
+ *
+ * Progressive loading strategy:
+ *   - On connect: load tool names + descriptions only (F2)
+ *   - On first callTool: fetch full JSON schema for that tool and cache it
+ *
+ * Tool namespace: mcp:<server-name>:<tool-name>
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { loadMcpConfig } from '@pellux/goodvibes-sdk/platform/mcp/config';
+import { McpClient } from './client.js';
+import { McpPermissionManager } from '@pellux/goodvibes-sdk/platform/runtime/mcp/permissions';
+import { McpSchemaFreshnessTracker } from '@pellux/goodvibes-sdk/platform/runtime/mcp/schema-freshness';
+import { emitMcpConfigured, emitMcpPolicyUpdated, emitMcpSchemaQuarantineApproved, emitMcpSchemaQuarantined, } from '../runtime/emitters/mcp.js';
+import { getSandboxConfigSnapshot } from '../runtime/sandbox/manager.js';
+import {} from '../runtime/sandbox/session-registry.js';
+import { resolveSandboxCommandPlan } from '../runtime/sandbox/backend.js';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+function compactEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter((entry) => typeof entry[1] === 'string'));
+}
+export class McpRegistry {
+    clients = new Map();
+    permissions = new McpPermissionManager();
+    freshness = new McpSchemaFreshnessTracker();
+    runtimeBus = null;
+    sandboxConfigManager = null;
+    sandboxSessions;
+    sandboxSessionByServer = new Map();
+    hookDispatcher;
+    constructor(options) {
+        this.hookDispatcher = options.hookDispatcher;
+        this.sandboxSessions = options.sandboxSessions;
+    }
+    setRuntimeBus(runtimeBus) {
+        this.runtimeBus = runtimeBus;
+    }
+    setSandboxRuntime(configManager, sessions) {
+        this.sandboxConfigManager = configManager;
+        this.sandboxSessions = sessions;
+    }
+    /**
+     * connectAll — Load config from .goodvibes/mcp.json and connect to all servers.
+     * Errors on individual servers are logged but do not abort the whole startup.
+     */
+    async connectAll(roots) {
+        const mcpConfig = loadMcpConfig(roots);
+        await Promise.allSettled(mcpConfig.servers.map((serverConfig) => this._connectServer(serverConfig)));
+    }
+    /**
+     * connectServer — Connect a single MCP server by config.
+     * Exposed for programmatic use (testing, dynamic registration).
+     */
+    async connectServer(serverConfig) {
+        await this._connectServer(serverConfig);
+    }
+    /**
+     * listAllTools — Return all registered tools (name + description) from all connected servers.
+     * Only loads tool names and descriptions — full schemas are NOT fetched here.
+     */
+    async listAllTools() {
+        const results = [];
+        for (const [serverName, client] of this.clients) {
+            if (!client.isConnected)
+                continue;
+            try {
+                const tools = await client.listTools();
+                for (const tool of tools) {
+                    results.push({
+                        qualifiedName: `mcp:${serverName}:${tool.name}`,
+                        serverName,
+                        toolName: tool.name,
+                        description: tool.description,
+                    });
+                }
+            }
+            catch (err) {
+                logger.info('McpRegistry: failed to list tools from server', { server: serverName, err: summarizeError(err) });
+            }
+        }
+        return results;
+    }
+    /**
+     * getToolSchema — Fetch full JSON schema for a qualified tool name.
+     * Triggers lazy schema load and caches within McpClient.
+     */
+    async getToolSchema(qualifiedName) {
+        const parsed = this._parseQualifiedName(qualifiedName);
+        if (!parsed)
+            return null;
+        const client = this.clients.get(parsed.serverName);
+        if (!client || !client.isConnected)
+            return null;
+        return client.getToolSchema(parsed.toolName);
+    }
+    /**
+     * callTool — Execute a tool by its qualified name.
+     * Fetches full schema on first use (progressive loading — F2).
+     */
+    async callTool(qualifiedName, args) {
+        const parsed = this._parseQualifiedName(qualifiedName);
+        if (!parsed) {
+            throw new Error(`McpRegistry: invalid qualified tool name '${qualifiedName}'`);
+        }
+        const client = this.clients.get(parsed.serverName);
+        if (!client) {
+            throw new Error(`McpRegistry: no server named '${parsed.serverName}'`);
+        }
+        if (!client.isConnected) {
+            throw new Error(`McpRegistry: server '${parsed.serverName}' is not connected`);
+        }
+        if (this.freshness.isQuarantined(parsed.serverName)) {
+            const record = this.freshness.getRecord(parsed.serverName);
+            throw new Error(`MCP call '${qualifiedName}' blocked: schema quarantined (${record?.quarantine?.reason ?? 'unknown'})${record?.quarantine?.detail ? ` — ${record.quarantine.detail}` : ''}`);
+        }
+        const permission = this.permissions.evaluateToolCall(parsed.serverName, parsed.toolName, args);
+        if (permission.verdict === 'deny') {
+            throw new Error(`MCP call '${qualifiedName}' denied: ${permission.reason}`);
+        }
+        if (permission.verdict === 'ask') {
+            throw new Error(`MCP call '${qualifiedName}' requires approval: ${permission.reason}`);
+        }
+        // Pre:mcp:call hook
+        const dispatcher = this.hookDispatcher;
+        const preEvent = {
+            path: 'Pre:mcp:call',
+            phase: 'Pre',
+            category: 'mcp',
+            specific: 'call',
+            sessionId: '', timestamp: Date.now(),
+            payload: { tool: qualifiedName, args },
+        };
+        const preResult = await dispatcher.fire(preEvent).catch(() => ({ ok: true, decision: undefined }));
+        if (preResult.decision === 'deny') {
+            throw new Error(`MCP call '${qualifiedName}' denied by hook: ${preResult.reason ?? 'no reason'}`);
+        }
+        try {
+            const result = await client.callTool(parsed.toolName, args);
+            this.freshness.markFresh(parsed.serverName);
+            // Post:mcp:call hook (fire-and-forget)
+            const postEvent = {
+                path: 'Post:mcp:call',
+                phase: 'Post',
+                category: 'mcp',
+                specific: 'call',
+                sessionId: '', timestamp: Date.now(),
+                payload: { tool: qualifiedName, args },
+            };
+            dispatcher.fire(postEvent).catch((err) => { logger.debug('Post:mcp:call hook error', { error: summarizeError(err) }); });
+            return result;
+        }
+        catch (err) {
+            this.freshness.markFailed(parsed.serverName, summarizeError(err));
+            // Fail:mcp:call hook (fire-and-forget)
+            const failEvent = {
+                path: 'Fail:mcp:call',
+                phase: 'Fail',
+                category: 'mcp',
+                specific: 'call',
+                sessionId: '', timestamp: Date.now(),
+                payload: { tool: qualifiedName, args, error: summarizeError(err) },
+            };
+            dispatcher.fire(failEvent).catch((hookErr) => { logger.debug('Fail:mcp:call hook error', { error: String(hookErr) }); });
+            throw err;
+        }
+    }
+    /**
+     * disconnectAll — Stop all connected MCP server processes.
+     */
+    async disconnectAll() {
+        // Lifecycle:mcp:disconnected hooks (fire-and-forget for each server)
+        const dispatcher = this.hookDispatcher;
+        for (const name of this.clients.keys()) {
+            const disconnectedEvent = {
+                path: 'Lifecycle:mcp:disconnected',
+                phase: 'Lifecycle',
+                category: 'mcp',
+                specific: 'disconnected',
+                sessionId: '', timestamp: Date.now(),
+                payload: { server: name },
+            };
+            dispatcher.fire(disconnectedEvent).catch((err) => { logger.debug('Lifecycle:mcp:disconnected hook error', { error: summarizeError(err) }); });
+        }
+        await Promise.allSettled(Array.from(this.clients.values()).map((client) => client.disconnect()));
+        this.clients.clear();
+        for (const sessionId of this.sandboxSessionByServer.values()) {
+            this.sandboxSessions.stop(sessionId);
+        }
+        this.sandboxSessionByServer.clear();
+    }
+    /**
+     * getClient — Get the McpClient for a given server name (for advanced use).
+     */
+    getClient(serverName) {
+        return this.clients.get(serverName);
+    }
+    /** Connected server names. */
+    get serverNames() {
+        return Array.from(this.clients.keys());
+    }
+    /**
+     * listServers — Return status info for all known servers (connected or not).
+     */
+    listServers() {
+        return Array.from(this.clients.entries()).map(([name, client]) => ({
+            name,
+            connected: client.isConnected,
+        }));
+    }
+    listServerSecurity() {
+        return this.listServers().map((server) => {
+            const permissions = this.permissions.getServerPermissions(server.name);
+            const freshnessRecord = this.freshness.getRecord(server.name);
+            return {
+                name: server.name,
+                connected: server.connected,
+                role: permissions?.profile.role ?? 'general',
+                trustMode: permissions?.profile.mode ?? 'ask-on-risk',
+                allowedPaths: permissions?.profile.allowedPaths ?? [],
+                allowedHosts: permissions?.profile.allowedHosts ?? [],
+                schemaFreshness: this.freshness.getFreshness(server.name),
+                quarantineReason: freshnessRecord?.quarantine?.reason,
+                quarantineDetail: freshnessRecord?.quarantine?.detail,
+                quarantineApprovedBy: freshnessRecord?.quarantine?.overrideAcknowledgedBy,
+            };
+        });
+    }
+    listServerSandboxBindings() {
+        return this.serverNames.map((name) => {
+            const sessionId = this.sandboxSessionByServer.get(name);
+            const session = sessionId ? this.sandboxSessions.get(sessionId) : null;
+            return {
+                name,
+                sessionId: sessionId ?? undefined,
+                profileId: session?.profileId === 'mcp-shared' || session?.profileId === 'mcp-per-server'
+                    ? session.profileId
+                    : undefined,
+                state: session?.state,
+                backend: session?.resolvedBackend ?? session?.backend,
+                startupStatus: session?.startupStatus,
+            };
+        });
+    }
+    setServerTrustMode(serverName, mode) {
+        this.permissions.setTrustMode(serverName, mode);
+        this._emitPolicyUpdate(serverName);
+    }
+    setServerRole(serverName, role) {
+        this.permissions.setServerRole(serverName, role);
+        this._emitPolicyUpdate(serverName);
+    }
+    listRecentSecurityDecisions(limit = 8) {
+        return this.permissions.listRecentDecisions(limit);
+    }
+    quarantineSchema(serverName, reason, detail) {
+        this.freshness.markQuarantined(serverName, reason, detail);
+        if (this.runtimeBus) {
+            emitMcpSchemaQuarantined(this.runtimeBus, {
+                sessionId: 'mcp-registry',
+                traceId: `mcp-registry:${serverName}:schema-quarantined`,
+                source: 'mcp-registry',
+            }, { serverId: serverName, reason, ...(detail ? { detail } : {}) });
+        }
+    }
+    approveSchemaQuarantine(serverName, operatorId) {
+        this.freshness.approveQuarantine(serverName, operatorId);
+        if (this.runtimeBus) {
+            emitMcpSchemaQuarantineApproved(this.runtimeBus, {
+                sessionId: 'mcp-registry',
+                traceId: `mcp-registry:${serverName}:schema-approved`,
+                source: 'mcp-registry',
+            }, { serverId: serverName, operatorId });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    async _connectServer(serverConfig) {
+        const { name } = serverConfig;
+        if (this.clients.has(name)) {
+            logger.info('McpRegistry: server already registered', { name });
+            return;
+        }
+        let sandboxSessionId = null;
+        let processSpec;
+        if (this.sandboxConfigManager) {
+            const resolved = await this._resolveSandboxProcessSpec(serverConfig);
+            sandboxSessionId = resolved?.sessionId ?? null;
+            processSpec = resolved?.processSpec;
+        }
+        const client = new McpClient(serverConfig, processSpec ? { processSpec } : undefined);
+        this.freshness.registerServer(name);
+        try {
+            await client.connect();
+            this.permissions.registerServer(name, 'standard', {
+                role: serverConfig.role ?? 'general',
+                mode: serverConfig.trustMode ?? 'ask-on-risk',
+                allowedPaths: serverConfig.allowedPaths ?? [],
+                allowedHosts: serverConfig.allowedHosts ?? [],
+            });
+            this.clients.set(name, client);
+            if (sandboxSessionId) {
+                this.sandboxSessionByServer.set(name, sandboxSessionId);
+            }
+            this.freshness.markFresh(name);
+            logger.info('McpRegistry: server connected', { name });
+            if (this.runtimeBus) {
+                emitMcpConfigured(this.runtimeBus, {
+                    sessionId: 'mcp-registry',
+                    traceId: `mcp-registry:${name}:configured`,
+                    source: 'mcp-registry',
+                }, {
+                    serverId: name,
+                    transport: 'stdio',
+                    role: serverConfig.role ?? 'general',
+                    trustMode: serverConfig.trustMode ?? 'ask-on-risk',
+                    allowedPaths: serverConfig.allowedPaths ?? [],
+                    allowedHosts: serverConfig.allowedHosts ?? [],
+                });
+            }
+            // Lifecycle:mcp:connected hook (fire-and-forget)
+            const connectedEvent = {
+                path: 'Lifecycle:mcp:connected',
+                phase: 'Lifecycle',
+                category: 'mcp',
+                specific: 'connected',
+                sessionId: '', timestamp: Date.now(),
+                payload: { server: name },
+            };
+            this.hookDispatcher.fire(connectedEvent).catch((err) => { logger.debug('Lifecycle:mcp:connected hook error', { error: summarizeError(err) }); });
+        }
+        catch (err) {
+            if (sandboxSessionId) {
+                this.sandboxSessions.stop(sandboxSessionId);
+                this.sandboxSessionByServer.delete(name);
+            }
+            this.freshness.markFailed(name, summarizeError(err));
+            logger.error('McpRegistry: failed to connect server', { name, err: summarizeError(err) });
+            // Don't register the client — it's not usable
+        }
+    }
+    async _resolveSandboxProcessSpec(serverConfig) {
+        const configManager = this.sandboxConfigManager;
+        if (!configManager)
+            return null;
+        const sandbox = getSandboxConfigSnapshot(configManager);
+        if (sandbox.mcpIsolation === 'disabled')
+            return null;
+        const profileId = this._selectSandboxProfile(serverConfig);
+        const label = `${serverConfig.name} MCP`;
+        const session = await this.sandboxSessions.start(profileId, label, configManager);
+        if (!session.launchPlan) {
+            throw new Error(`Sandbox session ${session.id} for MCP server '${serverConfig.name}' is missing a launch plan.`);
+        }
+        const resolvedPlan = resolveSandboxCommandPlan(session.launchPlan, serverConfig.command, serverConfig.args ?? [], configManager);
+        return {
+            sessionId: session.id,
+            processSpec: {
+                command: resolvedPlan.command,
+                args: [...resolvedPlan.args],
+                env: compactEnv({ ...(serverConfig.env ?? {}), ...(resolvedPlan.env ?? {}) }),
+                cwd: session.launchPlan.workspaceRoot,
+                summary: resolvedPlan.summary,
+                sandboxSessionId: session.id,
+            },
+        };
+    }
+    _selectSandboxProfile(serverConfig) {
+        const configManager = this.sandboxConfigManager;
+        if (!configManager)
+            return 'mcp-shared';
+        const sandbox = getSandboxConfigSnapshot(configManager);
+        switch (sandbox.mcpIsolation) {
+            case 'per-server-vm':
+                return 'mcp-per-server';
+            case 'shared-vm':
+                return 'mcp-shared';
+            case 'hybrid':
+                return this._requiresDedicatedMcpSandbox(serverConfig) ? 'mcp-per-server' : 'mcp-shared';
+            case 'disabled':
+            default:
+                return 'mcp-shared';
+        }
+    }
+    _requiresDedicatedMcpSandbox(serverConfig) {
+        return Boolean((serverConfig.allowedHosts?.length ?? 0) > 0
+            || (serverConfig.allowedPaths?.length ?? 0) > 0
+            || serverConfig.role === 'automation'
+            || serverConfig.role === 'browser'
+            || serverConfig.role === 'ops'
+            || serverConfig.role === 'remote');
+    }
+    /**
+     * Parse mcp:<server>:<tool> qualified name.
+     * Returns null if the name doesn't match the expected format.
+     */
+    _parseQualifiedName(qualifiedName) {
+        const parts = qualifiedName.split(':');
+        if (parts.length < 3 || parts[0] !== 'mcp')
+            return null;
+        // serverName is parts[1], toolName is the rest joined (tools can have colons)
+        const serverName = parts[1];
+        const toolName = parts.slice(2).join(':');
+        if (!serverName || !toolName)
+            return null;
+        return { serverName, toolName };
+    }
+    _emitPolicyUpdate(serverName) {
+        if (!this.runtimeBus)
+            return;
+        const permissions = this.permissions.getServerPermissions(serverName);
+        if (!permissions)
+            return;
+        emitMcpPolicyUpdated(this.runtimeBus, {
+            sessionId: 'mcp-registry',
+            traceId: `mcp-registry:${serverName}:policy`,
+            source: 'mcp-registry',
+        }, {
+            serverId: serverName,
+            role: permissions.profile.role,
+            trustMode: permissions.profile.mode,
+            allowedPaths: [...permissions.profile.allowedPaths],
+            allowedHosts: [...permissions.profile.allowedHosts],
+        });
+    }
+}

package/dist/_internal/platform/media/builtin-image-understanding.d.ts

@@ -0,0 +1,11 @@
+import { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts/index';
+import type { ProviderRegistry } from '../providers/registry.js';
+import type { MediaProvider } from '@pellux/goodvibes-sdk/platform/media/provider-registry';
+type ImageModelRegistry = Pick<ProviderRegistry, 'getCurrentModel' | 'getForModel' | 'listModels' | 'describeRuntime'>;
+export declare function createBuiltinImageUnderstandingProvider(providerRegistry: ImageModelRegistry, artifactStore: Pick<ArtifactStore, 'readContent'>): MediaProvider;
+export declare function createOpenAIImageUnderstandingProvider(providerRegistry: ImageModelRegistry, artifactStore: Pick<ArtifactStore, 'readContent'>): MediaProvider;
+export declare function createGeminiImageUnderstandingProvider(providerRegistry: ImageModelRegistry, artifactStore: Pick<ArtifactStore, 'readContent'>): MediaProvider;
+export declare function createAnthropicImageUnderstandingProvider(providerRegistry: ImageModelRegistry, artifactStore: Pick<ArtifactStore, 'readContent'>): MediaProvider;
+export declare function createLocalImageUnderstandingProvider(providerRegistry: ImageModelRegistry, artifactStore: Pick<ArtifactStore, 'readContent'>): MediaProvider;
+export {};
+//# sourceMappingURL=builtin-image-understanding.d.ts.map

package/dist/_internal/platform/media/builtin-image-understanding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-image-understanding.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/media/builtin-image-understanding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAE/E,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,KAAK,EAGV,aAAa,EAEd,MAAM,wDAAwD,CAAC;AAgBhE,KAAK,kBAAkB,GAAG,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,GAAG,aAAa,GAAG,YAAY,GAAG,iBAAiB,CAAC,CAAC;AAkOvH,wBAAgB,uCAAuC,CACrD,gBAAgB,EAAE,kBAAkB,EACpC,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,GAChD,aAAa,CAKf;AAED,wBAAgB,sCAAsC,CACpD,gBAAgB,EAAE,kBAAkB,EACpC,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,GAChD,aAAa,CAMf;AAED,wBAAgB,sCAAsC,CACpD,gBAAgB,EAAE,kBAAkB,EACpC,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,GAChD,aAAa,CAMf;AAED,wBAAgB,yCAAyC,CACvD,gBAAgB,EAAE,kBAAkB,EACpC,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,GAChD,aAAa,CAMf;AAED,wBAAgB,qCAAqC,CACnD,gBAAgB,EAAE,kBAAkB,EACpC,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,GAChD,aAAa,CAMf"}

package/dist/_internal/platform/media/builtin-image-understanding.js

@@ -0,0 +1,226 @@
+import { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts/index';
+function buildAnalysisPrompt(prompt) {
+    const task = prompt?.trim().length
+        ? prompt.trim()
+        : 'Describe the image, extract visible text, and identify the main labels or objects.';
+    return [
+        'Analyze the attached image.',
+        `Task: ${task}`,
+        'Return valid JSON only with this shape:',
+        '{"description":"string","text":"string","labels":["string"],"observations":{}}',
+        'Use an empty string or empty array when a field is not available.',
+    ].join('\n');
+}
+function parseStructuredAnalysis(content) {
+    const candidates = [
+        content.trim(),
+        ...[...content.matchAll(/```json\s*([\s\S]*?)```/gi)].map((match) => match[1]?.trim() ?? ''),
+        ...[...content.matchAll(/(\{[\s\S]*\})/g)].map((match) => match[1]?.trim() ?? ''),
+    ].filter((candidate, index, values) => candidate.length > 0 && values.indexOf(candidate) === index);
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed && typeof parsed === 'object')
+                return parsed;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function normalizeLabels(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+        .map((entry) => entry.trim());
+}
+async function modelMatchesScope(providerRegistry, model, scope) {
+    const providerId = typeof model.provider === 'string' ? model.provider : '';
+    if ((scope.allowProviderIds?.length ?? 0) > 0 && !scope.allowProviderIds.includes(providerId)) {
+        return false;
+    }
+    if (!scope.requireLocal)
+        return true;
+    try {
+        const runtime = await providerRegistry.describeRuntime(providerId);
+        return runtime?.policy?.local === true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveModel(providerRegistry, scope, modelId) {
+    const models = providerRegistry.listModels();
+    const resolveCandidate = async () => {
+        if (modelId) {
+            const explicit = models.find((model) => model.registryKey === modelId || model.id === modelId);
+            if (!explicit) {
+                throw new Error(`Unknown model for media analysis: ${modelId}`);
+            }
+            if (!explicit.capabilities.multimodal) {
+                throw new Error(`Model does not support image input: ${explicit.displayName}`);
+            }
+            if (!await modelMatchesScope(providerRegistry, explicit, scope)) {
+                throw new Error(`Model does not match media provider scope ${scope.label}: ${explicit.displayName}`);
+            }
+            return explicit;
+        }
+        const current = providerRegistry.getCurrentModel();
+        if (current.capabilities.multimodal && await modelMatchesScope(providerRegistry, current, scope)) {
+            return current;
+        }
+        for (const candidate of models) {
+            if (!candidate.selectable || !candidate.capabilities.multimodal)
+                continue;
+            if (await modelMatchesScope(providerRegistry, candidate, scope)) {
+                return candidate;
+            }
+        }
+        const fallback = models.find((model) => model.selectable && model.capabilities.multimodal);
+        if (fallback)
+            return fallback;
+        throw new Error('No multimodal model is available for image understanding');
+    };
+    const selected = await resolveCandidate();
+    const provider = providerRegistry.getForModel(selected.registryKey ?? selected.id, selected.provider);
+    return {
+        providerId: selected.provider,
+        provider,
+        modelId: selected.id,
+    };
+}
+async function resolveArtifactInput(artifactStore, request) {
+    if (request.artifact.dataBase64) {
+        return {
+            mimeType: request.artifact.mimeType,
+            dataBase64: request.artifact.dataBase64,
+            metadata: request.artifact.metadata,
+        };
+    }
+    const artifactId = request.artifact.artifactId ?? request.artifact.id;
+    if (artifactId) {
+        const { record, buffer } = await artifactStore.readContent(artifactId);
+        return {
+            mimeType: record.mimeType,
+            dataBase64: buffer.toString('base64'),
+            metadata: record.metadata,
+        };
+    }
+    throw new Error('Media analysis requires dataBase64 or artifactId');
+}
+async function analyzeWithScope(providerRegistry, scope, artifactStore, request) {
+    const artifact = await resolveArtifactInput(artifactStore, request);
+    if (!artifact.mimeType.toLowerCase().startsWith('image/')) {
+        throw new Error(`Unsupported media type for image understanding: ${artifact.mimeType}`);
+    }
+    const selected = await resolveModel(providerRegistry, scope, request.modelId);
+    const content = [
+        { type: 'text', text: buildAnalysisPrompt(request.prompt) },
+        { type: 'image', data: artifact.dataBase64, mediaType: artifact.mimeType },
+    ];
+    const messages = [
+        {
+            role: 'user',
+            content,
+        },
+    ];
+    const response = await selected.provider.chat({
+        model: selected.modelId,
+        messages,
+        maxTokens: 1200,
+    });
+    const structured = parseStructuredAnalysis(response.content);
+    if (structured) {
+        const { description, text, labels, ...rest } = structured;
+        return {
+            providerId: scope.providerId,
+            description: typeof description === 'string' ? description.trim() : undefined,
+            text: typeof text === 'string' ? text.trim() : undefined,
+            labels: normalizeLabels(labels),
+            metadata: {
+                ...request.metadata,
+                ...artifact.metadata,
+                llmProviderId: selected.providerId,
+                modelId: selected.modelId,
+                structured: rest,
+            },
+        };
+    }
+    return {
+        providerId: scope.providerId,
+        description: response.content.trim() || undefined,
+        metadata: {
+            ...request.metadata,
+            ...artifact.metadata,
+            llmProviderId: selected.providerId,
+            modelId: selected.modelId,
+            format: 'plain-text-fallback',
+        },
+    };
+}
+function createScopedImageUnderstandingProvider(providerRegistry, scope, artifactStore) {
+    return {
+        id: scope.providerId,
+        label: scope.label,
+        capabilities: ['understand'],
+        async status() {
+            let available = false;
+            for (const model of providerRegistry.listModels()) {
+                if (!model.selectable || !model.capabilities.multimodal)
+                    continue;
+                if (await modelMatchesScope(providerRegistry, model, scope)) {
+                    available = true;
+                    break;
+                }
+            }
+            return {
+                id: scope.providerId,
+                label: scope.label,
+                state: available ? 'healthy' : 'unconfigured',
+                capabilities: ['understand'],
+                configured: available,
+                detail: available
+                    ? `Uses ${scope.label} model routing for image understanding.`
+                    : `Register a matching multimodal model to enable ${scope.label}.`,
+                metadata: {},
+            };
+        },
+        analyze: (request) => analyzeWithScope(providerRegistry, scope, artifactStore, request),
+    };
+}
+export function createBuiltinImageUnderstandingProvider(providerRegistry, artifactStore) {
+    return createScopedImageUnderstandingProvider(providerRegistry, {
+        providerId: 'builtin:image-understanding',
+        label: 'Built-in Image Understanding',
+    }, artifactStore);
+}
+export function createOpenAIImageUnderstandingProvider(providerRegistry, artifactStore) {
+    return createScopedImageUnderstandingProvider(providerRegistry, {
+        providerId: 'builtin:image-openai',
+        label: 'OpenAI Image Understanding',
+        allowProviderIds: ['openai'],
+    }, artifactStore);
+}
+export function createGeminiImageUnderstandingProvider(providerRegistry, artifactStore) {
+    return createScopedImageUnderstandingProvider(providerRegistry, {
+        providerId: 'builtin:image-gemini',
+        label: 'Gemini Image Understanding',
+        allowProviderIds: ['gemini'],
+    }, artifactStore);
+}
+export function createAnthropicImageUnderstandingProvider(providerRegistry, artifactStore) {
+    return createScopedImageUnderstandingProvider(providerRegistry, {
+        providerId: 'builtin:image-anthropic',
+        label: 'Anthropic Image Understanding',
+        allowProviderIds: ['anthropic'],
+    }, artifactStore);
+}
+export function createLocalImageUnderstandingProvider(providerRegistry, artifactStore) {
+    return createScopedImageUnderstandingProvider(providerRegistry, {
+        providerId: 'builtin:image-local',
+        label: 'Local OpenAI-Compatible Image Understanding',
+        requireLocal: true,
+    }, artifactStore);
+}

package/dist/_internal/platform/media/builtin-providers.d.ts

@@ -0,0 +1,5 @@
+import { MediaProviderRegistry } from '@pellux/goodvibes-sdk/platform/media/provider-registry';
+import type { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts/index';
+import type { ProviderRegistry } from '../providers/registry.js';
+export declare function ensureBuiltinMediaProviders(registry: MediaProviderRegistry, artifactStore: Pick<ArtifactStore, 'readContent'>, providerRegistry: Pick<ProviderRegistry, 'describeRuntime' | 'getCurrentModel' | 'getForModel' | 'listModels'>): void;
+//# sourceMappingURL=builtin-providers.d.ts.map

package/dist/_internal/platform/media/builtin-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-providers.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/media/builtin-providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAS/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,qBAAqB,EAC/B,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,EACjD,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,aAAa,GAAG,YAAY,CAAC,GAC7G,IAAI,CASN"}