@pellux/goodvibes-sdk 0.18.14 → 0.18.15

package/dist/_internal/platform/channels/route-manager.js

@@ -0,0 +1,280 @@
+import { createHash } from 'node:crypto';
+import { createDomainDispatch } from '../runtime/store/index.js';
+import { emitRouteBindingCreated, emitRouteBindingFailed, emitRouteBindingResolved, emitRouteBindingUpdated, emitRouteReplyTargetCaptured, } from '../runtime/emitters/index.js';
+import { AutomationRouteStore } from '@pellux/goodvibes-sdk/platform/automation/store/routes';
+function toEventSurfaceKind(surfaceKind) {
+    switch (surfaceKind) {
+        case 'tui':
+        case 'slack':
+        case 'discord':
+        case 'web':
+        case 'ntfy':
+        case 'webhook':
+        case 'telegram':
+        case 'google-chat':
+        case 'signal':
+        case 'whatsapp':
+        case 'imessage':
+        case 'msteams':
+        case 'bluebubbles':
+        case 'mattermost':
+        case 'matrix':
+        case 'service':
+            return surfaceKind;
+    }
+    const _exhaustive = surfaceKind;
+    return _exhaustive;
+}
+function sortBindings(bindings) {
+    return [...bindings].sort((a, b) => b.lastSeenAt - a.lastSeenAt || a.id.localeCompare(b.id));
+}
+function routeNaturalKey(input) {
+    return [
+        input.surfaceKind,
+        input.surfaceId,
+        input.externalId,
+        input.threadId ?? '',
+        input.channelId ?? '',
+    ].join('\u001f');
+}
+function deterministicRouteId(input) {
+    return `route-${createHash('sha256').update(routeNaturalKey(input)).digest('hex').slice(0, 12)}`;
+}
+export class RouteBindingManager {
+    store;
+    bindings = new Map();
+    runtimeDispatch = null;
+    runtimeBus = null;
+    loaded = false;
+    constructor(config = {}) {
+        this.store = config.store ?? new AutomationRouteStore();
+        if (config.runtimeStore)
+            this.runtimeDispatch = createDomainDispatch(config.runtimeStore);
+        this.runtimeBus = config.runtimeBus ?? null;
+    }
+    attachRuntime(config) {
+        if (config.runtimeStore) {
+            this.runtimeDispatch = createDomainDispatch(config.runtimeStore);
+            for (const binding of this.bindings.values()) {
+                this.runtimeDispatch.syncRouteBinding(binding, 'routes.attach');
+            }
+        }
+        if (config.runtimeBus) {
+            this.runtimeBus = config.runtimeBus;
+        }
+    }
+    async start() {
+        if (this.loaded)
+            return;
+        const snapshot = await this.store.load();
+        this.bindings.clear();
+        for (const binding of snapshot.routes) {
+            this.bindings.set(binding.id, binding);
+            this.runtimeDispatch?.syncRouteBinding(binding, 'routes.load');
+        }
+        this.loaded = true;
+    }
+    listBindings() {
+        return sortBindings(this.bindings.values());
+    }
+    getBinding(bindingId) {
+        return this.bindings.get(bindingId);
+    }
+    resolve(surfaceKind, externalId, threadId) {
+        const binding = this.listBindings().find((entry) => {
+            if (entry.surfaceKind !== surfaceKind)
+                return false;
+            if (entry.externalId !== externalId)
+                return false;
+            if (threadId) {
+                return entry.threadId === threadId || entry.channelId === threadId;
+            }
+            return true;
+        });
+        if (!binding)
+            return undefined;
+        const eventSurfaceKind = toEventSurfaceKind(binding.surfaceKind);
+        if (this.runtimeBus) {
+            const targetId = binding.sessionId ?? binding.runId ?? binding.jobId ?? binding.externalId;
+            const targetKind = binding.sessionId ? 'session' : binding.runId ? 'run' : binding.jobId ? 'job' : 'message';
+            emitRouteBindingResolved(this.runtimeBus, {
+                sessionId: binding.sessionId ?? 'routes',
+                source: 'route-binding-manager',
+                traceId: binding.id,
+            }, {
+                bindingId: binding.id,
+                surfaceKind: eventSurfaceKind,
+                externalId: binding.externalId,
+                targetKind,
+                targetId,
+            });
+        }
+        return binding;
+    }
+    async upsertBinding(input) {
+        await this.start();
+        const now = Date.now();
+        const previous = input.id
+            ? this.bindings.get(input.id)
+            : this.listBindings().find((entry) => routeNaturalKey(entry) === routeNaturalKey(input));
+        const binding = {
+            id: input.id ?? previous?.id ?? deterministicRouteId(input),
+            kind: input.kind,
+            surfaceKind: input.surfaceKind,
+            surfaceId: input.surfaceId,
+            externalId: input.externalId,
+            sessionPolicy: input.sessionPolicy ?? previous?.sessionPolicy ?? 'create-or-bind',
+            threadPolicy: input.threadPolicy ?? previous?.threadPolicy ?? 'preserve',
+            deliveryGuarantee: input.deliveryGuarantee ?? previous?.deliveryGuarantee ?? 'best-effort',
+            threadId: input.threadId ?? previous?.threadId,
+            channelId: input.channelId ?? previous?.channelId,
+            sessionId: input.sessionId ?? previous?.sessionId,
+            jobId: input.jobId ?? previous?.jobId,
+            runId: input.runId ?? previous?.runId,
+            title: input.title ?? previous?.title,
+            lastSeenAt: now,
+            createdAt: previous?.createdAt ?? now,
+            updatedAt: now,
+            metadata: {
+                ...(previous?.metadata ?? {}),
+                ...(input.metadata ?? {}),
+            },
+        };
+        this.bindings.set(binding.id, binding);
+        await this.store.save(sortBindings(this.bindings.values()));
+        this.runtimeDispatch?.syncRouteBinding(binding, 'routes.upsert');
+        const eventSurfaceKind = toEventSurfaceKind(binding.surfaceKind);
+        if (this.runtimeBus) {
+            const targetId = binding.sessionId ?? binding.runId ?? binding.jobId ?? binding.externalId;
+            const targetKind = binding.sessionId ? 'session' : binding.runId ? 'run' : binding.jobId ? 'job' : 'message';
+            if (previous) {
+                emitRouteBindingUpdated(this.runtimeBus, {
+                    sessionId: binding.sessionId ?? 'routes',
+                    source: 'route-binding-manager',
+                    traceId: binding.id,
+                }, {
+                    bindingId: binding.id,
+                    changedFields: ['sessionPolicy', 'threadPolicy', 'deliveryGuarantee', 'threadId', 'channelId', 'sessionId', 'jobId', 'runId', 'metadata'],
+                });
+            }
+            else {
+                emitRouteBindingCreated(this.runtimeBus, {
+                    sessionId: binding.sessionId ?? 'routes',
+                    source: 'route-binding-manager',
+                    traceId: binding.id,
+                }, {
+                    bindingId: binding.id,
+                    surfaceKind: eventSurfaceKind,
+                    externalId: binding.externalId,
+                    targetKind,
+                    targetId,
+                });
+            }
+        }
+        return binding;
+    }
+    async captureReplyTarget(bindingId, replyTargetId, threadId) {
+        await this.start();
+        const binding = this.bindings.get(bindingId);
+        if (!binding)
+            return null;
+        const updated = {
+            ...binding,
+            threadId: threadId ?? binding.threadId,
+            updatedAt: Date.now(),
+            lastSeenAt: Date.now(),
+            metadata: {
+                ...binding.metadata,
+                replyTargetId,
+            },
+        };
+        this.bindings.set(bindingId, updated);
+        await this.store.save(sortBindings(this.bindings.values()));
+        this.runtimeDispatch?.syncRouteBinding(updated, 'routes.reply-target');
+        const eventSurfaceKind = toEventSurfaceKind(updated.surfaceKind);
+        if (this.runtimeBus) {
+            emitRouteReplyTargetCaptured(this.runtimeBus, {
+                sessionId: updated.sessionId ?? 'routes',
+                source: 'route-binding-manager',
+                traceId: updated.id,
+            }, {
+                bindingId: updated.id,
+                surfaceKind: eventSurfaceKind,
+                externalId: updated.externalId,
+                replyTargetId,
+                threadId: updated.threadId ?? '',
+            });
+        }
+        return updated;
+    }
+    async patchBinding(bindingId, patch) {
+        await this.start();
+        const binding = this.bindings.get(bindingId);
+        if (!binding)
+            return null;
+        const updated = {
+            ...binding,
+            ...(patch.sessionPolicy !== undefined ? { sessionPolicy: patch.sessionPolicy } : {}),
+            ...(patch.threadPolicy !== undefined ? { threadPolicy: patch.threadPolicy } : {}),
+            ...(patch.deliveryGuarantee !== undefined ? { deliveryGuarantee: patch.deliveryGuarantee } : {}),
+            ...(patch.threadId !== undefined ? { threadId: patch.threadId } : {}),
+            ...(patch.channelId !== undefined ? { channelId: patch.channelId } : {}),
+            ...(patch.sessionId !== undefined ? { sessionId: patch.sessionId ?? undefined } : {}),
+            ...(patch.jobId !== undefined ? { jobId: patch.jobId ?? undefined } : {}),
+            ...(patch.runId !== undefined ? { runId: patch.runId ?? undefined } : {}),
+            ...(patch.title !== undefined ? { title: patch.title } : {}),
+            updatedAt: Date.now(),
+            lastSeenAt: Date.now(),
+            metadata: {
+                ...binding.metadata,
+                ...(patch.metadata ?? {}),
+            },
+        };
+        this.bindings.set(bindingId, updated);
+        await this.store.save(sortBindings(this.bindings.values()));
+        this.runtimeDispatch?.syncRouteBinding(updated, 'routes.patch');
+        const eventSurfaceKind = toEventSurfaceKind(updated.surfaceKind);
+        if (this.runtimeBus) {
+            emitRouteBindingUpdated(this.runtimeBus, {
+                sessionId: updated.sessionId ?? 'routes',
+                source: 'route-binding-manager',
+                traceId: updated.id,
+            }, {
+                bindingId: updated.id,
+                changedFields: [
+                    ...(patch.threadId !== undefined ? ['threadId'] : []),
+                    ...(patch.channelId !== undefined ? ['channelId'] : []),
+                    ...(patch.sessionId !== undefined ? ['sessionId'] : []),
+                    ...(patch.jobId !== undefined ? ['jobId'] : []),
+                    ...(patch.runId !== undefined ? ['runId'] : []),
+                    ...(patch.title !== undefined ? ['title'] : []),
+                    ...(patch.metadata ? ['metadata'] : []),
+                ],
+            });
+        }
+        return updated;
+    }
+    async removeBinding(bindingId) {
+        await this.start();
+        const removed = this.bindings.delete(bindingId);
+        if (!removed)
+            return false;
+        await this.store.save(sortBindings(this.bindings.values()));
+        return true;
+    }
+    recordFailure(surfaceKind, externalId, error) {
+        this.runtimeDispatch?.recordRouteBindingFailure(surfaceKind, externalId, 'routes.failure');
+        const eventSurfaceKind = toEventSurfaceKind(surfaceKind);
+        if (this.runtimeBus) {
+            emitRouteBindingFailed(this.runtimeBus, {
+                sessionId: 'routes',
+                source: 'route-binding-manager',
+                traceId: `${surfaceKind}:${externalId}`,
+            }, {
+                surfaceKind: eventSurfaceKind,
+                externalId,
+                error,
+            });
+        }
+    }
+}

package/dist/_internal/platform/channels/surface-registry.d.ts

@@ -0,0 +1,16 @@
+import type { RuntimeStore } from '../runtime/store/index.js';
+import type { SurfaceRecord } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/surfaces';
+import { ConfigManager } from '../config/manager.js';
+import type { ChannelPluginRegistry } from './plugin-registry.js';
+export declare class SurfaceRegistry {
+    private readonly configManager;
+    private readonly surfaces;
+    private runtimeDispatch;
+    private pluginRegistry;
+    constructor(configManager: ConfigManager, runtimeStore?: RuntimeStore);
+    attachRuntime(runtimeStore: RuntimeStore): void;
+    attachPluginRegistry(pluginRegistry: ChannelPluginRegistry): void;
+    syncConfiguredSurfaces(): SurfaceRecord[];
+    list(): SurfaceRecord[];
+}
+//# sourceMappingURL=surface-registry.d.ts.map

package/dist/_internal/platform/channels/surface-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-registry.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/channels/surface-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+DAA+D,CAAC;AACnG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAMlE,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,cAAc,CAAsC;gBAEhD,aAAa,EAAE,aAAa,EAAE,YAAY,CAAC,EAAE,YAAY;IAKrE,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAO/C,oBAAoB,CAAC,cAAc,EAAE,qBAAqB,GAAG,IAAI;IAIjE,sBAAsB,IAAI,aAAa,EAAE;IAsJzC,IAAI,IAAI,aAAa,EAAE;CAGxB"}

package/dist/_internal/platform/channels/surface-registry.js

@@ -0,0 +1,197 @@
+import { createDomainDispatch } from '../runtime/store/index.js';
+import { ConfigManager } from '../config/manager.js';
+function now() {
+    return Date.now();
+}
+export class SurfaceRegistry {
+    configManager;
+    surfaces = new Map();
+    runtimeDispatch = null;
+    pluginRegistry = null;
+    constructor(configManager, runtimeStore) {
+        this.configManager = configManager;
+        if (runtimeStore)
+            this.runtimeDispatch = createDomainDispatch(runtimeStore);
+    }
+    attachRuntime(runtimeStore) {
+        this.runtimeDispatch = createDomainDispatch(runtimeStore);
+        for (const surface of this.surfaces.values()) {
+            this.runtimeDispatch.syncSurface(surface, 'surfaces.attach');
+        }
+    }
+    attachPluginRegistry(pluginRegistry) {
+        this.pluginRegistry = pluginRegistry;
+    }
+    syncConfiguredSurfaces() {
+        const configuredAt = now();
+        const pluginDescriptors = this.pluginRegistry?.listDescriptors() ?? [];
+        const enabledForSurface = (surface) => {
+            if (surface === 'tui')
+                return true;
+            if (surface === 'web')
+                return Boolean(this.configManager.get('web.enabled') || this.configManager.get('controlPlane.enabled'));
+            if (surface === 'slack')
+                return Boolean(this.configManager.get('surfaces.slack.enabled'));
+            if (surface === 'discord')
+                return Boolean(this.configManager.get('surfaces.discord.enabled'));
+            if (surface === 'ntfy')
+                return Boolean(this.configManager.get('surfaces.ntfy.enabled'));
+            if (surface === 'webhook') {
+                return Boolean(this.configManager.get('surfaces.webhook.enabled')
+                    || this.configManager.get('surfaces.webhook.defaultTarget')
+                    || this.configManager.get('surfaces.webhook.secret'));
+            }
+            const surfaces = this.configManager.getCategory('surfaces');
+            if (surface === 'telegram')
+                return Boolean(surfaces.telegram.enabled || surfaces.telegram.botToken || surfaces.telegram.defaultChatId);
+            if (surface === 'google-chat')
+                return Boolean(surfaces.googleChat.enabled || surfaces.googleChat.webhookUrl || surfaces.googleChat.spaceId);
+            if (surface === 'signal')
+                return Boolean(surfaces.signal.enabled || surfaces.signal.bridgeUrl || surfaces.signal.account);
+            if (surface === 'whatsapp')
+                return Boolean(surfaces.whatsapp.enabled || surfaces.whatsapp.accessToken || surfaces.whatsapp.phoneNumberId);
+            if (surface === 'imessage')
+                return Boolean(surfaces.imessage.enabled || surfaces.imessage.bridgeUrl || surfaces.imessage.account);
+            if (surface === 'msteams')
+                return Boolean(surfaces.msteams.enabled || surfaces.msteams.appId || surfaces.msteams.defaultConversationId);
+            if (surface === 'bluebubbles')
+                return Boolean(surfaces.bluebubbles.enabled || surfaces.bluebubbles.serverUrl || surfaces.bluebubbles.defaultChatGuid);
+            if (surface === 'mattermost')
+                return Boolean(surfaces.mattermost.enabled || surfaces.mattermost.baseUrl || surfaces.mattermost.defaultChannelId);
+            if (surface === 'matrix')
+                return Boolean(surfaces.matrix.enabled || surfaces.matrix.homeserverUrl || surfaces.matrix.defaultRoomId);
+            return false;
+        };
+        const accountIdForSurface = (surface) => {
+            const surfaces = this.configManager.getCategory('surfaces');
+            if (surface === 'slack')
+                return String(this.configManager.get('surfaces.slack.workspaceId') || '') || undefined;
+            if (surface === 'discord')
+                return String(this.configManager.get('surfaces.discord.applicationId') || '') || undefined;
+            if (surface === 'telegram')
+                return surfaces.telegram.botUsername || surfaces.telegram.defaultChatId || undefined;
+            if (surface === 'google-chat')
+                return surfaces.googleChat.appId || surfaces.googleChat.spaceId || undefined;
+            if (surface === 'signal')
+                return surfaces.signal.account || surfaces.signal.defaultRecipient || undefined;
+            if (surface === 'whatsapp')
+                return surfaces.whatsapp.phoneNumberId || surfaces.whatsapp.defaultRecipient || undefined;
+            if (surface === 'imessage')
+                return surfaces.imessage.account || surfaces.imessage.defaultChatId || undefined;
+            if (surface === 'msteams')
+                return surfaces.msteams.botId || surfaces.msteams.defaultConversationId || undefined;
+            if (surface === 'bluebubbles')
+                return surfaces.bluebubbles.account || surfaces.bluebubbles.defaultChatGuid || undefined;
+            if (surface === 'mattermost')
+                return surfaces.mattermost.teamId || surfaces.mattermost.defaultChannelId || undefined;
+            if (surface === 'matrix')
+                return surfaces.matrix.userId || surfaces.matrix.defaultRoomId || undefined;
+            return undefined;
+        };
+        const records = pluginDescriptors.length > 0 ? pluginDescriptors.map((descriptor) => ({
+            id: `surface:${descriptor.surface}`,
+            kind: descriptor.surface,
+            label: descriptor.displayName,
+            enabled: enabledForSurface(descriptor.surface),
+            state: enabledForSurface(descriptor.surface) ? 'healthy' : 'disabled',
+            configuredAt,
+            lastSeenAt: configuredAt,
+            ...(accountIdForSurface(descriptor.surface) ? { accountId: accountIdForSurface(descriptor.surface) } : {}),
+            capabilities: [...descriptor.capabilities],
+            metadata: {},
+        })) : [
+            {
+                id: 'surface:tui',
+                kind: 'tui',
+                label: 'Terminal UI',
+                enabled: true,
+                state: 'healthy',
+                configuredAt,
+                lastSeenAt: configuredAt,
+                capabilities: ['ingress', 'egress', 'session_binding'],
+                metadata: {},
+            },
+            {
+                id: 'surface:web',
+                kind: 'web',
+                label: 'Web control plane',
+                enabled: Boolean(this.configManager.get('web.enabled') || this.configManager.get('controlPlane.enabled')),
+                state: this.configManager.get('web.enabled') || this.configManager.get('controlPlane.enabled') ? 'healthy' : 'disabled',
+                configuredAt,
+                capabilities: ['ingress', 'egress', 'threaded_reply'],
+                metadata: {
+                    port: this.configManager.get('web.port'),
+                    baseUrl: this.configManager.get('web.publicBaseUrl'),
+                },
+            },
+            {
+                id: 'surface:slack',
+                kind: 'slack',
+                label: 'Slack',
+                enabled: Boolean(this.configManager.get('surfaces.slack.enabled')),
+                state: this.configManager.get('surfaces.slack.enabled') ? 'healthy' : 'disabled',
+                configuredAt,
+                accountId: String(this.configManager.get('surfaces.slack.workspaceId') || ''),
+                capabilities: ['ingress', 'egress', 'threaded_reply', 'interactive_actions'],
+                metadata: {
+                    defaultChannel: this.configManager.get('surfaces.slack.defaultChannel'),
+                },
+            },
+            {
+                id: 'surface:discord',
+                kind: 'discord',
+                label: 'Discord',
+                enabled: Boolean(this.configManager.get('surfaces.discord.enabled')),
+                state: this.configManager.get('surfaces.discord.enabled') ? 'healthy' : 'disabled',
+                configuredAt,
+                accountId: String(this.configManager.get('surfaces.discord.applicationId') || ''),
+                capabilities: ['ingress', 'egress', 'interactive_actions'],
+                metadata: {
+                    defaultChannelId: this.configManager.get('surfaces.discord.defaultChannelId'),
+                    guildId: this.configManager.get('surfaces.discord.guildId'),
+                },
+            },
+            {
+                id: 'surface:ntfy',
+                kind: 'ntfy',
+                label: 'ntfy',
+                enabled: Boolean(this.configManager.get('surfaces.ntfy.enabled')),
+                state: this.configManager.get('surfaces.ntfy.enabled') ? 'healthy' : 'disabled',
+                configuredAt,
+                capabilities: ['ingress', 'egress', 'delivery_only'],
+                metadata: {
+                    baseUrl: this.configManager.get('surfaces.ntfy.baseUrl'),
+                    topic: this.configManager.get('surfaces.ntfy.topic'),
+                },
+            },
+            {
+                id: 'surface:webhook',
+                kind: 'webhook',
+                label: 'Generic webhook',
+                enabled: Boolean(this.configManager.get('surfaces.webhook.enabled')
+                    || this.configManager.get('surfaces.webhook.defaultTarget')
+                    || this.configManager.get('surfaces.webhook.secret')),
+                state: this.configManager.get('surfaces.webhook.enabled')
+                    || this.configManager.get('surfaces.webhook.defaultTarget')
+                    || this.configManager.get('surfaces.webhook.secret')
+                    ? 'healthy'
+                    : 'disabled',
+                configuredAt,
+                capabilities: ['ingress', 'egress', 'delivery_only'],
+                metadata: {
+                    defaultTarget: this.configManager.get('surfaces.webhook.defaultTarget'),
+                    timeoutMs: this.configManager.get('surfaces.webhook.timeoutMs'),
+                },
+            },
+        ];
+        this.surfaces.clear();
+        for (const record of records) {
+            this.surfaces.set(record.id, record);
+            this.runtimeDispatch?.syncSurface(record, 'surfaces.sync');
+        }
+        return records;
+    }
+    list() {
+        return [...this.surfaces.values()].sort((a, b) => a.label.localeCompare(b.label));
+    }
+}

package/dist/_internal/platform/config/helper-model.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Helper Model — lightweight LLM routing for grunt-work tasks.
+ *
+ * Routes tasks like cache planning, compaction, commit messages, etc. to a
+ * cheaper/free model so expensive main models don't waste tokens on routine work.
+ *
+ * Resolution order:
+ *   1. Per-provider helper (helper.providers.{currentProvider}.provider + model)
+ *   2. Global helper (helper.globalProvider + helper.globalModel)
+ *   3. Tool LLM (tools.llmProvider + tools.llmModel) — if configured
+ *   4. Main model (fallback — not a true helper, but ensures the task runs)
+ *
+ * Design constraints:
+ *   - Never throws from HelperModel.chat() — returns empty string on any error
+ *   - Logs failures via logger.debug (non-fatal)
+ *   - Singleton pattern — import `helperModel` for use
+ *   - Tracks token usage separately from the main model
+ */
+import type { ConfigManager } from './manager.js';
+import type { LLMProvider } from '../providers/interface.js';
+import type { ProviderRegistry } from '../providers/registry.js';
+/** Tasks that can be routed to a helper model. */
+export type HelperTask = 'cache_strategy' | 'compaction' | 'intent_classify' | 'tool_summarize' | 'commit_message' | 'review_triage';
+/** Resolved helper model: provider instance + model ID. */
+export interface ResolvedHelper {
+    provider: LLMProvider;
+    modelId: string;
+    /** true if using a dedicated helper, false if falling back to main model. */
+    isHelper: boolean;
+}
+/** Options for helper model invocation. */
+export interface HelperChatOptions {
+    maxTokens?: number;
+    systemPrompt?: string;
+    /** If true, return empty string instead of falling back to main model. */
+    helperOnly?: boolean;
+}
+/** Token usage tracking for helper model calls. */
+export interface HelperUsage {
+    inputTokens: number;
+    outputTokens: number;
+    calls: number;
+}
+export interface HelperModelDeps {
+    readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
+    readonly providerRegistry: Pick<ProviderRegistry, 'get' | 'getCurrentModel' | 'getForModel'>;
+}
+/**
+ * HelperRouter — resolves which model to use for a given helper task.
+ *
+ * Resolution order:
+ *   1. Per-provider helper (helper.providers.{currentProvider}.provider + model)
+ *   2. Global helper (helper.globalProvider + helper.globalModel)
+ *   3. Tool LLM (tools.llmProvider + tools.llmModel) — if configured
+ *   4. Main model (fallback — not a true helper, but ensures the task runs)
+ */
+export declare class HelperRouter {
+    private readonly deps;
+    constructor(deps: HelperModelDeps);
+    /**
+     * Resolve the best helper for the given task.
+     *
+     * Returns null only if no provider can be resolved at all.
+     */
+    resolve(_task: HelperTask): ResolvedHelper | null;
+}
+/**
+ * HelperModel — lightweight LLM interface for helper tasks.
+ *
+ * Callers own HelperModel lifetimes explicitly. Never throws — returns empty string on failure.
+ * Tracks token usage separately from the main model.
+ */
+export declare class HelperModel {
+    private readonly deps;
+    private readonly router;
+    private _usage;
+    constructor(deps: HelperModelDeps);
+    /**
+     * Send a prompt to the helper model for the given task.
+     *
+     * @param task     The helper task type (for routing).
+     * @param prompt   The user prompt to send.
+     * @param options  Optional maxTokens, systemPrompt, helperOnly.
+     * @returns        The assistant's text response, or empty string on failure.
+     */
+    chat(task: HelperTask, prompt: string, options?: HelperChatOptions): Promise<string>;
+    /** Get cumulative helper usage since last reset. */
+    getUsage(): Readonly<HelperUsage>;
+    /** Reset usage counters. */
+    resetUsage(): void;
+}
+//# sourceMappingURL=helper-model.d.ts.map

package/dist/_internal/platform/config/helper-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-model.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/config/helper-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAClB,gBAAgB,GAChB,YAAY,GACZ,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,CAAC;AAEpB,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,aAAa,CAAC,CAAC;IACnE,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,iBAAiB,GAAG,aAAa,CAAC,CAAC;CAC9F;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,eAAe;IAElD;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI;CAwDlD;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,MAAM,CAA8D;gBAE/C,IAAI,EAAE,eAAe;IAIlD;;;;;;;OAOG;IACG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgE9F,oDAAoD;IACpD,QAAQ,IAAI,QAAQ,CAAC,WAAW,CAAC;IAIjC,4BAA4B;IAC5B,UAAU,IAAI,IAAI;CAGnB"}