agim-cli 1.0.1

package/dist/core/coord-systems.js

@@ -0,0 +1,229 @@
+// coord-systems.ts — every coordinate-system conversion + the
+// "normalize an incoming location" policy that adapters route through.
+//
+// Why this module exists (incident background, 2026-05-12):
+//   The old behavior was "treat every incoming lat/lng as GCJ-02 if it
+//   falls inside the China bbox" — true for iOS Core Location and
+//   Apple/Google GMS-with-China-region, FALSE for the WeChat X5
+//   webview, raw Android Chrome, Telegram Desktop, and other paths
+//   where the JS / IM payload is already WGS-84.
+//
+//   The user observed wrong markers in WeChat — `/memo here` H5 capture
+//   landed coords ~500m–1km off on both 高德 and 百度 maps. Root cause:
+//   X5 webview hands the page genuine WGS-84, but server.ts applied an
+//   inverse GCJ→WGS offset on top, so the stored value was *anti-shifted*
+//   and every downstream map URL re-shifted it back the wrong way.
+//
+//   Per-platform reality (empirically known as of 2026-05):
+//
+//   | Source                                | Coord system    |
+//   |---------------------------------------|-----------------|
+//   | Telegram native location (iOS in China)        | GCJ-02 |
+//   | Telegram native location (iOS outside China)   | WGS-84 |
+//   | Telegram native location (Telegram Desktop)    | WGS-84 |
+//   | Telegram native location (most Android cases)  | WGS-84 |
+//   | Feishu native location                          | GCJ-02 (mandated) |
+//   | DingTalk native location                        | n/a (not delivered to bots) |
+//   | DingTalk link msgtype → Amap/Tencent URL        | GCJ-02 |
+//   | DingTalk link msgtype → Baidu Maps URL          | BD-09  |
+//   | H5 `navigator.geolocation` in iOS Safari (CN)   | GCJ-02 |
+//   | H5 `navigator.geolocation` in WeChat X5 / Chrome| WGS-84 |
+//
+//   There is no reliable server-side way to know which of the two
+//   ambiguous paths produced any given coord, so we ship sensible
+//   defaults + env-var overrides for the edge cases.
+import { logger as rootLogger } from './logger.js';
+const log = rootLogger.child({ component: 'coord-systems' });
+/**
+ * Convert any incoming (lat, lng) to WGS-84 based on what we know about
+ * the source. Adapters route every native coord through this. Defaults
+ * favor "trust the payload as WGS-84" because that's the safer assumption
+ * when the source is ambiguous — applying an inverse GCJ offset to a
+ * value that's actually already WGS produces a 500m-1km error, while
+ * pass-through on actual GCJ leaves the user with the same ~1km error
+ * but in a recoverable direction. Both error modes get the user roughly
+ * the right country / city; an `IMHUB_*_COORDS_GCJ02=1` env flag flips
+ * the default for any source whose users tell us their device DOES apply
+ * the offset (Apple devices in China + Chinese region most often).
+ */
+export function normalizeIncomingCoords(source, lat, lng) {
+    if (!Number.isFinite(lat) || !Number.isFinite(lng)) {
+        return { lat, lng, applied: 'none', outOfChina: true };
+    }
+    if (outOfChina(lat, lng)) {
+        return { lat, lng, applied: 'none', outOfChina: true };
+    }
+    // Per-source policy. The flag-overrideable defaults reflect the empirical
+    // table at the top of this file. See env table at the bottom.
+    const treatAsGcj = (() => {
+        switch (source) {
+            case 'telegram-native':
+                // Default WGS-84 (covers Telegram Desktop + non-Apple in-China +
+                // anyone outside China). User can flip with the env flag if their
+                // Telegram is on Apple-zh-CN where Core Location applies the offset.
+                return process.env.IMHUB_TELEGRAM_COORDS_GCJ02 === '1';
+            case 'feishu-native':
+                // Feishu is mandated GCJ-02 server-side, no override expected.
+                return true;
+            case 'dingtalk-link-amap':
+            case 'dingtalk-link-tencent':
+                return true;
+            case 'dingtalk-link-baidu':
+                return false; // BD-09, handled below
+            case 'dingtalk-link-unknown':
+                return false; // pass-through; don't guess
+            case 'h5-browser-geolocation':
+                // Default WGS-84. THIS IS THE INCIDENT FIX (2026-05-12): WeChat
+                // X5 + Android Chrome without GMS hand the page raw WGS-84 and
+                // the old "always GCJ" assumption put markers ~1km off in WeChat.
+                // iOS Safari users in China can flip the flag to restore the old
+                // GCJ→WGS path.
+                return process.env.IMHUB_H5_COORDS_GCJ02 === '1';
+            case 'web-admin':
+                // Developer-facing console; PC browser is overwhelmingly WGS-84.
+                return false;
+        }
+    })();
+    if (source === 'dingtalk-link-baidu') {
+        const wgs = bd09ToWgs84(lat, lng);
+        log.debug({
+            event: 'coord.normalized',
+            source,
+            raw_lat: lat, raw_lng: lng,
+            wgs_lat: wgs.lat, wgs_lng: wgs.lng,
+            applied: 'bd09-to-wgs84',
+        });
+        return { lat: wgs.lat, lng: wgs.lng, applied: 'bd09-to-wgs84', outOfChina: false };
+    }
+    if (treatAsGcj) {
+        const wgs = gcj02ToWgs84(lat, lng);
+        log.debug({
+            event: 'coord.normalized',
+            source,
+            raw_lat: lat, raw_lng: lng,
+            wgs_lat: wgs.lat, wgs_lng: wgs.lng,
+            applied: 'gcj02-to-wgs84',
+        });
+        return { lat: wgs.lat, lng: wgs.lng, applied: 'gcj02-to-wgs84', outOfChina: false };
+    }
+    log.debug({
+        event: 'coord.normalized',
+        source,
+        raw_lat: lat, raw_lng: lng,
+        wgs_lat: lat, wgs_lng: lng,
+        applied: 'none',
+    });
+    return { lat, lng, applied: 'none', outOfChina: false };
+}
+// ─── coord-system math ──────────────────────────────────────────────
+// We keep the GCJ pair in this file alongside BD-09 (rather than
+// re-exporting from memos.ts) so all coord math lives in one place.
+// The originals in memos.ts are still exported for backwards-compat;
+// new code should import from here.
+const A = 6378245.0;
+const EE = 0.006693421622965943;
+const PI = Math.PI;
+/** WGS-84 → GCJ-02. */
+export function wgs84ToGcj02(lat, lng) {
+    if (outOfChina(lat, lng))
+        return { lat, lng };
+    let dLat = transformLat(lng - 105.0, lat - 35.0);
+    let dLng = transformLng(lng - 105.0, lat - 35.0);
+    const radLat = (lat / 180.0) * PI;
+    let magic = Math.sin(radLat);
+    magic = 1 - EE * magic * magic;
+    const sqrtMagic = Math.sqrt(magic);
+    dLat = (dLat * 180.0) / (((A * (1 - EE)) / (magic * sqrtMagic)) * PI);
+    dLng = (dLng * 180.0) / ((A / sqrtMagic) * Math.cos(radLat) * PI);
+    return { lat: lat + dLat, lng: lng + dLng };
+}
+/** GCJ-02 → WGS-84 (Newton iteration; converges to sub-meter in 3 passes). */
+export function gcj02ToWgs84(lat, lng) {
+    if (outOfChina(lat, lng))
+        return { lat, lng };
+    let wgsLat = lat;
+    let wgsLng = lng;
+    for (let i = 0; i < 3; i++) {
+        const forward = wgs84ToGcj02(wgsLat, wgsLng);
+        wgsLat = lat - (forward.lat - wgsLat);
+        wgsLng = lng - (forward.lng - wgsLng);
+    }
+    return { lat: wgsLat, lng: wgsLng };
+}
+/**
+ * Baidu BD-09 → GCJ-02. BD-09 is GCJ-02 plus an additional radial offset
+ * applied by Baidu. The math is well-known (cf. open-source `coordtransform`
+ * libraries); we lift the formula verbatim and add a comment so the next
+ * reader doesn't have to derive it.
+ */
+export function bd09ToGcj02(lat, lng) {
+    if (outOfChina(lat, lng))
+        return { lat, lng };
+    const X_PI = (PI * 3000.0) / 180.0;
+    const x = lng - 0.0065;
+    const y = lat - 0.006;
+    const z = Math.sqrt(x * x + y * y) - 0.00002 * Math.sin(y * X_PI);
+    const theta = Math.atan2(y, x) - 0.000003 * Math.cos(x * X_PI);
+    return { lat: z * Math.sin(theta), lng: z * Math.cos(theta) };
+}
+/** GCJ-02 → Baidu BD-09 (forward; closed form). */
+export function gcj02ToBd09(lat, lng) {
+    if (outOfChina(lat, lng))
+        return { lat, lng };
+    const X_PI = (PI * 3000.0) / 180.0;
+    const z = Math.sqrt(lng * lng + lat * lat) + 0.00002 * Math.sin(lat * X_PI);
+    const theta = Math.atan2(lat, lng) + 0.000003 * Math.cos(lng * X_PI);
+    return { lat: z * Math.sin(theta) + 0.006, lng: z * Math.cos(theta) + 0.0065 };
+}
+/** BD-09 → WGS-84 via GCJ-02 intermediate. */
+export function bd09ToWgs84(lat, lng) {
+    if (outOfChina(lat, lng))
+        return { lat, lng };
+    const gcj = bd09ToGcj02(lat, lng);
+    return gcj02ToWgs84(gcj.lat, gcj.lng);
+}
+/** WGS-84 → BD-09 via GCJ-02 intermediate. Useful for building Baidu
+ *  Maps URLs from our WGS-stored coords. */
+export function wgs84ToBd09(lat, lng) {
+    if (outOfChina(lat, lng))
+        return { lat, lng };
+    const gcj = wgs84ToGcj02(lat, lng);
+    return gcj02ToBd09(gcj.lat, gcj.lng);
+}
+// ─── internals ──────────────────────────────────────────────────────
+/** GCJ-02 offset is only defined for mainland China + the bbox below.
+ *  Outside, every conversion in this module is a no-op pass-through. */
+export function outOfChina(lat, lng) {
+    return lng < 72.004 || lng > 137.8347 || lat < 0.8293 || lat > 55.8271;
+}
+function transformLat(x, y) {
+    let r = -100.0 + 2.0 * x + 3.0 * y + 0.2 * y * y + 0.1 * x * y + 0.2 * Math.sqrt(Math.abs(x));
+    r += ((20.0 * Math.sin(6.0 * x * PI) + 20.0 * Math.sin(2.0 * x * PI)) * 2.0) / 3.0;
+    r += ((20.0 * Math.sin(y * PI) + 40.0 * Math.sin((y / 3.0) * PI)) * 2.0) / 3.0;
+    r += ((160.0 * Math.sin((y / 12.0) * PI) + 320 * Math.sin((y * PI) / 30.0)) * 2.0) / 3.0;
+    return r;
+}
+function transformLng(x, y) {
+    let r = 300.0 + x + 2.0 * y + 0.1 * x * x + 0.1 * x * y + 0.1 * Math.sqrt(Math.abs(x));
+    r += ((20.0 * Math.sin(6.0 * x * PI) + 20.0 * Math.sin(2.0 * x * PI)) * 2.0) / 3.0;
+    r += ((20.0 * Math.sin(x * PI) + 40.0 * Math.sin((x / 3.0) * PI)) * 2.0) / 3.0;
+    r += ((150.0 * Math.sin((x / 12.0) * PI) + 300.0 * Math.sin((x / 30.0) * PI)) * 2.0) / 3.0;
+    return r;
+}
+// ─── env vars exposed by this module ────────────────────────────────
+//
+// IMHUB_TELEGRAM_COORDS_GCJ02=1
+//   Apply GCJ-02 → WGS-84 to Telegram native location/venue messages.
+//   Default off (WGS pass-through). Turn ON if your Telegram clients are
+//   Apple devices in China (iOS Core Location applies the offset).
+//
+// IMHUB_H5_COORDS_GCJ02=1
+//   Apply GCJ-02 → WGS-84 to coordinates POSTed from the /memo here H5
+//   capture page. Default off (WGS pass-through). Turn ON if your users
+//   open the H5 link in iOS Safari / iOS WebKit in mainland China —
+//   navigator.geolocation respects Apple's GCJ offset there.
+//
+// (Feishu always GCJ→WGS, DingTalk amap/qmap always GCJ→WGS,
+//  DingTalk baidu always BD-09→WGS — those are server-mandated and
+//  don't need overrides.)
+//# sourceMappingURL=coord-systems.js.map

package/dist/core/coord-systems.js.map

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

package/dist/core/cron.d.ts

@@ -0,0 +1,29 @@
+interface FieldSpec {
+    raw: string;
+    values: Set<number>;
+    min: number;
+    max: number;
+}
+export interface CronSpec {
+    minute: FieldSpec;
+    hour: FieldSpec;
+    day: FieldSpec;
+    month: FieldSpec;
+    dow: FieldSpec;
+}
+export declare function parseCron(expr: string): CronSpec;
+/**
+ * Next firing strictly after `from`, found by field-level
+ * fast-forwarding. For "yearly at midnight Jan 1" (`0 0 1 1 *`) this
+ * converges in at most 4-5 jumps, vs ~525_000 minute increments under
+ * the previous brute-force loop.
+ *
+ * The loop walks fields outermost (month) → innermost (minute). On a
+ * mismatch we set the field to its ceiling (next valid value) and reset
+ * everything inside it. If no ceiling exists in the current scope we
+ * step one unit up in the parent field. JavaScript Date handles
+ * carries (month=12 → next year, hour=24 → next day) natively.
+ */
+export declare function nextOccurrence(spec: CronSpec, from?: Date): Date | null;
+export {};
+//# sourceMappingURL=cron.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../../src/core/cron.ts"],"names":[],"mappings":"AAgBA,UAAU,SAAS;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACZ;AA2DD,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,SAAS,CAAA;IACf,GAAG,EAAE,SAAS,CAAA;IACd,KAAK,EAAE,SAAS,CAAA;IAChB,GAAG,EAAE,SAAS,CAAA;CACf;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAYhD;AAgCD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAE,IAAiB,GAAG,IAAI,GAAG,IAAI,CA2DnF"}

package/dist/core/cron.js

@@ -0,0 +1,184 @@
+// Minimal POSIX-flavored cron parser (5 fields: minute hour day month dow).
+//
+// Supported syntax per field:
+//   *           wildcard
+//   N           single integer
+//   N,M,O       comma list
+//   N-M         inclusive range
+//   *\/K        step (e.g. */5 = every 5 minutes)
+//   N-M/K       stepped range
+//
+// Day-of-week: 0 or 7 = Sunday, 1 = Monday … 6 = Saturday.
+//
+// nextOccurrence() returns the next Date strictly greater than `from`.
+// Returns null only on bogus expressions; a valid expression always has
+// a future occurrence within ~6 years (the search loop bails after that).
+const FIELD_BOUNDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12 },
+    { name: 'dow', min: 0, max: 6 }, // 7 normalized to 0
+];
+function parseField(raw, min, max, fieldName) {
+    const out = new Set();
+    for (const piece of raw.split(',')) {
+        const stepMatch = piece.match(/^(.+)\/(\d+)$/);
+        let body = piece;
+        let step = 1;
+        if (stepMatch) {
+            body = stepMatch[1];
+            step = parseInt(stepMatch[2], 10);
+            if (!Number.isFinite(step) || step <= 0) {
+                throw new Error(`Invalid step in ${fieldName}: ${piece}`);
+            }
+        }
+        let lo;
+        let hi;
+        if (body === '*') {
+            lo = min;
+            hi = max;
+        }
+        else {
+            const range = body.match(/^(\d+)-(\d+)$/);
+            if (range) {
+                lo = parseInt(range[1], 10);
+                hi = parseInt(range[2], 10);
+            }
+            else {
+                const single = parseInt(body, 10);
+                if (!Number.isFinite(single)) {
+                    throw new Error(`Invalid value in ${fieldName}: ${piece}`);
+                }
+                lo = single;
+                hi = single;
+            }
+        }
+        if (fieldName === 'dow') {
+            if (lo === 7)
+                lo = 0;
+            if (hi === 7)
+                hi = 0;
+        }
+        if (lo < min || hi > max || lo > hi) {
+            throw new Error(`Out-of-range value in ${fieldName}: ${piece}`);
+        }
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return { raw, values: out, min, max };
+}
+export function parseCron(expr) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error(`Expected 5 fields (minute hour day month dow), got ${parts.length}`);
+    }
+    return {
+        minute: parseField(parts[0], FIELD_BOUNDS[0].min, FIELD_BOUNDS[0].max, FIELD_BOUNDS[0].name),
+        hour: parseField(parts[1], FIELD_BOUNDS[1].min, FIELD_BOUNDS[1].max, FIELD_BOUNDS[1].name),
+        day: parseField(parts[2], FIELD_BOUNDS[2].min, FIELD_BOUNDS[2].max, FIELD_BOUNDS[2].name),
+        month: parseField(parts[3], FIELD_BOUNDS[3].min, FIELD_BOUNDS[3].max, FIELD_BOUNDS[3].name),
+        dow: parseField(parts[4], FIELD_BOUNDS[4].min, FIELD_BOUNDS[4].max, FIELD_BOUNDS[4].name),
+    };
+}
+/**
+ * Smallest value in `values` that is ≥ target, or null if none.
+ * The set is iterated linearly; sizes are tiny (≤ 60) so the cost is
+ * negligible vs the surrounding work.
+ */
+function ceilingIn(values, target) {
+    let best = null;
+    for (const v of values) {
+        if (v >= target && (best === null || v < best))
+            best = v;
+    }
+    return best;
+}
+function firstIn(values) {
+    let best = Infinity;
+    for (const v of values)
+        if (v < best)
+            best = v;
+    return best;
+}
+function dayMatches(spec, d) {
+    const dayWild = spec.day.raw === '*';
+    const dowWild = spec.dow.raw === '*';
+    const dayOk = spec.day.values.has(d.getDate());
+    const dowOk = spec.dow.values.has(d.getDay());
+    if (dayWild && dowWild)
+        return true;
+    if (!dayWild && dowWild)
+        return dayOk;
+    if (dayWild && !dowWild)
+        return dowOk;
+    return dayOk || dowOk;
+}
+/**
+ * Next firing strictly after `from`, found by field-level
+ * fast-forwarding. For "yearly at midnight Jan 1" (`0 0 1 1 *`) this
+ * converges in at most 4-5 jumps, vs ~525_000 minute increments under
+ * the previous brute-force loop.
+ *
+ * The loop walks fields outermost (month) → innermost (minute). On a
+ * mismatch we set the field to its ceiling (next valid value) and reset
+ * everything inside it. If no ceiling exists in the current scope we
+ * step one unit up in the parent field. JavaScript Date handles
+ * carries (month=12 → next year, hour=24 → next day) natively.
+ */
+export function nextOccurrence(spec, from = new Date()) {
+    const cur = new Date(from);
+    cur.setSeconds(0, 0);
+    cur.setMinutes(cur.getMinutes() + 1);
+    // Sane upper bound: 1000 field jumps will resolve any 5-field spec —
+    // crontab can't repeat itself within that many adjustments.
+    for (let i = 0; i < 1000; i++) {
+        // 1) Month
+        const mthIdx = cur.getMonth() + 1; // 1-indexed
+        const mthCeil = ceilingIn(spec.month.values, mthIdx);
+        if (mthCeil === null) {
+            // No matching month this year — roll to next year's first valid month.
+            cur.setFullYear(cur.getFullYear() + 1, firstIn(spec.month.values) - 1, 1);
+            cur.setHours(0, 0, 0, 0);
+            continue;
+        }
+        if (mthCeil !== mthIdx) {
+            cur.setMonth(mthCeil - 1, 1);
+            cur.setHours(0, 0, 0, 0);
+            continue;
+        }
+        // 2) Day (handle the day-OR-dow quirk through dayMatches)
+        if (!dayMatches(spec, cur)) {
+            cur.setDate(cur.getDate() + 1);
+            cur.setHours(0, 0, 0, 0);
+            continue;
+        }
+        // 3) Hour
+        const hr = cur.getHours();
+        const hrCeil = ceilingIn(spec.hour.values, hr);
+        if (hrCeil === null) {
+            cur.setDate(cur.getDate() + 1);
+            cur.setHours(0, 0, 0, 0);
+            continue;
+        }
+        if (hrCeil !== hr) {
+            cur.setHours(hrCeil, 0, 0, 0);
+            continue;
+        }
+        // 4) Minute
+        const mn = cur.getMinutes();
+        const mnCeil = ceilingIn(spec.minute.values, mn);
+        if (mnCeil === null) {
+            cur.setHours(cur.getHours() + 1, 0, 0, 0);
+            continue;
+        }
+        if (mnCeil !== mn) {
+            cur.setMinutes(mnCeil, 0, 0);
+            continue;
+        }
+        // All four fields are valid simultaneously — done.
+        return new Date(cur);
+    }
+    return null;
+}
+//# sourceMappingURL=cron.js.map

package/dist/core/cron.js.map

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

package/dist/core/event-bus.d.ts

@@ -0,0 +1,80 @@
+import { EventEmitter } from 'node:events';
+/** Fired by audit-log.logInvocation after a successful (or failed) agent
+ *  invocation has been recorded. Mirrors the shape audit-log already
+ *  builds, plus a `ts` ISO string for client-side sorting. */
+export interface AuditEvent {
+    type: 'audit';
+    ts: string;
+    agent: string;
+    intent: string;
+    platform: string;
+    durationMs: number;
+    cost: number;
+    success: boolean;
+    traceId: string;
+    userId: string;
+}
+/** Fired when approval-bus enqueues a new pending or resolves one. The
+ *  /api/approvals snapshot is still authoritative; this event lets the
+ *  UI refresh that tab (and the in-chat card) without waiting on the
+ *  3 s poll. */
+export interface ApprovalEvent {
+    type: 'approval';
+    phase: 'requested' | 'resolved';
+    reqId: string;
+    threadId: string;
+    platform: string;
+    toolName: string;
+    /** Present on resolved events — 'allow' / 'deny' / 'timeout' from the
+     *  bus's metrics buckets. Absent on `requested`. */
+    outcome?: 'allow' | 'deny' | 'timeout';
+}
+/** Fired on job-board state transitions. The dashboard subscribes to
+ *  refresh the Jobs tab without polling. */
+export interface JobEvent {
+    type: 'job';
+    phase: 'created' | 'started' | 'completed' | 'failed' | 'cancelled';
+    jobId: number;
+    agent: string;
+}
+/** Periodic metrics tick. Different from individual audit events: this
+ *  is a snapshot of the full per-agent state (counters + latency
+ *  quantiles) so the Health tab's sparkline doesn't have to derive
+ *  everything from raw audits. Emitted by an internal interval, not by
+ *  any specific call site. */
+export interface MetricsEvent {
+    type: 'metrics';
+    ts: string;
+    agents: Array<{
+        agent: string;
+        total: number;
+        success: number;
+        failure: number;
+        p50Ms: number;
+        p95Ms: number;
+        p99Ms: number;
+    }>;
+}
+export type ImhubEvent = AuditEvent | ApprovalEvent | JobEvent | MetricsEvent;
+declare class ImhubEventBus extends EventEmitter {
+    /** Bounded recent-event log so a freshly-connected SSE client can
+     *  catch up on what happened in the last few seconds without needing
+     *  a separate REST poll. Cap at 200 entries — enough for the dashboard
+     *  to show a meaningful "what just happened" feed without bloating
+     *  process memory. */
+    private recent;
+    private static readonly RECENT_CAP;
+    constructor();
+    /**
+     * Publish a typed event. Listeners are called synchronously inside
+     * EventEmitter.emit; errors thrown from a listener are caught here so
+     * a bad subscriber can't break audit-log / approval-bus / job-board.
+     */
+    publish(event: ImhubEvent): void;
+    /** Snapshot of the recent ring buffer. Used by SSE handler on
+     *  connection to replay the last N events to a fresh client. */
+    getRecent(): ImhubEvent[];
+}
+export declare const eventBus: ImhubEventBus;
+export {};
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/core/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/core/event-bus.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;8DAE8D;AAC9D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAA;IACb,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;gBAGgB;AAChB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,WAAW,GAAG,UAAU,CAAA;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB;wDACoD;IACpD,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;CACvC;AAED;4CAC4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,KAAK,CAAA;IACX,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;8BAI8B;AAC9B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;QACb,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;QACf,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;KACd,CAAC,CAAA;CACH;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,GAAG,YAAY,CAAA;AAE7E,cAAM,aAAc,SAAQ,YAAY;IACtC;;;;0BAIsB;IACtB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAM;;IAUxC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAUhC;oEACgE;IAChE,SAAS,IAAI,UAAU,EAAE;CAG1B;AAED,eAAO,MAAM,QAAQ,eAAsB,CAAA"}

package/dist/core/event-bus.js

@@ -0,0 +1,62 @@
+// im-hub event bus — fan-out for cross-cutting state changes that the
+// dashboard / future plugins want to observe in real time.
+//
+// Why a dedicated bus instead of just exposing each module's
+// EventEmitter?
+//
+//   1. Type uniformity. Subscribers want to handle *any* event with one
+//      handler shape; otherwise tasks.html ends up wiring six different
+//      EventEmitters by hand.
+//   2. Cross-module decoupling. audit-log / approval-bus / job-board
+//      should not know that a Web SSE consumer exists. They emit on the
+//      bus; whoever wants to listen does.
+//   3. Backpressure / fan-out. The /events SSE endpoint multiplexes a
+//      single bus subscription out to N browser clients. If a single
+//      client is slow we don't want to drag the entire process; the bus
+//      only does fan-out, per-connection write-buffering is the SSE
+//      handler's responsibility.
+//
+// IMPORTANT: emit is best-effort. Never throw out of an emit() — the
+// caller (audit-log.logInvocation, approvalBus.handleApproval, etc.) is
+// in a hot path. We swallow listener errors here so a buggy subscriber
+// can't break the originating action.
+import { EventEmitter } from 'node:events';
+class ImhubEventBus extends EventEmitter {
+    /** Bounded recent-event log so a freshly-connected SSE client can
+     *  catch up on what happened in the last few seconds without needing
+     *  a separate REST poll. Cap at 200 entries — enough for the dashboard
+     *  to show a meaningful "what just happened" feed without bloating
+     *  process memory. */
+    recent = [];
+    static RECENT_CAP = 200;
+    constructor() {
+        super();
+        // EventEmitter defaults to 10 listeners before warning; we expect one
+        // handler per SSE connection plus a few internal subscribers, so 100
+        // is a comfortable cap that still flags accidental leaks.
+        this.setMaxListeners(100);
+    }
+    /**
+     * Publish a typed event. Listeners are called synchronously inside
+     * EventEmitter.emit; errors thrown from a listener are caught here so
+     * a bad subscriber can't break audit-log / approval-bus / job-board.
+     */
+    publish(event) {
+        this.recent.push(event);
+        while (this.recent.length > ImhubEventBus.RECENT_CAP)
+            this.recent.shift();
+        try {
+            this.emit('event', event);
+        }
+        catch {
+            // EventEmitter normally rethrows — caller is in a hot path so we swallow.
+        }
+    }
+    /** Snapshot of the recent ring buffer. Used by SSE handler on
+     *  connection to replay the last N events to a fresh client. */
+    getRecent() {
+        return this.recent.slice();
+    }
+}
+export const eventBus = new ImhubEventBus();
+//# sourceMappingURL=event-bus.js.map

package/dist/core/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/core/event-bus.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,2DAA2D;AAC3D,EAAE;AACF,6DAA6D;AAC7D,gBAAgB;AAChB,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,8BAA8B;AAC9B,qEAAqE;AACrE,wEAAwE;AACxE,0CAA0C;AAC1C,sEAAsE;AACtE,qEAAqE;AACrE,wEAAwE;AACxE,oEAAoE;AACpE,iCAAiC;AACjC,EAAE;AACF,qEAAqE;AACrE,wEAAwE;AACxE,uEAAuE;AACvE,sCAAsC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAgE1C,MAAM,aAAc,SAAQ,YAAY;IACtC;;;;0BAIsB;IACd,MAAM,GAAiB,EAAE,CAAA;IACzB,MAAM,CAAU,UAAU,GAAG,GAAG,CAAA;IAExC;QACE,KAAK,EAAE,CAAA;QACP,sEAAsE;QACtE,qEAAqE;QACrE,0DAA0D;QAC1D,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAA;IAC3B,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAiB;QACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,aAAa,CAAC,UAAU;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;QACzE,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;IAED;oEACgE;IAChE,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IAC5B,CAAC;;AAGH,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAA"}

package/dist/core/intent-llm.d.ts

@@ -0,0 +1,27 @@
+import type { AgentAdapter } from './types.js';
+export interface LLMJudgeConfig {
+    /** Agent name used as the judge. Must already be registered. */
+    agentName: string;
+    /** Score threshold below which the LLM is consulted (default 1.0). */
+    threshold?: number;
+    /** Override the default 5s response timeout. */
+    timeoutMs?: number;
+}
+export declare function configureLLMJudge(cfg: LLMJudgeConfig | null): void;
+/** Read the judge configuration. Used by classifyIntent to know whether
+ *  to attempt a fallback at all. */
+export declare function getLLMJudge(): LLMJudgeConfig | null;
+/**
+ * Ask the judge agent which candidate to use. Returns null on any
+ * failure path (timeout, judge unavailable, malformed response) so
+ * the caller can keep its rule-based decision.
+ */
+export declare function classifyWithLLM(text: string, candidates: string[], resolveAgent: (name: string) => AgentAdapter | undefined): Promise<{
+    agent: string;
+    reason: string;
+} | null>;
+/** Test-only: clear cache so memoization doesn't leak between cases. */
+export declare function _clearLLMCache(): void;
+/** Test/diagnostic: current cache size. */
+export declare function _cacheSize(): number;
+//# sourceMappingURL=intent-llm.d.ts.map