@framers/agentos 0.13.3 → 0.13.4

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

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview The broker's `fs.writeFile` and `fs.unlink` for code-forged
+ * tools under a ceiling: the path checks against the roots (lexical, then
+ * the parent's real path, then the last component), and the operations. A
+ * write opens its file with an exclusive create and no signal, so the broker
+ * always knows whether it made the file, and writes through the handle in
+ * chunks, checking the call's signal and its own time bound between them: a
+ * cut write closes the handle and removes what it made. A removal or a
+ * rename, once started, runs to its end. Node has no `openat`, so a process
+ * that swaps a parent directory for a link between the check and the open is
+ * outside what these checks stop; and an exclusive create on a network file
+ * system that does not honour it is too. The documentation says both.
+ * @module @framers/agentos/emergent/broker/fs-write
+ */
+import { lstat, open, realpath, rename, unlink } from 'node:fs/promises';
+import * as path from 'node:path';
+import { withinRoots } from './fs-read.js';
+import { isProtectedRoot } from './protected.js';
+import { CapabilityRefusal } from './refusal.js';
+/** The bytes a write hands the file system at once; the call's signal is checked between them. */
+const CHUNK_BYTES = 64 * 1024;
+/**
+ * An effect cut by the call's end or by its own time bound before it was
+ * done. `fileLeft` is set when the broker could not remove a file it made.
+ */
+export class EffectCut extends CapabilityRefusal {
+    constructor(outcome, detail, fileLeft = false) {
+        super(fileLeft ? 'file_left' : outcome, detail);
+        this.outcome = outcome;
+        this.fileLeft = fileLeft;
+    }
+}
+/**
+ * Write or delete roots, each root's real path resolved lazily and pinned,
+ * as the broker's read roots are. A root whose real path is protected (see
+ * protected.ts) is set apart when it resolves: a target under it is refused
+ * with `protected_path`, whether the root existed at construction or not.
+ */
+export class EffectRoots {
+    constructor(roots, protectedReal) {
+        this.roots = roots;
+        this.protectedReal = protectedReal;
+        this.cache = new Map();
+        this.guarded = new Set();
+    }
+    /** The roots' real paths, the protected ones set apart. */
+    async real() {
+        const allowed = [];
+        for (const root of this.roots) {
+            const real = await this.realOf(root);
+            if (real !== undefined && !this.guarded.has(real)) {
+                allowed.push(real);
+            }
+        }
+        return { allowed, guarded: [...this.guarded] };
+    }
+    realOf(root) {
+        const cached = this.cache.get(root);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const pending = realpath(root).then((real) => {
+            if (isProtectedRoot(real, this.protectedReal)) {
+                this.guarded.add(real);
+            }
+            return real;
+        }, () => {
+            // A root that does not resolve yet grants nothing until it does.
+            this.cache.delete(root);
+            return undefined;
+        });
+        this.cache.set(root, pending);
+        return pending;
+    }
+}
+/** What the run's view says of a path: the overlay first in a dry run, then the real tree. */
+async function kindOf(target, overlay) {
+    const seen = overlay?.look(target);
+    if (seen === 'file') {
+        return 'file';
+    }
+    if (seen === 'absent') {
+        return 'absent';
+    }
+    try {
+        const stats = await lstat(target);
+        return stats.isFile() ? 'file' : 'other';
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return 'absent';
+        }
+        throw error;
+    }
+}
+/**
+ * The path checks of a write or a delete, in order: a path string; the path
+ * resolved as a read's is (against the process's working directory) and
+ * checked against the roots; the real path of its parent checked against the
+ * roots' real paths, the parent having to exist (no directory is made).
+ * Returns the target as written: the parent's real path and the last
+ * component.
+ */
+async function checkPath(filePath, roots, functionName) {
+    if (typeof filePath !== 'string') {
+        throw new CapabilityRefusal('invalid_path', `${functionName} takes a path string`);
+    }
+    const resolved = path.resolve(filePath);
+    if (!withinRoots(resolved, roots.roots)) {
+        throw new CapabilityRefusal('path_not_allowed', resolved);
+    }
+    const name = path.basename(resolved);
+    if (name === '' || resolved === path.parse(resolved).root) {
+        throw new CapabilityRefusal('not_a_file', resolved);
+    }
+    let parent;
+    try {
+        parent = await realpath(path.dirname(resolved));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            throw new CapabilityRefusal('no_such_directory', path.dirname(resolved));
+        }
+        throw error;
+    }
+    const { allowed, guarded } = await roots.real();
+    if (withinRoots(parent, guarded)) {
+        throw new CapabilityRefusal('protected_path', `${resolved} is under a protected root`);
+    }
+    if (!withinRoots(parent, allowed)) {
+        throw new CapabilityRefusal('path_not_allowed', `${resolved} resolves outside the roots`);
+    }
+    return path.join(parent, name);
+}
+/**
+ * A write's scope: the path checks, then the last component, which may
+ * exist only as a regular file, and under `create-only` not at all.
+ */
+export async function checkWrite(filePath, roots, mode, overlay) {
+    const target = await checkPath(filePath, roots, 'fs.writeFile');
+    const kind = await kindOf(target, overlay);
+    if (kind === 'other') {
+        throw new CapabilityRefusal('not_a_file', target);
+    }
+    if (kind === 'file' && mode === 'create-only') {
+        throw new CapabilityRefusal('file_exists', target);
+    }
+    return target;
+}
+/** A delete's scope: the path checks, then the last component, which must be a regular file. */
+export async function checkDelete(filePath, roots, overlay) {
+    const target = await checkPath(filePath, roots, 'fs.unlink');
+    const kind = await kindOf(target, overlay);
+    if (kind === 'absent') {
+        throw new CapabilityRefusal('no_such_file', target);
+    }
+    if (kind === 'other') {
+        throw new CapabilityRefusal('not_a_file', target);
+    }
+    return target;
+}
+/** The data a write carries, as bytes: a string is written as UTF-8. */
+export function writeBytes(data) {
+    if (typeof data === 'string') {
+        return Buffer.from(data, 'utf8');
+    }
+    if (data instanceof Uint8Array) {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
+    }
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    throw new CapabilityRefusal('unsupported_data', 'fs.writeFile takes a string, an ArrayBuffer or a typed array');
+}
+async function removeQuietly(file) {
+    try {
+        await unlink(file);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'ENOENT';
+    }
+}
+/**
+ * Writes `data` at `target` (already checked). Under `create-only` the
+ * target itself is created exclusively; under `create-or-replace` a
+ * temporary file beside it, named for the call, is created exclusively and
+ * then renamed over the target. A cut (the call's `signal`, or the effect's
+ * `timer`, started when the effect was admitted) that arrives while the open
+ * runs takes effect once the open settles.
+ */
+export async function writeAt(target, data, mode, callId, signal, timer) {
+    const cutNow = () => signal.aborted
+        ? new EffectCut('aborted', target)
+        : timer.aborted
+            ? new EffectCut('timed_out', target)
+            : undefined;
+    const before = cutNow();
+    if (before) {
+        throw before;
+    }
+    const file = mode === 'create-only' ? target : path.join(path.dirname(target), `.${path.basename(target)}.${callId}.tmp`);
+    let handle;
+    try {
+        handle = await open(file, 'wx');
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            // Put there between the check and the open.
+            throw new CapabilityRefusal('file_exists', file);
+        }
+        throw error;
+    }
+    let failure;
+    try {
+        for (let offset = 0; offset < data.byteLength;) {
+            const cut = cutNow();
+            if (cut) {
+                failure = cut;
+                break;
+            }
+            const { bytesWritten } = await handle.write(data, offset, Math.min(CHUNK_BYTES, data.byteLength - offset));
+            offset += bytesWritten;
+        }
+    }
+    catch (error) {
+        failure = error;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    if (failure === undefined && mode === 'create-or-replace') {
+        try {
+            await rename(file, target);
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    if (failure !== undefined) {
+        const removed = await removeQuietly(file);
+        if (failure instanceof EffectCut) {
+            throw removed ? failure : new EffectCut(failure.outcome, `${file} could not be removed`, true);
+        }
+        throw failure;
+    }
+    return { bytes: data.byteLength };
+}
+/**
+ * Removes `target` (already checked): one directory entry, a regular file.
+ * The removal is one system call: the call's `signal` and the effect's
+ * `timer` can stop it from starting, and once started it runs to its end.
+ */
+export async function removeAt(target, signal, timer) {
+    if (signal.aborted) {
+        throw new EffectCut('aborted', target);
+    }
+    if (timer.aborted) {
+        throw new EffectCut('timed_out', target);
+    }
+    await unlink(target);
+    return { bytes: 0 };
+}
+//# sourceMappingURL=fs-write.js.map

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview The paths no `fs.write` or `fs.delete` root may hold or lie
+ * inside: the library's own package directory, the `node_modules` directory
+ * it was loaded from, the directory of the process's entry script, and the
+ * paths the host lists in `protectedPaths`; and no root may pass through a
+ * directory named `node_modules`. The check is partial, and the
+ * documentation says so: the library cannot find a host's own code and data
+ * in general, so the host lists them.
+ * @module @framers/agentos/emergent/broker/protected
+ */
+/**
+ * The real paths a write or delete root may neither hold nor lie inside,
+ * computed once per engine: the library's package directory, the nearest
+ * `node_modules` above it, the entry script's directory, and the host's list.
+ */
+export declare function protectedRealPaths(hostPaths?: readonly string[]): string[];
+/** A root (by its real path) that holds or lies inside a protected path, or passes through `node_modules`. */
+export declare function isProtectedRoot(realRoot: string, protectedReal: readonly string[]): boolean;
+//# sourceMappingURL=protected.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protected.d.ts","sourceRoot":"","sources":["../../../../src/cognition/emergent/broker/protected.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiDH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,EAAE,CAoB9E;AAED,8GAA8G;AAC9G,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK3F"}

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

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview The paths no `fs.write` or `fs.delete` root may hold or lie
+ * inside: the library's own package directory, the `node_modules` directory
+ * it was loaded from, the directory of the process's entry script, and the
+ * paths the host lists in `protectedPaths`; and no root may pass through a
+ * directory named `node_modules`. The check is partial, and the
+ * documentation says so: the library cannot find a host's own code and data
+ * in general, so the host lists them.
+ * @module @framers/agentos/emergent/broker/protected
+ */
+import { readFileSync, realpathSync } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const PACKAGE_NAME = '@framers/agentos';
+function realOrResolved(candidate) {
+    const resolved = path.resolve(candidate);
+    try {
+        return realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/** Whether `candidate` is `root` or lies under it, by path segments. */
+function within(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+/** The directory of the package.json named `@framers/agentos` above this module, if one is found. */
+function libraryRoot() {
+    let dir;
+    try {
+        dir = path.dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return undefined;
+    }
+    for (let depth = 0; depth < 8; depth += 1) {
+        try {
+            const manifest = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+            if (manifest.name === PACKAGE_NAME) {
+                return dir;
+            }
+        }
+        catch {
+            // Not this directory; look one up.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * The real paths a write or delete root may neither hold nor lie inside,
+ * computed once per engine: the library's package directory, the nearest
+ * `node_modules` above it, the entry script's directory, and the host's list.
+ */
+export function protectedRealPaths(hostPaths = []) {
+    const found = new Set();
+    const library = libraryRoot();
+    if (library) {
+        const real = realOrResolved(library);
+        found.add(real);
+        const segments = real.split(path.sep);
+        const index = segments.lastIndexOf('node_modules');
+        if (index > 0) {
+            found.add(segments.slice(0, index + 1).join(path.sep));
+        }
+    }
+    const entry = process.argv[1];
+    if (typeof entry === 'string' && entry !== '') {
+        found.add(path.dirname(realOrResolved(entry)));
+    }
+    for (const hostPath of hostPaths) {
+        found.add(realOrResolved(hostPath));
+    }
+    return [...found];
+}
+/** A root (by its real path) that holds or lies inside a protected path, or passes through `node_modules`. */
+export function isProtectedRoot(realRoot, protectedReal) {
+    if (realRoot.split(path.sep).includes('node_modules')) {
+        return true;
+    }
+    return protectedReal.some((guarded) => within(realRoot, guarded) || within(guarded, realRoot));
+}
+//# sourceMappingURL=protected.js.map

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

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

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

@@ -11,6 +11,8 @@ import type { CapabilityName, SandboxAPI } from './types.js';
  * has one stored form.
  */
 export declare const CAPABILITY_NAMES: readonly CapabilityName[];
+/** The capabilities that change something outside the process: an isolating executor and a ceiling only. */
+export declare const EFFECT_CAPABILITIES: readonly CapabilityName[];
 /** Names accepted in a request that are not catalogue names. */
 export declare const CAPABILITY_ALIASES: Readonly<Record<string, CapabilityName>>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/cognition/emergent/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAAmC,CAAC;AAE1F,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAEvE,CAAC;AAaF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG;IAC5D,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAYA;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,EAAE,CAEnF"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/cognition/emergent/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAA4D,CAAC;AAEnH,4GAA4G;AAC5G,eAAO,MAAM,mBAAmB,EAAE,SAAS,cAAc,EAA8B,CAAC;AAExF,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAIvE,CAAC;AAoBF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG;IAC5D,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAYA;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,EAAE,CAEnF"}

package/dist/cognition/emergent/capabilities.js

@@ -9,10 +9,20 @@
  * its names in this order whatever order a request wrote them in, so one grant
  * has one stored form.
  */
-export const CAPABILITY_NAMES = ['fetch', 'fs.read', 'crypto'];
+export const CAPABILITY_NAMES = ['fetch', 'fs.read', 'fs.write', 'fs.delete', 'crypto'];
+/** The capabilities that change something outside the process: an isolating executor and a ceiling only. */
+export const EFFECT_CAPABILITIES = ['fs.write', 'fs.delete'];
 /** Names accepted in a request that are not catalogue names. */
 export const CAPABILITY_ALIASES = {
     'fs.readFile': 'fs.read',
+    'fs.writeFile': 'fs.write',
+    'fs.unlink': 'fs.delete',
+};
+/** The function each file capability injects into forged code. */
+const INJECTED = {
+    'fs.read': 'fs.readFile',
+    'fs.write': 'fs.writeFile',
+    'fs.delete': 'fs.unlink',
 };
 /** The catalogue name a request's name stands for, or `undefined` for a name outside the catalogue. */
 function catalogueNameOf(raw) {
@@ -45,6 +55,6 @@ export function normalizeAllowlist(names) {
 }
 /** The names `SandboxedToolForge` injects for a set of catalogue names. */
 export function toSandboxApis(capabilities) {
-    return capabilities.map((name) => (name === 'fs.read' ? 'fs.readFile' : name));
+    return capabilities.map((name) => INJECTED[name] ?? name);
 }
 //# sourceMappingURL=capabilities.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/cognition/emergent/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA8B,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAE1F,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAA6C;IAC1E,aAAa,EAAE,SAAS;CACzB,CAAC;AAEF,uGAAuG;AACvG,SAAS,eAAe,CAAC,GAAW;IAClC,0EAA0E;IAC1E,qCAAqC;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC;QACzE,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC;QACzB,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC;IAC1B,OAAQ,gBAAsC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;AACvG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IAIzD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;AACzF,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,YAAuC;IACnE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACjF,CAAC"}
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/cognition/emergent/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA8B,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;AAEnH,4GAA4G;AAC5G,MAAM,CAAC,MAAM,mBAAmB,GAA8B,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AAExF,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAA6C;IAC1E,aAAa,EAAE,SAAS;IACxB,cAAc,EAAE,UAAU;IAC1B,WAAW,EAAE,WAAW;CACzB,CAAC;AAEF,kEAAkE;AAClE,MAAM,QAAQ,GAA0D;IACtE,SAAS,EAAE,aAAa;IACxB,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,WAAW;CACzB,CAAC;AAEF,uGAAuG;AACvG,SAAS,eAAe,CAAC,GAAW;IAClC,0EAA0E;IAC1E,qCAAqC;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC;QACzE,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC;QACzB,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC;IAC1B,OAAQ,gBAAsC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;AACvG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IAIzD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;AACzF,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,YAAuC;IACnE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAK,IAAmB,CAAC,CAAC;AAC5E,CAAC"}

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

@@ -4,21 +4,41 @@
  * the check of a host-built forge's options against it.
  * @module @framers/agentos/emergent/ceiling
  */
-import type { CapabilityName, EmergentAuditConfig, ForgedCapabilities } from './types.js';
+import type { CapabilityName, EffectApproval, EmergentAuditConfig, ForgedCapabilities, HttpMethod } from './types.js';
+/** The methods that change state: an isolating executor, a request bound and an approval setting. */
+export declare const STATE_CHANGING_METHODS: readonly HttpMethod[];
 /** A ceiling with every default applied and every list normalised. */
 export interface ResolvedCeiling {
     fetch?: {
         domains: string[] | '*';
-        methods: Array<'GET' | 'HEAD'>;
+        methods: HttpMethod[];
         maxResponseBytes: number;
         maxRedirects: number;
         timeoutMs: number;
+        /** Set exactly when `methods` holds a state-changing method. */
+        maxRequestBytes?: number;
+        approval?: EffectApproval;
     };
     'fs.read'?: {
         roots: string[];
         maxBytesPerRead: number;
         timeoutMs: number;
     };
+    'fs.write'?: {
+        roots: string[];
+        mode: 'create-only' | 'create-or-replace';
+        maxBytesPerFile: number;
+        maxBytesPerCall: number;
+        maxFilesPerCall: number;
+        timeoutMs: number;
+        approval: EffectApproval;
+    };
+    'fs.delete'?: {
+        roots: string[];
+        maxFilesPerCall: number;
+        timeoutMs: number;
+        approval: EffectApproval;
+    };
     crypto?: true;
     audit: {
         store: 'storage' | 'none';
@@ -26,7 +46,7 @@ export interface ResolvedCeiling {
         retainDays?: number;
     };
 }
-export type CeilingErrorCode = 'unknown_capability' | 'root_not_absolute' | 'method_not_allowed' | 'invalid_domain' | 'invalid_bound' | 'invalid_audit' | 'audit_needs_storage' | 'forge_wider_than_ceiling';
+export type CeilingErrorCode = 'unknown_capability' | 'root_not_absolute' | 'method_not_allowed' | 'invalid_domain' | 'invalid_bound' | 'invalid_audit' | 'audit_needs_storage' | 'forge_wider_than_ceiling' | 'invalid_mode' | 'invalid_approval' | 'approval_not_available' | 'executor_does_not_isolate' | 'protected_path';
 /** A ceiling the engine cannot build; the message starts with the code and the key. */
 export declare class CeilingError extends Error {
     readonly code: CeilingErrorCode;
@@ -53,6 +73,21 @@ export declare const CEILING_DEFAULTS: {
 export declare function resolveCeiling(capabilities: ForgedCapabilities, audit: EmergentAuditConfig | undefined, options: {
     hasStorage: boolean;
 }): ResolvedCeiling;
+/**
+ * Whether a resolved ceiling grants anything that changes the world outside
+ * the process: a write, a delete or a state-changing method. Such a ceiling
+ * constructs only on an executor that declares `isolates: true`.
+ */
+export declare function grantsEffects(ceiling: ResolvedCeiling): boolean;
+/**
+ * Refuses a write or delete root that holds, or lies inside, a protected
+ * path, or that passes through a `node_modules` directory. Roots that exist
+ * are checked by their real paths now; one that does not exist yet is
+ * checked by the broker when its real path is first resolved.
+ *
+ * @throws CeilingError (`protected_path`) naming the capability's roots key.
+ */
+export declare function checkProtectedRoots(ceiling: ResolvedCeiling, protectedReal: readonly string[]): void;
 /** 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. */

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

@@ -1 +1 @@
-{"version":3,"file":"ceiling.d.ts","sourceRoot":"","sources":["../../../src/cognition/emergent/ceiling.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,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,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;AA6DX;;;;;;;;;GASG;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,CA4GjB;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;AAoBD;;;;;;;;;;;;GAYG;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,CAwCjB"}
+{"version":3,"file":"ceiling.d.ts","sourceRoot":"","sources":["../../../src/cognition/emergent/ceiling.ts"],"names":[],"mappings":"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"}