@framers/agentos 0.12.4 → 0.12.6

package/dist/cognition/emergent/broker/CapabilityBroker.js

@@ -0,0 +1,288 @@
+/**
+ * @fileoverview The host-side broker for code-forged tools under a ceiling.
+ * It hands each run the functions the run's grant names, scoped by the
+ * ceiling. Before every capability call it checks, in this order: the run is
+ * live, the capability is in the grant, the target fits the scope. It then
+ * writes the intent record, checks the run is still live, performs the call
+ * while tracking it under the run's id, and writes the terminal record. When
+ * the run ends, `endCall` waits up to {@link CALL_SETTLE_MS} for what is in
+ * flight and returns the run's effects. On `node:vm` these checks are a
+ * guardrail for code that acts through these functions; Node's documentation
+ * says `node:vm` is not a security mechanism.
+ * @module @framers/agentos/emergent/broker/CapabilityBroker
+ */
+import { createHash, createHmac, randomUUID } from 'node:crypto';
+import { recordedTarget } from '../EffectsStore.js';
+import { fetchTarget, prepareFetch, sendFetch } from './fetch.js';
+import { prepareRead, readPrepared, ReadRoots, ReadTooLarge } from './fs-read.js';
+import { CapabilityRefusal } from './refusal.js';
+/** How long a run's end waits for its aborted capability calls to settle. */
+export const CALL_SETTLE_MS = 1000;
+/** The terminal half for a call that threw. */
+function endOf(error) {
+    if (error instanceof ReadTooLarge) {
+        return { outcome: 'refused', code: error.code, bytes: error.bytesRead };
+    }
+    if (error instanceof CapabilityRefusal) {
+        if (error.code === 'aborted' || error.code === 'timed_out') {
+            return { outcome: error.code, code: error.code };
+        }
+        return { outcome: 'refused', code: error.code };
+    }
+    return { outcome: 'error', code: error instanceof Error ? error.name : 'error' };
+}
+export class CapabilityBroker {
+    /**
+     * @param ceiling - The resolved ceiling the functions are scoped by.
+     * @param store - Where effect records go; absent with `audit.store: 'none'`.
+     */
+    constructor(ceiling, store) {
+        this.ceiling = ceiling;
+        this.store = store;
+        this.runs = new Map();
+        this.readRoots = ceiling['fs.read'] ? new ReadRoots(ceiling['fs.read'].roots) : undefined;
+    }
+    /**
+     * The globals injected into one run's sandbox: a function for each
+     * capability that both the grant and the ceiling hold, and nothing else.
+     * The owner of the run's handle calls {@link endCall} when the run ends.
+     */
+    functionsFor(grant, call) {
+        const run = this.ledgerFor(call);
+        const functions = {};
+        const fetchScope = this.ceiling.fetch;
+        if (grant.includes('fetch') && fetchScope) {
+            functions.fetch = (input, init) => this.perform(run, grant, 'fetch', fetchTarget(input) ?? String(input), () => {
+                const prepared = prepareFetch(input, init, fetchScope);
+                return async (signal) => {
+                    const sent = await sendFetch(prepared, fetchScope, signal);
+                    return { value: sent.response, bytes: sent.bytes };
+                };
+            });
+        }
+        const readScope = this.ceiling['fs.read'];
+        const roots = this.readRoots;
+        if (grant.includes('fs.read') && readScope && roots) {
+            functions.fs = {
+                readFile: (filePath) => this.perform(run, grant, 'fs.read', String(filePath), () => {
+                    const resolved = prepareRead(filePath, roots);
+                    return async (signal) => {
+                        const read = await readPrepared(resolved, roots, readScope, signal);
+                        return { value: read.text, bytes: read.bytes };
+                    };
+                }),
+            };
+        }
+        if (grant.includes('crypto') && this.ceiling.crypto) {
+            // Synchronous and reaching nothing outside the process: counted per
+            // run, with one record when the run ends, not one per call.
+            const use = () => {
+                this.admit(run, grant, 'crypto');
+                run.cryptoUses += 1;
+            };
+            functions.crypto = {
+                randomUUID: () => {
+                    use();
+                    return randomUUID();
+                },
+                createHash: (algorithm) => {
+                    use();
+                    return createHash(algorithm);
+                },
+                createHmac: (algorithm, key) => {
+                    use();
+                    return createHmac(algorithm, key);
+                },
+            };
+        }
+        return functions;
+    }
+    /**
+     * Ends a run: refuses its capability calls from now on (the owner aborts
+     * the run's signal too), waits up to `settleMs` for the calls in flight,
+     * writes the crypto count, and returns the run's effects. A call that has
+     * not settled is listed `pending`, and its record completes when it settles.
+     */
+    async endCall(callId, settleMs = CALL_SETTLE_MS) {
+        const run = this.runs.get(callId);
+        if (!run) {
+            return [];
+        }
+        run.ended = true;
+        this.runs.delete(callId);
+        if (run.inFlight.size > 0) {
+            let timer;
+            await Promise.race([
+                Promise.allSettled([...run.inFlight]),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, settleMs);
+                }),
+            ]);
+            clearTimeout(timer);
+        }
+        if (run.cryptoUses > 0) {
+            const effect = {
+                kind: 'capability',
+                toolId: run.call.toolId,
+                callId: run.call.id,
+                capability: 'crypto',
+                target: recordedTarget('', this.ceiling.audit.content),
+                decision: 'allowed',
+                decidedBy: 'ceiling',
+                outcome: 'ok',
+                uses: run.cryptoUses,
+                record: this.store ? 'written' : 'none',
+            };
+            if (this.store) {
+                try {
+                    await this.store.whole(this.intentOf(run.call, 'crypto', '', 'allowed', 'ceiling'), {
+                        outcome: 'ok',
+                        uses: run.cryptoUses,
+                    });
+                }
+                catch {
+                    effect.record = 'none';
+                }
+            }
+            run.effects.push(effect);
+        }
+        return run.effects.map((effect) => ({ ...effect }));
+    }
+    ledgerFor(call) {
+        let run = this.runs.get(call.id);
+        if (!run) {
+            run = { call, effects: [], inFlight: new Set(), cryptoUses: 0, ended: false };
+            this.runs.set(call.id, run);
+        }
+        return run;
+    }
+    /** The run is live and the capability is in its grant and the ceiling. */
+    admit(run, grant, capability) {
+        if (run.ended || run.call.signal.aborted) {
+            throw new CapabilityRefusal('call_ended', capability);
+        }
+        if (!grant.includes(capability) || this.ceiling[capability] === undefined) {
+            throw new CapabilityRefusal('capability_not_granted', capability);
+        }
+    }
+    /**
+     * One capability call: the checks (a refusal is recorded as one row), then
+     * the recorded call, tracked in flight from its intent write to its
+     * terminal write, so ending the run waits for both.
+     */
+    async perform(run, grant, capability, target, prepare) {
+        let operation;
+        try {
+            this.admit(run, grant, capability);
+            operation = prepare();
+        }
+        catch (error) {
+            if (error instanceof CapabilityRefusal) {
+                await this.recordRefusal(run, capability, target, error.code);
+            }
+            throw error;
+        }
+        const effect = {
+            kind: 'capability',
+            toolId: run.call.toolId,
+            callId: run.call.id,
+            capability,
+            target: recordedTarget(target, this.ceiling.audit.content),
+            decision: 'allowed',
+            decidedBy: 'ceiling',
+            outcome: 'pending',
+            record: this.store ? 'written' : 'none',
+        };
+        run.effects.push(effect);
+        const recorded = this.carryOut(run, effect, capability, target, operation);
+        const settled = recorded.then(() => undefined, () => undefined);
+        run.inFlight.add(settled);
+        try {
+            return await recorded;
+        }
+        finally {
+            run.inFlight.delete(settled);
+        }
+    }
+    /** The intent record, the run checked again, the call, and its terminal record. */
+    async carryOut(run, effect, capability, target, operation) {
+        let rowId;
+        if (this.store) {
+            try {
+                rowId = await this.store.intent(this.intentOf(run.call, capability, target, 'allowed', 'ceiling'));
+            }
+            catch {
+                Object.assign(effect, {
+                    decision: 'refused',
+                    decidedBy: 'audit_unavailable',
+                    outcome: 'refused',
+                    code: 'audit_unavailable',
+                    record: 'none',
+                });
+                throw new CapabilityRefusal('audit_unavailable', `${capability}: its effect record could not be written`);
+            }
+        }
+        // The run may have ended while its intent was written.
+        if (run.ended || run.call.signal.aborted) {
+            await this.finish(effect, rowId, { outcome: 'aborted', code: 'call_ended' });
+            throw new CapabilityRefusal('call_ended', capability);
+        }
+        let result;
+        try {
+            result = await operation(run.call.signal);
+        }
+        catch (error) {
+            await this.finish(effect, rowId, endOf(error));
+            throw error;
+        }
+        await this.finish(effect, rowId, { outcome: 'ok', bytes: result.bytes });
+        return result.value;
+    }
+    async finish(effect, rowId, end) {
+        effect.outcome = end.outcome;
+        if (end.code !== undefined) {
+            effect.code = end.code;
+        }
+        if (end.bytes !== undefined) {
+            effect.bytes = end.bytes;
+        }
+        if (this.store && rowId !== undefined) {
+            try {
+                await this.store.terminal(rowId, end);
+            }
+            catch {
+                effect.record = 'intent_only';
+            }
+        }
+    }
+    async recordRefusal(run, capability, target, code) {
+        const effect = {
+            kind: 'capability',
+            toolId: run.call.toolId,
+            callId: run.call.id,
+            capability,
+            target: recordedTarget(target, this.ceiling.audit.content),
+            decision: 'refused',
+            decidedBy: code,
+            outcome: 'refused',
+            code,
+            record: this.store ? 'written' : 'none',
+        };
+        run.effects.push(effect);
+        if (this.store) {
+            try {
+                await this.store.whole(this.intentOf(run.call, capability, target, 'refused', code), {
+                    outcome: 'refused',
+                    code,
+                });
+            }
+            catch {
+                effect.record = 'none';
+            }
+        }
+    }
+    intentOf(call, capability, target, decision, decidedBy) {
+        return { toolId: call.toolId, callId: call.id, agentId: call.agentId, capability, target, decision, decidedBy };
+    }
+}
+//# sourceMappingURL=CapabilityBroker.js.map

package/dist/cognition/emergent/broker/CapabilityBroker.js.map

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

package/dist/cognition/emergent/broker/fetch.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview The broker's `fetch` for code-forged tools under a ceiling.
+ * `prepareFetch` checks a request before anything is sent (the URL, its
+ * scheme, the method and the first host) and rebuilds the caller's options
+ * from the two it accepts; `sendFetch` sends it with `redirect: 'manual'`,
+ * follows each redirect itself after checking the next host, and reads the
+ * body as a stream that is refused past its limit.
+ * @module @framers/agentos/emergent/broker/fetch
+ */
+/** The scope a ceiling grants `fetch` under, with its defaults applied. */
+export interface FetchScope {
+    domains: string[] | '*';
+    methods: Array<'GET' | 'HEAD'>;
+    maxResponseBytes: number;
+    maxRedirects: number;
+    timeoutMs: number;
+}
+/** A request that passed every check made before anything is sent. */
+export interface PreparedFetch {
+    url: URL;
+    method: 'GET' | 'HEAD';
+    headers: Headers;
+}
+/** The URL a forged tool's first argument names: a string, a URL, or an object with a `url` string. */
+export declare function fetchTarget(input: unknown): string | undefined;
+/**
+ * The checks made before anything is sent. The caller's options are read for
+ * `method` and `headers` only: a body, a redirect mode, credentials or a
+ * signal of the caller's are never passed on.
+ */
+export declare function prepareFetch(input: unknown, init: unknown, scope: FetchScope): PreparedFetch;
+/**
+ * Sends a prepared request. `signal` is the call's; the scope's `timeoutMs`
+ * bounds the whole request, redirects and body included. Every redirect is
+ * followed here, its host checked like the first; GET and HEAD keep their
+ * method through every redirect status.
+ */
+export declare function sendFetch(prepared: PreparedFetch, scope: FetchScope, signal: AbortSignal): Promise<{
+    response: Response;
+    bytes: number;
+}>;
+/** The broker's fetch without its records: the checks, then the request. */
+export declare function brokeredFetch(input: unknown, init: unknown, scope: FetchScope, signal: AbortSignal): Promise<Response>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/cognition/emergent/broker/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../../src/cognition/emergent/broker/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IACxB,OAAO,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAOD,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAW9D;AAuCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,aAAa,CAmB5F;AA8BD;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAiEhD;AAED,4EAA4E;AAC5E,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,QAAQ,CAAC,CAEnB"}

package/dist/cognition/emergent/broker/fetch.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview The broker's `fetch` for code-forged tools under a ceiling.
+ * `prepareFetch` checks a request before anything is sent (the URL, its
+ * scheme, the method and the first host) and rebuilds the caller's options
+ * from the two it accepts; `sendFetch` sends it with `redirect: 'manual'`,
+ * follows each redirect itself after checking the next host, and reads the
+ * body as a stream that is refused past its limit.
+ * @module @framers/agentos/emergent/broker/fetch
+ */
+import { CapabilityRefusal } from './refusal.js';
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const NULL_BODY_STATUSES = new Set([204, 205, 304]);
+/** Dropped when a redirect changes the origin, as fetch itself does. */
+const CROSS_ORIGIN_DROPPED = ['authorization', 'proxy-authorization', 'cookie', 'host'];
+/** The URL a forged tool's first argument names: a string, a URL, or an object with a `url` string. */
+export function fetchTarget(input) {
+    if (typeof input === 'string') {
+        return input;
+    }
+    if (input instanceof URL) {
+        return input.href;
+    }
+    if (input && typeof input === 'object' && typeof input.url === 'string') {
+        return input.url;
+    }
+    return undefined;
+}
+function checkScheme(url) {
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new CapabilityRefusal('scheme_not_allowed', `${url.protocol} (http and https only)`);
+    }
+}
+function checkHost(url, scope) {
+    const host = url.hostname.toLowerCase();
+    if (scope.domains !== '*' && !scope.domains.includes(host)) {
+        throw new CapabilityRefusal('host_not_allowed', host);
+    }
+}
+function headersFrom(given) {
+    const headers = new Headers();
+    try {
+        if (given instanceof Headers) {
+            given.forEach((value, name) => headers.set(name, value));
+        }
+        else if (Array.isArray(given)) {
+            for (const pair of given) {
+                if (Array.isArray(pair) && typeof pair[0] === 'string' && typeof pair[1] === 'string') {
+                    headers.append(pair[0], pair[1]);
+                }
+            }
+        }
+        else if (given && typeof given === 'object') {
+            for (const [name, value] of Object.entries(given)) {
+                if (typeof value === 'string') {
+                    headers.set(name, value);
+                }
+            }
+        }
+    }
+    catch (error) {
+        throw new CapabilityRefusal('invalid_headers', error instanceof Error ? error.message : String(error));
+    }
+    return headers;
+}
+/**
+ * The checks made before anything is sent. The caller's options are read for
+ * `method` and `headers` only: a body, a redirect mode, credentials or a
+ * signal of the caller's are never passed on.
+ */
+export function prepareFetch(input, init, scope) {
+    const raw = fetchTarget(input);
+    if (raw === undefined) {
+        throw new CapabilityRefusal('invalid_url', 'fetch takes a URL');
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new CapabilityRefusal('invalid_url', `"${raw}" is not an absolute URL`);
+    }
+    checkScheme(url);
+    const options = init && typeof init === 'object' ? init : {};
+    const method = (typeof options.method === 'string' ? options.method : 'GET').toUpperCase();
+    if (!scope.methods.includes(method)) {
+        throw new CapabilityRefusal('method_not_allowed', method);
+    }
+    checkHost(url, scope);
+    return { url, method: method, headers: headersFrom(options.headers) };
+}
+async function cappedBody(response, limit) {
+    if (!response.body) {
+        return new Uint8Array(0);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        total += value.byteLength;
+        if (total > limit) {
+            await reader.cancel().catch(() => undefined);
+            throw new CapabilityRefusal('response_too_large', `more than ${limit} bytes`);
+        }
+        chunks.push(value);
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+/**
+ * Sends a prepared request. `signal` is the call's; the scope's `timeoutMs`
+ * bounds the whole request, redirects and body included. Every redirect is
+ * followed here, its host checked like the first; GET and HEAD keep their
+ * method through every redirect status.
+ */
+export async function sendFetch(prepared, scope, signal) {
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(scope.timeoutMs)]);
+    const ended = (host) => new CapabilityRefusal(signal.aborted ? 'aborted' : 'timed_out', host);
+    const headers = new Headers(prepared.headers);
+    let url = prepared.url;
+    for (let redirects = 0;; redirects += 1) {
+        let response;
+        try {
+            response = await fetch(url, { method: prepared.method, headers, redirect: 'manual', signal: bounded });
+        }
+        catch (error) {
+            if (bounded.aborted) {
+                throw ended(url.hostname);
+            }
+            throw error;
+        }
+        const location = response.headers.get('location');
+        if (REDIRECT_STATUSES.has(response.status) && location !== null) {
+            await response.body?.cancel().catch(() => undefined);
+            if (redirects >= scope.maxRedirects) {
+                throw new CapabilityRefusal('too_many_redirects', `more than ${scope.maxRedirects}`);
+            }
+            let next;
+            try {
+                next = new URL(location, url);
+            }
+            catch {
+                throw new CapabilityRefusal('invalid_url', `a redirect to "${location}"`);
+            }
+            checkScheme(next);
+            checkHost(next, scope);
+            if (next.origin !== url.origin) {
+                for (const name of CROSS_ORIGIN_DROPPED) {
+                    headers.delete(name);
+                }
+            }
+            url = next;
+            continue;
+        }
+        let body = null;
+        if (prepared.method === 'HEAD' || NULL_BODY_STATUSES.has(response.status)) {
+            await response.body?.cancel().catch(() => undefined);
+        }
+        else {
+            try {
+                body = await cappedBody(response, scope.maxResponseBytes);
+            }
+            catch (error) {
+                if (error instanceof CapabilityRefusal) {
+                    throw error;
+                }
+                if (bounded.aborted) {
+                    throw ended(url.hostname);
+                }
+                throw error;
+            }
+        }
+        return {
+            // The body's own ArrayBuffer (it was allocated whole above): a typed
+            // array is not a BodyInit under TypeScript 5.7 and later.
+            response: new Response(body === null ? null : body.buffer, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            }),
+            bytes: body?.byteLength ?? 0,
+        };
+    }
+}
+/** The broker's fetch without its records: the checks, then the request. */
+export async function brokeredFetch(input, init, scope, signal) {
+    return (await sendFetch(prepareFetch(input, init, scope), scope, signal)).response;
+}
+//# sourceMappingURL=fetch.js.map

package/dist/cognition/emergent/broker/fetch.js.map

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

package/dist/cognition/emergent/broker/fs-read.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview The broker's `fs.readFile` for code-forged tools under a
+ * ceiling, and the path rules it shares with the forge's legacy read:
+ * lexical containment first, then the real path against the roots' real
+ * paths, each root's real path pinned on first success. The read is a
+ * stream refused past its limit, so no file is held whole before the limit
+ * applies.
+ * @module @framers/agentos/emergent/broker/fs-read
+ */
+import { CapabilityRefusal } from './refusal.js';
+/**
+ * Whether a path lies under one of the roots. Decided by `path.relative`, not
+ * a string prefix: a root that ends in a separator (`/`, `C:\`) would
+ * otherwise be compared against a doubled separator, and `path.relative`
+ * applies the platform's case rules. `''` is the root itself; a result that
+ * climbs out (`..`, `../x`) or stays absolute (another Windows drive) is
+ * outside. Checking the `..` segment, not the prefix, keeps a sibling named
+ * `..foo` from reading as an escape.
+ */
+export declare function withinRoots(candidate: string, roots: readonly string[]): boolean;
+/**
+ * Read roots, each root's real path resolved lazily and pinned per root.
+ *
+ * Both sides of a containment check are real paths: a root is often itself a
+ * link (on macOS `/tmp` is a link to `/private/tmp`). A resolved root stays
+ * pinned for the life of this object, so a root link repointed under a
+ * running sandbox is not followed. A failed resolution is not pinned, so a
+ * root that becomes readable later is picked up, and one unreadable root
+ * never un-pins a sibling; its lexical form never matches a real path, so it
+ * cannot widen the reads while it stays unreadable.
+ */
+export declare class ReadRoots {
+    readonly roots: readonly string[];
+    private readonly cache;
+    constructor(roots: readonly string[]);
+    real(): Promise<string[]>;
+    private realOf;
+}
+/** A read refused past its limit, with how far it got. */
+export declare class ReadTooLarge extends CapabilityRefusal {
+    readonly bytesRead: number;
+    constructor(bytesRead: number, limit: number);
+}
+/** The check made before the filesystem is touched: a path string, lexically under a root. Returns the resolved path. */
+export declare function prepareRead(filePath: unknown, roots: ReadRoots): string;
+/**
+ * The real-path check and the read. The file read is the resolved real path,
+ * not the caller's string: resolving the caller's string again would walk a
+ * link a second time, and the link can be repointed between the two walks.
+ */
+export declare function readPrepared(resolved: string, roots: ReadRoots, scope: {
+    maxBytesPerRead: number;
+    timeoutMs: number;
+}, signal: AbortSignal): Promise<{
+    text: string;
+    bytes: number;
+}>;
+/** The broker's read without its records: the checks, then the read. */
+export declare function brokeredRead(filePath: unknown, roots: ReadRoots, scope: {
+    maxBytesPerRead: number;
+    timeoutMs: number;
+}, signal: AbortSignal): Promise<string>;
+//# sourceMappingURL=fs-read.d.ts.map

package/dist/cognition/emergent/broker/fs-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-read.d.ts","sourceRoot":"","sources":["../../../../src/cognition/emergent/broker/fs-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAQhF;AAED;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IAGR,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE;IAF7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;gBAEvC,KAAK,EAAE,SAAS,MAAM,EAAE;IAE7C,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIzB,OAAO,CAAC,MAAM;CAYf;AAED,0DAA0D;AAC1D,qBAAa,YAAa,SAAQ,iBAAiB;IAE/C,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM,EAC1B,KAAK,EAAE,MAAM;CAIhB;AAED,yHAAyH;AACzH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CASvE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACrD,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA8C1C;AAED,wEAAwE;AACxE,wBAAsB,YAAY,CAChC,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACrD,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAEjB"}