@adecore/agents 0.23.0 → 0.24.0

package/dist/usage/exchange.js

@@ -26,7 +26,7 @@ export class ExchangeRates {
     home;
     allowFetch;
     rate = null;
-    loadedFromDisk = false;
+    stored = null;
     inFlight = null;
     constructor(home, allowFetch = true) {
         this.home = home;
@@ -35,9 +35,16 @@ export class ExchangeRates {
     get current() {
         return this.rate;
     }
-    /* Refreshes at most one rate at a time; a second caller waits for the first one's answer. */
+    /* Reads the rate an earlier run stored, once; asking for a new one is left to `ensure`. */
+    load() {
+        this.stored ??= this.readStored();
+        return this.stored;
+    }
+    /* Refreshes at most one rate at a time, a second caller waiting for the first one's answer; true when a newer rate came in. */
     ensure() {
-        this.inFlight ??= this.refresh().finally(() => {
+        this.inFlight ??= this.load()
+            .then(() => this.fetchFresh())
+            .finally(() => {
             this.inFlight = null;
         });
         return this.inFlight;
@@ -45,24 +52,24 @@ export class ExchangeRates {
     get file() {
         return join(this.home, 'usage', 'exchange-rate.json');
     }
-    async refresh() {
-        if (!this.loadedFromDisk) {
-            this.loadedFromDisk = true;
-            try {
-                const stored = JSON.parse(await readFile(this.file, 'utf8'));
-                if (stored?.currency === TARGET_CURRENCY && typeof stored.rate === 'number' && stored.rate > 0) {
-                    this.rate = stored;
-                }
+    async readStored() {
+        try {
+            const stored = JSON.parse(await readFile(this.file, 'utf8'));
+            if (stored?.currency === TARGET_CURRENCY && typeof stored.rate === 'number' && stored.rate > 0) {
+                this.rate = stored;
             }
-            catch (e) {
-                if (!isNotFound(e)) {
-                    console.warn('The stored exchange rate would not read; asking for a new one:', errorText(e));
-                }
+        }
+        catch (e) {
+            if (!isNotFound(e)) {
+                console.warn('The stored exchange rate would not read; asking for a new one:', errorText(e));
             }
         }
+    }
+    async fetchFresh() {
         if (!this.allowFetch || (this.rate !== null && Date.now() - this.rate.fetchedAt < TTL_MS)) {
-            return;
+            return false;
         }
+        let changed = false;
         try {
             const response = await fetch(`${FRANKFURTER_URL}?from=USD&to=${TARGET_CURRENCY}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
             if (!response.ok) {
@@ -73,6 +80,7 @@ export class ExchangeRates {
                 throw new Error(`The answer carried no ${TARGET_CURRENCY} rate`);
             }
             this.rate = { ...parsed, fetchedAt: Date.now() };
+            changed = true;
             await mkdir(join(this.home, 'usage'), { recursive: true, mode: 0o700 });
             await writeAtomic(this.file, JSON.stringify(this.rate));
         }
@@ -80,5 +88,6 @@ export class ExchangeRates {
             // Yesterday's rate still converts; a rate that could not be refreshed is not a failure.
             console.warn('Could not refresh the exchange rate:', errorText(e));
         }
+        return changed;
     }
 }

package/dist/usage/index-file.d.ts

@@ -9,6 +9,7 @@ export interface IndexedFile {
     records: UsageRecord[];
     tail: UsageRecord[];
     codex: CodexParserState | null;
+    head: string | null;
 }
 export type UsageIndex = Map<string, IndexedFile>;
 export declare function encodeIndex(index: UsageIndex): string;

package/dist/usage/index-file.js

@@ -38,7 +38,16 @@ export function encodeIndex(index) {
         record.account === undefined ? 0 : accounts.index(record.account) + 1
     ];
     for (const [path, file] of index) {
-        files[path] = { p: file.provider, s: file.size, m: file.mtimeMs, o: file.offset, c: file.codex, r: file.records.map(row), t: file.tail.map(row) };
+        files[path] = {
+            p: file.provider,
+            s: file.size,
+            m: file.mtimeMs,
+            o: file.offset,
+            c: file.codex,
+            r: file.records.map(row),
+            t: file.tail.map(row),
+            ...(file.head === null ? {} : { h: file.head })
+        };
     }
     const document = {
         version: INDEX_VERSION,
@@ -116,7 +125,16 @@ export function decodeIndex(text) {
         const records = decode(file.r);
         const tail = decode(Array.isArray(file.t) ? file.t : []);
         if (!broken) {
-            index.set(path, { provider: file.p, size: file.s, mtimeMs: file.m, offset: file.o, records, tail, codex: file.c ?? null });
+            index.set(path, {
+                provider: file.p,
+                size: file.s,
+                mtimeMs: file.m,
+                offset: file.o,
+                records,
+                tail,
+                codex: file.c ?? null,
+                head: typeof file.h === 'string' ? file.h : null
+            });
         }
     }
     return index;

package/dist/usage/index.d.ts

@@ -0,0 +1,9 @@
+export { usageAccountsOf, usageRootsOf, limitAccountsOf, chatSessionAccounts } from './accounts.ts';
+export { UsageMonitor, type ProbeEnv, type LimitAccount, type LimitAccounts, type UsageMonitorOptions } from './limits/monitor.ts';
+export type { LimitsUpdate, ProviderReading } from './limits/normalize.ts';
+export type { ProbeResult } from './limits/probe.ts';
+export { LITELLM_URL } from './pricing.ts';
+export type { KnownProject } from './projects.ts';
+export { type UsageRootPath, usageRoots } from './roots.ts';
+export type { UsageScannerOptions } from './scanner.ts';
+export { UsageService, type UsageServiceOptions } from './usage-service.ts';

package/dist/usage/index.js

@@ -0,0 +1,6 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { usageAccountsOf, usageRootsOf, limitAccountsOf, chatSessionAccounts } from './accounts.js';
+export { UsageMonitor } from './limits/monitor.js';
+export { LITELLM_URL } from './pricing.js';
+export { usageRoots } from './roots.js';
+export { UsageService } from './usage-service.js';

package/dist/usage/limits/normalize.js

@@ -1,10 +1,8 @@
+import { isRecord } from '@adecore/agent-contracts';
 const MINUTE_MS = 60_000;
 const FIVE_HOURS_MS = 5 * 60 * MINUTE_MS;
 const WEEK_MS = 7 * 24 * 60 * MINUTE_MS;
 const MONTH_MS = 30 * 24 * 60 * MINUTE_MS;
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function num(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }

package/dist/usage/pricing.d.ts

@@ -23,12 +23,14 @@ export declare class PriceBook {
     private table;
     private source;
     private fetchedAt;
-    private loadedFromDisk;
+    private stored;
     private inFlight;
     constructor(home: string, allowFetch?: boolean);
     get pricing(): UsagePricing;
     look(model: string): PriceLookup;
-    ensure(): Promise<void>;
+    load(): Promise<void>;
+    ensure(): Promise<boolean>;
     private get file();
-    private refresh;
+    private readStored;
+    private fetchFresh;
 }

package/dist/usage/pricing.js

@@ -118,7 +118,7 @@ export class PriceBook {
     table;
     source = 'snapshot';
     fetchedAt = null;
-    loadedFromDisk = false;
+    stored = null;
     inFlight = null;
     constructor(home, allowFetch = true) {
         this.home = home;
@@ -131,9 +131,16 @@ export class PriceBook {
     look(model) {
         return lookupPrice(this.table, model);
     }
-    /* Refreshes at most one table at a time; a second caller waits for the first one's answer. */
+    /* Reads the table an earlier run stored, once; asking LiteLLM is left to `ensure`. */
+    load() {
+        this.stored ??= this.readStored();
+        return this.stored;
+    }
+    /* Refreshes at most one table at a time, a second caller waiting for the first one's answer; true when a newer table came in. */
     ensure() {
-        this.inFlight ??= this.refresh().finally(() => {
+        this.inFlight ??= this.load()
+            .then(() => this.fetchFresh())
+            .finally(() => {
             this.inFlight = null;
         });
         return this.inFlight;
@@ -141,27 +148,27 @@ export class PriceBook {
     get file() {
         return join(this.home, 'usage', 'prices.json');
     }
-    async refresh() {
-        if (!this.loadedFromDisk) {
-            this.loadedFromDisk = true;
-            try {
-                const snapshot = JSON.parse(await readFile(this.file, 'utf8'));
-                const table = parsePriceTable(snapshot?.document);
-                if (table.size > 0 && typeof snapshot.fetchedAt === 'number') {
-                    this.table = table;
-                    this.source = 'litellm';
-                    this.fetchedAt = snapshot.fetchedAt;
-                }
+    async readStored() {
+        try {
+            const snapshot = JSON.parse(await readFile(this.file, 'utf8'));
+            const table = parsePriceTable(snapshot?.document);
+            if (table.size > 0 && typeof snapshot.fetchedAt === 'number') {
+                this.table = table;
+                this.source = 'litellm';
+                this.fetchedAt = snapshot.fetchedAt;
             }
-            catch (e) {
-                if (!isNotFound(e)) {
-                    console.warn('The stored price table would not read; using the bundled one:', errorText(e));
-                }
+        }
+        catch (e) {
+            if (!isNotFound(e)) {
+                console.warn('The stored price table would not read; using the bundled one:', errorText(e));
             }
         }
+    }
+    async fetchFresh() {
         if (!this.allowFetch || (this.fetchedAt !== null && Date.now() - this.fetchedAt < TTL_MS)) {
-            return;
+            return false;
         }
+        let changed = false;
         try {
             const response = await fetch(LITELLM_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
             if (!response.ok) {
@@ -175,6 +182,7 @@ export class PriceBook {
             this.table = table;
             this.source = 'litellm';
             this.fetchedAt = Date.now();
+            changed = true;
             await mkdir(join(this.home, 'usage'), { recursive: true, mode: 0o700 });
             await writeAtomic(this.file, JSON.stringify({ fetchedAt: this.fetchedAt, document }));
         }
@@ -182,5 +190,6 @@ export class PriceBook {
             // Whatever is loaded keeps pricing; a table that could not be refreshed is not a failure.
             console.warn('Could not refresh the price table:', errorText(e));
         }
+        return changed;
     }
 }

package/dist/usage/scanner.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { mkdir, open, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { errorText } from '../error-text.js';
@@ -7,26 +8,46 @@ 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';
-/* What a file holds from `from` to its end, as it is at the read. */
-async function readFrom(path, from) {
+const HASH_CHUNK_BYTES = 65536;
+/*
+ * Hashes the bytes before `from` and returns the rest, in one pass over one handle, so verifying
+ * what a transcript committed and parsing what it added never reads a byte twice.
+ */
+async function readHashed(path, from) {
     const handle = await open(path, 'r');
     try {
+        const hash = createHash('sha256');
+        const chunk = Buffer.alloc(Math.min(from, HASH_CHUNK_BYTES));
+        let offset = 0;
+        while (offset < from) {
+            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, from - offset), offset);
+            if (bytesRead === 0) {
+                break;
+            }
+            hash.update(chunk.subarray(0, bytesRead));
+            offset += bytesRead;
+        }
         const { size } = await handle.stat();
-        const buffer = Buffer.alloc(Math.max(0, size - from));
+        const bytes = 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);
+        while (filled < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, filled, bytes.length - filled, from + filled);
             if (bytesRead === 0) {
                 break;
             }
             filled += bytesRead;
         }
-        return buffer.subarray(0, filled).toString('utf8');
+        return { bytes: bytes.subarray(0, filled), hash };
     }
     finally {
         await handle.close();
     }
 }
+/* Covers every committed byte, since a transcript can be rewritten after an unchanged session header. */
+function headOf(hash) {
+    // Older indexes hashed only the first 4 KB; they cannot establish that the rest stayed unchanged.
+    return `sha256:${hash.copy().digest('base64')}`;
+}
 async function listJsonl(dir, out = []) {
     let entries;
     try {
@@ -111,7 +132,7 @@ function withAccount(records, accountOf) {
     });
 }
 /*
- * Reads only what a transcript appended since the last scan, and starts a file over once it was
+ * Parses only what a transcript appended since the last scan, and starts a file over once it was
  * rewritten or cut. A deleted transcript keeps its totals, since its usage still happened.
  */
 export class UsageScanner {
@@ -210,10 +231,16 @@ export class UsageScanner {
         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 appended = known !== undefined && known.provider === provider && info.size > known.size && known.head?.startsWith('sha256:') === true;
+        let read = await readHashed(path, appended ? known.offset : 0);
+        // A file only counts as grown while it starts the way it did; one rewritten larger is read again from the start.
+        const grown = appended && headOf(read.hash) === known.head;
+        if (appended && !grown) {
+            read = await readHashed(path, 0);
+        }
         const from = grown ? known.offset : 0;
-        const text = await readFrom(path, from);
-        const parsed = parseChunk(text, provider, from, grown ? known.codex : null);
+        const parsed = parseChunk(read.bytes.toString('utf8'), provider, from, grown ? known.codex : null);
+        read.hash.update(read.bytes.subarray(0, parsed.offset - from));
         const before = grown ? known.records : [];
         const entry = {
             provider,
@@ -223,7 +250,8 @@ export class UsageScanner {
             // 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
+            codex: parsed.codex,
+            head: headOf(read.hash)
         };
         this.index.set(path, entry);
         this.dirty = true;

package/dist/usage/usage-service.js

@@ -105,14 +105,19 @@ export class UsageService {
         return this.inFlight;
     }
     async runScan() {
-        // The table and the rate are fetched beside the walk, so a slow answer never holds up the scan.
+        // A fetch never holds up the scan or the answer waiting on it; a table or rate it brings in is announced on its own.
+        void Promise.all([this.prices.ensure(), this.rates.ensure()]).then((fetched) => {
+            if (fetched.includes(true)) {
+                this.sinks.emit({ event: 'usage.changed', payload: { scannedAt: this.report.at } });
+            }
+        });
         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.prices.load(),
+            this.rates.load()
         ]);
         this.failed = report === null;
         if (report === null) {

package/package.json

@@ -1,17 +1,78 @@
 {
   "name": "@adecore/agents",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "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"
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./chat": {
+      "source": "./src/chat/index.ts",
+      "types": "./dist/chat/index.d.ts",
+      "default": "./dist/chat/index.js"
+    },
+    "./context": {
+      "source": "./src/context/index.ts",
+      "types": "./dist/context/index.d.ts",
+      "default": "./dist/context/index.js"
+    },
+    "./coordination": {
+      "source": "./src/coordination/index.ts",
+      "types": "./dist/coordination/index.d.ts",
+      "default": "./dist/coordination/index.js"
+    },
+    "./host": {
+      "source": "./src/host/index.ts",
+      "types": "./dist/host/index.d.ts",
+      "default": "./dist/host/index.js"
+    },
+    "./providers": {
+      "source": "./src/providers/index.ts",
+      "types": "./dist/providers/index.d.ts",
+      "default": "./dist/providers/index.js"
+    },
+    "./usage": {
+      "source": "./src/usage/index.ts",
+      "types": "./dist/usage/index.d.ts",
+      "default": "./dist/usage/index.js"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./testing/bin/fake-claude": {
+      "source": "./src/testing/bin/fake-claude.ts",
+      "types": "./dist/testing/bin/fake-claude.d.ts",
+      "default": "./dist/testing/bin/fake-claude.js"
+    },
+    "./testing/bin/fake-codex": {
+      "source": "./src/testing/bin/fake-codex.ts",
+      "types": "./dist/testing/bin/fake-codex.d.ts",
+      "default": "./dist/testing/bin/fake-codex.js"
+    },
+    "./providers/claude-models.json": {
+      "source": "./src/providers/claude-models.json",
+      "default": "./dist/providers/claude-models.json"
+    },
+    "./providers/codex-models.json": {
+      "source": "./src/providers/codex-models.json",
+      "default": "./dist/providers/codex-models.json"
+    },
+    "./usage/prices-snapshot.json": {
+      "source": "./src/usage/prices-snapshot.json",
+      "default": "./dist/usage/prices-snapshot.json"
+    },
+    "./testing/fixtures/*": {
+      "source": "./src/chat/fixtures/*",
+      "default": "./dist/chat/fixtures/*"
+    },
+    "./package.json": {
+      "source": "./package.json",
+      "default": "./package.json"
     }
   },
   "scripts": {
@@ -20,8 +81,8 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.23.0",
-    "@adecore/intelligent-ui": "0.23.0",
+    "@adecore/agent-contracts": "0.24.0",
+    "@adecore/intelligent-ui": "0.24.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/chat/attachment-store.ts

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
-import { attachmentImageMime, type ChatAttachment, type ChatAttachmentUpload } from '@adecore/agent-contracts';
+import { isRecord, attachmentImageMime, type ChatAttachment, type ChatAttachmentUpload } from '@adecore/agent-contracts';
 
 // The extension the file gets on disk when its name does not carry a usable one.
 const EXTENSIONS: Record<string, string> = {
@@ -100,14 +100,12 @@ export class AttachmentStore {
 
     /* Where the files of one chat are; a store that keeps more of a chat's files beside them writes them here. */
     folderOf(chatId: string): string {
-        return join(this.dir, encodeURIComponent(chatId));
+        // `encodeURIComponent` leaves `.` and `..` as they are, and those would name this folder or the host's own.
+        const segment = chatId === '.' || chatId === '..' ? chatId.replaceAll('.', '%2E') : encodeURIComponent(chatId);
+        return join(this.dir, segment);
     }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 // What an attachment looked like before the files moved out of the thread: the bytes inline.
 function isInline(value: unknown): value is { name: string; mediaType: string; data: string } {
     return isRecord(value) && typeof value.name === 'string' && typeof value.mediaType === 'string' && typeof value.data === 'string';

package/src/chat/backend.ts

@@ -2,6 +2,8 @@ import type {
     ChatAttachment,
     ChatAttachmentUpload,
     ChatFileChange,
+    ChatGoal,
+    ChatGoalAction,
     ChatQuestion,
     ChatSkill,
     ChatSubagentUsage,
@@ -38,6 +40,8 @@ export interface BackendLaunch {
     // The part of it a resumed thread has to hear again in front of its next prompt, for a CLI that ignores new
     // instructions on a resume; null when there is nothing to repeat.
     resumeNote: string | null;
+    // The goal the chat last knew of, which a CLI that takes it up again from its own transcript on a resume still works toward.
+    goal?: ChatGoal;
     // Folders outside `cwd` the agent may reach without asking. Claude Code takes them as `--add-dir`; Codex's
     // sandbox reads the whole disk already and keeps writes to the workspace, so it needs nothing.
     folders?: readonly string[];
@@ -158,6 +162,8 @@ export type BackendEvent =
     // What the CLI said in passing about the plan it runs on; it belongs to the machine, not the chat.
     | { type: 'limits'; update: LimitsUpdate }
     | { type: 'compaction'; preTokens: number | null }
+    // The goal the CLI works toward as it stands now, whole; null once there is none.
+    | { type: 'goal'; goal: ChatGoal | null }
     | { type: 'model'; model: string }
     | { type: 'note'; level: 'info' | 'warning' | 'error'; text: string }
     // The CLI answered a `stopTask` with an error, so the task still runs.
@@ -196,6 +202,8 @@ export interface ChatBackend {
     // False when nothing waits under that id, so the caller can answer the client with an error.
     respondApproval(requestId: string, decision: ApprovalDecision, message?: string): boolean;
     respondQuestion(requestId: string, answers: Record<string, string>): boolean;
+    // Pauses, resumes or clears the goal without a turn, for a protocol that has calls for it; what changed arrives as a `goal` event.
+    goal?(action: ChatGoalAction): Promise<void>;
     // Ends one command or monitor the CLI runs beside its turns, for a protocol that can name one.
     stopTask?(taskId: string): void;
     // Turns down a request the CLI still holds after a person stopped the turn, for a protocol that leaves one open past it.

package/src/chat/background-work.ts

@@ -1,4 +1,4 @@
-import type { AgentKind, ChatBackgroundTask, ChatItem, ChatSubagentItem, ChatToolItem } from '@adecore/agent-contracts';
+import { HOST_TASK_ORIGIN, type AgentKind, type ChatBackgroundTask, type ChatItem, type ChatSubagentItem, type ChatToolItem } from '@adecore/agent-contracts';
 
 export type BackgroundWork = ChatSubagentItem | ChatToolItem;
 
@@ -10,7 +10,7 @@ export type BackgroundWork = ChatSubagentItem | ChatToolItem;
  * work it delegated itself (origin `ruimte` on the wire) is that work's own.
  */
 export function isBackgroundWork(item: ChatItem): item is BackgroundWork {
-    return (item.kind === 'subagent' && item.background && item.origin !== 'ruimte') || (item.kind === 'tool' && item.name === 'Workflow');
+    return (item.kind === 'subagent' && item.background && item.origin !== HOST_TASK_ORIGIN) || (item.kind === 'tool' && item.name === 'Workflow');
 }
 
 export function runsInBackground(item: BackgroundWork): boolean {