apcore-js 0.10.0 → 0.11.0

package/dist/sys-modules/usage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * System usage modules -- summary and single-module usage detail.
+ */
+import type { Registry } from '../registry/registry.js';
+import type { UsageCollector } from '../observability/usage.js';
+export declare class UsageSummaryModule {
+    readonly description = "All modules usage overview with trend detection";
+    readonly annotations: {
+        readonly: boolean;
+        destructive: boolean;
+        idempotent: boolean;
+        requiresApproval: boolean;
+        openWorld: boolean;
+        streaming: boolean;
+    };
+    private readonly _collector;
+    constructor(collector: UsageCollector);
+    execute(inputs: Record<string, unknown>, _context: unknown): Record<string, unknown>;
+}
+export declare class UsageModuleModule {
+    readonly description = "Detailed usage statistics for a single module";
+    readonly annotations: {
+        readonly: boolean;
+        destructive: boolean;
+        idempotent: boolean;
+        requiresApproval: boolean;
+        openWorld: boolean;
+        streaming: boolean;
+    };
+    private readonly _registry;
+    private readonly _collector;
+    constructor(registry: Registry, usageCollector: UsageCollector);
+    execute(inputs: Record<string, unknown>, _context: unknown): Record<string, unknown>;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/sys-modules/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/sys-modules/usage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAmChE,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,WAAW,qDAAqD;IACzE,QAAQ,CAAC,WAAW;;;;;;;MAAyH;IAE7I,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;gBAEhC,SAAS,EAAE,cAAc;IAIrC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAsBrF;AAED,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,WAAW,mDAAmD;IACvE,QAAQ,CAAC,WAAW;;;;;;;MAAyH;IAE7I,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;gBAEhC,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc;IAK9D,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAmCrF"}

package/dist/sys-modules/usage.js

@@ -0,0 +1,105 @@
+/**
+ * System usage modules -- summary and single-module usage detail.
+ */
+import { InvalidInputError, ModuleNotFoundError } from '../errors.js';
+import { bucketKey } from '../observability/usage.js';
+function computeP99(latencies) {
+    if (latencies.length === 0)
+        return 0;
+    const sorted = [...latencies].sort((a, b) => a - b);
+    const idx = Math.max(0, Math.ceil(0.99 * sorted.length) - 1);
+    return sorted[idx];
+}
+function padHourlyDistribution(buckets) {
+    const now = new Date();
+    const existing = new Map();
+    for (const b of buckets)
+        existing.set(b.hour, b);
+    const keys = [];
+    for (let i = 0; i < 24; i++) {
+        const d = new Date(now.getTime() - (23 - i) * 3600_000);
+        keys.push(bucketKey(d));
+    }
+    for (const k of existing.keys()) {
+        if (!keys.includes(k))
+            keys.push(k);
+    }
+    keys.sort();
+    const latest = keys.slice(-24);
+    return latest.map((k) => {
+        const b = existing.get(k);
+        return b
+            ? { hour: k, call_count: b.callCount, error_count: b.errorCount }
+            : { hour: k, call_count: 0, error_count: 0 };
+    });
+}
+export class UsageSummaryModule {
+    description = 'All modules usage overview with trend detection';
+    annotations = { readonly: true, destructive: false, idempotent: true, requiresApproval: false, openWorld: false, streaming: false };
+    _collector;
+    constructor(collector) {
+        this._collector = collector;
+    }
+    execute(inputs, _context) {
+        const period = inputs['period'] ?? '24h';
+        const summaries = this._collector.getSummary(period);
+        const sorted = [...summaries].sort((a, b) => b.callCount - a.callCount);
+        const totalCalls = sorted.reduce((s, e) => s + e.callCount, 0);
+        const totalErrors = sorted.reduce((s, e) => s + e.errorCount, 0);
+        return {
+            period,
+            total_calls: totalCalls,
+            total_errors: totalErrors,
+            modules: sorted.map((e) => ({
+                module_id: e.moduleId,
+                call_count: e.callCount,
+                error_count: e.errorCount,
+                avg_latency_ms: e.avgLatencyMs,
+                unique_callers: e.uniqueCallers,
+                trend: e.trend,
+            })),
+        };
+    }
+}
+export class UsageModuleModule {
+    description = 'Detailed usage statistics for a single module';
+    annotations = { readonly: true, destructive: false, idempotent: true, requiresApproval: false, openWorld: false, streaming: false };
+    _registry;
+    _collector;
+    constructor(registry, usageCollector) {
+        this._registry = registry;
+        this._collector = usageCollector;
+    }
+    execute(inputs, _context) {
+        const moduleId = inputs['module_id'];
+        if (typeof moduleId !== 'string' || !moduleId) {
+            throw new InvalidInputError('module_id is required');
+        }
+        if (!this._registry.has(moduleId)) {
+            throw new ModuleNotFoundError(moduleId);
+        }
+        const period = inputs['period'] ?? '24h';
+        const detail = this._collector.getModule(moduleId, period);
+        const latencies = this._collector.getLatencies(moduleId, period);
+        const p99 = computeP99(latencies);
+        const callers = detail.callers.map((c) => ({
+            caller_id: c.callerId,
+            call_count: c.callCount,
+            error_count: c.errorCount,
+            avg_latency_ms: c.avgLatencyMs,
+        }));
+        const hourly = padHourlyDistribution(detail.hourlyDistribution);
+        return {
+            module_id: detail.moduleId,
+            period,
+            call_count: detail.callCount,
+            error_count: detail.errorCount,
+            avg_latency_ms: detail.avgLatencyMs,
+            p99_latency_ms: p99,
+            trend: detail.trend,
+            callers,
+            hourly_distribution: hourly,
+        };
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/sys-modules/usage.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",