@mongrov/analytics 0.1.0-alpha.8 → 0.1.0-alpha.9

package/dist/tools/__fakes__/engine.d.ts

@@ -0,0 +1,25 @@
+import type { AnalyticsEngine } from '../../core/types';
+/**
+ * Scriptable AnalyticsEngine fake for tool tests.
+ *
+ * Unlike the rules-side fake (single global queue), this fake supports
+ * per-SQL-substring row queues so multi-query tools (compare, activity)
+ * can script distinct responses per call.
+ *
+ * Usage:
+ *   const engine = createFakeEngine()
+ *   engine.queueRows('FROM hrv', [{ day: '2026-07-08', avg_hrv: 45 }])
+ *   engine.queueRows('FROM sleep_session', [...])
+ *   // ...invoke tool...
+ *   engine.calls.forEach(c => ...)
+ */
+export interface FakeEngine extends AnalyticsEngine {
+    readonly calls: {
+        sql: string;
+        params: Record<string, unknown>;
+    }[];
+    queueRows: (sqlSubstring: string, rows: unknown[]) => void;
+    setError: (err: Error | null) => void;
+}
+export declare function createFakeEngine(): FakeEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/tools/__fakes__/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/tools/__fakes__/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,QAAQ,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAA;IAClE,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;IAC1D,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,CAAA;CACtC;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAkC7C"}

package/dist/tools/__fakes__/engine.js

@@ -0,0 +1,37 @@
+export function createFakeEngine() {
+    const queues = [];
+    const calls = [];
+    let error = null;
+    const engine = {
+        async attach() { },
+        async detach() { },
+        async execute(sql, params) {
+            calls.push({ sql, params: params ?? {} });
+            if (error)
+                throw error;
+            const idx = queues.findIndex(q => sql.includes(q.substring));
+            if (idx === -1)
+                return [];
+            const [q] = queues.splice(idx, 1);
+            return q.rows;
+        },
+        stream() {
+            throw new Error('stream not implemented in fake');
+        },
+        createAppender() {
+            throw new Error('createAppender not implemented in fake');
+        },
+        state: 'attached',
+        lastError: null,
+        catalog: 'fake',
+        subscribe: () => () => { },
+        async setRetention() { },
+        async getLastAttach() { return null; },
+        async close() { },
+        calls,
+        queueRows(substring, rows) { queues.push({ substring, rows }); },
+        setError(err) { error = err; },
+    };
+    return engine;
+}
+//# sourceMappingURL=engine.js.map

package/dist/tools/__fakes__/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/tools/__fakes__/engine.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAA6C,EAAE,CAAA;IAC3D,MAAM,KAAK,GAAuD,EAAE,CAAA;IACpE,IAAI,KAAK,GAAiB,IAAI,CAAA;IAE9B,MAAM,MAAM,GAAe;QACzB,KAAK,CAAC,MAAM,KAAI,CAAC;QACjB,KAAK,CAAC,MAAM,KAAI,CAAC;QACjB,KAAK,CAAC,OAAO,CAAI,GAAW,EAAE,MAAgC;YAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC,CAAA;YACzC,IAAI,KAAK;gBAAE,MAAM,KAAK,CAAA;YACtB,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;YAC5D,IAAI,GAAG,KAAK,CAAC,CAAC;gBAAE,OAAO,EAAS,CAAA;YAChC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YACjC,OAAO,CAAC,CAAC,IAAW,CAAA;QACtB,CAAC;QACD,MAAM;YACJ,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;QACnD,CAAC;QACD,cAAc;YACZ,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;QAC3D,CAAC;QACD,KAAK,EAAE,UAAU;QACjB,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,MAAM;QACf,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QACzB,KAAK,CAAC,YAAY,KAAI,CAAC;QACvB,KAAK,CAAC,aAAa,KAAK,OAAO,IAAI,CAAA,CAAC,CAAC;QACrC,KAAK,CAAC,KAAK,KAAI,CAAC;QAChB,KAAK;QACL,SAAS,CAAC,SAAS,EAAE,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA,CAAC,CAAC;QAC/D,QAAQ,CAAC,GAAG,IAAI,KAAK,GAAG,GAAG,CAAA,CAAC,CAAC;KAC9B,CAAA;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/tools/audit.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Batched writer for `tool_call_audit`.
+ *
+ * `record()` enqueues synchronously (non-blocking). The batch flushes
+ * whenever:
+ *   - the pending queue reaches `batchSize` (default 10), or
+ *   - the flush timer fires (`flushIntervalMs`, default 1000ms).
+ *
+ * `flush()` and `close()` are cooperative exit hooks — `close`
+ * additionally halts the timer.
+ *
+ * On flush failure the batch is retained and retried on the next
+ * tick. A defensive `MAX_CONSECUTIVE_FAILURES` cap drops the buffer
+ * after repeated errors to avoid unbounded growth on a stuck
+ * warehouse.
+ *
+ * SQL uses a single INSERT with a suffix-indexed VALUES tuple per
+ * row (`$p0_ts, $p0_brand, …, $p1_ts, …`). DuckDB honors named
+ * parameters in this form.
+ */
+import type { AnalyticsEngine } from '../core/types';
+import type { AuditWriter, ToolsLogger } from './types';
+export interface CreateAuditWriterConfig {
+    analytics: AnalyticsEngine;
+    enabled?: boolean;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    logger?: ToolsLogger;
+}
+export declare function createAuditWriter(cfg: CreateAuditWriterConfig): AuditWriter;
+//# sourceMappingURL=audit.d.ts.map

package/dist/tools/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/tools/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAc,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAoBnE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,eAAe,CAAA;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,uBAAuB,GAAG,WAAW,CA6F3E"}

package/dist/tools/audit.js

@@ -0,0 +1,157 @@
+/**
+ * Batched writer for `tool_call_audit`.
+ *
+ * `record()` enqueues synchronously (non-blocking). The batch flushes
+ * whenever:
+ *   - the pending queue reaches `batchSize` (default 10), or
+ *   - the flush timer fires (`flushIntervalMs`, default 1000ms).
+ *
+ * `flush()` and `close()` are cooperative exit hooks — `close`
+ * additionally halts the timer.
+ *
+ * On flush failure the batch is retained and retried on the next
+ * tick. A defensive `MAX_CONSECUTIVE_FAILURES` cap drops the buffer
+ * after repeated errors to avoid unbounded growth on a stuck
+ * warehouse.
+ *
+ * SQL uses a single INSERT with a suffix-indexed VALUES tuple per
+ * row (`$p0_ts, $p0_brand, …, $p1_ts, …`). DuckDB honors named
+ * parameters in this form.
+ */
+const DEFAULT_BATCH_SIZE = 10;
+const DEFAULT_FLUSH_INTERVAL_MS = 1000;
+const MAX_CONSECUTIVE_FAILURES = 5;
+const COLUMNS = [
+    'ts',
+    'brand',
+    'family_id',
+    'requester_user_id',
+    'tool_name',
+    'args',
+    'result_bytes',
+    'result_row_count',
+    'latency_ms',
+    'outcome',
+    'error_message',
+];
+export function createAuditWriter(cfg) {
+    const enabled = cfg.enabled ?? true;
+    const batchSize = cfg.batchSize ?? DEFAULT_BATCH_SIZE;
+    const flushIntervalMs = cfg.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    const logger = cfg.logger;
+    const pending = [];
+    let timer = null;
+    let consecutiveFailures = 0;
+    let inFlight = null;
+    let closed = false;
+    function ensureTimer() {
+        if (timer || closed)
+            return;
+        timer = setInterval(() => {
+            void doFlush();
+        }, flushIntervalMs);
+        // Node timers are keep-alive by default; unref so a lingering
+        // audit writer doesn't block process exit.
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    }
+    function clearFlushTimer() {
+        if (!timer)
+            return;
+        clearInterval(timer);
+        timer = null;
+    }
+    async function doFlush() {
+        if (inFlight)
+            return inFlight;
+        if (pending.length === 0)
+            return;
+        const batch = pending.splice(0, pending.length);
+        inFlight = (async () => {
+            try {
+                await writeBatch(cfg.analytics, batch);
+                consecutiveFailures = 0;
+            }
+            catch (err) {
+                consecutiveFailures += 1;
+                const errMsg = err instanceof Error ? err.message : String(err);
+                logger?.warn('audit flush failed', {
+                    err: errMsg,
+                    batchSize: batch.length,
+                    consecutiveFailures,
+                });
+                if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                    logger?.error('audit flush cap reached, dropping batch', {
+                        droppedRows: batch.length,
+                    });
+                    consecutiveFailures = 0;
+                }
+                else {
+                    // Retain: prepend so retry preserves order.
+                    pending.unshift(...batch);
+                }
+            }
+            finally {
+                inFlight = null;
+            }
+        })();
+        return inFlight;
+    }
+    return {
+        record(entry) {
+            if (!enabled || closed)
+                return;
+            pending.push(entry);
+            ensureTimer();
+            if (pending.length >= batchSize) {
+                void doFlush();
+            }
+        },
+        async flush() {
+            if (!enabled)
+                return;
+            await doFlush();
+            // If the flush swallowed a failure and re-queued, drain once
+            // more so callers get a best-effort guarantee.
+            if (pending.length > 0) {
+                await doFlush();
+            }
+        },
+        async close() {
+            closed = true;
+            clearFlushTimer();
+            if (!enabled)
+                return;
+            await doFlush();
+            if (pending.length > 0) {
+                await doFlush();
+            }
+        },
+    };
+}
+async function writeBatch(analytics, batch) {
+    if (batch.length === 0)
+        return;
+    const tuples = [];
+    const params = {};
+    batch.forEach((entry, i) => {
+        const prefix = `p${i}`;
+        const placeholders = COLUMNS.map(col => `$${prefix}_${col}`);
+        tuples.push(`(${placeholders.join(', ')})`);
+        params[`${prefix}_ts`] = entry.ts;
+        params[`${prefix}_brand`] = entry.brand;
+        params[`${prefix}_family_id`] = entry.familyId;
+        params[`${prefix}_requester_user_id`] = entry.requesterUserId;
+        params[`${prefix}_tool_name`] = entry.toolName;
+        params[`${prefix}_args`] = JSON.stringify(entry.args);
+        params[`${prefix}_result_bytes`] = entry.resultBytes;
+        params[`${prefix}_result_row_count`] = entry.resultRowCount;
+        params[`${prefix}_latency_ms`] = entry.latencyMs;
+        params[`${prefix}_outcome`] = entry.outcome;
+        params[`${prefix}_error_message`] = entry.errorMessage;
+    });
+    const sql = `INSERT INTO tool_call_audit (${COLUMNS.join(', ')}) VALUES ${tuples.join(', ')}`;
+    await analytics.execute(sql, params);
+}
+//# sourceMappingURL=audit.js.map

package/dist/tools/audit.js.map

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

package/dist/tools/authorize.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Authorize hooks for analytics tools.
+ *
+ * `familyScopeAuthorize` — grants access iff `args.userId` is either
+ * the requester themselves or another member of the requester's
+ * family. When `config.familyMembersProvider` is supplied (the
+ * factory path since T-11), membership resolves via that provider;
+ * otherwise the legacy SQL path against a `family_member` table is
+ * used (kept for standalone hook usage and backwards compat).
+ *
+ * Both hooks fail closed on any error — provider throws, engine
+ * throws, missing/malformed args — return `false` rather than
+ * surfacing the error to the LLM.
+ */
+import type { AnalyticsEngine, FamilyMembersProvider } from '../core/types';
+import type { AuthorizeFn } from './types';
+export interface AuthorizeConfig {
+    /**
+     * When present, membership is resolved via the provider instead of
+     * SQL. This is the path wired by `createAnalyticsTools`.
+     */
+    familyMembersProvider?: FamilyMembersProvider;
+}
+export declare function familyScopeAuthorize(analytics: AnalyticsEngine, config?: AuthorizeConfig): AuthorizeFn;
+/**
+ * `orgScopeAuthorize` — parity with family scope but against an
+ * `org_member` table. Orgs are not first-class in v0.1.0; the ctx
+ * `familyId` is treated as the org id until org membership is wired
+ * through `RequestContext`.
+ *
+ * When `familyMembersProvider` is supplied, the same provider is
+ * consulted (v0.1.0 shim — a dedicated `orgMembersProvider` will
+ * split out once orgs land).
+ */
+export declare function orgScopeAuthorize(analytics: AnalyticsEngine, config?: AuthorizeConfig): AuthorizeFn;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/tools/authorize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../../src/tools/authorize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;CAC9C;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,eAAe,EAC1B,MAAM,GAAE,eAAoB,GAC3B,WAAW,CAmCb;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,eAAe,EAC1B,MAAM,GAAE,eAAoB,GAC3B,WAAW,CAmCb"}

package/dist/tools/authorize.js

@@ -0,0 +1,87 @@
+/**
+ * Authorize hooks for analytics tools.
+ *
+ * `familyScopeAuthorize` — grants access iff `args.userId` is either
+ * the requester themselves or another member of the requester's
+ * family. When `config.familyMembersProvider` is supplied (the
+ * factory path since T-11), membership resolves via that provider;
+ * otherwise the legacy SQL path against a `family_member` table is
+ * used (kept for standalone hook usage and backwards compat).
+ *
+ * Both hooks fail closed on any error — provider throws, engine
+ * throws, missing/malformed args — return `false` rather than
+ * surfacing the error to the LLM.
+ */
+export function familyScopeAuthorize(analytics, config = {}) {
+    return async (_toolName, args, ctx) => {
+        const targetUserId = args.userId;
+        if (typeof targetUserId !== 'string' || targetUserId.length === 0) {
+            return false;
+        }
+        if (targetUserId === ctx.requesterUserId) {
+            return true;
+        }
+        if (config.familyMembersProvider) {
+            try {
+                const members = await config.familyMembersProvider({
+                    brand: ctx.brand,
+                    familyId: ctx.familyId,
+                });
+                return members.includes(targetUserId);
+            }
+            catch {
+                return false;
+            }
+        }
+        try {
+            const rows = await analytics.execute('SELECT 1 AS one FROM family_member '
+                + 'WHERE family_id = $familyId AND user_id = $userId LIMIT 1', { familyId: ctx.familyId, userId: targetUserId });
+            return rows.length > 0;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/**
+ * `orgScopeAuthorize` — parity with family scope but against an
+ * `org_member` table. Orgs are not first-class in v0.1.0; the ctx
+ * `familyId` is treated as the org id until org membership is wired
+ * through `RequestContext`.
+ *
+ * When `familyMembersProvider` is supplied, the same provider is
+ * consulted (v0.1.0 shim — a dedicated `orgMembersProvider` will
+ * split out once orgs land).
+ */
+export function orgScopeAuthorize(analytics, config = {}) {
+    return async (_toolName, args, ctx) => {
+        const targetUserId = args.userId;
+        if (typeof targetUserId !== 'string' || targetUserId.length === 0) {
+            return false;
+        }
+        if (targetUserId === ctx.requesterUserId) {
+            return true;
+        }
+        if (config.familyMembersProvider) {
+            try {
+                const members = await config.familyMembersProvider({
+                    brand: ctx.brand,
+                    familyId: ctx.familyId,
+                });
+                return members.includes(targetUserId);
+            }
+            catch {
+                return false;
+            }
+        }
+        try {
+            const rows = await analytics.execute('SELECT 1 AS one FROM org_member '
+                + 'WHERE org_id = $orgId AND user_id = $userId LIMIT 1', { orgId: ctx.familyId, userId: targetUserId });
+            return rows.length > 0;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+//# sourceMappingURL=authorize.js.map

package/dist/tools/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../../src/tools/authorize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,MAAM,UAAU,oBAAoB,CAClC,SAA0B,EAC1B,SAA0B,EAAE;IAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACpC,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAA;QAChC,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClE,OAAO,KAAK,CAAA;QACd,CAAC;QACD,IAAI,YAAY,KAAK,GAAG,CAAC,eAAe,EAAE,CAAC;YACzC,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,MAAM,CAAC,qBAAqB,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC;oBACjD,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;iBACvB,CAAC,CAAA;gBACF,OAAO,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;YACvC,CAAC;YACD,MAAM,CAAC;gBACL,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAClC,qCAAqC;kBACnC,2DAA2D,EAC7D,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CACjD,CAAA;YACD,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAA;QACxB,CAAC;QACD,MAAM,CAAC;YACL,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA0B,EAC1B,SAA0B,EAAE;IAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACpC,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAA;QAChC,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClE,OAAO,KAAK,CAAA;QACd,CAAC;QACD,IAAI,YAAY,KAAK,GAAG,CAAC,eAAe,EAAE,CAAC;YACzC,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,MAAM,CAAC,qBAAqB,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC;oBACjD,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;iBACvB,CAAC,CAAA;gBACF,OAAO,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;YACvC,CAAC;YACD,MAAM,CAAC;gBACL,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAClC,kCAAkC;kBAChC,qDAAqD,EACvD,EAAE,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAC9C,CAAA;YACD,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAA;QACxB,CAAC;QACD,MAAM,CAAC;YACL,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/tools/budget.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Output budget enforcement for tool results.
+ *
+ * `applyOutputBudget` truncates `ToolResult.text` when its UTF-8
+ * byte size exceeds `budget.maxBytes`, appending a `\n[truncated]`
+ * suffix. Truncation is UTF-8-safe: bytes are sliced and re-decoded
+ * with `fatal: false` so any partial multi-byte codepoint at the
+ * boundary is dropped rather than emitting invalid sequences.
+ *
+ * `budget.maxRows` is informational — tool impls limit row count
+ * via SQL LIMIT. This helper does not attempt row-level truncation.
+ */
+import type { OutputBudget, ToolResult } from './types';
+export declare function applyOutputBudget(result: ToolResult, budget: OutputBudget): ToolResult;
+//# sourceMappingURL=budget.d.ts.map

package/dist/tools/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/tools/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAIvD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,YAAY,GACnB,UAAU,CAiBZ"}

package/dist/tools/budget.js

@@ -0,0 +1,64 @@
+/**
+ * Output budget enforcement for tool results.
+ *
+ * `applyOutputBudget` truncates `ToolResult.text` when its UTF-8
+ * byte size exceeds `budget.maxBytes`, appending a `\n[truncated]`
+ * suffix. Truncation is UTF-8-safe: bytes are sliced and re-decoded
+ * with `fatal: false` so any partial multi-byte codepoint at the
+ * boundary is dropped rather than emitting invalid sequences.
+ *
+ * `budget.maxRows` is informational — tool impls limit row count
+ * via SQL LIMIT. This helper does not attempt row-level truncation.
+ */
+const TRUNCATE_SUFFIX = '\n[truncated]';
+export function applyOutputBudget(result, budget) {
+    if (result.bytes <= budget.maxBytes)
+        return result;
+    const encoder = new TextEncoder();
+    const suffixBytes = encoder.encode(TRUNCATE_SUFFIX).byteLength;
+    const targetBytes = Math.max(0, budget.maxBytes - suffixBytes);
+    const encoded = encoder.encode(result.text);
+    const safeEnd = utf8SafeBoundary(encoded, Math.min(targetBytes, encoded.byteLength));
+    const decoded = new TextDecoder('utf-8').decode(encoded.slice(0, safeEnd));
+    const truncated = `${decoded}${TRUNCATE_SUFFIX}`;
+    return {
+        text: truncated,
+        rowCount: result.rowCount,
+        bytes: encoder.encode(truncated).byteLength,
+    };
+}
+/**
+ * Walk `end` backward until it points to a valid UTF-8 codepoint
+ * boundary — i.e. either past-the-end of the array or at a byte
+ * whose top bits are not `10` (continuation). This guarantees that
+ * `bytes.slice(0, boundary)` decodes without emitting replacement
+ * characters for a partial trailing multibyte sequence.
+ */
+function utf8SafeBoundary(bytes, end) {
+    let boundary = end;
+    // A continuation byte matches 10xxxxxx (0x80..0xBF).
+    while (boundary > 0 && (bytes[boundary] & 0xC0) === 0x80) {
+        boundary -= 1;
+    }
+    // If boundary now points to a lead byte (top bit set), check
+    // whether the full sequence fits inside `end`. If not, drop the
+    // lead byte as well.
+    if (boundary > 0 && boundary < bytes.byteLength) {
+        const lead = bytes[boundary];
+        let seqLen = 0;
+        if ((lead & 0x80) === 0x00)
+            seqLen = 1;
+        else if ((lead & 0xE0) === 0xC0)
+            seqLen = 2;
+        else if ((lead & 0xF0) === 0xE0)
+            seqLen = 3;
+        else if ((lead & 0xF8) === 0xF0)
+            seqLen = 4;
+        if (seqLen > 1 && boundary + seqLen > end) {
+            // Partial sequence — drop lead byte.
+            return boundary;
+        }
+    }
+    return boundary;
+}
+//# sourceMappingURL=budget.js.map

package/dist/tools/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/tools/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,eAAe,GAAG,eAAe,CAAA;AAEvC,MAAM,UAAU,iBAAiB,CAC/B,MAAkB,EAClB,MAAoB;IAEpB,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,QAAQ;QAAE,OAAO,MAAM,CAAA;IAElD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;IACjC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,UAAU,CAAA;IAC9D,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAA;IAE9D,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC3C,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAA;IACpF,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAA;IAC1E,MAAM,SAAS,GAAG,GAAG,OAAO,GAAG,eAAe,EAAE,CAAA;IAEhD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,UAAU;KAC5C,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,KAAiB,EAAE,GAAW;IACtD,IAAI,QAAQ,GAAG,GAAG,CAAA;IAClB,qDAAqD;IACrD,OAAO,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QACzD,QAAQ,IAAI,CAAC,CAAA;IACf,CAAC;IACD,6DAA6D;IAC7D,gEAAgE;IAChE,qBAAqB;IACrB,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAA;QAC5B,IAAI,MAAM,GAAG,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI;YAAE,MAAM,GAAG,CAAC,CAAA;aACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI;YAAE,MAAM,GAAG,CAAC,CAAA;aACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI;YAAE,MAAM,GAAG,CAAC,CAAA;aACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI;YAAE,MAAM,GAAG,CAAC,CAAA;QAC3C,IAAI,MAAM,GAAG,CAAC,IAAI,QAAQ,GAAG,MAAM,GAAG,GAAG,EAAE,CAAC;YAC1C,qCAAqC;YACrC,OAAO,QAAQ,CAAA;QACjB,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/dist/tools/factory.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `createAnalyticsTools` — assemble the 6 wrapped AI SDK tools into
+ * a single map ready to hand to `streamText({ tools })` / `generateText`.
+ *
+ * Wires:
+ *   - rate limiter   (or `null` if `rateLimit: false`)
+ *   - authorize hook (default `familyScopeAuthorize`, optionally with
+ *                     an injected `familyMembersProvider`)
+ *   - audit writer   (batched, optional)
+ *   - output budget  (default 4096 bytes / 100 rows)
+ *
+ * Per-request context threading: the AI SDK's `execute(input)` has no
+ * ctx arg. We hold a mutable `currentCtx` container and expose
+ * `setContext(ctx)`. Consumers (zivaone_app) call `setContext` before
+ * each LLM turn — matching how `@mongrov/ai`'s `AIProvider` threads
+ * per-request scopes. This design keeps rate-limiter buckets + audit
+ * writer state shared across requests rather than rebuilding the
+ * whole tool map per turn.
+ */
+import type { AnalyticsToolsConfig, AuditWriter, ToolContext } from './types';
+import { makeTool } from './wrap';
+import { type GetActivityTotalInput } from './impls/activity';
+import { type DetectAnomalyInput } from './impls/anomaly';
+import { type CompareTrendInput } from './impls/compare';
+import { type GetHRVInput } from './impls/hrv';
+import { type GetInsightsInput } from './impls/insights';
+import { type GetSleepSummaryInput } from './impls/sleep';
+export interface AnalyticsToolMap {
+    getHRV: ReturnType<typeof makeTool<GetHRVInput>>;
+    getSleepSummary: ReturnType<typeof makeTool<GetSleepSummaryInput>>;
+    getActivityTotal: ReturnType<typeof makeTool<GetActivityTotalInput>>;
+    compareTrend: ReturnType<typeof makeTool<CompareTrendInput>>;
+    detectAnomaly: ReturnType<typeof makeTool<DetectAnomalyInput>>;
+    getInsights: ReturnType<typeof makeTool<GetInsightsInput>>;
+}
+export interface AnalyticsToolsHandle {
+    tools: AnalyticsToolMap;
+    setContext: (ctx: ToolContext | null) => void;
+    auditWriter: AuditWriter;
+    close: () => Promise<void>;
+}
+export declare function createAnalyticsTools(config: AnalyticsToolsConfig): AnalyticsToolsHandle;
+//# sourceMappingURL=factory.d.ts.map

package/dist/tools/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/tools/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EACV,oBAAoB,EACpB,WAAW,EAEX,WAAW,EACZ,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AACzE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAA;AAoBtB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAA;IAChD,eAAe,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAA;IAClE,gBAAgB,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAA;IACpE,YAAY,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAA;IAC5D,aAAa,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAA;IAC9D,WAAW,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAA;CAC3D;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,gBAAgB,CAAA;IACvB,UAAU,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;IAC7C,WAAW,EAAE,WAAW,CAAA;IACxB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAiGtB"}