toolroll 0.9.47 → 0.9.49

package/dist/read-executor.d.ts

@@ -0,0 +1,49 @@
+import type { Store } from './store.js';
+import { type WorkIndexOptions, type WorkIndexPage } from './work-index.js';
+import type { WorkSummaryAccess } from './work-summary.js';
+/**
+ * Heavy, read-only database work for the server, run on worker threads (docs/server-performance.md).
+ * Each worker owns one read-only, query-only connection to the server's own database file, so the
+ * measured hot read (the work index behind `task list`) never holds the HTTP event loop. Callers
+ * authorize first and send only the already-admitted access; a worker never widens it, writes, or
+ * retries. Without a file-backed database (tests, the demo) nothing is attached and callers keep
+ * running the same builder in-process.
+ */
+export type ReadJob = {
+    kind: 'work-index-page';
+    now: string;
+    access: WorkSummaryAccess;
+    options: WorkIndexOptions;
+};
+export type ReadReply = {
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+    };
+};
+/** More queued reads than this fail at once instead of growing without bound. */
+export declare const READ_QUEUE_MAX = 1000;
+export declare class ReadExecutorError extends Error {
+    constructor(message: string);
+}
+export declare class ReadExecutor {
+    #private;
+    constructor(file: string, size?: number);
+    get size(): number;
+    /** workIndexPage(store, now, access, options) on a worker's read-only connection: same rows, same errors. */
+    workIndexPage(now: Date, access: WorkSummaryAccess, options: WorkIndexOptions): Promise<WorkIndexPage>;
+    /** Fails every queued and running read once, then stops the workers. */
+    close(): Promise<void>;
+}
+/** Half the cores, at most eight: the measured 20-engineer load needs over four (docs/server-performance.md),
+ * and the rest stay with the event loop and local agents. Workers start only when reads arrive. */
+export declare function defaultReadWorkers(): number;
+/** The server attaches its executor to its own Store; a command run on that Store reads through it. */
+export declare function attachReadExecutor(store: Store, executor: ReadExecutor): () => void;
+export declare function readExecutorOf(store: Store): ReadExecutor | null;

package/dist/read-executor.js

@@ -0,0 +1,119 @@
+import { Worker } from 'node:worker_threads';
+import { availableParallelism } from 'node:os';
+import { WorkIndexCursorError } from './work-index.js';
+/** More queued reads than this fail at once instead of growing without bound. */
+export const READ_QUEUE_MAX = 1_000;
+export class ReadExecutorError extends Error {
+    constructor(message) { super(message); this.name = 'ReadExecutorError'; }
+}
+export class ReadExecutor {
+    #file;
+    #size;
+    #slots = [];
+    #queue = [];
+    #next = 1;
+    #closed = false;
+    constructor(file, size = defaultReadWorkers()) {
+        this.#file = file;
+        this.#size = Math.max(1, Math.floor(size));
+    }
+    get size() { return this.#size; }
+    /** workIndexPage(store, now, access, options) on a worker's read-only connection: same rows, same errors. */
+    async workIndexPage(now, access, options) {
+        try {
+            return await this.#run({ kind: 'work-index-page', now: now.toISOString(), access, options });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'WorkIndexCursorError')
+                throw new WorkIndexCursorError();
+            throw error;
+        }
+    }
+    #run(job) {
+        if (this.#closed)
+            return Promise.reject(new ReadExecutorError('The server is closing.'));
+        if (this.#queue.length >= READ_QUEUE_MAX)
+            return Promise.reject(new ReadExecutorError('The server is too busy to read this now; try again shortly.'));
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ id: this.#next++, job, resolve, reject });
+            this.#pump();
+        });
+    }
+    #pump() {
+        while (this.#queue.length > 0) {
+            let slot = this.#slots.find(one => one.busy === null);
+            if (slot === undefined && this.#slots.length < this.#size)
+                slot = this.#spawn();
+            if (slot === undefined)
+                return;
+            const pending = this.#queue.shift();
+            slot.busy = pending;
+            slot.worker.postMessage({ id: pending.id, job: pending.job });
+        }
+    }
+    #spawn() {
+        // The installed server runs the built sibling; tests run the TypeScript source through tsx.
+        const worker = import.meta.url.endsWith('.ts')
+            ? new Worker(`import('tsx/esm/api').then(tsx => { tsx.register(); return import(${JSON.stringify(new URL('./read-executor-worker.ts', import.meta.url).href)}); });`, { eval: true, workerData: { file: this.#file } })
+            : new Worker(new URL('./read-executor-worker.js', import.meta.url), { workerData: { file: this.#file } });
+        const slot = { worker, busy: null };
+        this.#slots.push(slot);
+        worker.on('message', (reply) => {
+            const pending = slot.busy;
+            if (pending === null || pending.id !== reply.id)
+                return;
+            slot.busy = null;
+            if (reply.ok)
+                pending.resolve(reply.value);
+            else
+                pending.reject(Object.assign(new Error(reply.error.message), { name: reply.error.name }));
+            this.#pump();
+        });
+        // A crashed worker fails only the read it held; the next read starts a fresh one.
+        const lost = (error) => {
+            const at = this.#slots.indexOf(slot);
+            if (at < 0)
+                return;
+            this.#slots.splice(at, 1);
+            const pending = slot.busy;
+            slot.busy = null;
+            pending?.reject(error);
+            if (!this.#closed)
+                this.#pump();
+        };
+        worker.on('error', error => lost(error instanceof Error ? error : new ReadExecutorError(String(error))));
+        worker.on('exit', code => lost(new ReadExecutorError(`The read worker stopped (exit ${code}).`)));
+        worker.unref();
+        return slot;
+    }
+    /** Fails every queued and running read once, then stops the workers. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const stopped = new ReadExecutorError('The server is closing.');
+        for (const pending of this.#queue.splice(0))
+            pending.reject(stopped);
+        const slots = this.#slots.splice(0);
+        for (const slot of slots) {
+            slot.busy?.reject(stopped);
+            slot.busy = null;
+        }
+        await Promise.all(slots.map(slot => slot.worker.terminate().catch(() => 0)));
+    }
+}
+/** Half the cores, at most eight: the measured 20-engineer load needs over four (docs/server-performance.md),
+ * and the rest stay with the event loop and local agents. Workers start only when reads arrive. */
+export function defaultReadWorkers() {
+    return Math.max(1, Math.min(8, Math.floor(availableParallelism() / 2)));
+}
+const attached = new WeakMap();
+/** The server attaches its executor to its own Store; a command run on that Store reads through it. */
+export function attachReadExecutor(store, executor) {
+    attached.set(store, executor);
+    return () => { if (attached.get(store) === executor)
+        attached.delete(store); };
+}
+export function readExecutorOf(store) {
+    return attached.get(store) ?? null;
+}

package/dist/request-budget.d.ts

@@ -1,6 +1,6 @@
 /**
- * Request budgets for person API tokens (v112): how many requests one `so_` token may make to `/api/cli` and `/mcp`.
- * One budget per token, keyed by its api_token row id (never the secret, its name or an address), shared by both
+ * Request budgets for person API tokens (v112): how many requests one `so_` token may make across all accepting routes.
+ * One budget per token, keyed by its api_token row id (never the secret, its name or an address), shared by those
  * routes. A read token gets 120 requests in any sliding minute, an act token 30, and either 10,000 in a rolling day;
  * an instance operator may override any of these for the installation or for one token in the console (step-up).
  *
@@ -26,7 +26,7 @@ export declare const PER_DAY_MAX = 100000;
 export declare const TRACKED_TOKENS = 1024;
 export declare const FLUSH_MS = 5000;
 /** Which limit a refusal hit: the body of a 429 names only this and Retry-After. */
-export type BudgetLimit = "read-per-minute" | "act-per-minute" | "per-day";
+export type BudgetLimit = "read-per-minute" | "act-per-minute" | "per-day" | "per-minute";
 export type Admission = {
     ok: true;
 } | {
@@ -88,9 +88,37 @@ export declare class RequestBudget {
      * read. Anything unreadable refuses with 503 and nothing runs.
      */
     admit(tokenId: string, route: BudgetRoute): Admission;
+    private check;
     /** Save every changed entry. A server calls this on a timer and when it closes. */
     flush(): void;
     private save;
     /** The tracked entry (now the most recently used), from memory or as last saved; the least recently used is saved and let go. */
     private load;
 }
+/** Per-minute allowances for non-person-token identities and unauthenticated ingress. Password accounts get room
+ * for two-second follower polling plus ordinary commands; OAuth exchanges stay keyed by source address. */
+export declare const SOURCE_BUDGET_DEFAULTS: Readonly<{
+    password: 120;
+    oauthToken: 30;
+    coordinator: 120;
+    teamsSource: 120;
+    teamsTenant: 600;
+}>;
+/**
+ * A sliding minute per source or proved account, with bounded in-memory LRU history. Expired entries are
+ * pruned first; at capacity the least recently used entry is evicted so new callers are never globally locked out.
+ * Unverified account names must never be keys. Person API tokens use the persisted RequestBudget above.
+ */
+export declare class SourceAdmission {
+    private readonly perMinute;
+    private readonly clock;
+    private readonly tracked;
+    private readonly usage;
+    constructor(options: {
+        perMinute: number;
+        clock?: () => number;
+        tracked?: number;
+    });
+    get size(): number;
+    admit(source: string): Admission;
+}

package/dist/request-budget.js

@@ -22,7 +22,7 @@ export const TRACKED_TOKENS = 1024;
 export const FLUSH_MS = 5_000;
 const MINUTE = 60_000, DAY = 86_400_000;
 /** The words for a 429, in one line. */
-export const limitWords = (limit, retryAfter) => `Request limit reached (${limit === "per-day" ? "requests per day" : limit === "read-per-minute" ? "read requests per minute" : "act requests per minute"}). Try again in ${retryAfter} second${retryAfter === 1 ? "" : "s"}.`;
+export const limitWords = (limit, retryAfter) => `Request limit reached (${limit === "per-day" ? "requests per day" : limit === "read-per-minute" ? "read requests per minute" : limit === "act-per-minute" ? "act requests per minute" : "requests per minute"}). Try again in ${retryAfter} second${retryAfter === 1 ? "" : "s"}.`;
 /** A limit typed into a form: a whole number within bounds, "" for none, or a problem. */
 export function parseLimit(raw, max) {
     const text = raw.trim();
@@ -123,6 +123,12 @@ export class RequestBudget {
      * read. Anything unreadable refuses with 503 and nothing runs.
      */
     admit(tokenId, route) {
+        const result = this.check(tokenId, route);
+        if (!result.ok)
+            this.store.telemetry.budgetRefused(route, result.status === 429 ? result.limit : 'unavailable');
+        return result;
+    }
+    check(tokenId, route) {
         try {
             const now = this.clock();
             const token = this.store.apiTokenSecret(tokenId)?.row;
@@ -225,3 +231,46 @@ export class RequestBudget {
         return usage;
     }
 }
+/** Per-minute allowances for non-person-token identities and unauthenticated ingress. Password accounts get room
+ * for two-second follower polling plus ordinary commands; OAuth exchanges stay keyed by source address. */
+export const SOURCE_BUDGET_DEFAULTS = Object.freeze({ password: 120, oauthToken: 30, coordinator: 120, teamsSource: 120, teamsTenant: 600 });
+/**
+ * A sliding minute per source or proved account, with bounded in-memory LRU history. Expired entries are
+ * pruned first; at capacity the least recently used entry is evicted so new callers are never globally locked out.
+ * Unverified account names must never be keys. Person API tokens use the persisted RequestBudget above.
+ */
+export class SourceAdmission {
+    perMinute;
+    clock;
+    tracked;
+    usage = new Map();
+    constructor(options) {
+        this.perMinute = Math.max(1, Math.min(PER_MINUTE_MAX, options.perMinute));
+        this.clock = options.clock ?? Date.now;
+        this.tracked = Math.max(1, options.tracked ?? TRACKED_TOKENS);
+    }
+    get size() { return this.usage.size; }
+    admit(source) {
+        const now = this.clock();
+        let times = this.usage.get(source);
+        if (times === undefined) {
+            if (this.usage.size >= this.tracked) {
+                for (const [key, kept] of this.usage)
+                    if (kept.every(at => at <= now - MINUTE))
+                        this.usage.delete(key);
+                if (this.usage.size >= this.tracked)
+                    this.usage.delete(this.usage.keys().next().value);
+            }
+            times = [];
+        }
+        this.usage.delete(source);
+        this.usage.set(source, times);
+        while (times.length > 0 && times[0] <= now - MINUTE)
+            times.shift();
+        if (times.length >= this.perMinute) {
+            return { ok: false, status: 429, limit: "per-minute", retryAfter: Math.max(1, Math.ceil((times[times.length - this.perMinute] + MINUTE - now) / 1000)) };
+        }
+        times.push(now);
+        return { ok: true };
+    }
+}

package/dist/serve.d.ts

@@ -33,6 +33,8 @@ export type ServeOptions = {
     installBin?: string;
     /** Native coding workspace injection for isolated integration tests. */
     codingWorkspace?: CodingWorkspace;
+    /** Read-only worker connections for heavy reads (read-executor.ts); 0 reads in-process. Default: off under tests. */
+    readWorkers?: number;
     store: Store;
     evidenceRoot: string;
     clock?: () => Date;