@celestea/studio 2.7.1

package/dist/store/grants-tokens.js

@@ -0,0 +1,105 @@
+/**
+ * Confirm tokens + abuse limits for the grant endpoints (W516 §5.5, §6.4).
+ *
+ * A grant can only be POSTed with a one-shot token that a BROWSER interaction
+ * obtained: `GET /api/sessions/{id}/grants/confirm-token` requires same-origin
+ * evidence, so the session's own `http_request` tool cannot mint one even when
+ * it can reach `127.0.0.1` (a tool call carries no browser `Sec-Fetch-*`
+ * headers). The token is bound to `(session, cap, scope_hash)`, lives 60s and
+ * is burned on first use.
+ *
+ * The limiter is the anti-confirmation-fatigue half: at most 3 grant requests
+ * per session per minute (429), and 3 consecutive rejections put that session in
+ * a 5-minute cooldown (409 + remaining seconds).
+ */
+export const CONFIRM_HEADER = "x-celestea-grant-confirm";
+export const SEC_FETCH_SITE = "sec-fetch-site";
+export const SEC_FETCH_MODE = "sec-fetch-mode";
+export const ORIGIN_HEADER = "origin";
+export const CONFIRM_TTL_SEC = 60;
+export const RATE_LIMIT_MAX = 3;
+export const RATE_LIMIT_WINDOW_MS = 60_000;
+export const DENIAL_THRESHOLD = 3;
+export const DENIAL_COOLDOWN_MS = 5 * 60_000;
+/** One-shot `(session, cap, scope_hash)` tokens with a 60s TTL. */
+export class GrantTokenStore {
+    now;
+    tokens = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    issue(session, cap, scopeHash) {
+        this.gc();
+        const token = randomToken();
+        const expiresAt = Math.floor(this.now() / 1000) + CONFIRM_TTL_SEC;
+        this.tokens.set(token, { token, session, cap, scopeHash, expiresAt, used: false });
+        return { token, expiresAt };
+    }
+    /**
+     * Burn the token. `used` is reported separately from `invalid` so the caller
+     * can answer `409 confirmation token already used` (a replay) instead of 403.
+     */
+    consume(session, cap, scopeHash, token) {
+        this.gc();
+        const found = this.tokens.get(token);
+        if (found === undefined)
+            return "invalid";
+        if (found.session !== session || found.cap !== cap || found.scopeHash !== scopeHash)
+            return "invalid";
+        if (found.used)
+            return "used";
+        found.used = true;
+        return "ok";
+    }
+    /** Drop only EXPIRED tokens: a burned one must stay recognizable as `used`. */
+    gc() {
+        const deadline = Math.floor(this.now() / 1000);
+        for (const [key, value] of this.tokens)
+            if (value.expiresAt <= deadline)
+                this.tokens.delete(key);
+    }
+}
+/** Per-session grant-request rate limit + consecutive-denial cooldown. */
+export class GrantRateLimiter {
+    now;
+    hits = new Map();
+    denials = new Map();
+    cooldown = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** Called once per POST attempt, before validation. */
+    allow(session) {
+        const now = this.now();
+        const until = this.cooldown.get(session) ?? 0;
+        if (now < until)
+            return { ok: false, status: 409, retryAfterSec: Math.ceil((until - now) / 1000) };
+        const recent = (this.hits.get(session) ?? []).filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
+        if (recent.length >= RATE_LIMIT_MAX) {
+            const oldest = recent[recent.length - RATE_LIMIT_MAX] ?? now;
+            return { ok: false, status: 429, retryAfterSec: Math.max(1, Math.ceil((oldest + RATE_LIMIT_WINDOW_MS - now) / 1000)) };
+        }
+        recent.push(now);
+        this.hits.set(session, recent);
+        return { ok: true };
+    }
+    /** A rejected request counts toward the cooldown; a grant resets it. */
+    recordDenial(session) {
+        const count = (this.denials.get(session) ?? 0) + 1;
+        if (count >= DENIAL_THRESHOLD) {
+            this.denials.set(session, 0);
+            this.cooldown.set(session, this.now() + DENIAL_COOLDOWN_MS);
+            return;
+        }
+        this.denials.set(session, count);
+    }
+    recordSuccess(session) {
+        this.denials.set(session, 0);
+        this.cooldown.delete(session);
+    }
+}
+function randomToken() {
+    const bytes = new Uint8Array(24);
+    globalThis.crypto.getRandomValues(bytes);
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/dist/store/grants.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `<session dir>/grants.json` — the session's grant file (W516 §2.1, §5.4).
+ *
+ * The file is the ONLY source of a session's widenings and it is deliberately
+ * hostile-input-shaped: it lives next to `session.json` inside a workspace, so
+ * anything that can write the workspace can write it (including a session's own
+ * tools) — therefore every field is whitelisted, every value is validated, and
+ * a corrupt file means "no grants at all" rather than "repair it".
+ *
+ * Durability: `<path>.tmp` → rename (`fs-json.ts`) with mode 0600, like
+ * `providers.json`. Redaction: the `note` field is redacted before it is
+ * written, and a `roots`/`hosts`/`tools` value that LOOKS like a credential is
+ * rejected (400 at the endpoint, dropped entry when hand-edited) — no response,
+ * audit line or UI ever echoes such a value back.
+ *
+ * `grants.json` is NOT a session registry file: it is absent by default (that is
+ * the normal, least-privilege state) and it is not part of
+ * `contracts/data-files/index.json`.
+ */
+export declare const GRANTS_FILE = "grants.json";
+/** Env var enabling the `unsandboxed` cap (§2.2: hidden in the UI by default). */
+export declare const ENV_GRANTS_UNSANDBOXED = "CELESTEA_GRANTS_ALLOW_UNSANDBOXED";
+/** Default `ttl_sec` the UI pre-fills (§2.3). */
+export declare const DEFAULT_TTL_SEC = 1800;
+/** Cap on scope values (`roots`/`hosts`/`tools` entries). */
+export declare const MAX_SCOPE_VALUE_CHARS = 200;
+/** Cap on the number of entries per scope list. */
+export declare const MAX_SCOPE_ENTRIES = 32;
+export type GrantCap = "network" | "read_roots" | "write_roots" | "net_hosts" | "tool_extra" | "unsandboxed";
+export declare const GRANT_CAPS: readonly GrantCap[];
+/**
+ * W819-8: caps that are KNOWN and still read back (GRANT_CAPS) but are NOT
+ * offered any more. tool_extra is documented as reserved for future
+ * browser/net tools and no tool-exposure point ever consumed it, so offering
+ * it as a capability the deployment could honour was false. Stored entries
+ * keep parsing, echoing and warning; they just cannot be newly granted.
+ */
+export declare const RESERVED_GRANT_CAPS: readonly GrantCap[];
+/** Per-cap TTL ceiling, enforced by the SERVER (§2.3). */
+export declare const MAX_TTL_SEC: Readonly<Record<GrantCap, number>>;
+/** Scope of one grant entry: at most one of these lists is meaningful per cap. */
+export interface GrantScope {
+    roots?: string[];
+    hosts?: string[];
+    tools?: string[];
+}
+export interface GrantRecord {
+    id: string;
+    cap: GrantCap;
+    scope: GrantScope;
+    granted_at: number;
+    granted_by: string;
+    /** Absolute unix seconds; null = no expiry. */
+    expires_at: number | null;
+    /** null = unlimited; 1 = single use (forced for `unsandboxed`). */
+    uses_left: number | null;
+    note: string;
+}
+export interface GrantsFile {
+    version: number;
+    /** Self-description `<workspace>/<session>`; a mismatch voids the whole file. */
+    session: string;
+    updated_at: number;
+    grants: GrantRecord[];
+}
+export type GrantsRead = {
+    exists: boolean;
+    file?: GrantsFile;
+    error?: string;
+};
+/** The env-side secret set (`collectKnownSecrets`) used by [looksLikeCredential]. */
+export declare function knownSecretsOf(env?: NodeJS.ProcessEnv): string[];
+/** Shape-only credential screen (W516 §5.4) — never echoes the value. */
+export declare function looksLikeCredential(value: string, known: readonly string[]): boolean;
+export declare function isGrantCap(value: unknown): value is GrantCap;
+/** Known AND currently offerable (reserved caps are deliberately excluded). */
+export declare function isOfferedGrantCap(value: unknown): value is GrantCap;
+export declare function maxTtlOf(cap: GrantCap): number;
+/** Random, revocable-audit-stable id (`g-` + 8 hex, §2.1). */
+export declare function newGrantId(): string;
+export declare function emptyGrantsFile(session: string, now: number): GrantsFile;
+/** Canonical scope JSON — the `scope_hash` input shared with the UI (§6.4). */
+export declare function canonicalScopeJson(cap: string, scope: GrantScope): string;
+/** sha256 hex of [canonicalScopeJson] — the `scope_hash` of §6.4. */
+export declare function canonicalScopeHash(cap: string, scope: GrantScope): string;
+/**
+ * Validate + normalize one scope. Unknown keys are dropped (whitelist), values
+ * are credential-screened, and a wrong type is a 400-shaped error string.
+ */
+export declare function validateScope(cap: GrantCap, raw: unknown, known: readonly string[]): {
+    ok: true;
+    scope: GrantScope;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Read + validate the file. `exists:false` = the normal least-privilege state.
+ * Any structural problem (bad JSON, unknown version, self-description mismatch,
+ * `grants` not an array) returns `{exists:true, error}` and NO file: the caller
+ * turns that into an empty grant set plus a `grants_unreadable` audit line.
+ */
+export declare function readGrantsFile(dir: string, expectedSession: string): GrantsRead;
+/**
+ * Atomic 0600 write of the whitelisted, redacted file. `now` drives the lazy
+ * GC: expired entries are dropped here, on the next write (§2.3 — no timers).
+ */
+export declare function writeGrantsFile(dir: string, file: GrantsFile, opts: {
+    env?: NodeJS.ProcessEnv;
+    now: number;
+}): void;
+/** Expiry is evaluated at READ time (`now >= expires_at`, §2.3). */
+export declare function isExpired(grant: Pick<GrantRecord, "expires_at">, now: number): boolean;

package/dist/store/grants.js

@@ -0,0 +1,238 @@
+/**
+ * `<session dir>/grants.json` — the session's grant file (W516 §2.1, §5.4).
+ *
+ * The file is the ONLY source of a session's widenings and it is deliberately
+ * hostile-input-shaped: it lives next to `session.json` inside a workspace, so
+ * anything that can write the workspace can write it (including a session's own
+ * tools) — therefore every field is whitelisted, every value is validated, and
+ * a corrupt file means "no grants at all" rather than "repair it".
+ *
+ * Durability: `<path>.tmp` → rename (`fs-json.ts`) with mode 0600, like
+ * `providers.json`. Redaction: the `note` field is redacted before it is
+ * written, and a `roots`/`hosts`/`tools` value that LOOKS like a credential is
+ * rejected (400 at the endpoint, dropped entry when hand-edited) — no response,
+ * audit line or UI ever echoes such a value back.
+ *
+ * `grants.json` is NOT a session registry file: it is absent by default (that is
+ * the normal, least-privilege state) and it is not part of
+ * `contracts/data-files/index.json`.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { collectKnownSecrets, createRedactor } from "@celestea/core";
+import { readJsonIfExists, writeJsonAtomic } from "./fs-json.js";
+export const GRANTS_FILE = "grants.json";
+/** Env var enabling the `unsandboxed` cap (§2.2: hidden in the UI by default). */
+export const ENV_GRANTS_UNSANDBOXED = "CELESTEA_GRANTS_ALLOW_UNSANDBOXED";
+/** Default `ttl_sec` the UI pre-fills (§2.3). */
+export const DEFAULT_TTL_SEC = 1800;
+/** Cap on scope values (`roots`/`hosts`/`tools` entries). */
+export const MAX_SCOPE_VALUE_CHARS = 200;
+/** Cap on the number of entries per scope list. */
+export const MAX_SCOPE_ENTRIES = 32;
+export const GRANT_CAPS = ["network", "read_roots", "write_roots", "net_hosts", "tool_extra", "unsandboxed"];
+/**
+ * W819-8: caps that are KNOWN and still read back (GRANT_CAPS) but are NOT
+ * offered any more. tool_extra is documented as reserved for future
+ * browser/net tools and no tool-exposure point ever consumed it, so offering
+ * it as a capability the deployment could honour was false. Stored entries
+ * keep parsing, echoing and warning; they just cannot be newly granted.
+ */
+export const RESERVED_GRANT_CAPS = ["tool_extra"];
+/** Per-cap TTL ceiling, enforced by the SERVER (§2.3). */
+export const MAX_TTL_SEC = {
+    network: 3600,
+    read_roots: 86400,
+    write_roots: 86400,
+    net_hosts: 86400,
+    tool_extra: 86400,
+    unsandboxed: 900,
+};
+/** The env-side secret set (`collectKnownSecrets`) used by [looksLikeCredential]. */
+export function knownSecretsOf(env = process.env) {
+    return collectKnownSecrets({ env });
+}
+/** Shape-only credential screen (W516 §5.4) — never echoes the value. */
+export function looksLikeCredential(value, known) {
+    if (value.trim() !== value || /[\r\n]/.test(value))
+        return true;
+    if (createRedactor(known).redact(value) !== value)
+        return true;
+    return false;
+}
+export function isGrantCap(value) {
+    return typeof value === "string" && GRANT_CAPS.includes(value);
+}
+/** Known AND currently offerable (reserved caps are deliberately excluded). */
+export function isOfferedGrantCap(value) {
+    return isGrantCap(value) && !RESERVED_GRANT_CAPS.includes(value);
+}
+export function maxTtlOf(cap) {
+    return MAX_TTL_SEC[cap];
+}
+/** Random, revocable-audit-stable id (`g-` + 8 hex, §2.1). */
+export function newGrantId() {
+    const hex = Math.floor(Math.random() * 0xffff_ffff)
+        .toString(16)
+        .padStart(8, "0");
+    return `g-${hex}`;
+}
+export function emptyGrantsFile(session, now) {
+    return { version: 1, session, updated_at: now, grants: [] };
+}
+/** Canonical scope JSON — the `scope_hash` input shared with the UI (§6.4). */
+export function canonicalScopeJson(cap, scope) {
+    const keys = Object.keys(scope).sort();
+    const out = {};
+    for (const key of keys) {
+        const value = scope[key];
+        if (value === undefined)
+            continue;
+        out[key] = [...value].sort();
+    }
+    return JSON.stringify({ cap, scope: out });
+}
+/** sha256 hex of [canonicalScopeJson] — the `scope_hash` of §6.4. */
+export function canonicalScopeHash(cap, scope) {
+    return createHash("sha256").update(canonicalScopeJson(cap, scope)).digest("hex");
+}
+/**
+ * Validate + normalize one scope. Unknown keys are dropped (whitelist), values
+ * are credential-screened, and a wrong type is a 400-shaped error string.
+ */
+export function validateScope(cap, raw, known) {
+    const source = raw === undefined || raw === null ? {} : raw;
+    if (typeof source !== "object" || Array.isArray(source))
+        return { ok: false, error: "scope must be an object" };
+    const rec = source;
+    const key = SCOPE_KEY[cap];
+    if (key === null)
+        return { ok: true, scope: {} };
+    const values = rec[key];
+    if (values === undefined || values === null)
+        return { ok: false, error: `scope.${key} is required` };
+    if (!Array.isArray(values))
+        return { ok: false, error: `scope.${key} must be an array of strings` };
+    if (values.length === 0)
+        return { ok: false, error: `scope.${key} must not be empty` };
+    if (values.length > MAX_SCOPE_ENTRIES)
+        return { ok: false, error: `scope.${key} holds more than ${MAX_SCOPE_ENTRIES} entries` };
+    const out = [];
+    for (const value of values) {
+        if (typeof value !== "string" || value.trim() === "")
+            return { ok: false, error: `scope.${key} entries must be non-empty strings` };
+        if (value.length > MAX_SCOPE_VALUE_CHARS)
+            return { ok: false, error: `scope.${key} entry is longer than ${MAX_SCOPE_VALUE_CHARS} chars` };
+        if (looksLikeCredential(value, known))
+            return { ok: false, error: "value looks like a credential" };
+        out.push(value.trim());
+    }
+    return { ok: true, scope: { [key]: [...new Set(out)] } };
+}
+const SCOPE_KEY = {
+    network: null,
+    unsandboxed: null,
+    read_roots: "roots",
+    write_roots: "roots",
+    net_hosts: "hosts",
+    tool_extra: "tools",
+};
+/**
+ * Read + validate the file. `exists:false` = the normal least-privilege state.
+ * Any structural problem (bad JSON, unknown version, self-description mismatch,
+ * `grants` not an array) returns `{exists:true, error}` and NO file: the caller
+ * turns that into an empty grant set plus a `grants_unreadable` audit line.
+ */
+export function readGrantsFile(dir, expectedSession) {
+    const out = readJsonIfExists(join(dir, GRANTS_FILE));
+    if (!out.exists)
+        return { exists: false };
+    if (out.error !== undefined)
+        return { exists: true, error: `unparsable grants.json: ${out.error}` };
+    const value = out.value;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return { exists: true, error: "grants.json is not an object" };
+    const rec = value;
+    if (rec["version"] !== 1)
+        return { exists: true, error: `unknown grants.json version '${String(rec["version"])}'` };
+    if (rec["session"] !== expectedSession)
+        return { exists: true, error: `grants.json belongs to '${String(rec["session"])}'` };
+    if (!Array.isArray(rec["grants"]))
+        return { exists: true, error: "grants.json has no grants array" };
+    const grants = [];
+    rec["grants"].forEach((entry, index) => {
+        const parsed = parseGrantEntry(entry, index);
+        if (parsed !== null)
+            grants.push(parsed);
+    });
+    const updated = typeof rec["updated_at"] === "number" ? rec["updated_at"] : 0;
+    return { exists: true, file: { version: 1, session: expectedSession, updated_at: updated, grants } };
+}
+/** Whitelist one entry; `null` = unusable row (dropped, never guessed at). */
+function parseGrantEntry(raw, index) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const rec = raw;
+    if (!isGrantCap(rec["cap"]))
+        return null;
+    const id = typeof rec["id"] === "string" && rec["id"] !== "" ? rec["id"] : `g-invalid-${index}`;
+    const scope = isGrantCap(rec["cap"]) ? normalizeStoredScope(rec["cap"], rec["scope"]) : {};
+    return {
+        id,
+        cap: rec["cap"],
+        scope,
+        granted_at: numberOr(rec["granted_at"], 0),
+        granted_by: typeof rec["granted_by"] === "string" ? rec["granted_by"] : "",
+        expires_at: numberOrNull(rec["expires_at"]),
+        uses_left: numberOrNull(rec["uses_left"]),
+        note: typeof rec["note"] === "string" ? rec["note"] : "",
+    };
+}
+function normalizeStoredScope(cap, raw) {
+    const key = SCOPE_KEY[cap];
+    if (key === null)
+        return {};
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return {};
+    const values = raw[key];
+    if (!Array.isArray(values))
+        return {};
+    return { [key]: values.filter((v) => typeof v === "string") };
+}
+function numberOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function numberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Atomic 0600 write of the whitelisted, redacted file. `now` drives the lazy
+ * GC: expired entries are dropped here, on the next write (§2.3 — no timers).
+ */
+export function writeGrantsFile(dir, file, opts) {
+    const redactor = createRedactor(knownSecretsOf(opts.env ?? process.env));
+    const body = {
+        version: 1,
+        session: file.session,
+        updated_at: opts.now,
+        grants: file.grants.filter((g) => !isExpired(g, opts.now)).map((g) => sanitizeGrant(g, redactor.redact(g.note))),
+    };
+    writeJsonAtomic(join(dir, GRANTS_FILE), body, { mode: 0o600 });
+}
+/** Field whitelist: unknown fields are DROPPED, never passed through (§5.4). */
+function sanitizeGrant(grant, note) {
+    return {
+        id: grant.id,
+        cap: grant.cap,
+        scope: normalizeStoredScope(grant.cap, grant.scope),
+        granted_at: grant.granted_at,
+        granted_by: grant.granted_by,
+        expires_at: grant.expires_at,
+        uses_left: grant.uses_left,
+        note,
+    };
+}
+/** Expiry is evaluated at READ time (`now >= expires_at`, §2.3). */
+export function isExpired(grant, now) {
+    return grant.expires_at !== null && now >= grant.expires_at;
+}

package/dist/store/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Studio data stores — the public surface of this directory.
+ *
+ * Module map:
+ *   fs-json.ts          atomic JSON read/write + dir helpers (durability map)
+ *   result.ts           StoreResult / StoreFailure + `{e}` formatting
+ *   session-id.ts       sanitize / parse `<ws>/<session>` / name validation
+ *   mode.ts             session mode vocabulary (standard | execution, W729)
+ *   session-meta.ts     `<dir>/session.json` (model + prompt binding + mode)
+ *   validate.ts         model / prompt-id / url / effort validation
+ *   builtin-sections.ts frozen 10-row builtin prompt registry (data only)
+ *   prompts-template.ts `{{var}}` scan / validate / render
+ *   celestea-home.ts    CELESTEA_HOME data-root re-export (W880)
+ *   prompts.ts          prompts.json + <CELESTEA_HOME>/.../prompts.json registry
+ *   prompts-compose.ts  build_gen assembly + active-prompt chain
+ *   workspaces.ts       workspaces.json v2 registry (+ folder rename)
+ *   sessions.ts         session scan / resolve / create / transcript
+ *   session-ops.ts      rename / branch / archive / trash moves
+ *   providers.ts        providers.json (0600) + public_view redaction
+ *   provider-probe.ts   /models probe incl. keyless same-origin borrow
+ */
+export * from "./result.js";
+export * from "./fs-json.js";
+export * from "./session-id.js";
+export * from "./mode.js";
+export * from "./session-meta.js";
+export * from "./validate.js";
+export * from "./builtin-sections.js";
+export * from "./prompts-template.js";
+export * from "./prompts.js";
+export * from "./prompts-compose.js";
+export * from "./workspaces.js";
+export * from "./sessions.js";
+export * from "./session-ops.js";
+export * from "./providers.js";
+export * from "./provider-probe.js";

package/dist/store/index.js

@@ -0,0 +1,36 @@
+/**
+ * Studio data stores — the public surface of this directory.
+ *
+ * Module map:
+ *   fs-json.ts          atomic JSON read/write + dir helpers (durability map)
+ *   result.ts           StoreResult / StoreFailure + `{e}` formatting
+ *   session-id.ts       sanitize / parse `<ws>/<session>` / name validation
+ *   mode.ts             session mode vocabulary (standard | execution, W729)
+ *   session-meta.ts     `<dir>/session.json` (model + prompt binding + mode)
+ *   validate.ts         model / prompt-id / url / effort validation
+ *   builtin-sections.ts frozen 10-row builtin prompt registry (data only)
+ *   prompts-template.ts `{{var}}` scan / validate / render
+ *   celestea-home.ts    CELESTEA_HOME data-root re-export (W880)
+ *   prompts.ts          prompts.json + <CELESTEA_HOME>/.../prompts.json registry
+ *   prompts-compose.ts  build_gen assembly + active-prompt chain
+ *   workspaces.ts       workspaces.json v2 registry (+ folder rename)
+ *   sessions.ts         session scan / resolve / create / transcript
+ *   session-ops.ts      rename / branch / archive / trash moves
+ *   providers.ts        providers.json (0600) + public_view redaction
+ *   provider-probe.ts   /models probe incl. keyless same-origin borrow
+ */
+export * from "./result.js";
+export * from "./fs-json.js";
+export * from "./session-id.js";
+export * from "./mode.js";
+export * from "./session-meta.js";
+export * from "./validate.js";
+export * from "./builtin-sections.js";
+export * from "./prompts-template.js";
+export * from "./prompts.js";
+export * from "./prompts-compose.js";
+export * from "./workspaces.js";
+export * from "./sessions.js";
+export * from "./session-ops.js";
+export * from "./providers.js";
+export * from "./provider-probe.js";

package/dist/store/mode.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session modes — the P0 vocabulary of "how a session works"
+ * (`docs/modes-standard-vs-execution.md` §1.1, D1/D2).
+ *
+ * `standard` is exactly today's behaviour (call the tools directly); `execution`
+ * is the same engine with the *behaviour contract* turned toward one
+ * `run_code` program per dependent sequence. P0 changes ONLY the assembled
+ * `tool_access` section — the tool face is identical in both modes (§1.2, D5).
+ *
+ * K3: the whole mode table lives here as module-level constants (no literal list
+ * is re-written at a call site), and this file is plain data + pure parsers, so
+ * every consumer (session meta, session rows, prompts, handlers) shares ONE
+ * definition of the vocabulary.
+ *
+ * This is NOT the DSH host's agent preset (D4/§3.3): `mode` is the only mode
+ * semantics the Studio engine knows; the host preset name is derived OUTSIDE
+ * this repository, at the spawn boundary, and must never appear here.
+ */
+/** The two literals, in frozen order. */
+export declare const SESSION_MODES: readonly ["standard", "execution"];
+/** The mode of a session; a session that never declared one reads as `standard`. */
+export type SessionMode = (typeof SESSION_MODES)[number];
+/** Absent/blank/unknown mode reads as this — and it is never written to disk. */
+export declare const DEFAULT_SESSION_MODE: SessionMode;
+/** A mode literal, or `null` when `raw` is not one (never throws). */
+export declare function parseMode(raw: unknown): SessionMode | null;
+/**
+ * Tolerant read: anything that is not a literal (absent, blank, hand-edited
+ * junk) degrades to [DEFAULT_SESSION_MODE], exactly like a missing key (K8/U9).
+ */
+export declare function effectiveMode(raw: unknown): SessionMode;
+/** Write-path validation: `null` = acceptable, else the frozen 400 text (M2). */
+export declare function validateMode(raw: string): string | null;
+/** True when the value is a declared literal (the `contracts/` enum, §4.1). */
+export declare function isSessionMode(raw: unknown): raw is SessionMode;

package/dist/store/mode.js

@@ -0,0 +1,41 @@
+/**
+ * Session modes — the P0 vocabulary of "how a session works"
+ * (`docs/modes-standard-vs-execution.md` §1.1, D1/D2).
+ *
+ * `standard` is exactly today's behaviour (call the tools directly); `execution`
+ * is the same engine with the *behaviour contract* turned toward one
+ * `run_code` program per dependent sequence. P0 changes ONLY the assembled
+ * `tool_access` section — the tool face is identical in both modes (§1.2, D5).
+ *
+ * K3: the whole mode table lives here as module-level constants (no literal list
+ * is re-written at a call site), and this file is plain data + pure parsers, so
+ * every consumer (session meta, session rows, prompts, handlers) shares ONE
+ * definition of the vocabulary.
+ *
+ * This is NOT the DSH host's agent preset (D4/§3.3): `mode` is the only mode
+ * semantics the Studio engine knows; the host preset name is derived OUTSIDE
+ * this repository, at the spawn boundary, and must never appear here.
+ */
+/** The two literals, in frozen order. */
+export const SESSION_MODES = ["standard", "execution"];
+/** Absent/blank/unknown mode reads as this — and it is never written to disk. */
+export const DEFAULT_SESSION_MODE = "standard";
+/** A mode literal, or `null` when `raw` is not one (never throws). */
+export function parseMode(raw) {
+    return typeof raw === "string" && SESSION_MODES.includes(raw) ? raw : null;
+}
+/**
+ * Tolerant read: anything that is not a literal (absent, blank, hand-edited
+ * junk) degrades to [DEFAULT_SESSION_MODE], exactly like a missing key (K8/U9).
+ */
+export function effectiveMode(raw) {
+    return parseMode(raw) ?? DEFAULT_SESSION_MODE;
+}
+/** Write-path validation: `null` = acceptable, else the frozen 400 text (M2). */
+export function validateMode(raw) {
+    return parseMode(raw) === null ? `invalid mode: ${raw}` : null;
+}
+/** True when the value is a declared literal (the `contracts/` enum, §4.1). */
+export function isSessionMode(raw) {
+    return parseMode(raw) !== null;
+}

package/dist/store/permissions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Permission presets (W9) - the built-in constants and the two files.
+ *
+ * Model (design approved by the architect):
+ *   - built-in presets read-only / write-read / full-access are CODE constants;
+ *   - custom presets live at <data dir>/permissions.json (atomic 0600);
+ *   - a session's chosen preset lives at <session dir>/permission.json, a file
+ *     PARALLEL to grants.json (whose v1 shape is deliberately untouched).
+ *
+ * Same discipline as grants.json: whitelist + validate every field, and a
+ * corrupt file means "fall back to the default", never "repair it". A permission
+ * is a BASELINE: engine-grants.ts intersects grants into it and a grant can
+ * never widen past it.
+ */
+export declare const PERMISSIONS_FILE = "permissions.json";
+export declare const SESSION_PERMISSION_FILE = "permission.json";
+export declare const ENV_PERMISSION_DEFAULT = "CELESTEA_PERMISSION_DEFAULT";
+export declare const ENV_PERMISSION_MAX = "CELESTEA_PERMISSION_MAX";
+export declare const DEFAULT_PERMISSION_ID = "full-access";
+export declare const MAX_PRESET_ROOTS = 32;
+export declare const MAX_PRESET_TOOLS = 64;
+export declare const MAX_PRESET_LABEL_CHARS = 80;
+export declare const BUILTIN_PRESET_IDS: readonly ["read-only", "write-read", "full-access"];
+export type BuiltinPresetId = (typeof BUILTIN_PRESET_IDS)[number];
+export interface PermissionPreset {
+    id: string;
+    label: string;
+    network: boolean;
+    workspaceWritable: boolean;
+    /** The deployment CELESTEA_TOOL_ROOTS (repo/harness/tmp) become writable. */
+    toolRootsWritable: boolean;
+    /** Explicit absolute extra write roots, besides workspace + tool roots. */
+    writeRoots: string[];
+    /**
+     * W864: the whole filesystem is readable AND writable ("/" as the one root).
+     * Path-only: network / unsandboxed / toolDeny are untouched by it.
+     */
+    allPaths: boolean;
+    unsandboxed: boolean;
+    /** Tools removed from the session face (baseline filter, before tool_extra). */
+    toolDeny: string[];
+}
+export declare const BUILTIN_PRESETS: readonly PermissionPreset[];
+export declare function isBuiltinPresetId(id: string): id is BuiltinPresetId;
+export declare function builtinPreset(id: string): PermissionPreset | null;
+export declare function defaultPermissionId(env?: NodeJS.ProcessEnv): string;
+export declare function maxPermissionId(env?: NodeJS.ProcessEnv): string;
+export interface PermissionsRead {
+    presets: PermissionPreset[];
+    warnings: string[];
+}
+export declare function readPermissionsFile(dataDir: string): PermissionsRead;
+export declare function writePermissionsFile(dataDir: string, presets: readonly PermissionPreset[], now: number): void;
+export declare function parsePreset(raw: unknown): PermissionPreset | null;
+export interface SessionPermissionRead {
+    exists: boolean;
+    preset?: string;
+    error?: string;
+}
+export declare function readSessionPermission(dir: string, expectedSession: string): SessionPermissionRead;
+export declare function writeSessionPermission(dir: string, session: string, preset: string, now: number): void;