apcore-js 0.10.0 → 0.11.0

package/dist/middleware/index.js

@@ -3,4 +3,6 @@ export { MiddlewareManager, MiddlewareChainError } from './manager.js';
 export { BeforeMiddleware, AfterMiddleware } from './adapters.js';
 export { LoggingMiddleware } from './logging.js';
 export { RetryMiddleware, CTX_RETRY_COUNT_PREFIX, CTX_RETRY_DELAY_PREFIX } from './retry.js';
+export { ErrorHistoryMiddleware } from './error-history.js';
+export { PlatformNotifyMiddleware } from './platform-notify.js';
 //# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE7F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/middleware/platform-notify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * PlatformNotifyMiddleware -- threshold sensor with hysteresis.
+ *
+ * Monitors error rates and latency, emits threshold events with hysteresis.
+ * Emits error_threshold_exceeded when a module's error rate crosses the
+ * configured threshold, latency_threshold_exceeded when p99 latency
+ * exceeds the limit, and module_health_changed when a previously alerted
+ * module recovers below threshold * 0.5.
+ */
+import type { Context } from '../context.js';
+import type { EventEmitter } from '../events/emitter.js';
+import type { MetricsCollector } from '../observability/metrics.js';
+import { Middleware } from './base.js';
+export declare class PlatformNotifyMiddleware extends Middleware {
+    private readonly _emitter;
+    private readonly _metricsCollector;
+    private readonly _errorRateThreshold;
+    private readonly _latencyP99ThresholdMs;
+    private readonly _alerted;
+    constructor(eventEmitter: EventEmitter, metricsCollector?: MetricsCollector | null, errorRateThreshold?: number, latencyP99ThresholdMs?: number);
+    after(moduleId: string, _inputs: Record<string, unknown>, _output: Record<string, unknown>, _context: Context): Record<string, unknown> | null;
+    onError(moduleId: string, _inputs: Record<string, unknown>, _error: Error, _context: Context): Record<string, unknown> | null;
+    private _getAlerted;
+    private _computeErrorRate;
+    private _checkErrorRateThreshold;
+    private _checkLatencyThreshold;
+    private _estimateP99Ms;
+    private _checkErrorRecovery;
+}
+//# sourceMappingURL=platform-notify.d.ts.map

package/dist/middleware/platform-notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-notify.d.ts","sourceRoot":"","sources":["../../src/middleware/platform-notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,sBAAsB,CAAC;AAEtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,qBAAa,wBAAyB,SAAQ,UAAU;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAC5D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;gBAG9D,YAAY,EAAE,YAAY,EAC1B,gBAAgB,GAAE,gBAAgB,GAAG,IAAW,EAChD,kBAAkB,GAAE,MAAY,EAChC,qBAAqB,GAAE,MAAa;IAS7B,KAAK,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,OAAO,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMxB,OAAO,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,KAAK,EACb,QAAQ,EAAE,OAAO,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKjC,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,mBAAmB;CAe5B"}

package/dist/middleware/platform-notify.js

@@ -0,0 +1,84 @@
+/**
+ * PlatformNotifyMiddleware -- threshold sensor with hysteresis.
+ *
+ * Monitors error rates and latency, emits threshold events with hysteresis.
+ * Emits error_threshold_exceeded when a module's error rate crosses the
+ * configured threshold, latency_threshold_exceeded when p99 latency
+ * exceeds the limit, and module_health_changed when a previously alerted
+ * module recovers below threshold * 0.5.
+ */
+import { createEvent } from '../events/emitter.js';
+import { computeModuleErrorRate, estimateP99FromHistogram } from '../observability/metrics-utils.js';
+import { Middleware } from './base.js';
+export class PlatformNotifyMiddleware extends Middleware {
+    _emitter;
+    _metricsCollector;
+    _errorRateThreshold;
+    _latencyP99ThresholdMs;
+    _alerted = new Map();
+    constructor(eventEmitter, metricsCollector = null, errorRateThreshold = 0.1, latencyP99ThresholdMs = 5000) {
+        super();
+        this._emitter = eventEmitter;
+        this._metricsCollector = metricsCollector;
+        this._errorRateThreshold = errorRateThreshold;
+        this._latencyP99ThresholdMs = latencyP99ThresholdMs;
+    }
+    after(moduleId, _inputs, _output, _context) {
+        this._checkLatencyThreshold(moduleId);
+        this._checkErrorRecovery(moduleId);
+        return null;
+    }
+    onError(moduleId, _inputs, _error, _context) {
+        this._checkErrorRateThreshold(moduleId);
+        return null;
+    }
+    _getAlerted(moduleId) {
+        let set = this._alerted.get(moduleId);
+        if (!set) {
+            set = new Set();
+            this._alerted.set(moduleId, set);
+        }
+        return set;
+    }
+    _computeErrorRate(moduleId) {
+        if (!this._metricsCollector)
+            return 0;
+        return computeModuleErrorRate(this._metricsCollector, moduleId).errorRate;
+    }
+    _checkErrorRateThreshold(moduleId) {
+        const errorRate = this._computeErrorRate(moduleId);
+        const alerted = this._getAlerted(moduleId);
+        if (errorRate >= this._errorRateThreshold && !alerted.has('error_rate')) {
+            this._emitter.emit(createEvent('error_threshold_exceeded', moduleId, 'warning', { error_rate: errorRate, threshold: this._errorRateThreshold }));
+            alerted.add('error_rate');
+        }
+    }
+    _checkLatencyThreshold(moduleId) {
+        if (!this._metricsCollector)
+            return;
+        const alerted = this._getAlerted(moduleId);
+        if (alerted.has('latency'))
+            return;
+        const p99Ms = this._estimateP99Ms(moduleId);
+        if (p99Ms >= this._latencyP99ThresholdMs) {
+            this._emitter.emit(createEvent('latency_threshold_exceeded', moduleId, 'warning', { p99_latency_ms: p99Ms, threshold_ms: this._latencyP99ThresholdMs }));
+            alerted.add('latency');
+        }
+    }
+    _estimateP99Ms(moduleId) {
+        if (!this._metricsCollector)
+            return 0;
+        return estimateP99FromHistogram(this._metricsCollector, moduleId).p99LatencyMs;
+    }
+    _checkErrorRecovery(moduleId) {
+        const alerted = this._alerted.get(moduleId);
+        if (!alerted || !alerted.has('error_rate'))
+            return;
+        const errorRate = this._computeErrorRate(moduleId);
+        if (errorRate < this._errorRateThreshold * 0.5) {
+            this._emitter.emit(createEvent('module_health_changed', moduleId, 'info', { status: 'recovered', error_rate: errorRate }));
+            alerted.delete('error_rate');
+        }
+    }
+}
+//# sourceMappingURL=platform-notify.js.map

package/dist/middleware/platform-notify.js.map

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

package/dist/observability/error-history.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error history with ring-buffer eviction and deduplication.
+ */
+import { ModuleError } from '../errors.js';
+export interface ErrorEntry {
+    readonly moduleId: string;
+    readonly code: string;
+    readonly message: string;
+    readonly aiGuidance: string | null;
+    readonly timestamp: string;
+    count: number;
+    firstOccurred: string;
+    lastOccurred: string;
+}
+/**
+ * Ring buffer storing recent error details per module.
+ * Supports deduplication by (code, message) within each module,
+ * per-module eviction, and global total eviction.
+ */
+export declare class ErrorHistory {
+    private readonly _maxEntriesPerModule;
+    private readonly _maxTotalEntries;
+    private readonly _entries;
+    constructor(maxEntriesPerModule?: number, maxTotalEntries?: number);
+    record(moduleId: string, error: ModuleError): void;
+    get(moduleId: string, limit?: number): ErrorEntry[];
+    clear(): void;
+    clearModule(moduleId: string): void;
+    getAll(limit?: number): ErrorEntry[];
+    private _evictModule;
+    private _evictTotal;
+}
+//# sourceMappingURL=error-history.d.ts.map

package/dist/observability/error-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-history.d.ts","sourceRoot":"","sources":["../../src/observability/error-history.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;gBAErD,mBAAmB,GAAE,MAAW,EAAE,eAAe,GAAE,MAAa;IAK5E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAgClD,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAMnD,KAAK,IAAI,IAAI;IAIb,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IASpC,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;CA0BpB"}

package/dist/observability/error-history.js

@@ -0,0 +1,96 @@
+/**
+ * Error history with ring-buffer eviction and deduplication.
+ */
+/**
+ * Ring buffer storing recent error details per module.
+ * Supports deduplication by (code, message) within each module,
+ * per-module eviction, and global total eviction.
+ */
+export class ErrorHistory {
+    _maxEntriesPerModule;
+    _maxTotalEntries;
+    _entries = new Map();
+    constructor(maxEntriesPerModule = 50, maxTotalEntries = 1000) {
+        this._maxEntriesPerModule = maxEntriesPerModule;
+        this._maxTotalEntries = maxTotalEntries;
+    }
+    record(moduleId, error) {
+        const now = new Date().toISOString();
+        let moduleEntries = this._entries.get(moduleId);
+        if (!moduleEntries) {
+            moduleEntries = [];
+            this._entries.set(moduleId, moduleEntries);
+        }
+        const existing = moduleEntries.find((e) => e.code === error.code && e.message === error.message);
+        if (existing) {
+            existing.count++;
+            existing.lastOccurred = now;
+            return;
+        }
+        const entry = {
+            moduleId,
+            code: error.code,
+            message: error.message,
+            aiGuidance: error.aiGuidance,
+            timestamp: now,
+            count: 1,
+            firstOccurred: now,
+            lastOccurred: now,
+        };
+        moduleEntries.push(entry);
+        this._evictModule(moduleEntries);
+        this._evictTotal();
+    }
+    get(moduleId, limit) {
+        const moduleEntries = this._entries.get(moduleId) ?? [];
+        const result = [...moduleEntries].reverse();
+        return limit !== undefined ? result.slice(0, limit) : result;
+    }
+    clear() {
+        this._entries.clear();
+    }
+    clearModule(moduleId) {
+        this._entries.delete(moduleId);
+    }
+    getAll(limit) {
+        const all = [];
+        for (const entries of this._entries.values()) {
+            all.push(...entries);
+        }
+        all.sort((a, b) => (a.lastOccurred > b.lastOccurred ? -1 : 1));
+        return limit !== undefined ? all.slice(0, limit) : all;
+    }
+    _evictModule(moduleEntries) {
+        while (moduleEntries.length > this._maxEntriesPerModule) {
+            moduleEntries.shift();
+        }
+    }
+    _evictTotal() {
+        let total = 0;
+        for (const entries of this._entries.values()) {
+            total += entries.length;
+        }
+        while (total > this._maxTotalEntries) {
+            let oldestEntry = null;
+            let oldestModuleId = null;
+            for (const [mid, entries] of this._entries) {
+                if (entries.length > 0) {
+                    const candidate = entries[0];
+                    if (oldestEntry === null || candidate.lastOccurred < oldestEntry.lastOccurred) {
+                        oldestEntry = candidate;
+                        oldestModuleId = mid;
+                    }
+                }
+            }
+            if (oldestModuleId === null)
+                break;
+            const entries = this._entries.get(oldestModuleId);
+            entries.shift();
+            if (entries.length === 0) {
+                this._entries.delete(oldestModuleId);
+            }
+            total--;
+        }
+    }
+}
+//# sourceMappingURL=error-history.js.map

package/dist/observability/error-history.js.map

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

package/dist/observability/index.d.ts

@@ -2,4 +2,8 @@ export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from
 export type { Span, SpanExporter } from './tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';
+export { ErrorHistory } from './error-history.js';
+export type { ErrorEntry } from './error-history.js';
+export { UsageCollector, UsageMiddleware, bucketKey } from './usage.js';
+export type { UsageRecord, CallerUsageSummary, HourlyBucket, ModuleUsageSummary, ModuleUsageDetail } from './usage.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/F,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/F,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/observability/index.js

@@ -1,4 +1,6 @@
 export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from './tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';
+export { ErrorHistory } from './error-history.js';
+export { UsageCollector, UsageMiddleware, bucketKey } from './usage.js';
 //# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/observability/metrics-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared utilities for extracting module-level metrics from MetricsCollector snapshots.
+ */
+import type { MetricsCollector } from './metrics.js';
+export declare const METRIC_CALLS_TOTAL = "apcore_module_calls_total";
+export declare const METRIC_DURATION_SECONDS = "apcore_module_duration_seconds";
+/**
+ * Check if a metric key's labels contain an exact module_id match.
+ * Keys have the format: "metric_name|module_id=foo,status=bar"
+ * This prevents false-matching when one module ID is a suffix of another.
+ */
+export declare function matchesModuleId(key: string, moduleId: string): boolean;
+/**
+ * Compute error rate for a module from a MetricsCollector snapshot.
+ */
+export declare function computeModuleErrorRate(metricsCollector: MetricsCollector, moduleId: string): {
+    totalCalls: number;
+    errorCount: number;
+    errorRate: number;
+};
+/**
+ * Estimate p99 latency in milliseconds from histogram buckets.
+ * Returns the upper bound of the first bucket that contains ≥99% of observations.
+ * If all observations exceed the largest bucket, returns the last bucket upper bound.
+ */
+export declare function estimateP99FromHistogram(metricsCollector: MetricsCollector, moduleId: string): {
+    avgLatencyMs: number;
+    p99LatencyMs: number;
+};
+//# sourceMappingURL=metrics-utils.d.ts.map

package/dist/observability/metrics-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-utils.d.ts","sourceRoot":"","sources":["../../src/observability/metrics-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAC9D,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAMxE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGtE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,EAAE,MAAM,GACf;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAiB/D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,EAAE,MAAM,GACf;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CA8BhD"}

package/dist/observability/metrics-utils.js

@@ -0,0 +1,71 @@
+/**
+ * Shared utilities for extracting module-level metrics from MetricsCollector snapshots.
+ */
+export const METRIC_CALLS_TOTAL = 'apcore_module_calls_total';
+export const METRIC_DURATION_SECONDS = 'apcore_module_duration_seconds';
+const DEFAULT_HISTOGRAM_BUCKETS = [
+    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0,
+];
+/**
+ * Check if a metric key's labels contain an exact module_id match.
+ * Keys have the format: "metric_name|module_id=foo,status=bar"
+ * This prevents false-matching when one module ID is a suffix of another.
+ */
+export function matchesModuleId(key, moduleId) {
+    const labelMatch = `|module_id=${moduleId}`;
+    return key.includes(`${labelMatch},`) || key.endsWith(labelMatch);
+}
+/**
+ * Compute error rate for a module from a MetricsCollector snapshot.
+ */
+export function computeModuleErrorRate(metricsCollector, moduleId) {
+    const snap = metricsCollector.snapshot();
+    const counters = snap['counters'];
+    if (!counters)
+        return { totalCalls: 0, errorCount: 0, errorRate: 0 };
+    let total = 0;
+    let errors = 0;
+    const prefix = `${METRIC_CALLS_TOTAL}|`;
+    for (const [key, value] of Object.entries(counters)) {
+        if (!key.startsWith(prefix))
+            continue;
+        if (!matchesModuleId(key, moduleId))
+            continue;
+        total += value;
+        if (key.includes('status=error')) {
+            errors += value;
+        }
+    }
+    return { totalCalls: total, errorCount: errors, errorRate: total === 0 ? 0 : errors / total };
+}
+/**
+ * Estimate p99 latency in milliseconds from histogram buckets.
+ * Returns the upper bound of the first bucket that contains ≥99% of observations.
+ * If all observations exceed the largest bucket, returns the last bucket upper bound.
+ */
+export function estimateP99FromHistogram(metricsCollector, moduleId) {
+    const snap = metricsCollector.snapshot();
+    const histograms = snap['histograms'];
+    if (!histograms)
+        return { avgLatencyMs: 0, p99LatencyMs: 0 };
+    const durationKey = `${METRIC_DURATION_SECONDS}|module_id=${moduleId}`;
+    const sumVal = histograms.sums?.[durationKey] ?? 0;
+    const countVal = histograms.counts?.[durationKey] ?? 0;
+    const avgLatencyMs = countVal > 0 ? (sumVal / countVal) * 1000 : 0;
+    let p99LatencyMs = 0;
+    if (countVal > 0 && histograms.buckets) {
+        const target = countVal * 0.99;
+        for (const b of DEFAULT_HISTOGRAM_BUCKETS) {
+            const bkey = `${durationKey}|${b}`;
+            const cumCount = histograms.buckets[bkey] ?? 0;
+            if (cumCount >= target) {
+                p99LatencyMs = b * 1000;
+                return { avgLatencyMs, p99LatencyMs };
+            }
+        }
+        // All observations exceed the largest bucket
+        p99LatencyMs = DEFAULT_HISTOGRAM_BUCKETS[DEFAULT_HISTOGRAM_BUCKETS.length - 1] * 1000;
+    }
+    return { avgLatencyMs, p99LatencyMs };
+}
+//# sourceMappingURL=metrics-utils.js.map

package/dist/observability/metrics-utils.js.map

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

package/dist/observability/usage.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Time-windowed usage tracking with per-module and per-caller analytics.
+ */
+import { Middleware } from '../middleware/base.js';
+import type { Context } from '../context.js';
+export interface UsageRecord {
+    readonly timestamp: string;
+    readonly callerId: string;
+    readonly latencyMs: number;
+    readonly success: boolean;
+}
+export interface CallerUsageSummary {
+    readonly callerId: string;
+    readonly callCount: number;
+    readonly errorCount: number;
+    readonly avgLatencyMs: number;
+}
+export interface HourlyBucket {
+    readonly hour: string;
+    readonly callCount: number;
+    readonly errorCount: number;
+}
+export interface ModuleUsageSummary {
+    readonly moduleId: string;
+    readonly callCount: number;
+    readonly errorCount: number;
+    readonly avgLatencyMs: number;
+    readonly uniqueCallers: number;
+    readonly trend: string;
+}
+export interface ModuleUsageDetail extends ModuleUsageSummary {
+    readonly callers: CallerUsageSummary[];
+    readonly hourlyDistribution: HourlyBucket[];
+}
+export declare function bucketKey(date: Date): string;
+/**
+ * In-memory usage tracker with hourly buckets and configurable retention.
+ */
+export declare class UsageCollector {
+    readonly retentionHours: number;
+    private readonly _maxRecordsPerBucket;
+    private readonly _data;
+    constructor(retentionHours?: number, maxRecordsPerBucket?: number);
+    record(moduleId: string, callerId: string, latencyMs: number, success: boolean, timestamp?: string): void;
+    getSummary(period?: string): ModuleUsageSummary[];
+    getModule(moduleId: string, period?: string): ModuleUsageDetail;
+    getLatencies(moduleId: string, period?: string): number[];
+    private _collectRecords;
+    private _buildSummary;
+    private _buildDetail;
+    private _perCallerBreakdown;
+    private _hourlyDistribution;
+    private _cleanupExpired;
+}
+/**
+ * Middleware that records module call usage via UsageCollector.
+ */
+export declare class UsageMiddleware extends Middleware {
+    private readonly _collector;
+    constructor(collector: UsageCollector);
+    before(_moduleId: string, _inputs: Record<string, unknown>, context: Context): Record<string, unknown> | null;
+    after(moduleId: string, _inputs: Record<string, unknown>, _output: Record<string, unknown>, context: Context): Record<string, unknown> | null;
+    onError(moduleId: string, _inputs: Record<string, unknown>, _error: Error, context: Context): Record<string, unknown> | null;
+    private _popElapsedMs;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/observability/usage.d.ts.map

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