@celestea/studio 2.7.1

package/dist/runtime/context-snapshot.js

@@ -0,0 +1,113 @@
+/**
+ * Engine request -> host view (W725): the projection behind
+ * `GET /api/sessions/{id}/context`.
+ *
+ * The projection is deliberately thin and lossless in the direction that
+ * matters: everything the model sees comes from the agent loop's own
+ * `contextSnapshot()` (system prompt, post-trim derived history, tool schemas).
+ * This module never trims, filters or re-derives a single message — it only
+ * flattens the engine's `Message[]` into one display row per message, because
+ * the wire contract carries `content` as a string.
+ *
+ * Flattening rules (frozen; the frontend renders them verbatim):
+ *   - a message's content blocks are joined with "\n";
+ *   - a `tool_call` block contributes `[tool_call] <name> <compact JSON args>`;
+ *   - an assistant tool-call row carries the FIRST call's `tool_name` +
+ *     `tool_call_id` (`tool_name` = what it called, id = the call it made);
+ *   - a `tool` result row carries its own `tool_call_id`, resolved back to the
+ *     call's `tool_name` while the messages are walked in order.
+ */
+/** One message's content blocks as a single display string. */
+export function renderContent(content) {
+    return content
+        .map((block) => {
+        // W804: an image block is NOT a tool call; render it as a byte-free label.
+        if (block.type === "text")
+            return block.content;
+        if (block.type === "image")
+            return imageText(block.content);
+        return callText(block.content);
+    })
+        .join("\n");
+}
+/** W804: e.g. `[image] logo.png image/png 512x512 (attachment <sha>)`. */
+export function imageText(ref) {
+    const label = ref.name === undefined ? "" : ` ${ref.name}`;
+    return `[image]${label} ${ref.media_type} ${ref.width}x${ref.height} (attachment ${ref.attachment_id})`;
+}
+/** `Message[]` -> one view row each, resolving tool names in message order. */
+export function messageViews(messages) {
+    const names = new Map();
+    const rows = [];
+    for (const message of messages) {
+        const call = firstCall(message);
+        if (call !== null)
+            names.set(call.id, call.name);
+        rows.push(rowOf(message, names));
+    }
+    return rows;
+}
+/**
+ * The session's context as the engine assembled it. `runtime.contextSnapshot()`
+ * is the ONLY source; the fallback (a loop without the capability) reports the
+ * profile's system prompt and the composed tool schemas with no history.
+ */
+export function contextViewOf(runtime, fallback) {
+    const request = runtime.contextSnapshot();
+    if (request === null) {
+        return { model: fallback.model, system: fallback.system, tools: toolViews(fallback.tools), messages: [] };
+    }
+    return {
+        model: request.model,
+        system: request.system ?? "",
+        tools: toolViews(request.tools),
+        messages: messageViews(request.messages),
+    };
+}
+/**
+ * W769: the read-only view helpers the adapter's HTTP surface needs, so the
+ * adapter stays a router instead of an assembly site (it is at its size budget).
+ *
+ * `sessionContextOf` is `/api/sessions/{id}/context` for one already-composed
+ * runtime: the read-only view of a runtime the caller already resolved.
+ */
+export function sessionContextOf(runtime, profile) {
+    return contextViewOf(runtime, { model: profile.model, system: profile.system_prompt, tools: runtime.tools?.schemas() ?? [] });
+}
+/** Tool schemas pass through verbatim (name / description / parameters). */
+export function toolViews(specs) {
+    return specs.map((spec) => ({ name: spec.name, description: spec.description, parameters: spec.parameters }));
+}
+function rowOf(message, names) {
+    const row = { role: message.role, content: renderContent(message.content) };
+    const call = firstCall(message);
+    if (call !== null) {
+        row.tool_name = call.name;
+        row.tool_call_id = call.id;
+    }
+    const answered = message.tool_call_id;
+    if (answered !== null) {
+        row.tool_call_id = answered;
+        const name = names.get(answered);
+        if (name !== undefined)
+            row.tool_name = name;
+    }
+    return row;
+}
+function firstCall(message) {
+    for (const block of message.content)
+        if (block.type === "tool_call")
+            return block.content;
+    return null;
+}
+function callText(call) {
+    return `[tool_call] ${call.name} ${argsText(call.args)}`;
+}
+function argsText(args) {
+    try {
+        return JSON.stringify(args) ?? "null";
+    }
+    catch {
+        return "<unserializable args>";
+    }
+}

package/dist/runtime/engine-grants.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `effectiveGrantsOf` — the ONE reader of a session's grants (W516 §4.1/§4.3).
+ *
+ * Every rule here is fail-closed and "only widen":
+ *   1. file level: missing = no grants; bad JSON / unknown version / a
+ *      self-description that does not match the directory / `grants` not an
+ *      array = the WHOLE file is void + a warning (never repaired, never
+ *      guessed at);
+ *   2. entry level: an unknown `cap` or a wrong-typed `scope` drops THAT entry;
+ *   3. path scopes must be absolute, `realpath`-able directories, not `/`, not
+ *      the data dir, not `$HOME`, and a `write_roots` entry must not overlap a
+ *      read root (workspace/env/other grants) — all six must hold or the entry
+ *      is ignored;
+ *   4. roots are additive: the workspace and the env roots are never removed;
+ *   5. `unsandboxed` is only ever *consumed* by the provider policy, which
+ *      ignores it while bwrap works (`sandbox/provider.ts`) — this module only
+ *      validates it;
+ *   6. unparseable `net_hosts` entries are ignored one by one;
+ *   7. ignoring a bad entry is deliberate and the OPPOSITE of the env
+ *      `CELESTEA_TOOL_ROOTS` fail-closed rule: env is an operator posture where
+ *      a typo must be loud, grants are per-session widenings where "ignore" is
+ *      the safe side, while a hard failure would only push users toward
+ *      `CELESTEA_TOOL_GUARD=0`. Do NOT "unify" the two.
+ */
+/**
+ * W747: `sessionIdOfDir` moved to the engine (`@celestea/runtime`, host layer
+ * `host/engine-session.ts`) — the `<workspace>/<session>` id space is what that
+ * module already owns. Imported + re-exported here so every `./engine-grants.js`
+ * import of it keeps working, unchanged.
+ */
+import { sessionIdOfDir } from "@celestea/runtime";
+export { sessionIdOfDir };
+import type { GrantsAuditEventName } from "../store/grants-audit.js";
+import { type PermissionPreset } from "../store/permissions.js";
+import { type GrantRecord, type GrantsFile } from "../store/grants.js";
+/** The effective, widen-only grant set of ONE session instance. */
+export interface EffectiveGrants {
+    network: boolean;
+    readRoots: readonly string[];
+    writeRoots: readonly string[];
+    netHosts: readonly string[];
+    toolExtra: readonly string[];
+    unsandboxed: boolean;
+    /** W9: the permission baseline of the session (enforced by the sandbox/guard). */
+    workspaceWritable: boolean;
+    /** W9: tools the baseline removes from the face (before tool_extra adds). */
+    toolDeny: readonly string[];
+    /** Provenance for the audit trail / UI (`cap` + grant id + expiry). */
+    sources: ReadonlyArray<{
+        cap: string;
+        grantId: string;
+        expiresAt: number | null;
+    }>;
+}
+export declare const EMPTY_GRANTS: EffectiveGrants;
+export interface EffectiveGrantsResult {
+    grants: EffectiveGrants;
+    warnings: string[];
+}
+/** `unsandboxed` is only offered when the operator opts in (§2.2). */
+export declare function unsandboxedAvailable(env: NodeJS.ProcessEnv): boolean;
+/**
+ * W757: whether this session's `net_hosts` entries take effect AT ALL in this
+ * deployment.
+ *
+ * ONE definition, and deliberately the SAME construction path the engine mounts
+ * its tools with (`engineTools` → `httpOptions` → `HttpTargetPolicy.fromEnv`):
+ * `net_hosts` is merged into the allow side only, so an inactive env policy
+ * (neither `CELESTEA_HTTP_ALLOW` nor `CELESTEA_HTTP_DENY` set) drops the whole
+ * list — `netHostsIneffective` is exactly that verdict and this module never
+ * re-derives it (a second implementation would silently drift from the mount).
+ *
+ * `false` ⇒ the session holds `net_hosts` entries the deployment ignores
+ * entirely. Empty `net_hosts` ⇒ `true`: there is nothing to be dropped.
+ *
+ * Reporting only: the policy object is built and discarded, so no authorization
+ * decision here changes, and the union / deny-wins / fail-closed semantics of
+ * `ssrf.ts` stay exactly as they are.
+ */
+export declare function netHostsEffective(env: NodeJS.ProcessEnv, grants: EffectiveGrants): boolean;
+/** Read + validate; NEVER throws, only degrades with warnings (§4.1). */
+/**
+ * W9: read the session's permission baseline and intersect its grants into it
+ * (the permission is authoritative; grants only widen INSIDE it).
+ */
+export declare function effectiveGrantsOf(sessionDir: string | null, sessionId: string | null, env: NodeJS.ProcessEnv, now: number, presetHint?: string | null): EffectiveGrantsResult;
+/** Env-declared read roots, canonicalized best-effort (grant overlap check). */
+export declare function envReadRoots(env: NodeJS.ProcessEnv): string[];
+/**
+ * What the assembly layers may report back (W516 §4.4). Deliberately tiny and
+ * credential-free: no command text ever travels through here.
+ */
+export interface EngineGrantEvent {
+    event: GrantsAuditEventName;
+    cap?: string;
+    grant_id?: string;
+    provider?: string;
+    reason?: string;
+    detail?: string;
+}
+/** Sink bound to one session (see `session-grants.ts`). */
+export type EngineGrantAudit = (event: EngineGrantEvent) => void;
+/** Cap names currently in force (never paths) — `GET /api/status` (§5.7). */
+/**
+ * W9: validate a CUSTOM permission preset, reusing the grants root rules
+ * (`rejectRoot`) so a preset can never declare a root an equivalent
+ * `write_roots` grant would have been refused (data dir, $HOME, `/`,
+ * non-absolute, non-existent, credential-shaped, read-root overlap).
+ * Returns `conflict: true` for a built-in or already-taken id.
+ */
+export declare function validatePermissionPreset(raw: unknown, env: NodeJS.ProcessEnv, existingIds: readonly string[]): {
+    ok: true;
+    preset: PermissionPreset;
+} | {
+    ok: false;
+    error: string;
+    conflict?: boolean;
+};
+export declare function grantsActiveCaps(grants: EffectiveGrants): string[];
+/** Grant ids that are past their `expires_at` (the `expire` audit event). */
+export declare function expiredGrants(file: GrantsFile, now: number): GrantRecord[];

package/dist/runtime/engine-grants.js

@@ -0,0 +1,338 @@
+/**
+ * `effectiveGrantsOf` — the ONE reader of a session's grants (W516 §4.1/§4.3).
+ *
+ * Every rule here is fail-closed and "only widen":
+ *   1. file level: missing = no grants; bad JSON / unknown version / a
+ *      self-description that does not match the directory / `grants` not an
+ *      array = the WHOLE file is void + a warning (never repaired, never
+ *      guessed at);
+ *   2. entry level: an unknown `cap` or a wrong-typed `scope` drops THAT entry;
+ *   3. path scopes must be absolute, `realpath`-able directories, not `/`, not
+ *      the data dir, not `$HOME`, and a `write_roots` entry must not overlap a
+ *      read root (workspace/env/other grants) — all six must hold or the entry
+ *      is ignored;
+ *   4. roots are additive: the workspace and the env roots are never removed;
+ *   5. `unsandboxed` is only ever *consumed* by the provider policy, which
+ *      ignores it while bwrap works (`sandbox/provider.ts`) — this module only
+ *      validates it;
+ *   6. unparseable `net_hosts` entries are ignored one by one;
+ *   7. ignoring a bad entry is deliberate and the OPPOSITE of the env
+ *      `CELESTEA_TOOL_ROOTS` fail-closed rule: env is an operator posture where
+ *      a typo must be loud, grants are per-session widenings where "ignore" is
+ *      the safe side, while a hard failure would only push users toward
+ *      `CELESTEA_TOOL_GUARD=0`. Do NOT "unify" the two.
+ */
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute } from "node:path";
+import { httpOptions, isInside, parseIpRange, parseToolRoots } from "@celestea/tools";
+/**
+ * W747: `sessionIdOfDir` moved to the engine (`@celestea/runtime`, host layer
+ * `host/engine-session.ts`) — the `<workspace>/<session>` id space is what that
+ * module already owns. Imported + re-exported here so every `./engine-grants.js`
+ * import of it keeps working, unchanged.
+ */
+import { sessionIdOfDir } from "@celestea/runtime";
+export { sessionIdOfDir };
+import { loadStudioConfig } from "../config.js";
+import { isBuiltinPresetId, parsePreset } from "../store/permissions.js";
+import { effectivePermissionOf } from "./engine-permissions.js";
+import { readSessionTools } from "../store/session-tools.js";
+import { ENV_GRANTS_UNSANDBOXED, isExpired, knownSecretsOf, looksLikeCredential, readGrantsFile, } from "../store/grants.js";
+export const EMPTY_GRANTS = {
+    network: false,
+    readRoots: [],
+    writeRoots: [],
+    netHosts: [],
+    toolExtra: [],
+    unsandboxed: false,
+    workspaceWritable: true,
+    toolDeny: [],
+    sources: [],
+};
+/** `unsandboxed` is only offered when the operator opts in (§2.2). */
+export function unsandboxedAvailable(env) {
+    const raw = (env[ENV_GRANTS_UNSANDBOXED] ?? "").trim().toLowerCase();
+    return ["1", "true", "on", "yes"].includes(raw);
+}
+/**
+ * W757: whether this session's `net_hosts` entries take effect AT ALL in this
+ * deployment.
+ *
+ * ONE definition, and deliberately the SAME construction path the engine mounts
+ * its tools with (`engineTools` → `httpOptions` → `HttpTargetPolicy.fromEnv`):
+ * `net_hosts` is merged into the allow side only, so an inactive env policy
+ * (neither `CELESTEA_HTTP_ALLOW` nor `CELESTEA_HTTP_DENY` set) drops the whole
+ * list — `netHostsIneffective` is exactly that verdict and this module never
+ * re-derives it (a second implementation would silently drift from the mount).
+ *
+ * `false` ⇒ the session holds `net_hosts` entries the deployment ignores
+ * entirely. Empty `net_hosts` ⇒ `true`: there is nothing to be dropped.
+ *
+ * Reporting only: the policy object is built and discarded, so no authorization
+ * decision here changes, and the union / deny-wins / fail-closed semantics of
+ * `ssrf.ts` stay exactly as they are.
+ */
+export function netHostsEffective(env, grants) {
+    return httpOptions(env, { netHosts: grants.netHosts }).policy?.netHostsIneffective !== true;
+}
+/** Read + validate; NEVER throws, only degrades with warnings (§4.1). */
+/**
+ * W9: read the session's permission baseline and intersect its grants into it
+ * (the permission is authoritative; grants only widen INSIDE it).
+ */
+export function effectiveGrantsOf(sessionDir, sessionId, env, now, presetHint) {
+    const permission = effectivePermissionOf(sessionDir, sessionId, env, presetHint);
+    /**
+     * W860: the session's own DISABLED tool list is read HERE, through the same
+     * reader every other consumer of the effective grants goes through
+     * (`session-grants.ts` for the composed instance, `RealRuntimeAdapter.sessionTools`
+     * for `GET /api/tools?session=`). A void `tools.json` warns and changes no
+     * other cap; a session without a directory has nothing to read, so its
+     * `toolDeny` is exactly the permission baseline's.
+     */
+    // W878: both sidecars are self-describing, so the TRUSTED id from `resolve()`
+    // must be used; a null id with a real directory is a caller bug and degrades
+    // fail-closed (nothing readable) rather than falling back to path inference.
+    const sessionTools = sessionDir === null || sessionId === null ? { disabled: [], warnings: [] } : readSessionTools(sessionDir, sessionId);
+    const base = collectGrants(sessionDir, sessionId, env, now);
+    const merged = intersectGrants(base.grants, permission, env, sessionTools.disabled);
+    return { grants: merged.grants, warnings: [...permission.warnings, ...sessionTools.warnings, ...base.warnings, ...merged.warnings] };
+}
+function collectGrants(sessionDir, sessionId, env, now) {
+    if (sessionDir === null || sessionId === null)
+        return { grants: EMPTY_GRANTS, warnings: [] };
+    const read = readGrantsFile(sessionDir, sessionId);
+    if (!read.exists)
+        return { grants: EMPTY_GRANTS, warnings: [] };
+    if (read.file === undefined) {
+        const reason = read.error ?? "unreadable";
+        return { grants: EMPTY_GRANTS, warnings: [`grants_unreadable: ${reason} — the session runs with no grants`] };
+    }
+    return collect(read.file, env, now);
+}
+/**
+ * W9: the permission baseline is the ceiling. `network` is decided by the
+ * baseline; `write_roots` is dropped (with a warning) when the baseline allows
+ * no writes at all (read-only); reads/hosts stay additive; `unsandboxed` is
+ * `preset.unsandboxed && the operator env gate` (decision W9-b).
+ */
+function intersectGrants(grants, permission, env, sessionDisabled = []) {
+    const warnings = [];
+    /**
+     * W864: an `allPaths` baseline replaces BOTH root lists with the filesystem
+     * root. Both sides are required: `writeRoots` alone would leave the path
+     * guard denying `read_file`/`list_dir`, and bwrap without the rw bind.
+     * Scoping note: this is the ONLY cap `allPaths` moves — network, net_hosts,
+     * tool_extra, unsandboxed and the W860 toolDeny union keep their own rules.
+     */
+    const allPaths = permission.allPaths === true;
+    const writesAllowed = allPaths || permission.workspaceWritable || permission.toolRootsWritable || permission.writeRoots.length > 0;
+    if (!writesAllowed && grants.writeRoots.length > 0)
+        warnings.push("write_roots grant ignored: the session permission is read-only");
+    return {
+        grants: {
+            network: permission.network,
+            readRoots: allPaths ? ["/"] : grants.readRoots,
+            writeRoots: allPaths ? ["/"] : writesAllowed ? [...new Set([...permission.writeRoots, ...grants.writeRoots])] : [],
+            netHosts: grants.netHosts,
+            toolExtra: grants.toolExtra,
+            unsandboxed: (permission.unsandboxed || grants.unsandboxed) && unsandboxedAvailable(env),
+            workspaceWritable: permission.workspaceWritable,
+            // W860: preset deny first, session-level deny second, deduped. Both are
+            // pure SUBTRACTION, so a name the `execution` mode already folded away can
+            // never come back through this list (engine-plugins keeps them blocked).
+            toolDeny: [...new Set([...permission.toolDeny, ...sessionDisabled])],
+            sources: grants.sources,
+        },
+        warnings,
+    };
+}
+/** Fold the (already shape-checked) entries into the effective set. */
+function collect(file, env, now) {
+    const warnings = [];
+    const acc = { readRoots: [], writeRoots: [], netHosts: [], toolExtra: [], sources: [] };
+    const ctx = { env, known: knownSecretsOf(env), readRoots: envReadRoots(env) };
+    for (const grant of file.grants) {
+        if (isExpired(grant, now)) {
+            warnings.push(`grant ${grant.id} (${grant.cap}) has expired — ignored`);
+            continue;
+        }
+        applyGrant(acc, grant, ctx, warnings);
+    }
+    return { grants: { ...acc, network: acc.network === true, unsandboxed: acc.unsandboxed === true, workspaceWritable: true, toolDeny: [] }, warnings };
+}
+/** `entry`, or a placeholder when the value must not be echoed (§5.4). */
+function show(entry, ctx) {
+    return looksLikeCredential(entry, ctx.known) ? "<value looks like a credential>" : entry;
+}
+function applyGrant(acc, grant, ctx, warnings) {
+    const keep = () => {
+        acc.sources.push({ cap: grant.cap, grantId: grant.id, expiresAt: grant.expires_at });
+    };
+    if (grant.cap === "network") {
+        acc.network = true;
+        keep();
+        return;
+    }
+    if (grant.cap === "unsandboxed") {
+        acc.unsandboxed = true;
+        keep();
+        return;
+    }
+    if (grant.cap === "read_roots" || grant.cap === "write_roots") {
+        const roots = rootsOf(grant, { ...ctx, readRoots: [...ctx.readRoots, ...acc.readRoots] }, warnings);
+        if (roots.length === 0)
+            return;
+        if (grant.cap === "read_roots")
+            acc.readRoots.push(...roots);
+        else
+            acc.writeRoots.push(...roots);
+        keep();
+        return;
+    }
+    if (grant.cap === "net_hosts") {
+        const hosts = (grant.scope.hosts ?? []).filter((h) => isHostEntry(h) || isIpEntry(h));
+        if (hosts.length === 0) {
+            warnings.push(`grant ${grant.id} (net_hosts): no usable host (dropped: ${(grant.scope.hosts ?? []).map((h) => show(h, ctx)).join(", ")}) — ignored`);
+            return;
+        }
+        acc.netHosts.push(...hosts);
+        keep();
+        return;
+    }
+    const tools = (grant.scope.tools ?? []).filter((t) => /^[a-z][a-z0-9_]{0,63}$/.test(t));
+    if (tools.length === 0) {
+        warnings.push(`grant ${grant.id} (tool_extra) holds no usable tool name — ignored`);
+        return;
+    }
+    acc.toolExtra.push(...tools);
+    keep();
+}
+/** The six path rules of §4.3.3 — ALL must hold, else the whole entry is dropped. */
+function rootsOf(grant, ctx, warnings) {
+    const raw = grant.scope.roots ?? [];
+    const canonical = [];
+    for (const entry of raw) {
+        const rejected = rejectRoot(entry, { ...ctx, readRoots: [...ctx.readRoots, ...canonical] }, grant);
+        if (rejected !== null) {
+            warnings.push(`grant ${grant.id} (${grant.cap}): ${rejected} — the entry is ignored`);
+            return [];
+        }
+        const resolved = canonicalPath(entry);
+        if (resolved !== null)
+            canonical.push(resolved);
+    }
+    return canonical.length === 0 ? [] : [...new Set(canonical)];
+}
+/** `null` = usable; otherwise the reason (never echoing a credential value). */
+function rejectRoot(entry, ctx, grant) {
+    if (looksLikeCredential(entry, ctx.known))
+        return "the value looks like a credential";
+    if (!isAbsolute(entry))
+        return `root '${show(entry, ctx)}' is not absolute`;
+    const resolved = canonicalPath(entry);
+    if (resolved === null)
+        return `root '${show(entry, ctx)}' does not exist`;
+    if (!isDirectory(resolved))
+        return `root '${show(entry, ctx)}' is not a directory`;
+    if (resolved === "/")
+        return "root '/' is the filesystem root";
+    const dataDir = canonicalPath(dirname(loadStudioConfig({ env: ctx.env }).paths.workspacesFile));
+    if (dataDir !== null && (isInside(dataDir, resolved) || dataDir === resolved))
+        return "root covers the studio data directory";
+    const home = canonicalPath(ctx.env["HOME"] ?? homedir());
+    if (home !== null && resolved === home)
+        return "root is $HOME";
+    if (grant.cap === "write_roots") {
+        const clash = ctx.readRoots.find((root) => isInside(resolved, root) || isInside(root, resolved));
+        if (clash !== undefined)
+            return `write root overlaps the read root '${clash}'`;
+    }
+    return null;
+}
+function canonicalPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Env-declared read roots, canonicalized best-effort (grant overlap check). */
+export function envReadRoots(env) {
+    const out = [];
+    for (const entry of parseToolRoots(env["CELESTEA_TOOL_ROOTS"])) {
+        const resolved = canonicalPath(entry);
+        if (resolved !== null)
+            out.push(resolved);
+    }
+    return out;
+}
+function isIpEntry(entry) {
+    try {
+        parseIpRange(entry);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isHostEntry(entry) {
+    return /^(?=.{1,253}$)[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i.test(entry);
+}
+/** Cap names currently in force (never paths) — `GET /api/status` (§5.7). */
+/**
+ * W9: validate a CUSTOM permission preset, reusing the grants root rules
+ * (`rejectRoot`) so a preset can never declare a root an equivalent
+ * `write_roots` grant would have been refused (data dir, $HOME, `/`,
+ * non-absolute, non-existent, credential-shaped, read-root overlap).
+ * Returns `conflict: true` for a built-in or already-taken id.
+ */
+export function validatePermissionPreset(raw, env, existingIds) {
+    const parsed = parsePreset(raw);
+    if (parsed === null)
+        return { ok: false, error: "preset must be an object with a valid id ([a-z][a-z0-9_-]{0,63})" };
+    if (isBuiltinPresetId(parsed.id) || existingIds.includes(parsed.id)) {
+        return { ok: false, error: "preset '" + parsed.id + "' already exists", conflict: true };
+    }
+    const ctx = { env, known: knownSecretsOf(env), readRoots: envReadRoots(env) };
+    const roots = [];
+    for (const entry of parsed.writeRoots) {
+        const rejected = rejectRoot(entry, ctx, { cap: "write_roots" });
+        if (rejected !== null)
+            return { ok: false, error: "write root '" + entry + "': " + rejected };
+        const resolved = canonicalPath(entry);
+        if (resolved !== null && !roots.includes(resolved))
+            roots.push(resolved);
+    }
+    return { ok: true, preset: { ...parsed, writeRoots: roots } };
+}
+export function grantsActiveCaps(grants) {
+    const caps = [];
+    if (grants.network)
+        caps.push("network");
+    if (grants.readRoots.length > 0)
+        caps.push("read_roots");
+    if (grants.writeRoots.length > 0)
+        caps.push("write_roots");
+    if (grants.netHosts.length > 0)
+        caps.push("net_hosts");
+    if (grants.toolExtra.length > 0)
+        caps.push("tool_extra");
+    if (grants.unsandboxed)
+        caps.push("unsandboxed");
+    return caps;
+}
+/** Grant ids that are past their `expires_at` (the `expire` audit event). */
+export function expiredGrants(file, now) {
+    return file.grants.filter((grant) => isExpired(grant, now));
+}

package/dist/runtime/engine-permissions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * effectivePermissionOf (W9) - the ONE reader of a session's permission
+ * BASELINE. engine-grants.ts intersects grants into it.
+ *
+ * Resolution of the requested preset:
+ *   1. the caller hint (worker sessions have no directory and carry it in meta);
+ *   2. <session dir>/permission.json;
+ *   3. CELESTEA_PERMISSION_DEFAULT (default "full-access").
+ * The baseline capabilities are then CLAMPED by CELESTEA_PERMISSION_MAX
+ * (default "full-access"). The operator env gate for "unsandboxed" is applied
+ * by engine-grants.ts when it builds the final EffectiveGrants, so this module
+ * never imports engine-grants (no cycle).
+ */
+export interface PermissionBaseline {
+    preset: string;
+    network: boolean;
+    workspaceWritable: boolean;
+    toolRootsWritable: boolean;
+    writeRoots: readonly string[];
+    /** W864: the whole filesystem is readable + writable (never env-gated). */
+    allPaths: boolean;
+    /** The preset capability; the env gate is applied by engine-grants.ts. */
+    unsandboxed: boolean;
+    toolDeny: readonly string[];
+    warnings: readonly string[];
+}
+/** The data dir of the studio (same one workspaces.json / auth secret use). */
+export declare function permissionDataDir(env: NodeJS.ProcessEnv): string;
+export declare function effectivePermissionOf(sessionDir: string | null, sessionId: string | null, env: NodeJS.ProcessEnv, presetHint?: string | null): PermissionBaseline;