@celestea/studio 2.7.1

package/dist/store/permissions.js

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+import { join } from "node:path";
+import { readJsonIfExists, writeJsonAtomic } from "./fs-json.js";
+export const PERMISSIONS_FILE = "permissions.json";
+export const SESSION_PERMISSION_FILE = "permission.json";
+export const ENV_PERMISSION_DEFAULT = "CELESTEA_PERMISSION_DEFAULT";
+export const ENV_PERMISSION_MAX = "CELESTEA_PERMISSION_MAX";
+export const DEFAULT_PERMISSION_ID = "full-access";
+export const MAX_PRESET_ROOTS = 32;
+export const MAX_PRESET_TOOLS = 64;
+export const MAX_PRESET_LABEL_CHARS = 80;
+export const BUILTIN_PRESET_IDS = ["read-only", "write-read", "full-access"];
+export const BUILTIN_PRESETS = [
+    { id: "read-only", label: "Read only", network: false, workspaceWritable: false, toolRootsWritable: false, writeRoots: [], allPaths: false, unsandboxed: false, toolDeny: ["write_file"] },
+    { id: "write-read", label: "Write + read (workspace)", network: false, workspaceWritable: true, toolRootsWritable: false, writeRoots: [], allPaths: false, unsandboxed: false, toolDeny: [] },
+    { id: "full-access", label: "Full access", network: true, workspaceWritable: true, toolRootsWritable: true, writeRoots: [], allPaths: true, unsandboxed: true, toolDeny: [] },
+];
+export function isBuiltinPresetId(id) {
+    return BUILTIN_PRESET_IDS.includes(id);
+}
+export function builtinPreset(id) {
+    for (const preset of BUILTIN_PRESETS)
+        if (preset.id === id)
+            return preset;
+    return null;
+}
+export function defaultPermissionId(env = process.env) {
+    const raw = (env[ENV_PERMISSION_DEFAULT] ?? "").trim();
+    return raw === "" ? DEFAULT_PERMISSION_ID : raw;
+}
+export function maxPermissionId(env = process.env) {
+    const raw = (env[ENV_PERMISSION_MAX] ?? "").trim();
+    return raw === "" ? DEFAULT_PERMISSION_ID : raw;
+}
+export function readPermissionsFile(dataDir) {
+    const out = readJsonIfExists(join(dataDir, PERMISSIONS_FILE));
+    if (!out.exists)
+        return { presets: [], warnings: [] };
+    if (out.error !== undefined)
+        return { presets: [], warnings: ["permissions_unreadable: " + out.error] };
+    const value = out.value;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return { presets: [], warnings: ["permissions.json is not an object"] };
+    const rec = value;
+    if (rec["version"] !== 1)
+        return { presets: [], warnings: ["unknown permissions.json version " + JSON.stringify(rec["version"])] };
+    if (!Array.isArray(rec["presets"]))
+        return { presets: [], warnings: ["permissions.json has no presets array"] };
+    const presets = [];
+    for (const raw of rec["presets"]) {
+        const parsed = parsePreset(raw);
+        if (parsed !== null && !isBuiltinPresetId(parsed.id))
+            presets.push(parsed);
+    }
+    return { presets, warnings: [] };
+}
+export function writePermissionsFile(dataDir, presets, now) {
+    writeJsonAtomic(join(dataDir, PERMISSIONS_FILE), { version: 1, updated_at: now, presets: presets.map(sanitizePreset) }, { mode: 0o600 });
+}
+function stringArray(raw, max) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const value of raw) {
+        if (typeof value !== "string" || value.trim() === "")
+            continue;
+        out.push(value.trim());
+        if (out.length >= max)
+            break;
+    }
+    return [...new Set(out)];
+}
+export function parsePreset(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const rec = raw;
+    const id = rec["id"];
+    if (typeof id !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(id))
+        return null;
+    const label = typeof rec["label"] === "string" ? rec["label"].slice(0, MAX_PRESET_LABEL_CHARS) : id;
+    return {
+        id,
+        label,
+        network: rec["network"] === true,
+        workspaceWritable: rec["workspaceWritable"] === true,
+        toolRootsWritable: rec["toolRootsWritable"] === true,
+        writeRoots: stringArray(rec["writeRoots"], MAX_PRESET_ROOTS),
+        allPaths: rec["allPaths"] === true,
+        unsandboxed: rec["unsandboxed"] === true,
+        toolDeny: stringArray(rec["toolDeny"], MAX_PRESET_TOOLS),
+    };
+}
+function sanitizePreset(preset) {
+    return {
+        id: preset.id,
+        label: preset.label.slice(0, MAX_PRESET_LABEL_CHARS),
+        network: preset.network === true,
+        workspaceWritable: preset.workspaceWritable === true,
+        toolRootsWritable: preset.toolRootsWritable === true,
+        writeRoots: stringArray(preset.writeRoots, MAX_PRESET_ROOTS),
+        allPaths: preset.allPaths === true,
+        unsandboxed: preset.unsandboxed === true,
+        toolDeny: stringArray(preset.toolDeny, MAX_PRESET_TOOLS),
+    };
+}
+export function readSessionPermission(dir, expectedSession) {
+    const out = readJsonIfExists(join(dir, SESSION_PERMISSION_FILE));
+    if (!out.exists)
+        return { exists: false };
+    if (out.error !== undefined)
+        return { exists: true, error: "unparsable permission.json: " + out.error };
+    const value = out.value;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return { exists: true, error: "permission.json is not an object" };
+    const rec = value;
+    if (rec["version"] !== 1)
+        return { exists: true, error: "unknown permission.json version " + JSON.stringify(rec["version"]) };
+    if (rec["session"] !== expectedSession)
+        return { exists: true, error: "permission.json belongs to " + JSON.stringify(rec["session"]) };
+    if (typeof rec["preset"] !== "string" || rec["preset"] === "")
+        return { exists: true, error: "permission.json has no preset" };
+    return { exists: true, preset: rec["preset"] };
+}
+export function writeSessionPermission(dir, session, preset, now) {
+    writeJsonAtomic(join(dir, SESSION_PERMISSION_FILE), { version: 1, session, preset, updated_at: now }, { mode: 0o600 });
+}

package/dist/store/prompts-compose.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `build_gen` — assembling the system prompt from the section registry
+ * (`src/prompts.rs:108-130,472-500`).
+ *
+ * The composed prompt is a DERIVED value: sections are rendered in `(order, id)`
+ * order, empty/whitespace templates are dropped, the survivors are joined with
+ * a blank line, and the result is truncated to `PROMPT_MAX_LEN` bytes on a char
+ * boundary. A `USER_OVERRIDE` (POST /api/config `system_prompt`) bypasses this
+ * assembly entirely — it is never a section.
+ */
+import { type SessionMode } from "./mode.js";
+import type { PromptScope, PromptsStore } from "./prompts.js";
+import { type PromptVars } from "./prompts-template.js";
+export interface PromptVarInput {
+    model: string;
+    provider: string;
+    base_url: string;
+    /** W768: the workspace NAME (`CelesteaTeamAPI`). */
+    workspace: string;
+    /** W768: the workspace ROOT PATH — the same value the tools run in. */
+    workspace_dir: string;
+    session: string;
+    tools: string;
+    context_window: number;
+    max_output_tokens: number | null;
+    date: string;
+    /** W782: `/src/...` repo root of the RUNNING process (derived, never typed). */
+    studio_repo: string;
+    /** W782: `{{studio_repo}}/apps/web` — the frontend sources. */
+    studio_frontend_dir: string;
+    /** W782: `config.paths.staticRoot` — where the built frontend is served. */
+    studio_static_root: string;
+    /** W782: the systemd unit name (derived or centrally configured). */
+    studio_service: string;
+    /** W782: `config.bind` — host:port the backend listens on. */
+    studio_bind: string;
+    /** W782: the public site (the one irreducible literal, see deployment.ts). */
+    studio_site: string;
+}
+/** Interpolation values; every whitelisted variable gets a string. */
+export declare function toPromptVars(input: PromptVarInput): PromptVars;
+/**
+ * Assemble the registry-resolved system prompt for one scope.
+ *
+ * W729: `mode` selects the `tool_access` VARIANT (K6 — the registry stays 10
+ * rows); everything else is mode-independent, and a scope/bound override of
+ * `tool_access` still replaces the variant (R4). The default keeps every
+ * existing caller on the `standard` text.
+ */
+export declare function assembleSystemPrompt(store: PromptsStore, scope: PromptScope, boundId: string | null, vars: PromptVars, mode?: SessionMode): string;
+/**
+ * `active_prompt` resolution chain: the active session's bound prompt id wins;
+ * a bound id that no longer exists resolves to null (there is NO fallback for a
+ * bound-but-missing prompt); otherwise scope default -> global default.
+ */
+export declare function resolveActivePrompt(store: PromptsStore, scope: PromptScope, sessionPromptId: string | null): string | null;

package/dist/store/prompts-compose.js

@@ -0,0 +1,62 @@
+/**
+ * `build_gen` — assembling the system prompt from the section registry
+ * (`src/prompts.rs:108-130,472-500`).
+ *
+ * The composed prompt is a DERIVED value: sections are rendered in `(order, id)`
+ * order, empty/whitespace templates are dropped, the survivors are joined with
+ * a blank line, and the result is truncated to `PROMPT_MAX_LEN` bytes on a char
+ * boundary. A `USER_OVERRIDE` (POST /api/config `system_prompt`) bypasses this
+ * assembly entirely — it is never a section.
+ */
+import { DEFAULT_SESSION_MODE } from "./mode.js";
+import { renderTemplate, truncateToCap } from "./prompts-template.js";
+/** Interpolation values; every whitelisted variable gets a string. */
+export function toPromptVars(input) {
+    return {
+        model: input.model,
+        provider: input.provider,
+        base_url: input.base_url,
+        workspace: input.workspace,
+        workspace_dir: input.workspace_dir,
+        session: input.session,
+        tools: input.tools,
+        context_window: String(input.context_window),
+        max_output_tokens: input.max_output_tokens === null ? "" : String(input.max_output_tokens),
+        date: input.date,
+        studio_repo: input.studio_repo,
+        studio_frontend_dir: input.studio_frontend_dir,
+        studio_static_root: input.studio_static_root,
+        studio_service: input.studio_service,
+        studio_bind: input.studio_bind,
+        studio_site: input.studio_site,
+    };
+}
+/**
+ * Assemble the registry-resolved system prompt for one scope.
+ *
+ * W729: `mode` selects the `tool_access` VARIANT (K6 — the registry stays 10
+ * rows); everything else is mode-independent, and a scope/bound override of
+ * `tool_access` still replaces the variant (R4). The default keeps every
+ * existing caller on the `standard` text.
+ */
+export function assembleSystemPrompt(store, scope, boundId, vars, mode = DEFAULT_SESSION_MODE) {
+    const parts = [];
+    for (const row of store.sections(scope, boundId, mode)) {
+        const rendered = renderTemplate(row.template, vars).trim();
+        if (rendered === "")
+            continue;
+        parts.push(rendered);
+    }
+    return truncateToCap(parts.join("\n\n"));
+}
+/**
+ * `active_prompt` resolution chain: the active session's bound prompt id wins;
+ * a bound id that no longer exists resolves to null (there is NO fallback for a
+ * bound-but-missing prompt); otherwise scope default -> global default.
+ */
+export function resolveActivePrompt(store, scope, sessionPromptId) {
+    if (sessionPromptId !== null && sessionPromptId !== "") {
+        return store.find(scope, sessionPromptId) === undefined ? null : sessionPromptId;
+    }
+    return store.defaultFor(scope)?.id ?? null;
+}

package/dist/store/prompts-template.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Prompt template rules (`src/prompts.rs:126-165,472-560`).
+ *
+ * `{{name}}` is the ONLY syntax: the name is trimmed, there are no aliases and
+ * no escaping. Validation and rendering share one scanner so a template can
+ * never validate under one rule and render under another.
+ */
+/** `PROMPT_MAX_LEN`. */
+export declare const PROMPT_MAX_LEN = 8192;
+/** `ORDER_FALLBACK`: a section that is new to a scope lands after the builtins. */
+export declare const ORDER_FALLBACK = 2000;
+/** The whitelist; anything else is `undefined prompt variable '{{name}}'`. */
+export declare const PROMPT_VARS: readonly ["model", "provider", "base_url", "workspace", "workspace_dir", "session", "tools", "context_window", "max_output_tokens", "date", "studio_repo", "studio_frontend_dir", "studio_static_root", "studio_service", "studio_bind", "studio_site"];
+export type PromptVar = (typeof PROMPT_VARS)[number];
+export type PromptVars = Partial<Record<PromptVar, string>>;
+export interface TemplateError {
+    error: string;
+}
+/** Byte length of the UTF-8 encoding (the cap is in BYTES, not chars). */
+export declare function byteLength(text: string): number;
+/** Validate one template against the cap, the whitelist and closure. */
+export declare function validateTemplate(template: string): TemplateError | null;
+/** Render `{{var}}` with the given values; a missing value renders empty. */
+export declare function renderTemplate(template: string, vars: PromptVars): string;
+/** Truncate to the byte cap on a char boundary (`truncate_prompt`). */
+export declare function truncateToCap(text: string): string;

package/dist/store/prompts-template.js

@@ -0,0 +1,99 @@
+/**
+ * Prompt template rules (`src/prompts.rs:126-165,472-560`).
+ *
+ * `{{name}}` is the ONLY syntax: the name is trimmed, there are no aliases and
+ * no escaping. Validation and rendering share one scanner so a template can
+ * never validate under one rule and render under another.
+ */
+/** `PROMPT_MAX_LEN`. */
+export const PROMPT_MAX_LEN = 8192;
+/** `ORDER_FALLBACK`: a section that is new to a scope lands after the builtins. */
+export const ORDER_FALLBACK = 2000;
+/** The whitelist; anything else is `undefined prompt variable '{{name}}'`. */
+export const PROMPT_VARS = [
+    "model",
+    "provider",
+    "base_url",
+    "workspace",
+    "workspace_dir",
+    "session",
+    "tools",
+    "context_window",
+    "max_output_tokens",
+    "date",
+    // W782: the deployment facts the `environment` section states. Every one is
+    // resolved at runtime (see `src/deployment.ts`) so no template has to spell
+    // out a path, a port or a unit name that the next move/rename would falsify.
+    "studio_repo",
+    "studio_frontend_dir",
+    "studio_static_root",
+    "studio_service",
+    "studio_bind",
+    "studio_site",
+];
+/** Split a template into literals and `{{var}}` slots (never throws). */
+function scan(template) {
+    const tokens = [];
+    let rest = template;
+    for (;;) {
+        const open = rest.indexOf("{{");
+        if (open < 0) {
+            tokens.push({ literal: rest });
+            return { tokens, unclosed: false };
+        }
+        const close = rest.indexOf("}}", open + 2);
+        if (close < 0) {
+            tokens.push({ literal: rest.slice(0, open) });
+            return { tokens, unclosed: true };
+        }
+        tokens.push({ literal: rest.slice(0, open) });
+        tokens.push({ literal: "", name: rest.slice(open + 2, close).trim() });
+        rest = rest.slice(close + 2);
+    }
+}
+/** Byte length of the UTF-8 encoding (the cap is in BYTES, not chars). */
+export function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/** Validate one template against the cap, the whitelist and closure. */
+export function validateTemplate(template) {
+    const bytes = byteLength(template);
+    if (bytes > PROMPT_MAX_LEN)
+        return { error: `template exceeds the ${PROMPT_MAX_LEN} byte cap (${bytes} bytes)` };
+    const { tokens, unclosed } = scan(template);
+    if (unclosed)
+        return { error: "unclosed '{{' in template" };
+    for (const t of tokens) {
+        if (t.name === undefined)
+            continue;
+        if (!PROMPT_VARS.includes(t.name)) {
+            return { error: `undefined prompt variable '{{${t.name}}}'` };
+        }
+    }
+    return null;
+}
+/** Render `{{var}}` with the given values; a missing value renders empty. */
+export function renderTemplate(template, vars) {
+    const { tokens } = scan(template);
+    let out = "";
+    for (const t of tokens) {
+        if (t.name === undefined) {
+            out += t.literal;
+            continue;
+        }
+        out += vars[t.name] ?? "";
+    }
+    return out;
+}
+/** Truncate to the byte cap on a char boundary (`truncate_prompt`). */
+export function truncateToCap(text) {
+    if (byteLength(text) <= PROMPT_MAX_LEN)
+        return text;
+    let acc = "";
+    for (const ch of text) {
+        if (byteLength(acc + ch) > PROMPT_MAX_LEN)
+            break;
+        acc += ch;
+    }
+    return acc;
+}

package/dist/store/prompts.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Prompt registry store — global `prompts.json` + per-workspace
+ * `<CELESTEA_HOME>/workspaces/<ws>/prompts.json` (W880; legacy
+ * `<ws>/.celestea-prompts.json` stays readable) (`contracts/data-files/prompts.schema.json`,
+ * `src/prompts.rs:560-880`).
+ *
+ * Tolerated-on-read, strict-on-write: a missing OR malformed registry file
+ * degrades to an empty one (the registry must never break compose or the UI),
+ * while every write validates the id and every override template before the
+ * file is touched. There are four registry levels — builtin → global →
+ * workspace → the bound prompt's `section_overrides` — and writing is
+ * `persist -> hot apply -> roll the file back when the apply fails`.
+ */
+import { type StoreResult } from "./result.js";
+import { type SessionMode } from "./mode.js";
+export interface PromptSectionRow {
+    id: string;
+    name: string;
+    template: string;
+    order: number;
+    source: "builtin" | "global" | "workspace";
+}
+export interface PromptEntry {
+    id: string;
+    name: string;
+    section_overrides: Record<string, string>;
+    is_default: boolean;
+}
+export interface PromptListEntry extends PromptEntry {
+    scope: "global" | "workspace";
+    shadowed: boolean;
+}
+export interface PromptFileData {
+    sections: Array<{
+        id: string;
+        name: string;
+        template: string;
+        order: number;
+    }>;
+    prompts: PromptEntry[];
+    default_prompt: string | null;
+}
+export interface PromptScope {
+    kind: "global" | "workspace";
+    workspace: string | null;
+    /** Canonical write target (reads fall back through `files`). */
+    file: string;
+    /**
+     * Every file this scope READS, canonical FIRST (W880). `file` === `files[0]`
+     * is the single write target; the rest are legacy locations kept readable so a
+     * pre-W880 workspace registry is never lost. Writes always land in `file`,
+     * which keeps `snapshot`/`restore` correct: they roll the write target back,
+     * leaving a legacy source untouched.
+     */
+    files: readonly string[];
+}
+export interface PromptDefaultRef {
+    id: string;
+    scope: "global" | "workspace";
+}
+export interface PromptListResponse {
+    ok: true;
+    scope: "global" | "workspace";
+    workspace: string | null;
+    global_file: string;
+    sections: PromptSectionRow[];
+    prompts: PromptListEntry[];
+    default_prompt: PromptDefaultRef | null;
+    active_prompt: string | null;
+}
+export interface PromptUpsertRequest {
+    id: string;
+    name: string;
+    section_overrides?: Record<string, string>;
+    is_default?: boolean;
+}
+export declare class PromptsStore {
+    private readonly globalFile;
+    constructor(globalFile: string);
+    scopeGlobal(): PromptScope;
+    scopeWorkspace(name: string, wsPath: string): PromptScope;
+    /**
+     * Tolerant read: missing OR malformed both degrade to an empty registry. The
+     * first EXISTING candidate wins (canonical, then the legacy locations).
+     */
+    read(scope: PromptScope): PromptFileData;
+    /** Raw file text (the rollback snapshot for a failed hot apply). */
+    snapshot(scope: PromptScope): string | null;
+    /**
+     * Roll a failed hot apply back to its snapshot.
+     *
+     * W815-1: a null snapshot means the scope file did NOT exist before the
+     * mutate, so "back to the snapshot" is "remove the file" — returning early
+     * left the fresh content on disk while the engine had rejected it (registry
+     * ahead of the engine). A present snapshot is restored verbatim.
+     */
+    restore(scope: PromptScope, text: string | null): void;
+    private persist;
+    find(scope: PromptScope, id: string): PromptEntry | undefined;
+    /** `default_prompt` of this scope, falling back to the global one. */
+    defaultFor(scope: PromptScope): PromptDefaultRef | null;
+    private promptList;
+    /** GET /api/prompts body (handler fills `active_prompt`). */
+    list(scope: PromptScope, activePrompt: string | null): PromptListResponse;
+    private effective;
+    /**
+     * The registry-resolved sections (used by the sections listing and by
+     * `build_gen`). `mode` swaps the `tool_access` builtin VARIANT (W729/K6); it
+     * never adds or removes a row.
+     */
+    sections(scope: PromptScope, boundId?: string | null, mode?: SessionMode): PromptSectionRow[];
+    upsert(scope: PromptScope, req: PromptUpsertRequest): StoreResult<{
+        id: string;
+        scope: "global" | "workspace";
+        hot_applied: true;
+    }>;
+    remove(scope: PromptScope, rawId: string): StoreResult<{
+        scope: "global" | "workspace";
+        hot_applied: true;
+    }>;
+    setDefault(scope: PromptScope, rawId: string): StoreResult<{
+        default_prompt: string;
+        scope: "global" | "workspace";
+        hot_applied: true;
+    }>;
+}
+export interface SectionComposeInput {
+    global: PromptFileData;
+    workspace: PromptFileData | null;
+    bound: PromptEntry | null;
+    /** Builtin `tool_access` variant to start the overlay from (default standard). */
+    mode?: SessionMode;
+}
+/**
+ * Four-level overlay: builtin -> global -> workspace -> bound overrides.
+ * A known id keeps its ORIGINAL order and only swaps its template; an unknown
+ * id is appended with ORDER_FALLBACK and sorted by `(order, id)`.
+ */
+export declare function composeSections(input: SectionComposeInput): {
+    rows: PromptSectionRow[];
+    templates: Map<string, string>;
+};