@adecore/agents 0.0.1 → 0.17.0-beta.2

package/dist/usage/scanner.js

@@ -0,0 +1,234 @@
+import { mkdir, open, readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isNotFound, writeAtomic } from '../fs.js';
+import { decodeIndex, encodeIndex } from './index-file.js';
+import { foldByKey } from './record.js';
+import { claudeMightCarryUsage, parseClaudeLine } from './readers/claude.js';
+import { cloneCodexState, codexMightCarryUsage, createCodexState, parseCodexLine } from './readers/codex.js';
+import { usageRoots } from './roots.js';
+import { errorText } from '../error-text.js';
+/* What a file holds from `from` to its end, as it is at the read. */
+async function readFrom(path, from) {
+    const handle = await open(path, 'r');
+    try {
+        const { size } = await handle.stat();
+        const buffer = Buffer.alloc(Math.max(0, size - from));
+        let filled = 0;
+        while (filled < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, from + filled);
+            if (bytesRead === 0) {
+                break;
+            }
+            filled += bytesRead;
+        }
+        return buffer.subarray(0, filled).toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function listJsonl(dir, out = []) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        // A directory that cannot be read is one the scan walks past; the root itself reports status.
+        return out;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await listJsonl(path, out);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+            out.push(path);
+        }
+    }
+    return out;
+}
+/*
+ * Reads what a file added since the last scan. Only whole lines count towards the offset; the piece
+ * after the last newline is a line still being written, so it is parsed for what it is worth and
+ * read again next time. The Codex state is snapshotted before that tail for the same reason.
+ */
+function parseChunk(text, provider, from, state) {
+    let records = [];
+    const end = text.lastIndexOf('\n');
+    const whole = end === -1 ? '' : text.slice(0, end);
+    const tail = text.slice(end + 1);
+    const read = (chunk, codex) => {
+        for (const raw of chunk.split('\n')) {
+            const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+            if (line === '') {
+                continue;
+            }
+            if (provider === 'claude') {
+                if (claudeMightCarryUsage(line)) {
+                    const record = parseClaudeLine(line);
+                    if (record !== null) {
+                        records.push(record);
+                    }
+                }
+                continue;
+            }
+            if (codex !== null && codexMightCarryUsage(line)) {
+                const record = parseCodexLine(line, codex);
+                if (record !== null) {
+                    records.push(record);
+                }
+            }
+        }
+    };
+    const codex = provider === 'codex' ? (state ?? createCodexState()) : null;
+    read(whole, codex);
+    const committed = codex === null ? null : cloneCodexState(codex);
+    const counted = records;
+    records = [];
+    read(tail, codex);
+    return { records: counted, tail: records, offset: from + (end === -1 ? 0 : Buffer.byteLength(whole, 'utf8') + 1), codex: committed };
+}
+/*
+ * The account a record of a root belongs to, as a record keeps it (absent for the default account):
+ * the one account that writes there, else the one the host knows ran the session, else the
+ * default account of the CLI, which is the only one a session nobody started through the host ran under.
+ */
+export function accountResolver(root, sessionAccounts) {
+    const accounts = root.accounts ?? [root.provider];
+    const stored = (id) => (id === root.provider ? undefined : id);
+    if (accounts.length === 1) {
+        const only = stored(accounts[0]);
+        return () => only;
+    }
+    const fallback = accounts.includes(root.provider) ? root.provider : accounts[0];
+    return (record) => {
+        const ran = sessionAccounts().get(`${root.provider}\0${record.sessionId}`);
+        return stored(ran !== undefined && accounts.includes(ran) ? ran : fallback);
+    };
+}
+function withAccount(records, accountOf) {
+    return records.map((record) => {
+        const account = accountOf(record);
+        return account === undefined ? record : { ...record, account };
+    });
+}
+/*
+ * Read appended transcript bytes incrementally, but restart after rewrites or truncation. Preserve
+ * totals for deleted transcripts because their usage still happened.
+ */
+export class UsageScanner {
+    home;
+    roots;
+    sessionAccounts;
+    index = new Map();
+    loaded = false;
+    dirty = false;
+    /* `roots` as a function is asked again on every scan, so an account added since is walked too. */
+    constructor(home, roots = usageRoots(), options = {}) {
+        this.home = home;
+        this.roots = typeof roots === 'function' ? roots : () => roots;
+        this.sessionAccounts = options.sessionAccounts ?? (() => new Map());
+    }
+    get file() {
+        return join(this.home, 'usage', 'index.json');
+    }
+    async load() {
+        if (this.loaded) {
+            return;
+        }
+        this.loaded = true;
+        try {
+            this.index = decodeIndex(await readFile(this.file, 'utf8'));
+        }
+        catch (e) {
+            if (!isNotFound(e)) {
+                console.warn('The usage index would not read; starting from a cold scan:', errorText(e));
+            }
+        }
+    }
+    async scan() {
+        const started = Date.now();
+        await this.load();
+        const roots = [];
+        let files = 0;
+        let changedFiles = 0;
+        let sessions = null;
+        const sessionAccounts = () => {
+            sessions ??= this.sessionAccounts();
+            return sessions;
+        };
+        for (const root of this.roots()) {
+            try {
+                const info = await stat(root.path);
+                if (!info.isDirectory()) {
+                    roots.push({ provider: root.provider, path: root.path, status: 'missing', message: null });
+                    continue;
+                }
+            }
+            catch (e) {
+                const missing = isNotFound(e);
+                roots.push({
+                    provider: root.provider,
+                    path: root.path,
+                    status: missing ? 'missing' : 'failed',
+                    message: missing ? null : errorText(e)
+                });
+                continue;
+            }
+            let failure = null;
+            const accountOf = accountResolver(root, sessionAccounts);
+            for (const path of await listJsonl(root.path)) {
+                files += 1;
+                try {
+                    if (await this.readFileInto(path, root.provider, accountOf)) {
+                        changedFiles += 1;
+                    }
+                }
+                catch (e) {
+                    // One unreadable transcript is not the root failing; the count simply misses it.
+                    failure ??= errorText(e);
+                }
+            }
+            roots.push({ provider: root.provider, path: root.path, status: failure === null ? 'ok' : 'failed', message: failure });
+        }
+        if (this.dirty) {
+            this.dirty = false;
+            await mkdir(join(this.home, 'usage'), { recursive: true, mode: 0o700 });
+            await writeAtomic(this.file, encodeIndex(this.index));
+        }
+        return { at: Date.now(), files, changedFiles, durationMs: Date.now() - started, roots };
+    }
+    /* Every record the index holds, with the copies one message left in several transcripts folded. */
+    records() {
+        const all = [];
+        for (const file of this.index.values()) {
+            all.push(...file.records, ...file.tail);
+        }
+        return foldByKey(all);
+    }
+    async readFileInto(path, provider, accountOf) {
+        const info = await stat(path);
+        const known = this.index.get(path);
+        if (known !== undefined && known.provider === provider && known.size === info.size && known.mtimeMs === info.mtimeMs) {
+            return false;
+        }
+        const grown = known !== undefined && known.provider === provider && info.size > known.size;
+        const from = grown ? known.offset : 0;
+        const text = await readFrom(path, from);
+        const parsed = parseChunk(text, provider, from, grown ? known.codex : null);
+        const before = grown ? known.records : [];
+        const entry = {
+            provider,
+            size: info.size,
+            mtimeMs: info.mtimeMs,
+            offset: parsed.offset,
+            // Folding here keeps the streaming copies of one message out of the index entirely.
+            records: foldByKey([...before, ...withAccount(parsed.records, accountOf)]),
+            tail: withAccount(parsed.tail, accountOf),
+            codex: parsed.codex
+        };
+        this.index.set(path, entry);
+        this.dirty = true;
+        return true;
+    }
+}

package/dist/usage/usage-service.d.ts

@@ -0,0 +1,35 @@
+import type { UsageAccount, UsageSummaryPayload, UsageSummaryResult } from '@adecore/agent-contracts';
+import type { AgentSink } from '../events.ts';
+import type { KnownProject } from './projects.ts';
+import { type UsageScannerOptions } from './scanner.ts';
+import type { UsageRootPath } from './roots.ts';
+export interface UsageServiceOptions {
+    home: string;
+    allowPriceFetch?: boolean;
+    knownProjects(): Promise<KnownProject[]>;
+    roots?: UsageRootPath[] | (() => UsageRootPath[]);
+    sessionAccounts?: UsageScannerOptions['sessionAccounts'];
+    accounts?: () => UsageAccount[];
+}
+export declare class UsageService {
+    private readonly scanner;
+    private readonly prices;
+    private readonly rates;
+    private readonly knownProjects;
+    private readonly accounts;
+    private readonly sinks;
+    private readonly followers;
+    private report;
+    private failed;
+    private inFlight;
+    private timer;
+    constructor(options: UsageServiceOptions);
+    subscribe(clientId: string, sink: AgentSink): () => void;
+    follow(clientId: string): void;
+    unfollow(clientId: string): void;
+    summary(payload: UsageSummaryPayload): Promise<UsageSummaryResult>;
+    stop(): void;
+    private rescan;
+    private runScan;
+    private emit;
+}

package/dist/usage/usage-service.js

@@ -0,0 +1,130 @@
+import { accountOfRecord, aggregate } from './aggregate.js';
+import { ExchangeRates } from './exchange.js';
+import { PriceBook } from './pricing.js';
+import { UsageScanner } from './scanner.js';
+import { errorText } from '../error-text.js';
+import { ClientSinks } from '../client-sinks.js';
+/* A scan this fresh answers the question the page is asking, so nothing is opened for it. */
+const SCAN_TTL_MS = 60_000;
+/* The accounts of the machine, and after them any a record names that the machine no longer has, under its id. */
+function withRecordAccounts(accounts, records) {
+    const listed = new Set(accounts.map((account) => account.id));
+    const gone = [];
+    for (const record of records) {
+        const id = accountOfRecord(record);
+        if (!listed.has(id)) {
+            listed.add(id);
+            gone.push({ id, kind: record.provider, label: id });
+        }
+    }
+    return [...accounts, ...gone];
+}
+const EMPTY_SCAN = { at: 0, files: 0, changedFiles: 0, durationMs: 0, roots: [] };
+/*
+ * What the usage page asks the host. It owns one scanner and one price table for every client:
+ * the transcripts are machine-wide, so a second person looking costs a second aggregation and not a
+ * second scan. The scan runs when a request finds the last one stale and, while any client has the
+ * page open, once a minute, which is what `usage.changed` announces.
+ */
+export class UsageService {
+    scanner;
+    prices;
+    rates;
+    knownProjects;
+    accounts;
+    sinks = new ClientSinks((clientId) => this.unfollow(clientId));
+    followers = new Set();
+    report = EMPTY_SCAN;
+    failed = false;
+    inFlight = null;
+    timer = null;
+    constructor(options) {
+        this.scanner = new UsageScanner(options.home, options.roots, options.sessionAccounts ? { sessionAccounts: options.sessionAccounts } : {});
+        this.accounts = options.accounts ?? null;
+        this.prices = new PriceBook(options.home, options.allowPriceFetch ?? true);
+        this.rates = new ExchangeRates(options.home, options.allowPriceFetch ?? true);
+        this.knownProjects = options.knownProjects;
+    }
+    subscribe(clientId, sink) {
+        return this.sinks.subscribe(clientId, sink);
+    }
+    /* The page is open here: keep the numbers moving until it closes or the socket does. */
+    follow(clientId) {
+        this.followers.add(clientId);
+        this.timer ??= setInterval(() => {
+            void this.rescan();
+        }, SCAN_TTL_MS);
+    }
+    unfollow(clientId) {
+        this.followers.delete(clientId);
+        if (this.followers.size === 0 && this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    async summary(payload) {
+        if (Date.now() - this.report.at > SCAN_TTL_MS) {
+            await this.rescan();
+        }
+        const records = this.scanner.records();
+        const { buckets, models, projects, sessions } = await aggregate(records, payload, this.prices, await this.knownProjects());
+        return {
+            from: payload.from,
+            to: payload.to,
+            resolution: payload.resolution,
+            timeZone: payload.timeZone,
+            buckets,
+            models,
+            projects,
+            sessions,
+            scan: {
+                at: this.report.at,
+                files: this.report.files,
+                changedFiles: this.report.changedFiles,
+                durationMs: this.report.durationMs,
+                running: this.inFlight !== null,
+                failed: this.failed
+            },
+            pricing: this.prices.pricing,
+            rate: this.rates.current,
+            roots: this.report.roots,
+            ...(this.accounts === null ? {} : { accounts: withRecordAccounts(this.accounts(), records) })
+        };
+    }
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /* One pass at a time: a request that arrives while a pass runs waits for that one's answer. */
+    rescan() {
+        this.inFlight ??= this.runScan().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async runScan() {
+        // The table and the rate are fetched beside the walk, so a slow answer never holds up the scan.
+        const [report] = await Promise.all([
+            this.scanner.scan().catch((e) => {
+                console.error('The usage scan failed:', errorText(e));
+                return null;
+            }),
+            this.prices.ensure(),
+            this.rates.ensure()
+        ]);
+        this.failed = report === null;
+        if (report === null) {
+            // The last good numbers stay on screen; only the moment of the scan is not moved on.
+            return;
+        }
+        this.report = report;
+        if (report.changedFiles > 0) {
+            this.emit({ event: 'usage.changed', payload: { scannedAt: report.at } });
+        }
+    }
+    emit(event) {
+        this.sinks.emit(event);
+    }
+}

package/dist/watch-seam.d.ts

@@ -0,0 +1,29 @@
+export interface DirectoryWatcher {
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    close(): void;
+}
+export type WatchDirectory = (path: string, options: {
+    recursive: boolean;
+}, listener: (event: string, filename: string | null) => void) => DirectoryWatcher;
+export type Schedule = (callback: () => unknown, ms: number) => () => void;
+export interface WatchSeams {
+    watch: WatchDirectory;
+    schedule: Schedule;
+}
+export declare function supportsRecursive(platform: NodeJS.Platform): boolean;
+export declare const SYSTEM_WATCH: WatchSeams;
+export interface Settled {
+    nudge(): void;
+    stop(): void;
+}
+export declare function settled(seams: WatchSeams, ms: number, run: () => unknown): Settled;
+export declare class PerClientWatches<TState> {
+    private readonly byClient;
+    private readonly stop;
+    constructor(stop: (state: TState) => void);
+    get(clientId: string, key: string): TState | undefined;
+    put(clientId: string, key: string, state: TState): void;
+    all(clientId: string): Array<[string, TState]>;
+    remove(clientId: string, key: string): void;
+    detachAll(clientId: string): void;
+}

package/dist/watch-seam.js

@@ -0,0 +1,78 @@
+import { watch } from 'node:fs';
+/*
+ * Recursive watching is one call to the platform on macOS and Windows; elsewhere it costs a
+ * descriptor per directory, which a folder tree has too many of to be worth it.
+ */
+export function supportsRecursive(platform) {
+    return platform === 'darwin' || platform === 'win32';
+}
+export const SYSTEM_WATCH = {
+    watch: (path, options, listener) => watch(path, options, listener),
+    schedule: (callback, ms) => {
+        const timer = setTimeout(callback, ms);
+        return () => clearTimeout(timer);
+    }
+};
+/*
+ * A save, a formatter and a build all touch a folder in a burst, and one answer per burst is enough.
+ * How long a burst is differs per watcher: reading one file again is cheap, a status run over a
+ * whole repository is not.
+ */
+export function settled(seams, ms, run) {
+    let cancel = null;
+    return {
+        nudge: () => {
+            cancel?.();
+            cancel = seams.schedule(() => {
+                cancel = null;
+                return run();
+            }, ms);
+        },
+        stop: () => {
+            cancel?.();
+            cancel = null;
+        }
+    };
+}
+/*
+ * What each client watches, keyed on the path it asked for. A watch is per client, like a session
+ * attach: two windows on the same folder each get their own, and a socket that goes takes only its
+ * own with it.
+ */
+export class PerClientWatches {
+    byClient = new Map();
+    stop;
+    constructor(stop) {
+        this.stop = stop;
+    }
+    get(clientId, key) {
+        return this.byClient.get(clientId)?.get(key);
+    }
+    put(clientId, key, state) {
+        const watches = this.byClient.get(clientId) ?? new Map();
+        watches.set(key, state);
+        this.byClient.set(clientId, watches);
+    }
+    /* Everything this client watches, as a copy, so a caller may close one while it walks them. */
+    all(clientId) {
+        return [...(this.byClient.get(clientId) ?? [])];
+    }
+    remove(clientId, key) {
+        const watches = this.byClient.get(clientId);
+        const state = watches?.get(key);
+        if (!watches || state === undefined) {
+            return;
+        }
+        this.stop(state);
+        watches.delete(key);
+        if (watches.size === 0) {
+            this.byClient.delete(clientId);
+        }
+    }
+    detachAll(clientId) {
+        for (const state of this.byClient.get(clientId)?.values() ?? []) {
+            this.stop(state);
+        }
+        this.byClient.delete(clientId);
+    }
+}

package/dist/watch-test-helpers.d.ts

@@ -0,0 +1,28 @@
+import type { DirectoryWatcher, WatchDirectory, WatchSeams } from './watch-seam.ts';
+export declare class FakeDirectoryWatcher implements DirectoryWatcher {
+    readonly path: string;
+    readonly recursive: boolean;
+    closed: boolean;
+    private readonly listener;
+    constructor(path: string, recursive: boolean, listener: (event: string, filename: string | null) => void);
+    emit(filename: string | null, event?: 'change' | 'rename'): void;
+    on(): this;
+    close(): void;
+}
+export declare class FakeWatch implements WatchSeams {
+    readonly watchers: FakeDirectoryWatcher[];
+    private readonly due;
+    private nextId;
+    readonly watch: WatchDirectory;
+    readonly schedule: (callback: () => unknown, _ms: number) => (() => void);
+    get pending(): number;
+    openOn(path: string): FakeDirectoryWatcher[];
+    on(path: string): FakeDirectoryWatcher;
+    settle(): Promise<void>;
+}
+export declare class EventLog<T> {
+    readonly events: T[];
+    private waiters;
+    readonly push: (event: T) => void;
+    until(check: (events: T[]) => boolean): Promise<void>;
+}

package/dist/watch-test-helpers.js

@@ -0,0 +1,86 @@
+export class FakeDirectoryWatcher {
+    path;
+    recursive;
+    closed = false;
+    listener;
+    constructor(path, recursive, listener) {
+        this.path = path;
+        this.recursive = recursive;
+        this.listener = listener;
+    }
+    /* What the platform would report for a write to `filename`, relative to the watched directory. */
+    emit(filename, event = 'change') {
+        if (this.closed) {
+            return;
+        }
+        this.listener(event, filename);
+    }
+    on() {
+        return this;
+    }
+    close() {
+        this.closed = true;
+    }
+}
+/*
+ * A watch function and a settle timer that only move when a test says so: `emit` on a watcher stands
+ * in for the platform, and `settle` runs every timer that is due and waits for the work it started.
+ */
+export class FakeWatch {
+    watchers = [];
+    due = new Map();
+    nextId = 1;
+    watch = (path, options, listener) => {
+        const watcher = new FakeDirectoryWatcher(path, options.recursive, listener);
+        this.watchers.push(watcher);
+        return watcher;
+    };
+    schedule = (callback, _ms) => {
+        const id = this.nextId++;
+        this.due.set(id, callback);
+        return () => {
+            this.due.delete(id);
+        };
+    };
+    /* How many timers are waiting to run. */
+    get pending() {
+        return this.due.size;
+    }
+    openOn(path) {
+        return this.watchers.filter((watcher) => watcher.path === path && !watcher.closed);
+    }
+    /* The one open watcher on `path`, which a test that emits on it expects to exist. */
+    on(path) {
+        const [watcher, ...rest] = this.openOn(path);
+        if (!watcher || rest.length > 0) {
+            throw new Error(`Expected one open watcher on ${path}, found ${rest.length + (watcher ? 1 : 0)}`);
+        }
+        return watcher;
+    }
+    async settle() {
+        const callbacks = [...this.due.values()];
+        this.due.clear();
+        await Promise.all(callbacks.map((callback) => callback()));
+    }
+}
+/* A sink's events, with a promise for the moment one of them passes a check, so a test awaits the event itself rather than a deadline. */
+export class EventLog {
+    events = [];
+    waiters = [];
+    push = (event) => {
+        this.events.push(event);
+        const ready = this.waiters.filter((waiter) => waiter.check(this.events));
+        this.waiters = this.waiters.filter((waiter) => !ready.includes(waiter));
+        for (const waiter of ready) {
+            waiter.resolve();
+        }
+    };
+    until(check) {
+        if (check(this.events)) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push({ check, resolve });
+        });
+    }
+}

package/package.json

@@ -1,11 +1,50 @@
 {
   "name": "@adecore/agents",
-  "version": "0.0.1",
-  "description": "Placeholder for the first release.",
+  "version": "0.17.0-beta.2",
+  "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
+  "type": "module",
+  "exports": {
+    "./*.json": {
+      "source": "./src/*.json",
+      "default": "./dist/*.json"
+    },
+    "./*": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "bun scripts/build.ts",
+    "test": "bun --conditions=source test"
+  },
+  "dependencies": {
+    "@adecore/agent-contracts": "0.17.0-beta.2",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2",
+    "@types/node": "^26.6.3"
+  },
   "license": "FSL-1.1-MIT",
+  "author": "Bas Milius",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/basmilius/adecore.git",
     "directory": "packages/agents"
-  }
+  },
+  "bugs": {
+    "url": "https://github.com/basmilius/adecore/issues"
+  },
+  "homepage": "https://adecore.dev/agents/",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__snapshots__"
+  ],
+  "sideEffects": false
 }