@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/usage/aggregate.js

@@ -0,0 +1,212 @@
+/**
+ * Shared, read-only reader/aggregator over the Agent turn trace archive
+ * (`data/agent-traces/*.jsonl`, ADR 0043 §6). Used by `zhin usage report` and the
+ * Console RPC `plugin.root.usage-stats`. Streams files line by line and only
+ * looks at token counts, ids, session keys and provider/model names — never
+ * message text.
+ */
+import { createReadStream } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+export const DAY_MS = 86_400_000;
+export const HOUR_MS = 3_600_000;
+export const FIXED_SEGMENTS = new Set(['system', 'tool_schemas', 'output_schema', 'tool_index', 'skill_catalog', 'agent_catalog', 'memory', 'bootstrap']);
+export function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+export function sessionMatcher(pattern) {
+    if (!pattern)
+        return () => true;
+    if (!pattern.includes('*'))
+        return key => key.includes(pattern);
+    const re = new RegExp(`^${pattern.split('*').map(part => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
+    return key => re.test(key);
+}
+/**
+ * Streams every valid trace record in range to `visit`. A missing dir yields an
+ * empty scan. A record is valid with a numeric `started_at` and a string `session_key`.
+ */
+export async function scanTraces(dir, options, visit) {
+    let names = [];
+    try {
+        names = (await readdir(dir)).filter(name => name.endsWith('.jsonl')).sort();
+    }
+    catch {
+        names = [];
+    }
+    const matches = sessionMatcher(options.session);
+    let filesRead = 0;
+    let lines = 0;
+    let malformed = 0;
+    for (const name of names) {
+        // Files are named for their day; skip those clearly outside the window (slack for time zones).
+        const stamp = /^(\d{4}-\d{2}-\d{2})/.exec(name);
+        if (stamp) {
+            const fileStart = Date.parse(`${stamp[1]}T00:00:00Z`);
+            if (options.since !== undefined && fileStart + 2 * DAY_MS <= options.since)
+                continue;
+            if (options.until !== undefined && fileStart - DAY_MS >= options.until)
+                continue;
+        }
+        filesRead++;
+        const reader = createInterface({ input: createReadStream(join(dir, name), { encoding: 'utf8' }), crlfDelay: Infinity });
+        for await (const line of reader) {
+            if (line.trim() === '')
+                continue;
+            lines++;
+            let trace;
+            try {
+                trace = JSON.parse(line);
+            }
+            catch {
+                malformed++;
+                continue;
+            }
+            const startedAt = num(trace?.started_at);
+            if (!trace || typeof trace !== 'object' || startedAt === undefined || typeof trace.session_key !== 'string') {
+                malformed++;
+                continue;
+            }
+            if (options.since !== undefined && startedAt < options.since)
+                continue;
+            if (options.until !== undefined && startedAt >= options.until)
+                continue;
+            if (!matches(trace.session_key))
+                continue;
+            visit(trace, startedAt);
+        }
+    }
+    return { files: names.length, filesRead, lines, malformed };
+}
+export const USAGE_STATS_SESSION_LIMIT = 50;
+/** Start of the local hour/day containing `ms`. */
+export function bucketStartOf(ms, bucket) {
+    const d = new Date(ms);
+    return bucket === 'day'
+        ? new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+        : new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours()).getTime();
+}
+function nextBucket(start, bucket) {
+    const d = new Date(start);
+    return bucket === 'day'
+        ? new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime()
+        : start + HOUR_MS;
+}
+/** `platform:endpoint:scope:sceneId`; other shapes keep whatever parts they have. */
+export function parseSessionKey(key) {
+    const parts = key.split(':');
+    if (parts.length >= 4)
+        return { platform: parts[0], scope: parts[2], sceneId: parts.slice(3).join(':') };
+    if (parts.length === 3)
+        return { platform: parts[0], scope: parts[1], sceneId: parts[2] };
+    return parts[0] ? { platform: parts[0] } : {};
+}
+const tally = () => ({ calls: 0, input: 0, output: 0, cache: 0, cacheWrite: 0 });
+function tokens(t) {
+    return {
+        calls: t.calls,
+        inputTokens: t.input,
+        outputTokens: t.output,
+        cacheReadTokens: t.cache,
+        cacheWriteTokens: t.cacheWrite,
+        cacheShare: t.input > 0 ? Math.min(1, t.cache / t.input) : 0,
+    };
+}
+function nearestRank(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1))];
+}
+export async function buildUsageStats(dir, query) {
+    const { since, until, bucket } = query;
+    const total = tally();
+    let turns = 0;
+    const callShares = [];
+    const segments = { history: 0, fixed: 0, user: 0 };
+    const models = new Map();
+    const sessions = new Map();
+    const buckets = new Map();
+    for (let t = bucketStartOf(since, bucket); t < until; t = nextBucket(t, bucket)) {
+        buckets.set(t, { ...tally(), byModel: {} });
+    }
+    const scan = await scanTraces(dir, { since, until, session: query.session }, (trace, startedAt) => {
+        turns++;
+        const session = sessions.get(trace.session_key) ?? { ...tally(), turns: 0 };
+        session.turns++;
+        sessions.set(trace.session_key, session);
+        const calls = Array.isArray(trace.model_calls) ? trace.model_calls : [];
+        for (const raw of calls) {
+            const call = raw;
+            const prompt = num(call?.prompt_tokens);
+            if (prompt === undefined)
+                continue;
+            const output = num(call?.completion_tokens) ?? 0;
+            const cache = num(call?.cache_read_tokens) ?? 0;
+            const cacheWrite = num(call?.cache_write_tokens) ?? 0;
+            if (prompt > 0)
+                callShares.push(Math.min(1, cache / prompt));
+            const provider = typeof call?.provider === 'string' && call.provider ? call.provider : 'unknown';
+            const model = typeof call?.model === 'string' && call.model ? call.model : 'unknown';
+            const at = num(call?.started_at) ?? num(call?.at) ?? startedAt;
+            for (const t of [total, session]) {
+                t.calls++;
+                t.input += prompt;
+                t.output += output;
+                t.cache += cache;
+                t.cacheWrite += cacheWrite;
+            }
+            const modelKey = `${provider}/${model}`;
+            const m = models.get(modelKey) ?? { ...tally(), provider, model };
+            m.calls++;
+            m.input += prompt;
+            m.output += output;
+            m.cache += cache;
+            m.cacheWrite += cacheWrite;
+            models.set(modelKey, m);
+            const slot = buckets.get(bucketStartOf(at, bucket)) ?? buckets.get(bucketStartOf(startedAt, bucket));
+            if (slot) {
+                slot.calls++;
+                slot.input += prompt;
+                slot.output += output;
+                slot.cache += cache;
+                slot.cacheWrite += cacheWrite;
+                slot.byModel[modelKey] = (slot.byModel[modelKey] ?? 0) + prompt;
+            }
+        }
+        const budget = trace.context_budget?.segments;
+        if (budget && typeof budget === 'object') {
+            for (const [key, value] of Object.entries(budget)) {
+                const n = num(value) ?? 0;
+                if (key === 'history')
+                    segments.history += n;
+                else if (key === 'user')
+                    segments.user += n;
+                else if (FIXED_SEGMENTS.has(key))
+                    segments.fixed += n;
+            }
+        }
+    });
+    callShares.sort((a, b) => a - b);
+    return {
+        range: { since, until, bucket, timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone },
+        totals: {
+            turns,
+            ...tokens(total),
+            cacheShareByCall: { p50: nearestRank(callShares, 50), p90: nearestRank(callShares, 90) },
+        },
+        byModel: [...models.values()]
+            .map(m => ({ provider: m.provider, model: m.model, ...tokens(m) }))
+            .sort((a, b) => b.inputTokens - a.inputTokens),
+        bySession: [...sessions.entries()]
+            .map(([sessionKey, s]) => ({ sessionKey, ...parseSessionKey(sessionKey), turns: s.turns, ...tokens(s) }))
+            .sort((a, b) => b.inputTokens - a.inputTokens)
+            .slice(0, USAGE_STATS_SESSION_LIMIT),
+        series: [...buckets.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([bucketStart, b]) => ({ bucketStart, ...tokens(b), byModel: b.byModel })),
+        segments,
+        filesRead: scan.filesRead,
+        malformedLines: scan.malformed,
+    };
+}

package/lib/usage.d.ts

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/usage` — usage statistics aggregation. */
+export * from './usage/aggregate.js';

package/lib/usage.js

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/usage` — usage statistics aggregation. */
+export * from './usage/aggregate.js';

package/package.json

@@ -1,6 +1,119 @@
 {
   "name": "@zhin.js/gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.1",
+  "description": "Zhin.js management gateway: Console access control, terminal, project configuration and instance supervision (ADR 0054)",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./iam": {
+      "types": "./lib/iam.d.ts",
+      "import": "./lib/iam.js"
+    },
+    "./terminal": {
+      "types": "./lib/terminal.d.ts",
+      "import": "./lib/terminal.js"
+    },
+    "./config": {
+      "types": "./lib/config.d.ts",
+      "import": "./lib/config.js"
+    },
+    "./plugin-management": {
+      "types": "./lib/plugin-management.d.ts",
+      "import": "./lib/plugin-management.js"
+    },
+    "./project": {
+      "types": "./lib/project.d.ts",
+      "import": "./lib/project.js"
+    },
+    "./supervisor": {
+      "types": "./lib/supervisor.d.ts",
+      "import": "./lib/supervisor.js"
+    },
+    "./usage": {
+      "types": "./lib/usage.d.ts",
+      "import": "./lib/usage.js"
+    },
+    "./onboarding": {
+      "types": "./lib/onboarding.d.ts",
+      "import": "./lib/onboarding.js"
+    },
+    "./http": {
+      "types": "./lib/http.d.ts",
+      "import": "./lib/http.js"
+    },
+    "./packages": {
+      "types": "./lib/packages.d.ts",
+      "import": "./lib/packages.js"
+    },
+    "./server": {
+      "types": "./lib/server.d.ts",
+      "import": "./lib/server.js"
+    },
+    "./database": {
+      "types": "./lib/database.d.ts",
+      "import": "./lib/database.js"
+    },
+    "./local": {
+      "types": "./lib/local.d.ts",
+      "import": "./lib/local.js"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "fs-extra": "^11.4.0",
+    "tsx": "^4.23.1",
+    "yaml": "^2.9.0",
+    "@zhin.js/console-protocol": "1.2.0",
+    "@zhin.js/database": "1.1.8",
+    "@zhin.js/host-http": "1.2.0",
+    "@zhin.js/logger": "1.1.3",
+    "@zhin.js/plugin-runtime": "1.2.0",
+    "@zhin.js/runtime": "1.2.0",
+    "@zhin.js/scaffold-wizard": "1.1.19"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.0.0",
+    "ssh2": "^1.16.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^26.1.2",
+    "@types/ssh2": "^1.15.5",
+    "@types/ws": "^8.18.1",
+    "typescript": "^6.0.3",
+    "ws": "^8.21.1"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/host/gateway"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "zhin",
+    "gateway",
+    "console",
+    "rbac"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/host/gateway/tests"
+  }
 }