@oka-core/reason 0.2.15 → 0.2.17

package/dist/fps-tracker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Frame-rate tracker with percentile-based metrics.
+ *
+ * Records individual frame durations and computes:
+ *   - averageFps: total frames / elapsed wall-clock time
+ *   - low1PctFps: 1/p99-frame-duration (worst 1% frames)
+ *
+ * Useful for render loops, streaming pipelines, or any periodic work
+ * where throughput and tail latency matter.
+ */
+export type FpsMetrics = {
+    averageFps: number;
+    low1PctFps: number;
+};
+export declare class FpsTracker {
+    private frameDurations;
+    private firstRenderTime;
+    private lastRenderTime;
+    record(durationMs: number): void;
+    getMetrics(): FpsMetrics | undefined;
+}
+//# sourceMappingURL=fps-tracker.d.ts.map

package/dist/fps-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fps-tracker.d.ts","sourceRoot":"","sources":["../src/fps-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,UAAU,GAAG;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAAqB;IAE3C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAShC,UAAU,IAAI,UAAU,GAAG,SAAS;CA2BrC"}

package/dist/fps-tracker.js

@@ -0,0 +1,44 @@
+/**
+ * Frame-rate tracker with percentile-based metrics.
+ *
+ * Records individual frame durations and computes:
+ *   - averageFps: total frames / elapsed wall-clock time
+ *   - low1PctFps: 1/p99-frame-duration (worst 1% frames)
+ *
+ * Useful for render loops, streaming pipelines, or any periodic work
+ * where throughput and tail latency matter.
+ */
+export class FpsTracker {
+    frameDurations = [];
+    firstRenderTime;
+    lastRenderTime;
+    record(durationMs) {
+        const now = performance.now();
+        if (this.firstRenderTime === undefined) {
+            this.firstRenderTime = now;
+        }
+        this.lastRenderTime = now;
+        this.frameDurations.push(durationMs);
+    }
+    getMetrics() {
+        if (this.frameDurations.length === 0 ||
+            this.firstRenderTime === undefined ||
+            this.lastRenderTime === undefined) {
+            return undefined;
+        }
+        const totalTimeMs = this.lastRenderTime - this.firstRenderTime;
+        if (totalTimeMs <= 0) {
+            return undefined;
+        }
+        const totalFrames = this.frameDurations.length;
+        const averageFps = totalFrames / (totalTimeMs / 1000);
+        const sorted = this.frameDurations.slice().sort((a, b) => b - a);
+        const p99Index = Math.max(0, Math.ceil(sorted.length * 0.01) - 1);
+        const p99FrameTimeMs = sorted[p99Index];
+        const low1PctFps = p99FrameTimeMs > 0 ? 1000 / p99FrameTimeMs : 0;
+        return {
+            averageFps: Math.round(averageFps * 100) / 100,
+            low1PctFps: Math.round(low1PctFps * 100) / 100,
+        };
+    }
+}

package/dist/graceful-shutdown.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Graceful shutdown orchestrator — depends on cleanup-registry.ts, sleep.ts.
+ *
+ * Registers signal handlers, runs cleanup phases in order, and guarantees
+ * process exit via a failsafe timer.
+ *
+ * Inspired by Claude Code's `src/utils/gracefulShutdown.ts` (simplified).
+ */
+export type ShutdownOptions = {
+    /** Time budget in ms for cleanup before force-exit. Default: 5000. */
+    budget?: number;
+    /** Called when shutdown starts. */
+    onShutdown?: (reason: string) => void;
+    /** Called after cleanup, before exit. Use for analytics flush. */
+    onBeforeExit?: () => Promise<void>;
+};
+/** Whether the process is currently shutting down. */
+export declare function isShuttingDown(): boolean;
+/**
+ * Register SIGINT, SIGTERM, SIGHUP handlers for graceful shutdown.
+ * Idempotent — safe to call multiple times.
+ */
+export declare function setupGracefulShutdown(opts?: ShutdownOptions): void;
+/**
+ * Execute a graceful shutdown sequence:
+ * 1. Run cleanup registry functions (parallel, with timeout)
+ * 2. Call onBeforeExit hook (e.g., analytics flush)
+ * 3. Exit process
+ */
+export declare function gracefulShutdown(exitCode?: number, reason?: string, opts?: ShutdownOptions): Promise<never>;
+/**
+ * Reset shutdown state (for testing only).
+ */
+export declare function _resetShutdownForTesting(): void;
+//# sourceMappingURL=graceful-shutdown.d.ts.map

package/dist/graceful-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful-shutdown.d.ts","sourceRoot":"","sources":["../src/graceful-shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,MAAM,eAAe,GAAG;IAC5B,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC,CAAC;AAEF,sDAAsD;AACtD,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI,CAiBlE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,SAAI,EACZ,MAAM,SAAa,EACnB,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,KAAK,CAAC,CA8ChB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C"}

package/dist/graceful-shutdown.js

@@ -0,0 +1,89 @@
+/**
+ * Graceful shutdown orchestrator — depends on cleanup-registry.ts, sleep.ts.
+ *
+ * Registers signal handlers, runs cleanup phases in order, and guarantees
+ * process exit via a failsafe timer.
+ *
+ * Inspired by Claude Code's `src/utils/gracefulShutdown.ts` (simplified).
+ */
+import { runCleanupFunctions } from "./cleanup-registry.js";
+// ─── State ──────────────────────────────────────────────────────────
+let shuttingDown = false;
+let setupDone = false;
+/** Whether the process is currently shutting down. */
+export function isShuttingDown() {
+    return shuttingDown;
+}
+/**
+ * Register SIGINT, SIGTERM, SIGHUP handlers for graceful shutdown.
+ * Idempotent — safe to call multiple times.
+ */
+export function setupGracefulShutdown(opts) {
+    if (setupDone)
+        return;
+    setupDone = true;
+    const handler = (signal) => {
+        if (shuttingDown) {
+            // Double-signal: force immediate exit
+            process.exit(1);
+        }
+        void gracefulShutdown(0, signal, opts);
+    };
+    process.on("SIGINT", () => handler("SIGINT"));
+    process.on("SIGTERM", () => handler("SIGTERM"));
+    if (process.platform !== "win32") {
+        process.on("SIGHUP", () => handler("SIGHUP"));
+    }
+}
+/**
+ * Execute a graceful shutdown sequence:
+ * 1. Run cleanup registry functions (parallel, with timeout)
+ * 2. Call onBeforeExit hook (e.g., analytics flush)
+ * 3. Exit process
+ */
+export async function gracefulShutdown(exitCode = 0, reason = "shutdown", opts) {
+    if (shuttingDown) {
+        process.exit(exitCode);
+    }
+    shuttingDown = true;
+    const budget = opts?.budget ?? 5000;
+    // Failsafe: guarantee exit even if cleanup hangs
+    const failsafe = setTimeout(() => {
+        process.exit(exitCode || 1);
+    }, budget);
+    if (typeof failsafe === "object" && "unref" in failsafe) {
+        failsafe.unref();
+    }
+    opts?.onShutdown?.(reason);
+    // Phase 1: Run registered cleanup functions
+    try {
+        await Promise.race([
+            runCleanupFunctions(),
+            new Promise((resolve) => setTimeout(resolve, Math.floor(budget * 0.6))),
+        ]);
+    }
+    catch {
+        // Continue shutdown even if cleanup fails
+    }
+    // Phase 2: Before-exit hook (analytics flush, etc.)
+    if (opts?.onBeforeExit) {
+        try {
+            await Promise.race([
+                opts.onBeforeExit(),
+                new Promise((resolve) => setTimeout(resolve, Math.floor(budget * 0.3))),
+            ]);
+        }
+        catch {
+            // Continue shutdown
+        }
+    }
+    clearTimeout(failsafe);
+    process.exit(exitCode);
+}
+/**
+ * Reset shutdown state (for testing only).
+ */
+export function _resetShutdownForTesting() {
+    shuttingDown = false;
+    setupDone = false;
+}

package/dist/hash.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Content hashing utilities — uses Node built-in `crypto`.
+ *
+ * Inspired by Claude Code's `src/utils/hash.ts`.
+ */
+/**
+ * Fast non-cryptographic DJB2 hash.
+ * Returns a signed 32-bit integer. Deterministic across runtimes.
+ */
+export declare function djb2Hash(str: string): number;
+/**
+ * SHA-256 content hash. Returns a hex string.
+ * Suitable for change detection and content-addressable caching (not crypto-signing).
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Hash two strings together without concatenation allocation.
+ * Uses a null separator to disambiguate ("ab","c") from ("a","bc").
+ */
+export declare function hashPair(a: string, b: string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/hash.js

@@ -0,0 +1,31 @@
+/**
+ * Content hashing utilities — uses Node built-in `crypto`.
+ *
+ * Inspired by Claude Code's `src/utils/hash.ts`.
+ */
+import { createHash } from "node:crypto";
+/**
+ * Fast non-cryptographic DJB2 hash.
+ * Returns a signed 32-bit integer. Deterministic across runtimes.
+ */
+export function djb2Hash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+/**
+ * SHA-256 content hash. Returns a hex string.
+ * Suitable for change detection and content-addressable caching (not crypto-signing).
+ */
+export function hashContent(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/**
+ * Hash two strings together without concatenation allocation.
+ * Uses a null separator to disambiguate ("ab","c") from ("a","bc").
+ */
+export function hashPair(a, b) {
+    return createHash("sha256").update(a).update("\0").update(b).digest("hex");
+}

package/dist/heap-diagnostics.d.ts

@@ -0,0 +1,68 @@
+/**
+ * V8 heap diagnostics and leak detection.
+ *
+ * Pure diagnostic capture — no snapshot writing, no CC-specific deps.
+ * Extracted from Claude Code's heapDumpService.
+ */
+export type MemoryDiagnostics = {
+    timestamp: string;
+    uptimeSeconds: number;
+    memoryUsage: {
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+        arrayBuffers: number;
+        rss: number;
+    };
+    memoryGrowthRate: {
+        bytesPerSecond: number;
+        mbPerHour: number;
+    };
+    v8HeapStats: {
+        heapSizeLimit: number;
+        mallocedMemory: number;
+        peakMallocedMemory: number;
+        detachedContexts: number;
+        nativeContexts: number;
+    };
+    v8HeapSpaces?: Array<{
+        name: string;
+        size: number;
+        used: number;
+        available: number;
+    }>;
+    resourceUsage: {
+        maxRSS: number;
+        userCPUTime: number;
+        systemCPUTime: number;
+    };
+    activeHandles: number;
+    activeRequests: number;
+    openFileDescriptors?: number;
+    analysis: LeakAnalysis;
+    smapsRollup?: string;
+    platform: string;
+    nodeVersion: string;
+};
+export type LeakAnalysis = {
+    potentialLeaks: string[];
+    recommendation: string;
+};
+export type DiagnosticsOptions = {
+    /** Override timestamp (for testing). */
+    timestamp?: string;
+};
+/** Capture a full memory diagnostics snapshot. */
+export declare function captureMemoryDiagnostics(options?: DiagnosticsOptions): Promise<MemoryDiagnostics>;
+type LeakInputs = {
+    detachedContexts: number;
+    activeHandles: number;
+    nativeMemory: number;
+    heapUsed: number;
+    mbPerHour: number;
+    openFileDescriptors?: number;
+};
+/** Analyze memory metrics for potential leak indicators. */
+export declare function analyzeLeaks(inputs: LeakInputs): LeakAnalysis;
+export {};
+//# sourceMappingURL=heap-diagnostics.d.ts.map

package/dist/heap-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-diagnostics.d.ts","sourceRoot":"","sources":["../src/heap-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,gBAAgB,EAAE;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,WAAW,EAAE;QACX,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,YAAY,CAAC,EAAE,KAAK,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,aAAa,EAAE;QACb,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,kDAAkD;AAClD,wBAAsB,wBAAwB,CAC5C,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAmF5B;AAED,KAAK,UAAU,GAAG;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAkC7D"}

package/dist/heap-diagnostics.js

@@ -0,0 +1,110 @@
+/**
+ * V8 heap diagnostics and leak detection.
+ *
+ * Pure diagnostic capture — no snapshot writing, no CC-specific deps.
+ * Extracted from Claude Code's heapDumpService.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { getHeapSpaceStatistics, getHeapStatistics, } from "node:v8";
+/** Capture a full memory diagnostics snapshot. */
+export async function captureMemoryDiagnostics(options) {
+    const usage = process.memoryUsage();
+    const heapStats = getHeapStatistics();
+    const resourceUsage = process.resourceUsage();
+    const uptimeSeconds = process.uptime();
+    let heapSpaceStats;
+    try {
+        heapSpaceStats = getHeapSpaceStatistics();
+    }
+    catch {
+        // Not available in Bun runtime
+    }
+    const activeHandles = process._getActiveHandles().length;
+    const activeRequests = process._getActiveRequests().length;
+    let openFileDescriptors;
+    try {
+        openFileDescriptors = (await readdir("/proc/self/fd")).length;
+    }
+    catch {
+        // Not on Linux
+    }
+    let smapsRollup;
+    try {
+        smapsRollup = await readFile("/proc/self/smaps_rollup", "utf8");
+    }
+    catch {
+        // Not on Linux or no access
+    }
+    const bytesPerSecond = uptimeSeconds > 0 ? usage.rss / uptimeSeconds : 0;
+    const mbPerHour = (bytesPerSecond * 3600) / (1024 * 1024);
+    const analysis = analyzeLeaks({
+        detachedContexts: heapStats.number_of_detached_contexts,
+        activeHandles,
+        nativeMemory: usage.rss - usage.heapUsed,
+        heapUsed: usage.heapUsed,
+        mbPerHour,
+        openFileDescriptors,
+    });
+    return {
+        timestamp: options?.timestamp ?? new Date().toISOString(),
+        uptimeSeconds,
+        memoryUsage: {
+            heapUsed: usage.heapUsed,
+            heapTotal: usage.heapTotal,
+            external: usage.external,
+            arrayBuffers: usage.arrayBuffers,
+            rss: usage.rss,
+        },
+        memoryGrowthRate: { bytesPerSecond, mbPerHour },
+        v8HeapStats: {
+            heapSizeLimit: heapStats.heap_size_limit,
+            mallocedMemory: heapStats.malloced_memory,
+            peakMallocedMemory: heapStats.peak_malloced_memory,
+            detachedContexts: heapStats.number_of_detached_contexts,
+            nativeContexts: heapStats.number_of_native_contexts,
+        },
+        v8HeapSpaces: heapSpaceStats?.map((space) => ({
+            name: space.space_name,
+            size: space.space_size,
+            used: space.space_used_size,
+            available: space.space_available_size,
+        })),
+        resourceUsage: {
+            maxRSS: resourceUsage.maxRSS * 1024,
+            userCPUTime: resourceUsage.userCPUTime,
+            systemCPUTime: resourceUsage.systemCPUTime,
+        },
+        activeHandles,
+        activeRequests,
+        openFileDescriptors,
+        analysis,
+        smapsRollup,
+        platform: process.platform,
+        nodeVersion: process.version,
+    };
+}
+/** Analyze memory metrics for potential leak indicators. */
+export function analyzeLeaks(inputs) {
+    const potentialLeaks = [];
+    if (inputs.detachedContexts > 0) {
+        potentialLeaks.push(`${inputs.detachedContexts} detached context(s) - possible iframe/context leak`);
+    }
+    if (inputs.activeHandles > 100) {
+        potentialLeaks.push(`${inputs.activeHandles} active handles - possible timer/socket leak`);
+    }
+    if (inputs.nativeMemory > inputs.heapUsed) {
+        potentialLeaks.push("Native memory > heap - leak may be in native addons");
+    }
+    if (inputs.mbPerHour > 100) {
+        potentialLeaks.push(`High memory growth rate: ${inputs.mbPerHour.toFixed(1)} MB/hour`);
+    }
+    if (inputs.openFileDescriptors && inputs.openFileDescriptors > 500) {
+        potentialLeaks.push(`${inputs.openFileDescriptors} open file descriptors - possible file/socket leak`);
+    }
+    return {
+        potentialLeaks,
+        recommendation: potentialLeaks.length > 0
+            ? `WARNING: ${potentialLeaks.length} potential leak indicator(s) found. See potentialLeaks array.`
+            : "No obvious leak indicators. Check heap snapshot for retained objects.",
+    };
+}

package/dist/idle-timeout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Idle timeout manager for long-running services.
+ *
+ * Configurable via options or environment variable. Calls a shutdown
+ * callback after continuous idle duration exceeds threshold.
+ *
+ * Inspired by Claude Code's `src/utils/idleTimeout.ts`.
+ */
+export type IdleTimeoutOptions = {
+    /** Returns true when the system is idle. */
+    isIdle: () => boolean;
+    /** Idle duration in ms before triggering shutdown. Default: from OKA_EXIT_AFTER_IDLE_MS env. */
+    delayMs?: number;
+    /** Called when idle timeout fires. Default: process.exit(0). */
+    onTimeout?: () => void;
+};
+export declare function createIdleTimeoutManager(opts: IdleTimeoutOptions): {
+    start: () => void;
+    stop: () => void;
+};
+//# sourceMappingURL=idle-timeout.d.ts.map

package/dist/idle-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-timeout.d.ts","sourceRoot":"","sources":["../src/idle-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG;IAClE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAsCA"}

package/dist/idle-timeout.js

@@ -0,0 +1,42 @@
+/**
+ * Idle timeout manager for long-running services.
+ *
+ * Configurable via options or environment variable. Calls a shutdown
+ * callback after continuous idle duration exceeds threshold.
+ *
+ * Inspired by Claude Code's `src/utils/idleTimeout.ts`.
+ */
+export function createIdleTimeoutManager(opts) {
+    const envDelay = process.env["OKA_EXIT_AFTER_IDLE_MS"];
+    const delayMs = opts.delayMs ?? (envDelay ? parseInt(envDelay, 10) : undefined);
+    const isValidDelay = delayMs !== undefined && !isNaN(delayMs) && delayMs > 0;
+    const onTimeout = opts.onTimeout ?? (() => process.exit(0));
+    let timer = null;
+    let lastIdleTime = 0;
+    return {
+        start() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            if (isValidDelay && delayMs) {
+                lastIdleTime = Date.now();
+                timer = setTimeout(() => {
+                    const idleDuration = Date.now() - lastIdleTime;
+                    if (opts.isIdle() && idleDuration >= delayMs) {
+                        onTimeout();
+                    }
+                }, delayMs);
+                if (typeof timer === "object" && "unref" in timer) {
+                    timer.unref();
+                }
+            }
+        },
+        stop() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-export {};
+export { analytics } from "./analytics.js";
+export type { AnalyticsSink } from "./analytics.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAWA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -7,8 +7,16 @@ import { registerWriteTools } from "./tools/write.js";
 import { registerReadTools } from "./tools/read.js";
 import { registerAuthTools } from "./tools/auth.js";
 import { loadEnvFile } from "./auth.js";
+import { analytics } from "./analytics.js";
+import { initTelemetry, shutdownTelemetry } from "./telemetry.js";
+export { analytics } from "./analytics.js";
 // Load .env from the project root (cwd), env vars take precedence
 loadEnvFile(process.cwd());
+// Initialize OTel tracing (no-op if OTEL_EXPORTER_OTLP_ENDPOINT is not set)
+await initTelemetry();
+// Attach a no-op sink so analytics events don't queue indefinitely.
+// Downstream consumers can replace this by calling analytics.attach() with a real sink.
+analytics.attach({ track: () => { } });
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 const server = new McpServer({
@@ -22,4 +30,7 @@ registerWriteTools(server, client);
 registerReadTools(server, client);
 registerAuthTools(server, client);
 const transport = new StdioServerTransport();
+// Flush OTel spans on shutdown
+process.on("SIGTERM", () => void shutdownTelemetry());
+process.on("SIGINT", () => void shutdownTelemetry());
 await server.connect(transport);

package/dist/intl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Lazy-cached Intl object instances.
+ *
+ * Intl constructors are expensive (~0.05-0.1ms each). Caching avoids
+ * re-instantiation across hot paths.
+ *
+ * Inspired by Claude Code's `src/utils/intl.ts`.
+ */
+export declare function getGraphemeSegmenter(): Intl.Segmenter;
+/** Extract the first grapheme cluster from a string. */
+export declare function firstGrapheme(text: string): string;
+/** Extract the last grapheme cluster from a string. */
+export declare function lastGrapheme(text: string): string;
+export declare function getWordSegmenter(): Intl.Segmenter;
+export declare function getRelativeTimeFormat(style: "long" | "short" | "narrow", numeric: "always" | "auto"): Intl.RelativeTimeFormat;
+export declare function getTimeZone(): string;
+export declare function getSystemLocaleLanguage(): string | undefined;
+//# sourceMappingURL=intl.d.ts.map

package/dist/intl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intl.d.ts","sourceRoot":"","sources":["../src/intl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,wBAAgB,oBAAoB,IAAI,IAAI,CAAC,SAAS,CAOrD;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAAC,SAAS,CAKjD;AAMD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,EAClC,OAAO,EAAE,QAAQ,GAAG,MAAM,GACzB,IAAI,CAAC,kBAAkB,CAQzB;AAMD,wBAAgB,WAAW,IAAI,MAAM,CAKpC;AAID,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,SAAS,CAU5D"}

package/dist/intl.js

@@ -0,0 +1,75 @@
+/**
+ * Lazy-cached Intl object instances.
+ *
+ * Intl constructors are expensive (~0.05-0.1ms each). Caching avoids
+ * re-instantiation across hot paths.
+ *
+ * Inspired by Claude Code's `src/utils/intl.ts`.
+ */
+// ── Segmenters ────────────────────────────────────────────────────
+let graphemeSegmenter = null;
+let wordSegmenter = null;
+export function getGraphemeSegmenter() {
+    if (!graphemeSegmenter) {
+        graphemeSegmenter = new Intl.Segmenter(undefined, {
+            granularity: "grapheme",
+        });
+    }
+    return graphemeSegmenter;
+}
+/** Extract the first grapheme cluster from a string. */
+export function firstGrapheme(text) {
+    if (!text)
+        return "";
+    const segments = getGraphemeSegmenter().segment(text);
+    const first = segments[Symbol.iterator]().next().value;
+    return first?.segment ?? "";
+}
+/** Extract the last grapheme cluster from a string. */
+export function lastGrapheme(text) {
+    if (!text)
+        return "";
+    let last = "";
+    for (const { segment } of getGraphemeSegmenter().segment(text)) {
+        last = segment;
+    }
+    return last;
+}
+export function getWordSegmenter() {
+    if (!wordSegmenter) {
+        wordSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+    }
+    return wordSegmenter;
+}
+// ── RelativeTimeFormat ────────────────────────────────────────────
+const rtfCache = new Map();
+export function getRelativeTimeFormat(style, numeric) {
+    const key = `${style}:${numeric}`;
+    let rtf = rtfCache.get(key);
+    if (!rtf) {
+        rtf = new Intl.RelativeTimeFormat("en", { style, numeric });
+        rtfCache.set(key, rtf);
+    }
+    return rtf;
+}
+// ── Timezone & locale ─────────────────────────────────────────────
+let cachedTimeZone = null;
+export function getTimeZone() {
+    if (!cachedTimeZone) {
+        cachedTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    return cachedTimeZone;
+}
+let cachedSystemLocaleLanguage = null;
+export function getSystemLocaleLanguage() {
+    if (cachedSystemLocaleLanguage === null) {
+        try {
+            const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+            cachedSystemLocaleLanguage = new Intl.Locale(locale).language;
+        }
+        catch {
+            cachedSystemLocaleLanguage = undefined;
+        }
+    }
+    return cachedSystemLocaleLanguage;
+}

package/dist/jsonl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * JSONL parsing and safe JSON utilities.
+ *
+ * Inspired by Claude Code's `src/utils/json.ts` (generic parts only).
+ */
+/**
+ * Parse JSON safely, returning `null` on failure.
+ * Results are LRU-memoized (50 entries max, keys ≤ 8KB).
+ */
+export declare function safeParseJSON<T = unknown>(json: string | null | undefined): T | null;
+/**
+ * Parse a JSONL string into an array of typed values.
+ * Skips blank lines and silently drops malformed lines.
+ */
+export declare function parseJSONL<T = unknown>(data: string): T[];
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../src/jsonl.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EACvC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,CAAC,GAAG,IAAI,CAyBV;AAID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,CAkBzD"}