@chozzz/vargos 2.0.5 → 2.0.7

package/dist/services/agent/prompt-interpolate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Prompt interpolation — replace template variables in prompts with actual paths/values.
+ *
+ * Supports:
+ * - ${WORKSPACE_DIR} → ~/.vargos/workspace
+ * - ${DATA_DIR} → ~/.vargos (or $VARGOS_DATA_DIR)
+ * - ${SESSIONS_DIR} → ~/.vargos/sessions
+ * - ${CACHE_DIR} → ~/.cache/vargos
+ * - ${LOGS_DIR} → ~/.vargos/logs
+ * - ${CHANNELS_DIR} → ~/.vargos/channels
+ * - ${HOME} → user's home directory
+ * - ${PWD} → current working directory
+ * - ${SESSION_KEY}, ${CHANNEL_ID}, ${CHANNEL_TYPE}, ${CHAT_ID} → session identity
+ * - ${USER_ID}, ${USER_NAME}, ${USER_HANDLE} → message sender (from agent metadata)
+ * - ${BOT_ID}, ${BOT_NAME}, ${BOT_HANDLE} → bot identity (from agent metadata)
+ *
+ * Default values use bash-style syntax: ${VAR:-default}
+ *   - Used when VAR is missing OR an empty string.
+ *   - Default may be empty: ${VAR:-} resolves to '' if VAR is missing.
+ *   - Default cannot contain '}' (closes the placeholder).
+ *
+ * Missing keys without a default fallback to the original ${KEY} placeholder
+ * and are logged as warnings.
+ *
+ * Usage:
+ *   const prompt = 'Read ${WORKSPACE_DIR}/HEARTBEAT.md as ${BRAND:-Vargos}';
+ *   const resolved = interpolatePrompt(prompt);
+ *   // → 'Read /home/user/.vargos/workspace/HEARTBEAT.md as Vargos'
+ */
+export interface InterpolationResult {
+    prompt: string;
+    missing: string[];
+}
+/**
+ * Interpolate prompt variables and return the resolved string.
+ * Missing variables (without a default) remain as ${KEY} placeholders and are
+ * logged as warnings. Context variables (e.g., from channel metadata) are
+ * merged into the template variables.
+ */
+export declare function interpolatePrompt(prompt: string, context?: Record<string, string>): string;
+//# sourceMappingURL=prompt-interpolate.d.ts.map

package/dist/services/agent/prompt-interpolate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-interpolate.d.ts","sourceRoot":"","sources":["../../../services/agent/prompt-interpolate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAG1F"}

package/dist/services/agent/prompt-interpolate.js

@@ -0,0 +1,102 @@
+/**
+ * Prompt interpolation — replace template variables in prompts with actual paths/values.
+ *
+ * Supports:
+ * - ${WORKSPACE_DIR} → ~/.vargos/workspace
+ * - ${DATA_DIR} → ~/.vargos (or $VARGOS_DATA_DIR)
+ * - ${SESSIONS_DIR} → ~/.vargos/sessions
+ * - ${CACHE_DIR} → ~/.cache/vargos
+ * - ${LOGS_DIR} → ~/.vargos/logs
+ * - ${CHANNELS_DIR} → ~/.vargos/channels
+ * - ${HOME} → user's home directory
+ * - ${PWD} → current working directory
+ * - ${SESSION_KEY}, ${CHANNEL_ID}, ${CHANNEL_TYPE}, ${CHAT_ID} → session identity
+ * - ${USER_ID}, ${USER_NAME}, ${USER_HANDLE} → message sender (from agent metadata)
+ * - ${BOT_ID}, ${BOT_NAME}, ${BOT_HANDLE} → bot identity (from agent metadata)
+ *
+ * Default values use bash-style syntax: ${VAR:-default}
+ *   - Used when VAR is missing OR an empty string.
+ *   - Default may be empty: ${VAR:-} resolves to '' if VAR is missing.
+ *   - Default cannot contain '}' (closes the placeholder).
+ *
+ * Missing keys without a default fallback to the original ${KEY} placeholder
+ * and are logged as warnings.
+ *
+ * Usage:
+ *   const prompt = 'Read ${WORKSPACE_DIR}/HEARTBEAT.md as ${BRAND:-Vargos}';
+ *   const resolved = interpolatePrompt(prompt);
+ *   // → 'Read /home/user/.vargos/workspace/HEARTBEAT.md as Vargos'
+ */
+import { getDataPaths } from '../../lib/paths.js';
+import { createLogger } from '../../lib/logger.js';
+import os from 'node:os';
+import process from 'node:process';
+const log = createLogger('interpolate');
+const PATTERN = /\$\{([A-Z_]+)(?::-?([^}]*))?\}/g;
+/**
+ * Interpolate prompt variables and return the resolved string.
+ * Missing variables (without a default) remain as ${KEY} placeholders and are
+ * logged as warnings. Context variables (e.g., from channel metadata) are
+ * merged into the template variables.
+ */
+export function interpolatePrompt(prompt, context) {
+    const { prompt: resolved } = interpolatePromptWithMissing(prompt, context);
+    return resolved;
+}
+/**
+ * Interpolate and return both result and missing variable list.
+ * Used when you need to know what failed to interpolate.
+ */
+function interpolatePromptWithMissing(prompt, context) {
+    const paths = getDataPaths();
+    const currentTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const variables = {
+        DATA_DIR: paths.dataDir,
+        WORKSPACE_DIR: paths.workspaceDir,
+        SESSIONS_DIR: paths.sessionsDir,
+        CRON_DIR: paths.cronDir,
+        CACHE_DIR: paths.cacheDir,
+        LOGS_DIR: paths.logsDir,
+        CHANNELS_DIR: paths.channelsDir,
+        HOME: os.homedir(),
+        PWD: process.cwd(),
+        CURRENT_DATE: new Date().toLocaleString(undefined, {
+            timeZone: currentTimezone,
+            year: 'numeric', month: 'long', day: '2-digit',
+            hour: '2-digit', minute: '2-digit', second: '2-digit',
+            hour12: false,
+            timeZoneName: 'short',
+        }),
+        CURRENT_TIMEZONE: currentTimezone,
+        // Channel context variables — fall back to 'unknown' when not provided.
+        // Handles default to '' so templates can override with ${VAR:-fallback}.
+        CHANNEL_TYPE: context?.CHANNEL_TYPE || 'unknown',
+        CHANNEL_ID: context?.CHANNEL_ID || 'unknown',
+        CHAT_ID: context?.CHAT_ID || 'unknown',
+        USER_ID: context?.USER_ID || 'unknown',
+        USER_NAME: context?.USER_NAME || 'unknown',
+        USER_HANDLE: context?.USER_HANDLE || '',
+        BOT_ID: context?.BOT_ID || 'unknown',
+        BOT_NAME: context?.BOT_NAME || 'unknown',
+        BOT_HANDLE: context?.BOT_HANDLE || '',
+        // Just in case context is provided, but not all variables are present.
+        ...context,
+    };
+    const missing = [];
+    const result = prompt.replace(PATTERN, (full, key, defaultValue) => {
+        const value = variables[key];
+        if (value !== undefined && value !== '') {
+            return value;
+        }
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        missing.push(key);
+        return full;
+    });
+    if (missing.length > 0) {
+        log.warn(`Missing interpolation keys: ${missing.join(', ')}`);
+    }
+    return { prompt: result, missing };
+}
+//# sourceMappingURL=prompt-interpolate.js.map

package/dist/services/agent/prompt-interpolate.js.map

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

package/dist/services/agent/schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Agent — Type schemas
+ */
+import type { Bus } from '../../gateway/bus.js';
+import type { AppConfig } from '../../services/config/index.js';
+export interface AgentDeps {
+    bus: Bus;
+    config: AppConfig;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/services/agent/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../services/agent/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,SAAS,CAAC;CACnB"}

package/dist/services/agent/schema.js

@@ -0,0 +1,5 @@
+/**
+ * Agent — Type schemas
+ */
+export {};
+//# sourceMappingURL=schema.js.map

package/dist/services/agent/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../services/agent/schema.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/services/agent/tools.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent — Bus Tools Integration
+ *
+ * Converts bus callable events with @register decorators into PiAgent ToolDefinitions.
+ *
+ * Session key injection:
+ * - Every tool closes over the parent sessionKey from getCustomTools().
+ * - For agent.execute specifically, sessionKey is injected as ':subagent' suffix
+ *   so the agent doesn't need to (and can't) provide its own session key.
+ * - Other tools inherit the parent sessionKey for context-aware operations
+ *   (e.g. channel.send delivers to the right recipient).
+ *
+ * Schema vs EventMap gap:
+ * - The agent.execute schema omits sessionKey (it's injected here before bus.call).
+ * - EventMap['agent.execute']['params'] still declares sessionKey as required because
+ *   direct callers (channels, cron, webhooks, TCP clients) must provide it.
+ * - This mismatch is intentional — the tool wrapper is the bridge between the agent's
+ *   view (no sessionKey) and the service's view (sessionKey required).
+ */
+import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
+import type { Bus } from '../../gateway/bus.js';
+/**
+ * Create PiAgent custom tools from bus callable events.
+ */
+export declare function createCustomTools(sessionKey: string, bus: Bus): Promise<ToolDefinition[]>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/services/agent/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../services/agent/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAgFhD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAK/F"}

package/dist/services/agent/tools.js

@@ -0,0 +1,85 @@
+/**
+ * Agent — Bus Tools Integration
+ *
+ * Converts bus callable events with @register decorators into PiAgent ToolDefinitions.
+ *
+ * Session key injection:
+ * - Every tool closes over the parent sessionKey from getCustomTools().
+ * - For agent.execute specifically, sessionKey is injected as ':subagent' suffix
+ *   so the agent doesn't need to (and can't) provide its own session key.
+ * - Other tools inherit the parent sessionKey for context-aware operations
+ *   (e.g. channel.send delivers to the right recipient).
+ *
+ * Schema vs EventMap gap:
+ * - The agent.execute schema omits sessionKey (it's injected here before bus.call).
+ * - EventMap['agent.execute']['params'] still declares sessionKey as required because
+ *   direct callers (channels, cron, webhooks, TCP clients) must provide it.
+ * - This mismatch is intentional — the tool wrapper is the bridge between the agent's
+ *   view (no sessionKey) and the service's view (sessionKey required).
+ */
+import { createLogger } from '../../lib/logger.js';
+import { isToolEvent } from '../../gateway/emitter.js';
+import { toMessage } from '../../lib/error.js';
+import { appendError } from '../../lib/error-store.js';
+const log = createLogger('agent-tools');
+const LARGE_RESULT_TOKEN_THRESHOLD = 5_000;
+/**
+ * Wrap a bus event as a PiAgent ToolDefinition.
+ */
+function wrapEventAsToolDefinition(eventName, description, parameters, sessionKey, bus) {
+    // Sanitize tool name for anthropic: replace dots with dashes (e.g., agent.execute → agent-execute)
+    const sanitizedName = eventName.replace(/\./g, '-');
+    return {
+        name: sanitizedName,
+        label: eventName,
+        description,
+        parameters: parameters,
+        execute: async (_toolCallId, params, _signal, _onUpdate, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        _ctx) => {
+            const paramsObj = params;
+            log.debug(`${eventName}: ${Object.entries(paramsObj).map(([k, v]) => `${k}=${JSON.stringify(v).slice(0, 100)}`).join(', ')}`);
+            try {
+                // Auto-inject sessionKey for agent.execute subagent calls.
+                // The agent.execute schema omits sessionKey (it's always injected here).
+                if (eventName === 'agent.execute') {
+                    paramsObj.sessionKey = `${sessionKey}:subagent`;
+                }
+                const result = await bus.call(eventName, paramsObj);
+                let resultText = '';
+                if (result && typeof result === 'object') {
+                    resultText = JSON.stringify(result).slice(0, 10_000);
+                }
+                else if (result !== undefined && result !== null) {
+                    resultText = String(result).slice(0, 10_000);
+                }
+                const resultTokens = Math.ceil(resultText.length / 4);
+                log.debug(`${eventName} ok (${resultTokens} tokens): ${resultText.slice(0, 200).replace(/\n/g, ' ')}${resultText.length > 200 ? '...' : ''}`);
+                const content = [{ type: 'text', text: resultText }];
+                if (resultTokens > LARGE_RESULT_TOKEN_THRESHOLD) {
+                    const warning = `⚠ Large tool response (~${(resultTokens / 1000).toFixed(1)}k tokens). Extract what you need and avoid additional large calls.\n\n`;
+                    content[0] = { type: 'text', text: warning + content[0].text };
+                    log.info(`${eventName}: large result warning (${resultTokens} tokens)`);
+                }
+                return { content, details: {} };
+            }
+            catch (err) {
+                const message = toMessage(err);
+                log.debug(`${eventName} error: ${message}`);
+                appendError({ tool: eventName, sessionKey, message }).catch(() => { });
+                return {
+                    content: [{ type: 'text', text: `Error: ${message}` }],
+                    details: { error: message },
+                };
+            }
+        },
+    };
+}
+/**
+ * Create PiAgent custom tools from bus callable events.
+ */
+export async function createCustomTools(sessionKey, bus) {
+    const metadata = await bus.call('bus.search', {});
+    return metadata.filter(isToolEvent).map(m => wrapEventAsToolDefinition(m.event, m.description, m.schema?.params || {}, sessionKey, bus));
+}
+//# sourceMappingURL=tools.js.map

package/dist/services/agent/tools.js.map

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

package/dist/services/channels/base-adapter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Base channel adapter — shared logic for typing indicators, debounce, dedupe, and media handling.
+ */
+import type { ChannelType, OnInboundMessageFn, InboundMediaSource } from './types.js';
+import type { ChannelAdapter, NormalizedInboundMessage, AdapterDeps } from './contracts.js';
+import type { ChannelStatus } from '../../gateway/events.js';
+import { createMessageDebouncer } from './debounce.js';
+import { TypingStateManager } from './typing-state.js';
+export declare abstract class BaseChannelAdapter implements ChannelAdapter {
+    abstract readonly type: ChannelType;
+    readonly instanceId: string;
+    status: ChannelStatus;
+    protected dedupe: import("./dedupe.js").DedupeCache;
+    protected debouncer: ReturnType<typeof createMessageDebouncer>;
+    protected onInboundMessage?: OnInboundMessageFn;
+    protected typingState: TypingStateManager;
+    protected readonly log: {
+        debug: (msg: string, data?: import("../config/schemas/primitives.js").Json) => void;
+        info: (msg: string, data?: import("../config/schemas/primitives.js").Json) => void;
+        warn: (msg: string, data?: import("../config/schemas/primitives.js").Json) => void;
+        error: (msg: string, data?: import("../config/schemas/primitives.js").Json) => void;
+    };
+    protected debounceMs: number;
+    protected latestMessageId: Map<string, string>;
+    protected transcribeFn?: (filePath: string) => Promise<string>;
+    protected describeFn?: (filePath: string) => Promise<string>;
+    protected extractFn?: (filePath: string, mimeType: string) => Promise<{
+        text: string;
+    }>;
+    constructor(instanceId: string, _channelType: ChannelType, deps: AdapterDeps, debounceMs?: number);
+    protected createDebouncer(): ReturnType<typeof createMessageDebouncer>;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract send(sessionKey: string, text: string): Promise<void>;
+    protected abstract sendTypingIndicator(sessionKey: string): Promise<void>;
+    /** Extract userId from sessionKey for adapter-specific use. */
+    extractUserId(sessionKey: string): string;
+    /** Get latest message ID for a user (used for reactions). */
+    extractLatestMessageId(userId: string): string | null | undefined;
+    startTyping(sessionKey: string, inToolExecution?: boolean): void;
+    resumeTyping(sessionKey: string): void;
+    stopTyping(sessionKey: string, final?: boolean): void;
+    protected handleBatch(id: string, messages: string[], normalizedMsg?: NormalizedInboundMessage): Promise<void>;
+    protected buildSessionKey(id: string): string;
+    protected cleanupTimers(): void;
+    /** Override to handle media resolution for your channel. */
+    protected resolveMedia(_msg: unknown): Promise<InboundMediaSource | null>;
+    /**
+     * Process inbound media message.
+     * @param msg - Raw message from channel
+     * @param sessionKey - Session key (channel:userId)
+     * @param normalizedMsg - Normalized message with flags (skipAgent, etc)
+     * @param route - Function to route processed text to onInboundMessage
+     */
+    protected processInboundMedia(msg: unknown, sessionKey: string, normalizedMsg: NormalizedInboundMessage, route: (text: string) => Promise<void>): Promise<{
+        caption: string;
+        savedPath: string;
+        mimeType: string;
+    }>;
+}
+//# sourceMappingURL=base-adapter.d.ts.map

package/dist/services/channels/base-adapter.d.ts.map

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

package/dist/services/channels/base-adapter.js

@@ -0,0 +1,181 @@
+/**
+ * Base channel adapter — shared logic for typing indicators, debounce, dedupe, and media handling.
+ */
+import path from 'node:path';
+import { createDedupeCache } from './dedupe.js';
+import { createMessageDebouncer } from './debounce.js';
+import { createLogger } from '../../lib/logger.js';
+import { toMessage } from '../../lib/error.js';
+import { parseSessionKey } from '../../lib/subagent.js';
+import { TypingStateManager } from './typing-state.js';
+import { saveMedia } from '../../lib/media.js';
+import { getDataPaths } from '../../lib/paths.js';
+const MEDIA_TYPE_LABELS = {
+    audio: 'Voice message',
+    video: 'Video message',
+    document: 'Document',
+    sticker: 'Sticker',
+};
+export class BaseChannelAdapter {
+    instanceId;
+    status = 'disconnected';
+    dedupe = createDedupeCache({ ttlMs: 120_000 });
+    debouncer;
+    onInboundMessage;
+    typingState = new TypingStateManager({ ttlMs: 120_000, failureLimit: 3 });
+    log;
+    debounceMs;
+    latestMessageId = new Map();
+    transcribeFn;
+    describeFn;
+    extractFn;
+    constructor(instanceId, _channelType, deps, debounceMs) {
+        this.instanceId = instanceId;
+        this.onInboundMessage = deps.onInbound;
+        this.transcribeFn = deps.transcribe;
+        this.describeFn = deps.describe;
+        this.extractFn = deps.extract;
+        this.log = createLogger(instanceId);
+        this.debounceMs = debounceMs ?? 2000;
+        this.debouncer = this.createDebouncer();
+    }
+    createDebouncer() {
+        return createMessageDebouncer((id, messages, normalizedMsg) => {
+            this.handleBatch(id, messages, normalizedMsg).catch((err) => {
+                this.log.error('handleBatch error', { id, error: toMessage(err) });
+            });
+        }, { delayMs: this.debounceMs });
+    }
+    /** Extract userId from sessionKey for adapter-specific use. */
+    extractUserId(sessionKey) {
+        const { id } = parseSessionKey(sessionKey);
+        return id;
+    }
+    /** Get latest message ID for a user (used for reactions). */
+    extractLatestMessageId(userId) {
+        return this.latestMessageId.get(userId);
+    }
+    startTyping(sessionKey, inToolExecution = false) {
+        this.typingState.start(sessionKey, () => this.sendTypingIndicator(sessionKey), inToolExecution);
+    }
+    resumeTyping(sessionKey) {
+        this.typingState.resume(sessionKey, () => this.sendTypingIndicator(sessionKey));
+    }
+    stopTyping(sessionKey, final = true) {
+        this.typingState.stop(sessionKey, final);
+    }
+    async handleBatch(id, messages, normalizedMsg) {
+        if (!this.onInboundMessage) {
+            this.log.error('No inbound message handler');
+            return;
+        }
+        if (!normalizedMsg) {
+            this.log.error('No normalized message provided for batch');
+            return;
+        }
+        const text = messages.join('\n');
+        this.log.info(`batch for ${this.instanceId}:${id}: "${text.slice(0, 80)}"`);
+        await this.onInboundMessage(this.buildSessionKey(id), { ...normalizedMsg, text });
+    }
+    buildSessionKey(id) {
+        return `${this.instanceId}:${id}`;
+    }
+    cleanupTimers() {
+        this.debouncer.flushAll();
+        this.typingState.cleanup();
+    }
+    /** Override to handle media resolution for your channel. */
+    async resolveMedia(_msg) {
+        return null;
+    }
+    /**
+     * Process inbound media message.
+     * @param msg - Raw message from channel
+     * @param sessionKey - Session key (channel:userId)
+     * @param normalizedMsg - Normalized message with flags (skipAgent, etc)
+     * @param route - Function to route processed text to onInboundMessage
+     */
+    async processInboundMedia(msg, sessionKey, normalizedMsg, route) {
+        const source = await this.resolveMedia(msg);
+        const defaultReturn = { caption: '', savedPath: '', mimeType: '' };
+        if (!source)
+            return defaultReturn;
+        const { buffer, mimeType, mediaType, caption, duration } = source;
+        const mediaDir = path.join(getDataPaths().dataDir, 'media');
+        const savedPath = await saveMedia({ buffer, sessionKey, mimeType, mediaDir });
+        // Skip transcription for messages agent won't process (e.g., group mentions)
+        if (normalizedMsg.skipAgent) {
+            const label = MEDIA_TYPE_LABELS[mediaType] ?? 'Media';
+            const durationSuffix = duration != null ? `, ${duration}s` : '';
+            const fallbackCaption = caption || `[${label}${durationSuffix}]`;
+            await route(`${fallbackCaption}\n\n[${label} saved: ${savedPath}]`);
+            return {
+                caption: fallbackCaption,
+                savedPath,
+                mimeType
+            };
+        }
+        if (mediaType === 'image') {
+            if (this.describeFn) {
+                try {
+                    const description = await this.describeFn(savedPath);
+                    await route(`${description}\n\n[Image described from: ${savedPath}]`);
+                    return {
+                        caption: description,
+                        savedPath,
+                        mimeType
+                    };
+                }
+                catch (err) {
+                    this.log.warn(`Image description failed: ${err}. Falling back to caption.`);
+                }
+            }
+            const text = caption || 'User sent an image.';
+            await route(`${text}\n\n[Image saved: ${savedPath}]`);
+            return {
+                caption: text,
+                savedPath,
+                mimeType
+            };
+        }
+        if (mediaType === 'audio' && this.transcribeFn) {
+            try {
+                const transcription = await this.transcribeFn(savedPath);
+                await route(`${transcription}\n\n[Audio transcribed from: ${savedPath}]`);
+                return {
+                    caption: transcription,
+                    savedPath,
+                    mimeType
+                };
+            }
+            catch (err) {
+                this.log.warn(`Audio transcription failed: ${err}. Falling back to file path.`);
+            }
+        }
+        if (mediaType === 'document' && this.extractFn) {
+            try {
+                const { text } = await this.extractFn(savedPath, mimeType);
+                await route(`${text}\n\n[Document extracted from: ${savedPath}]`);
+                return {
+                    caption: text,
+                    savedPath,
+                    mimeType
+                };
+            }
+            catch (err) {
+                this.log.warn(`Document extraction failed: ${err}. Falling back to file path.`);
+            }
+        }
+        // Default handling for audio (no transcription), documents (no extraction), or other media types
+        const label = MEDIA_TYPE_LABELS[mediaType] ?? 'Media';
+        const durationSuffix = duration != null ? `, ${duration}s` : '';
+        const fallbackCaption = caption || `[${label}${durationSuffix}]`;
+        await route(`${fallbackCaption}\n\n[${label} saved: ${savedPath}]`);
+        return {
+            caption: fallbackCaption,
+            savedPath,
+            mimeType,
+        };
+    }
+}
+//# sourceMappingURL=base-adapter.js.map

package/dist/services/channels/base-adapter.js.map

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

package/dist/services/channels/contracts.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Channel adapter contracts — defines what every channel provider must implement.
+ * These interfaces form the boundary between core policy and adapter implementations.
+ */
+import type { ChannelStatus } from '../../gateway/events.js';
+import type { ChannelEntry } from '../config/schemas/channels.js';
+import type { ChannelType, InboundMediaSource } from './types.js';
+/**
+ * Required interface all channel adapters must implement.
+ * Core calls these methods; adapters call onInboundMessage callback.
+ */
+export interface ChannelAdapter {
+    readonly instanceId: string;
+    readonly type: ChannelType;
+    readonly status: ChannelStatus;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(sessionKey: string, text: string): Promise<void>;
+    startTyping(sessionKey: string, withToolFlag: boolean): void;
+    stopTyping(sessionKey: string, final?: boolean): void;
+    resumeTyping(sessionKey: string): void;
+    extractLatestMessageId(userId: string): string | null | undefined;
+    sendMedia?: (sessionKey: string, filePath: string, mimeType: string, caption?: string) => Promise<void>;
+    react?: (sessionKey: string, messageId: string, emoji: string) => Promise<void>;
+}
+/**
+ * Adapter dependencies — passed during construction.
+ * Unifies callback injection into a single parameter.
+ */
+export interface AdapterDeps {
+    onInbound: OnInboundMessageFn;
+    transcribe?: (filePath: string) => Promise<string>;
+    describe?: (filePath: string) => Promise<string>;
+    extract?: (filePath: string, mimeType: string) => Promise<{
+        text: string;
+    }>;
+}
+/**
+ * Provider pattern: factory for creating channel adapters.
+ * Generic over the channel entry type for type-safe config passing.
+ */
+export interface ChannelProvider<TEntry extends ChannelEntry = ChannelEntry> {
+    readonly type: TEntry['type'];
+    createAdapter(instanceId: string, config: TEntry, deps: AdapterDeps): Promise<ChannelAdapter>;
+}
+/**
+ * Canonical inbound message shape after normalization.
+ * All adapters emit this (via normalizers), core policy handles this.
+ */
+export interface NormalizedInboundMessage {
+    messageId: string;
+    fromUserId: string;
+    fromUser: string;
+    fromUserHandle?: string;
+    chatType: 'private' | 'group';
+    isMentioned: boolean;
+    channelType: string;
+    botUserId?: string;
+    botName?: string;
+    botHandle?: string;
+    skipAgent: boolean;
+    text?: string;
+    media?: InboundMediaSource;
+}
+/**
+ * Callback signature for inbound messages.
+ * Adapters call this when a message arrives.
+ */
+export type OnInboundMessageFn = (sessionKey: string, normalizedMessage: NormalizedInboundMessage) => Promise<void>;
+/**
+ * Normalizer function: adapter-specific message → canonical NormalizedInboundMessage.
+ * Each adapter has a normalizer that handles its raw message type.
+ */
+export type MessageNormalizer<T> = (msg: T, botId: string) => NormalizedInboundMessage | null;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/services/channels/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../services/channels/contracts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7D,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtD,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAGlE,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxG,KAAK,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjF;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,kBAAkB,CAAC;IAC9B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/F;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,wBAAwB,KACxC,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CACjC,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,MAAM,KACV,wBAAwB,GAAG,IAAI,CAAC"}