@framers/agentos 0.12.3 → 0.12.5

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"}

package/dist/cognition/emergent/broker/fs-read.js

@@ -0,0 +1,133 @@
+/**
+ * @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 { createReadStream } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import * as path from 'node:path';
+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 function withinRoots(candidate, roots) {
+    return roots.some((root) => {
+        const relative = path.relative(root, candidate);
+        return (relative === '' ||
+            (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)));
+    });
+}
+/**
+ * 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 class ReadRoots {
+    constructor(roots) {
+        this.roots = roots;
+        this.cache = new Map();
+    }
+    real() {
+        return Promise.all(this.roots.map((root) => this.realOf(root)));
+    }
+    realOf(root) {
+        const cached = this.cache.get(root);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const pending = realpath(root).catch(() => {
+            this.cache.delete(root);
+            return root;
+        });
+        this.cache.set(root, pending);
+        return pending;
+    }
+}
+/** A read refused past its limit, with how far it got. */
+export class ReadTooLarge extends CapabilityRefusal {
+    constructor(bytesRead, limit) {
+        super('file_too_large', `more than ${limit} bytes`);
+        this.bytesRead = bytesRead;
+    }
+}
+/** The check made before the filesystem is touched: a path string, lexically under a root. Returns the resolved path. */
+export function prepareRead(filePath, roots) {
+    if (typeof filePath !== 'string') {
+        throw new CapabilityRefusal('invalid_path', 'fs.readFile takes a path string');
+    }
+    const resolved = path.resolve(filePath);
+    if (!withinRoots(resolved, roots.roots)) {
+        throw new CapabilityRefusal('path_not_allowed', resolved);
+    }
+    return resolved;
+}
+/**
+ * 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 async function readPrepared(resolved, roots, scope, signal) {
+    const real = await realpath(resolved);
+    if (!withinRoots(real, await roots.real())) {
+        throw new CapabilityRefusal('path_not_allowed', `${resolved} resolves outside the roots`);
+    }
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(scope.timeoutMs)]);
+    if (bounded.aborted) {
+        throw new CapabilityRefusal(signal.aborted ? 'aborted' : 'timed_out', resolved);
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const stream = createReadStream(real);
+        function finish(error, result) {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            bounded.removeEventListener('abort', onAbort);
+            if (error) {
+                stream.destroy();
+                reject(error);
+                return;
+            }
+            resolve(result);
+        }
+        function onAbort() {
+            finish(new CapabilityRefusal(signal.aborted ? 'aborted' : 'timed_out', resolved));
+        }
+        bounded.addEventListener('abort', onAbort, { once: true });
+        stream.on('data', (chunk) => {
+            const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+            total += buffer.byteLength;
+            if (total > scope.maxBytesPerRead) {
+                finish(new ReadTooLarge(total, scope.maxBytesPerRead));
+                return;
+            }
+            chunks.push(buffer);
+        });
+        stream.on('error', (error) => finish(error));
+        stream.on('end', () => finish(null, { text: Buffer.concat(chunks).toString('utf-8'), bytes: total }));
+    });
+}
+/** The broker's read without its records: the checks, then the read. */
+export async function brokeredRead(filePath, roots, scope, signal) {
+    return (await readPrepared(prepareRead(filePath, roots), roots, scope, signal)).text;
+}
+//# sourceMappingURL=fs-read.js.map

package/dist/cognition/emergent/broker/fs-read.js.map

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

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

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview A capability call the broker refused or ended. The message
+ * starts with the code; forged code sees it, and an effect record keeps it.
+ * @module @framers/agentos/emergent/broker/refusal
+ */
+export declare class CapabilityRefusal extends Error {
+    readonly code: string;
+    constructor(code: string, detail: string);
+}
+//# sourceMappingURL=refusal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../../../src/cognition/emergent/broker/refusal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM;CAKjB"}

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

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview A capability call the broker refused or ended. The message
+ * starts with the code; forged code sees it, and an effect record keeps it.
+ * @module @framers/agentos/emergent/broker/refusal
+ */
+export class CapabilityRefusal extends Error {
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+        this.name = 'CapabilityRefusal';
+    }
+}
+//# sourceMappingURL=refusal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../../../src/cognition/emergent/broker/refusal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YACW,IAAY,EACrB,MAAc;QAEd,KAAK,CAAC,GAAG,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QAHnB,SAAI,GAAJ,IAAI,CAAQ;QAIrB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/cognition/emergent/ceiling.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview The host's ceiling for code-forged tools: validation into a
+ * resolved ceiling, the check of a forging agent's request against it, and
+ * the check of a host-built forge's options against it.
+ * @module @framers/agentos/emergent/ceiling
+ */
+import type { CapabilityName, EmergentAuditConfig, ForgedCapabilities } from './types.js';
+/** A ceiling with every default applied and every list normalised. */
+export interface ResolvedCeiling {
+    fetch?: {
+        domains: string[] | '*';
+        methods: Array<'GET' | 'HEAD'>;
+        maxResponseBytes: number;
+        maxRedirects: number;
+        timeoutMs: number;
+    };
+    'fs.read'?: {
+        roots: string[];
+        maxBytesPerRead: number;
+        timeoutMs: number;
+    };
+    crypto?: true;
+    audit: {
+        store: 'storage' | 'none';
+        content: 'digest' | 'full';
+        retainDays?: number;
+    };
+}
+export type CeilingErrorCode = 'unknown_capability' | 'root_not_absolute' | 'method_not_allowed' | 'invalid_domain' | 'invalid_bound' | 'audit_needs_storage' | 'forge_wider_than_ceiling';
+/** A ceiling the engine cannot build; the message starts with the code and the key. */
+export declare class CeilingError extends Error {
+    readonly code: CeilingErrorCode;
+    readonly key: string;
+    constructor(code: CeilingErrorCode, key: string, detail: string);
+}
+export declare const CEILING_DEFAULTS: {
+    readonly methods: Array<"GET" | "HEAD">;
+    readonly maxResponseBytes: number;
+    readonly maxRedirects: 5;
+    readonly maxBytesPerRead: number;
+    readonly timeoutMs: 30000;
+};
+/**
+ * Validates a host's ceiling and applies its defaults. An empty `domains` or
+ * `roots` list removes its capability (an empty list grants nothing).
+ *
+ * @throws CeilingError naming the code and the key of the first failure.
+ */
+export declare function resolveCeiling(capabilities: ForgedCapabilities, audit: EmergentAuditConfig | undefined, options: {
+    hasStorage: boolean;
+}): ResolvedCeiling;
+/** The capabilities a resolved ceiling grants, in catalogue order. */
+export declare function grantedCapabilities(ceiling: ResolvedCeiling): CapabilityName[];
+/** Whether a request (catalogue names) fits the ceiling; a refusal names the rest and what is allowed. */
+export declare function checkRequest(request: readonly CapabilityName[], ceiling: ResolvedCeiling): {
+    ok: true;
+} | {
+    ok: false;
+    refused: CapabilityName[];
+    allowed: CapabilityName[];
+};
+/**
+ * A host-built forge under a ceiling: its options may be narrower than the
+ * ceiling, and then they narrow it; they may never be wider. Only the
+ * capabilities the ceiling grants are compared, since the broker injects no
+ * other. An intersection is taken in the ceiling's terms and never widens:
+ * disjoint lists are wider, not empty.
+ *
+ * @throws CeilingError (`forge_wider_than_ceiling`) naming the forge option.
+ */
+export declare function narrowToForge(ceiling: ResolvedCeiling, forge: {
+    fetchDomainAllowlist: string[];
+    fsReadRoots: string[];
+}): ResolvedCeiling;
+//# sourceMappingURL=ceiling.d.ts.map

package/dist/cognition/emergent/ceiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceiling.d.ts","sourceRoot":"","sources":["../../../src/cognition/emergent/ceiling.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE1F,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;QACxB,OAAO,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;QAC/B,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,KAAK,EAAE;QAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;QAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF;AAED,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,eAAe,GACf,qBAAqB,GACrB,0BAA0B,CAAC;AAE/B,uFAAuF;AACvF,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM;gBADX,IAAI,EAAE,gBAAgB,EACtB,GAAG,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM;CAKjB;AAED,eAAO,MAAM,gBAAgB;sBACC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC;;;;;CAKzC,CAAC;AAcX;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,kBAAkB,EAChC,KAAK,EAAE,mBAAmB,GAAG,SAAS,EACtC,OAAO,EAAE;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,GAC/B,eAAe,CA4EjB;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,EAAE,CAE9E;AAED,0GAA0G;AAC1G,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,EAAE,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,EAAE,cAAc,EAAE,CAAA;CAAE,CAIpF;AAOD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE;IAAE,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/D,eAAe,CAkCjB"}

package/dist/cognition/emergent/ceiling.js

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview The host's ceiling for code-forged tools: validation into a
+ * resolved ceiling, the check of a forging agent's request against it, and
+ * the check of a host-built forge's options against it.
+ * @module @framers/agentos/emergent/ceiling
+ */
+import * as path from 'node:path';
+import { CAPABILITY_NAMES } from './capabilities.js';
+/** A ceiling the engine cannot build; the message starts with the code and the key. */
+export class CeilingError extends Error {
+    constructor(code, key, detail) {
+        super(`${code}: ${key}: ${detail}`);
+        this.code = code;
+        this.key = key;
+        this.name = 'CeilingError';
+    }
+}
+export const CEILING_DEFAULTS = {
+    methods: ['GET', 'HEAD'],
+    maxResponseBytes: 5 * 1024 * 1024,
+    maxRedirects: 5,
+    maxBytesPerRead: 1024 * 1024,
+    timeoutMs: 30000,
+};
+const HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$|^\d{1,3}(\.\d{1,3}){3}$/;
+function bound(value, fallback, key, min) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isInteger(value) || value < min) {
+        throw new CeilingError('invalid_bound', key, `expected an integer of at least ${min}, got ${String(value)}`);
+    }
+    return value;
+}
+/**
+ * Validates a host's ceiling and applies its defaults. An empty `domains` or
+ * `roots` list removes its capability (an empty list grants nothing).
+ *
+ * @throws CeilingError naming the code and the key of the first failure.
+ */
+export function resolveCeiling(capabilities, audit, options) {
+    for (const key of Object.keys(capabilities)) {
+        if (!CAPABILITY_NAMES.includes(key)) {
+            throw new CeilingError('unknown_capability', `capabilities.${key}`, `not in the catalogue (${CAPABILITY_NAMES.join(', ')})`);
+        }
+    }
+    const resolved = {
+        audit: {
+            store: audit?.store ?? 'storage',
+            content: audit?.content ?? 'digest',
+            ...(audit?.retainDays !== undefined
+                ? { retainDays: bound(audit.retainDays, 0, 'audit.retainDays', 1) }
+                : {}),
+        },
+    };
+    const fetch = capabilities.fetch;
+    if (fetch) {
+        const methods = fetch.methods ?? [...CEILING_DEFAULTS.methods];
+        for (const method of methods) {
+            if (method !== 'GET' && method !== 'HEAD') {
+                throw new CeilingError('method_not_allowed', 'capabilities.fetch.methods', `${String(method)}: stage 1 allows GET and HEAD`);
+            }
+        }
+        let domains = '*';
+        if (fetch.domains !== '*') {
+            domains = fetch.domains.map((domain) => domain.toLowerCase());
+            for (const domain of domains) {
+                if (!HOSTNAME.test(domain)) {
+                    throw new CeilingError('invalid_domain', 'capabilities.fetch.domains', `"${domain}" is not a host name (no scheme, port or path)`);
+                }
+            }
+        }
+        if (domains === '*' || domains.length > 0) {
+            resolved.fetch = {
+                domains,
+                methods,
+                maxResponseBytes: bound(fetch.maxResponseBytes, CEILING_DEFAULTS.maxResponseBytes, 'capabilities.fetch.maxResponseBytes', 1),
+                maxRedirects: bound(fetch.maxRedirects, CEILING_DEFAULTS.maxRedirects, 'capabilities.fetch.maxRedirects', 0),
+                timeoutMs: bound(fetch.timeoutMs, CEILING_DEFAULTS.timeoutMs, 'capabilities.fetch.timeoutMs', 1),
+            };
+        }
+    }
+    const read = capabilities['fs.read'];
+    if (read) {
+        for (const root of read.roots) {
+            if (!path.isAbsolute(root)) {
+                throw new CeilingError('root_not_absolute', 'capabilities.fs.read.roots', `"${root}" is not an absolute path`);
+            }
+        }
+        if (read.roots.length > 0) {
+            resolved['fs.read'] = {
+                roots: read.roots.map((root) => path.resolve(root)),
+                maxBytesPerRead: bound(read.maxBytesPerRead, CEILING_DEFAULTS.maxBytesPerRead, 'capabilities.fs.read.maxBytesPerRead', 1),
+                timeoutMs: bound(read.timeoutMs, CEILING_DEFAULTS.timeoutMs, 'capabilities.fs.read.timeoutMs', 1),
+            };
+        }
+    }
+    if (capabilities.crypto) {
+        resolved.crypto = true;
+    }
+    if (resolved.audit.store === 'storage' && !options.hasStorage) {
+        throw new CeilingError('audit_needs_storage', 'audit.store', "a ceiling records every capability call; pass a storage adapter, or set audit.store: 'none' (then no effect records are kept)");
+    }
+    return resolved;
+}
+/** The capabilities a resolved ceiling grants, in catalogue order. */
+export function grantedCapabilities(ceiling) {
+    return CAPABILITY_NAMES.filter((name) => ceiling[name] !== undefined);
+}
+/** Whether a request (catalogue names) fits the ceiling; a refusal names the rest and what is allowed. */
+export function checkRequest(request, ceiling) {
+    const allowed = grantedCapabilities(ceiling);
+    const refused = request.filter((name) => !allowed.includes(name));
+    return refused.length === 0 ? { ok: true } : { ok: false, refused, allowed };
+}
+function within(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+/**
+ * A host-built forge under a ceiling: its options may be narrower than the
+ * ceiling, and then they narrow it; they may never be wider. Only the
+ * capabilities the ceiling grants are compared, since the broker injects no
+ * other. An intersection is taken in the ceiling's terms and never widens:
+ * disjoint lists are wider, not empty.
+ *
+ * @throws CeilingError (`forge_wider_than_ceiling`) naming the forge option.
+ */
+export function narrowToForge(ceiling, forge) {
+    const narrowed = { ...ceiling };
+    if (ceiling.fetch) {
+        const forgeDomains = forge.fetchDomainAllowlist.map((domain) => domain.toLowerCase());
+        if (forgeDomains.length === 0) {
+            // The forge's empty list means every domain.
+            if (ceiling.fetch.domains !== '*') {
+                throw new CeilingError('forge_wider_than_ceiling', 'sandboxForge.fetchDomainAllowlist', 'the forge allows every domain');
+            }
+        }
+        else {
+            const ceilingDomains = ceiling.fetch.domains;
+            const wider = ceilingDomains === '*' ? [] : forgeDomains.filter((domain) => !ceilingDomains.includes(domain));
+            if (wider.length > 0) {
+                throw new CeilingError('forge_wider_than_ceiling', 'sandboxForge.fetchDomainAllowlist', `outside the ceiling: ${wider.join(', ')}`);
+            }
+            narrowed.fetch = { ...ceiling.fetch, domains: forgeDomains };
+        }
+    }
+    if (ceiling['fs.read']) {
+        const ceilingRoots = ceiling['fs.read'].roots;
+        const forgeRoots = forge.fsReadRoots.map((root) => path.resolve(root));
+        const wider = forgeRoots.filter((root) => !ceilingRoots.some((ceilingRoot) => within(root, ceilingRoot)));
+        if (wider.length > 0) {
+            throw new CeilingError('forge_wider_than_ceiling', 'sandboxForge.fsReadRoots', `outside the ceiling: ${wider.join(', ')}`);
+        }
+        if (forgeRoots.length === 0) {
+            // A forge that reads nowhere: the intersection is empty, and an empty
+            // intersection removes the capability rather than granting an empty list.
+            delete narrowed['fs.read'];
+        }
+        else {
+            narrowed['fs.read'] = { ...ceiling['fs.read'], roots: forgeRoots };
+        }
+    }
+    return narrowed;
+}
+//# sourceMappingURL=ceiling.js.map

package/dist/cognition/emergent/ceiling.js.map

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

package/dist/cognition/emergent/index.d.ts

@@ -18,6 +18,8 @@ export type { StepGate, StepGateOptions, Chainability, ChainRefusalCode } from '
 export { SandboxedToolForge } from './SandboxedToolForge.js';
 export type { SandboxedToolForgeConfig } from './SandboxedToolForge.js';
 export { CAPABILITY_NAMES, CAPABILITY_ALIASES, normalizeAllowlist, toSandboxApis } from './capabilities.js';
+export { CeilingError, checkRequest, grantedCapabilities, narrowToForge, resolveCeiling, CEILING_DEFAULTS } from './ceiling.js';
+export type { CeilingErrorCode, ResolvedCeiling } from './ceiling.js';
 export { parsePersistedSource, inferRequestFromCode, requestFromImplementation, parseStoredRequest, } from './persisted-source.js';
 export type { PersistedSource } from './persisted-source.js';
 export { EmergentToolRegistry } from './EmergentToolRegistry.js';

package/dist/cognition/emergent/index.d.ts.map

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

package/dist/cognition/emergent/index.js

@@ -16,6 +16,7 @@ export { ComposableToolBuilder } from './ComposableToolBuilder.js';
 export { createStepGate, checkChainable, COMPOSE_NEEDS_GATE_MESSAGE, MAX_COMPOSITION_DEPTH } from './StepGate.js';
 export { SandboxedToolForge } from './SandboxedToolForge.js';
 export { CAPABILITY_NAMES, CAPABILITY_ALIASES, normalizeAllowlist, toSandboxApis } from './capabilities.js';
+export { CeilingError, checkRequest, grantedCapabilities, narrowToForge, resolveCeiling, CEILING_DEFAULTS } from './ceiling.js';
 export { parsePersistedSource, inferRequestFromCode, requestFromImplementation, parseStoredRequest, } from './persisted-source.js';
 export { EmergentToolRegistry } from './EmergentToolRegistry.js';
 export { EMERGENT_TOOL_PACKAGE_SCHEMA_VERSION, buildEmergentToolPackage, serializeEmergentToolPackage, parseEmergentToolPackage, materializeEmergentToolFromPackage, } from './ToolPackage.js';

package/dist/cognition/emergent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cognition/emergent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAA8B,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAElH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5G,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKjE,OAAO,EACL,oCAAoC,EACpC,wBAAwB,EACxB,4BAA4B,EAC5B,wBAAwB,EACxB,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AASzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,qEAAqE;AACrE,wEAAwE;AACxE,mEAAmE;AACnE,eAAe;AACf,OAAO,EACL,sBAAsB,GAEvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,GAEzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,aAAa,GAId,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,eAAe,GAEhB,MAAM,2BAA2B,CAAC;AAEnC,oEAAoE;AACpE,0EAA0E;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAM7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cognition/emergent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAA8B,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAElH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5G,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhI,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKjE,OAAO,EACL,oCAAoC,EACpC,wBAAwB,EACxB,4BAA4B,EAC5B,wBAAwB,EACxB,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AASzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,qEAAqE;AACrE,wEAAwE;AACxE,mEAAmE;AACnE,eAAe;AACf,OAAO,EACL,sBAAsB,GAEvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,GAEzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,aAAa,GAId,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,eAAe,GAEhB,MAAM,2BAA2B,CAAC;AAEnC,oEAAoE;AACpE,0EAA0E;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAM7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}