im-hub-pro 0.2.29

package/dist/core/metrics.js

@@ -0,0 +1,291 @@
+// Metrics — in-process counters + latency / cost histograms.
+//
+// Lightweight & dependency-free: a sliding sample ring per (agent, intent,
+// success) bucket lets us compute p50/p95/p99 on demand. /api/metrics
+// emits a Prometheus-compatible text body so scraping tools can ingest
+// without us pulling in prom-client.
+//
+// This module is fed by audit-log.logInvocation (so every recorded request
+// also updates metrics) — single source of truth, no duplicate observers.
+const MAX_SAMPLES = 1024; // rolling window per metric label set
+/**
+ * Bounded sliding window. Append-only writes overwrite the oldest entry
+ * once full, so memory is fixed regardless of traffic.
+ */
+class SlidingWindow {
+    buf;
+    idx = 0;
+    full = false;
+    constructor(capacity = MAX_SAMPLES) {
+        this.buf = new Array(capacity);
+    }
+    push(v) {
+        this.buf[this.idx] = v;
+        this.idx = (this.idx + 1) % this.buf.length;
+        if (this.idx === 0)
+            this.full = true;
+    }
+    /** Copy the current sample set (unsorted). */
+    snapshot() {
+        const len = this.full ? this.buf.length : this.idx;
+        return this.buf.slice(0, len);
+    }
+    size() {
+        return this.full ? this.buf.length : this.idx;
+    }
+}
+/**
+ * Hoare-style partition. Returns an index `p` such that everything in
+ * [lo, p] is ≤ pivot and everything in [p+1, hi] is ≥ pivot.
+ */
+function partition(arr, lo, hi) {
+    const pivot = arr[(lo + hi) >>> 1];
+    let i = lo - 1, j = hi + 1;
+    while (true) {
+        do {
+            i++;
+        } while (arr[i] < pivot);
+        do {
+            j--;
+        } while (arr[j] > pivot);
+        if (i >= j)
+            return j;
+        const tmp = arr[i];
+        arr[i] = arr[j];
+        arr[j] = tmp;
+    }
+}
+/**
+ * In-place quickselect: after the call, arr[k] is the value that would
+ * be at index k in a fully-sorted array. Average O(n).
+ */
+function quickselect(arr, k, lo, hi) {
+    while (lo < hi) {
+        const p = partition(arr, lo, hi);
+        if (k <= p)
+            hi = p;
+        else
+            lo = p + 1;
+    }
+}
+/**
+ * Compute multiple quantiles in a single shared copy. Sorts the
+ * quantiles ascending, then runs quickselect with each successive
+ * `lo` bounded by the previous index — so we only re-partition the
+ * tail relevant to the higher quantile.
+ *
+ * For 3 quantiles on n=1024 this is ~3n comparisons vs n·log(n) ≈ 10n
+ * for a full sort.
+ */
+function multiQuantile(buf, qs) {
+    if (buf.length === 0)
+        return qs.map(() => 0);
+    const arr = buf.slice();
+    const n = arr.length;
+    const ordered = qs.map((q, i) => ({
+        q,
+        i,
+        idx: Math.min(n - 1, Math.max(0, Math.floor(q * (n - 1)))),
+    }));
+    ordered.sort((a, b) => a.idx - b.idx);
+    const out = new Array(qs.length);
+    let lo = 0;
+    for (const { i, idx } of ordered) {
+        quickselect(arr, idx, lo, n - 1);
+        out[i] = arr[idx];
+        lo = idx; // next quantile is at or after this one
+    }
+    return out;
+}
+const agentBuckets = new Map();
+const intentCounter = new Map();
+const platformCounter = new Map();
+const startedAt = Date.now();
+/**
+ * Operational counters that aren't tied to a specific invocation. Today:
+ *   - auditPruneFailures: every time pruneExpired() in audit-log catches.
+ *     A non-zero value here means retention is silently failing — alert
+ *     on `rate(im_hub_audit_prune_failed_total[1h]) > 0`.
+ *   - agentCleanupFailures: every time AgentBase's per-spawn cleanup hook
+ *     throws (mcp-config tmpdir unlink, etc.). Surfaces tmpdir leakage
+ *     that would otherwise only appear in scattered warn lines.
+ */
+const internalCounters = {
+    auditPruneFailures: 0,
+    agentCleanupFailures: 0,
+};
+/** Increment when audit-log retention sweep fails. Exposed as a Prometheus
+ *  counter; ops should alert on any non-zero rate. */
+export function recordAuditPruneFailure() {
+    internalCounters.auditPruneFailures++;
+}
+/** Increment when an agent's per-spawn cleanup hook throws. Exposed as a
+ *  Prometheus counter so leaked tmpdirs (mcp-config etc.) become visible
+ *  on /api/metrics rather than only in warn-level pino output. */
+export function recordAgentCleanupFailure() {
+    internalCounters.agentCleanupFailures++;
+}
+/**
+ * Optional snapshot provider for the approval-bus. Set once at startup
+ * (cli wires it after instantiating ApprovalBus). Lazy decoupling avoids
+ * the metrics module importing approval-bus directly.
+ */
+let approvalBusSnapshot = null;
+export function setApprovalBusSnapshotProvider(fn) {
+    approvalBusSnapshot = fn;
+}
+/**
+ * Allowlist of intent names emitted as Prometheus labels. Anything outside
+ * this set buckets into 'other' so a malicious or buggy caller can't
+ * explode label cardinality (every distinct user-supplied intent string
+ * would otherwise produce a new metric series, growing memory and scrape
+ * cost without bound). Mirrors the values produced by router.ts and
+ * intent.ts; if you add a new triggeredBy reason there, add it here too.
+ */
+const KNOWN_INTENTS = new Set([
+    'default', 'explicit', 'fallback', 'llm',
+    'topic', 'keyword', 'sticky',
+]);
+/**
+ * Allowlist of platform names. Each adapter pins its own platform string
+ * (telegram / feishu / wechat / discord / web / acp / acp-server / rest /
+ * rest-msg). Anything else funnels to 'other' to bound cardinality.
+ */
+const KNOWN_PLATFORMS = new Set([
+    'telegram', 'feishu', 'wechat', 'discord',
+    'web', 'acp', 'acp-server', 'rest', 'rest-msg',
+]);
+function bucketLabel(known, value) {
+    if (!value)
+        return 'other';
+    return known.has(value) ? value : 'other';
+}
+function getBucket(agent) {
+    let b = agentBuckets.get(agent);
+    if (!b) {
+        b = { total: 0, success: 0, failure: 0, costSum: 0, latency: new SlidingWindow() };
+        agentBuckets.set(agent, b);
+    }
+    return b;
+}
+export function recordInvocation(rec) {
+    const b = getBucket(rec.agent);
+    b.total++;
+    if (rec.success)
+        b.success++;
+    else
+        b.failure++;
+    b.costSum += rec.cost || 0;
+    if (Number.isFinite(rec.durationMs) && rec.durationMs >= 0) {
+        b.latency.push(rec.durationMs);
+    }
+    const intentLabel = bucketLabel(KNOWN_INTENTS, rec.intent);
+    const platformLabel = bucketLabel(KNOWN_PLATFORMS, rec.platform);
+    intentCounter.set(intentLabel, (intentCounter.get(intentLabel) || 0) + 1);
+    platformCounter.set(platformLabel, (platformCounter.get(platformLabel) || 0) + 1);
+}
+export function snapshot() {
+    const now = Date.now();
+    const agents = [];
+    for (const [agent, b] of agentBuckets) {
+        const samples = b.latency.snapshot();
+        const [p50Ms, p95Ms, p99Ms] = multiQuantile(samples, [0.5, 0.95, 0.99]);
+        agents.push({
+            agent,
+            total: b.total,
+            success: b.success,
+            failure: b.failure,
+            successRate: b.total > 0 ? b.success / b.total : 0,
+            costSum: b.costSum,
+            sampleCount: samples.length,
+            p50Ms,
+            p95Ms,
+            p99Ms,
+        });
+    }
+    agents.sort((a, b) => a.agent.localeCompare(b.agent));
+    return {
+        uptimeSec: Math.round((now - startedAt) / 1000),
+        agents,
+        intentTotals: Object.fromEntries(intentCounter),
+        platformTotals: Object.fromEntries(platformCounter),
+    };
+}
+/**
+ * Render the snapshot in Prometheus text exposition format. Keeps line
+ * count low and uses bare metric names without a HELP/TYPE preamble per
+ * line family (we emit one preamble each).
+ */
+export function toPrometheus() {
+    const snap = snapshot();
+    const lines = [];
+    lines.push('# HELP im_hub_uptime_seconds Process uptime in seconds');
+    lines.push('# TYPE im_hub_uptime_seconds gauge');
+    lines.push(`im_hub_uptime_seconds ${snap.uptimeSec}`);
+    lines.push('# HELP im_hub_agent_invocations_total Total agent invocations');
+    lines.push('# TYPE im_hub_agent_invocations_total counter');
+    for (const a of snap.agents) {
+        lines.push(`im_hub_agent_invocations_total{agent="${esc(a.agent)}",result="success"} ${a.success}`);
+        lines.push(`im_hub_agent_invocations_total{agent="${esc(a.agent)}",result="failure"} ${a.failure}`);
+    }
+    lines.push('# HELP im_hub_agent_cost_sum Sum of recorded cost per agent');
+    lines.push('# TYPE im_hub_agent_cost_sum counter');
+    for (const a of snap.agents) {
+        lines.push(`im_hub_agent_cost_sum{agent="${esc(a.agent)}"} ${a.costSum}`);
+    }
+    lines.push('# HELP im_hub_agent_latency_ms Latency quantiles (sliding window)');
+    lines.push('# TYPE im_hub_agent_latency_ms summary');
+    for (const a of snap.agents) {
+        lines.push(`im_hub_agent_latency_ms{agent="${esc(a.agent)}",quantile="0.5"} ${a.p50Ms}`);
+        lines.push(`im_hub_agent_latency_ms{agent="${esc(a.agent)}",quantile="0.95"} ${a.p95Ms}`);
+        lines.push(`im_hub_agent_latency_ms{agent="${esc(a.agent)}",quantile="0.99"} ${a.p99Ms}`);
+        lines.push(`im_hub_agent_latency_ms_count{agent="${esc(a.agent)}"} ${a.sampleCount}`);
+    }
+    lines.push('# HELP im_hub_intent_total Routing decisions by intent');
+    lines.push('# TYPE im_hub_intent_total counter');
+    for (const [intent, n] of Object.entries(snap.intentTotals)) {
+        lines.push(`im_hub_intent_total{intent="${esc(intent)}"} ${n}`);
+    }
+    lines.push('# HELP im_hub_platform_total Requests by platform');
+    lines.push('# TYPE im_hub_platform_total counter');
+    for (const [platform, n] of Object.entries(snap.platformTotals)) {
+        lines.push(`im_hub_platform_total{platform="${esc(platform)}"} ${n}`);
+    }
+    // Internal operational counters (M7).
+    lines.push('# HELP im_hub_audit_prune_failed_total Audit retention sweep failure count');
+    lines.push('# TYPE im_hub_audit_prune_failed_total counter');
+    lines.push(`im_hub_audit_prune_failed_total ${internalCounters.auditPruneFailures}`);
+    lines.push('# HELP im_hub_agent_cleanup_failed_total Per-spawn cleanup hook failures (e.g. mcp-config tmpdir unlink)');
+    lines.push('# TYPE im_hub_agent_cleanup_failed_total counter');
+    lines.push(`im_hub_agent_cleanup_failed_total ${internalCounters.agentCleanupFailures}`);
+    // Approval-bus snapshot (M14). Pulled lazily so metrics scrapes pick up
+    // the latest live counts. When no provider is wired (early startup,
+    // tests) we omit the family entirely instead of emitting zeros.
+    const ab = approvalBusSnapshot?.();
+    if (ab) {
+        lines.push('# HELP im_hub_approval_pending Currently pending approval requests');
+        lines.push('# TYPE im_hub_approval_pending gauge');
+        lines.push(`im_hub_approval_pending ${ab.pending}`);
+        lines.push('# HELP im_hub_approval_requests_total Lifetime approval requests received');
+        lines.push('# TYPE im_hub_approval_requests_total counter');
+        lines.push(`im_hub_approval_requests_total ${ab.totalRequests}`);
+        lines.push('# HELP im_hub_approval_resolved_total Lifetime approval resolutions');
+        lines.push('# TYPE im_hub_approval_resolved_total counter');
+        lines.push(`im_hub_approval_resolved_total{result="allow"} ${ab.totalAllowed}`);
+        lines.push(`im_hub_approval_resolved_total{result="deny"} ${ab.totalDenied}`);
+        lines.push(`im_hub_approval_resolved_total{result="timeout"} ${ab.totalTimedOut}`);
+    }
+    return lines.join('\n') + '\n';
+}
+/** Reset all counters. Test-only. */
+export function reset() {
+    agentBuckets.clear();
+    intentCounter.clear();
+    platformCounter.clear();
+    internalCounters.auditPruneFailures = 0;
+    internalCounters.agentCleanupFailures = 0;
+}
+function esc(s) {
+    return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+//# sourceMappingURL=metrics.js.map

package/dist/core/metrics.js.map

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

package/dist/core/onboarding.d.ts

@@ -0,0 +1,94 @@
+export interface OnboardingResult {
+    needsOnboarding: boolean;
+    availableMessengers: MessengerInfo[];
+    warnings?: string[];
+}
+export interface MessengerInfo {
+    id: string;
+    displayName: string;
+    description: string;
+}
+export interface AgentCheckResult {
+    available: string[];
+    missing: string[];
+    allMissing: boolean;
+}
+export interface AgentInstallHint {
+    agent: string;
+    npmPackage: string;
+    command: string;
+}
+export interface Config {
+    messengers: string[];
+    agents: string[];
+    defaultAgent: string;
+    telegram?: {
+        botToken: string;
+        channelId?: string;
+    };
+    feishu?: {
+        appId: string;
+        appSecret: string;
+        channelId?: string;
+    };
+    discord?: {
+        botToken: string;
+        channelId?: string;
+        allowedGuilds?: string[];
+        allowedChannels?: string[];
+    };
+    acpAgents?: Array<{
+        name: string;
+        aliases?: string[];
+        endpoint: string;
+        auth?: {
+            type: 'none' | 'apikey' | 'bearer';
+            token?: string;
+        };
+        enabled?: boolean;
+    }>;
+    [key: string]: unknown;
+}
+export declare function loadConfig(): Promise<Config>;
+export declare function saveConfig(config: Config): Promise<void>;
+/**
+ * Check if messengers are configured.
+ * IMPORTANT: This checks the config.messengers array BEFORE any default fill.
+ */
+export declare function checkMessengerConfig(config: Config): OnboardingResult;
+/**
+ * Check which agents are available.
+ * Result is cached with a 2-minute TTL.
+ */
+export declare function checkAgentAvailability(): Promise<AgentCheckResult>;
+/**
+ * Check if a specific agent is available.
+ *
+ * Uses the bulk cache when present, but falls through to a one-off probe
+ * if the agent name isn't represented (e.g. agent registered after the
+ * last bulk refresh). The probe result is itself cached for the TTL.
+ */
+export declare function isAgentAvailableCached(agentName: string): Promise<boolean>;
+/**
+ * Clear the agent availability caches. Useful for tests that change the
+ * registry state, and for the future `/router refresh` ops command.
+ */
+export declare function clearAgentCache(): void;
+/**
+ * Generate friendly install message for missing agents
+ */
+export declare function formatAgentInstallHint(missing: string[]): string;
+/**
+ * Format error message when agent is not available
+ */
+export declare function formatAgentNotAvailableError(agentName: string): string;
+/**
+ * Interactive onboarding flow.
+ * Returns updated config on success, null on failure/cancel.
+ */
+export declare function runMessengerOnboarding(config: Config): Promise<Config | null>;
+/**
+ * Format a user-friendly error message for messenger startup failures
+ */
+export declare function formatMessengerStartError(messengerName: string, error: unknown): string;
+//# sourceMappingURL=onboarding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/core/onboarding.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,OAAO,CAAA;IACxB,mBAAmB,EAAE,aAAa,EAAE,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnD,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjE,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IACxG,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;QAClB,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;QAC7D,OAAO,CAAC,EAAE,OAAO,CAAA;KAClB,CAAC,CAAA;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AA6BD,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAWlD;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9D;AAyBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAarE;AAiBD;;;GAGG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA+BxE;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoBhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAehE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgBtE;AAMD;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgEnF;AA0KD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAWvF"}