@celestea/studio 2.7.1

package/dist/store/providers.js

@@ -0,0 +1,219 @@
+/**
+ * `providers.json` store — `contracts/data-files/providers.schema.json`,
+ * `src/providers.rs:52-86,219-241,673-797`.
+ *
+ * Security rules enforced here, not by convention:
+ *   - the file holds PLAINTEXT keys and is written through
+ *     `OpenOptions::mode(0600)` + fsync + rename, i.e. EVERY save re-asserts
+ *     0600 (see `save()`);
+ *   - `public_view` has NO `api_key` key at all (not null, not empty) — the
+ *     type returned by every read path simply has no such field, so a handler
+ *     cannot leak it by accident;
+ *   - update semantics: `api_key` absent/null/blank KEEPS the stored key (the
+ *     only keep-on-default field), while `models` absent CLEARS the list,
+ *     `note` absent clears to "", `request_format` absent silently resets to
+ *     chat_completions and `name` absent falls back to `id`.
+ */
+import { readJsonIfExists, writeJsonAtomic } from "./fs-json.js";
+import { badRequest, errText, fail, notFound, ok } from "./result.js";
+import { isHttpUrl } from "./validate.js";
+export const REQUEST_FORMATS = ["chat_completions", "responses", "anthropic_messages"];
+export const PROVIDERS_MODE = 0o600;
+function asString(v, fallback = "") {
+    return typeof v === "string" ? v : fallback;
+}
+function nullableInt(v) {
+    return typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : null;
+}
+function parseModel(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const rec = raw;
+    const id = asString(rec["id"]);
+    if (id === "")
+        return null;
+    const efforts = Array.isArray(rec["reasoning_efforts"]) ? rec["reasoning_efforts"].filter((x) => typeof x === "string") : [];
+    const model = {
+        id,
+        name: asString(rec["name"], id) || id,
+        reasoning_efforts: efforts,
+        context_window: nullableInt(rec["context_window"]),
+        max_output_tokens: nullableInt(rec["max_output_tokens"]),
+    };
+    // W804: preserved only when present, so a legacy row is re-serialized verbatim.
+    const input = modalityList(rec["input_modalities"]);
+    if (input !== undefined)
+        model.input_modalities = input;
+    const output = modalityList(rec["output_modalities"]);
+    if (output !== undefined)
+        model.output_modalities = output;
+    return model;
+}
+/** W804: a non-empty array of modality strings, else undefined (absent). */
+function modalityList(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((x) => typeof x === "string" && x !== "");
+    return out.length === 0 ? undefined : out;
+}
+function parseRow(raw, file) {
+    const rec = (raw ?? {});
+    const id = asString(rec["id"]);
+    const base_url = asString(rec["base_url"]);
+    const fmt = asString(rec["request_format"]);
+    if (id === "" || base_url === "" || !REQUEST_FORMATS.includes(fmt)) {
+        throw new Error(`providers.json '${file}' is malformed: provider row needs id, base_url and a valid request_format`);
+    }
+    const models = Array.isArray(rec["models"]) ? rec["models"].map(parseModel).filter((m) => m !== null) : [];
+    return {
+        id,
+        name: asString(rec["name"], id) || id,
+        note: asString(rec["note"]),
+        base_url,
+        request_format: fmt,
+        api_key: typeof rec["api_key"] === "string" ? rec["api_key"] : null,
+        models,
+    };
+}
+function load(file) {
+    const out = readJsonIfExists(file);
+    if (!out.exists)
+        return { providers: [], default_model: null };
+    if (out.error !== undefined)
+        throw new Error(`providers.json '${file}' is malformed: ${out.error}`);
+    const rec = (typeof out.value === "object" && out.value !== null ? out.value : {});
+    const rows = Array.isArray(rec["providers"]) ? rec["providers"] : [];
+    const def = rec["default_model"];
+    return {
+        providers: rows.map((r) => parseRow(r, file)),
+        default_model: typeof def === "string" && def !== "" ? def : null,
+    };
+}
+/** Normalize a base_url for the keyless-borrow comparison (trim + no trailing '/'). */
+export function normalizeBaseUrl(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+export class ProvidersStore {
+    file;
+    data;
+    constructor(file) {
+        this.file = file;
+        this.data = load(file);
+    }
+    /** Internal rows — used by the probe and by `/api/config` model listing. */
+    rows() {
+        return this.data.providers;
+    }
+    find(id) {
+        return this.data.providers.find((p) => p.id === id);
+    }
+    defaultModel() {
+        return this.data.default_model;
+    }
+    /** Every id listed by any provider (used to validate `default_model`). */
+    modelIds() {
+        const out = new Set();
+        for (const p of this.data.providers)
+            for (const m of p.models)
+                out.add(m.id);
+        return [...out];
+    }
+    view(p) {
+        const def = this.data.default_model;
+        return {
+            id: p.id,
+            name: p.name,
+            note: p.note,
+            base_url: p.base_url,
+            request_format: p.request_format,
+            models: p.models.map((m) => ({ ...m, reasoning_efforts: [...m.reasoning_efforts] })),
+            is_default: def !== null && p.models.some((m) => m.id === def),
+            has_key: typeof p.api_key === "string" && p.api_key !== "",
+        };
+    }
+    viewOf(p) {
+        return this.view(p);
+    }
+    list() {
+        return this.data.providers.map((p) => this.view(p));
+    }
+    /** GET /api/providers body (no `ok`, never a key). */
+    response() {
+        return { providers: this.list(), default_model: this.data.default_model };
+    }
+    save() {
+        try {
+            writeJsonAtomic(this.file, { providers: this.data.providers, default_model: this.data.default_model }, { mode: PROVIDERS_MODE, fsync: true });
+            return ok(undefined);
+        }
+        catch (e) {
+            return fail(500, `providers serialize failed: ${errText(e)}`);
+        }
+    }
+    validate(req) {
+        const id = (req.id ?? "").trim();
+        if (id === "")
+            return badRequest("provider id must not be empty");
+        const base_url = (req.base_url ?? "").trim();
+        if (base_url === "")
+            return badRequest("base_url is required");
+        if (!isHttpUrl(base_url))
+            return badRequest("base_url must be an http:// or https:// URL");
+        const format = (req.request_format ?? "chat_completions");
+        if (!REQUEST_FORMATS.includes(format)) {
+            return badRequest(`invalid request_format '${format}': expected chat_completions | responses | anthropic_messages`);
+        }
+        const models = [];
+        for (const raw of req.models ?? []) {
+            const model = parseModel(raw);
+            if (model === null)
+                return badRequest("each model needs a non-empty id");
+            models.push(model);
+        }
+        return ok({ id, base_url, format, models });
+    }
+    /** POST /api/providers — upsert by id; returns the public view. */
+    upsert(req) {
+        const checked = this.validate(req);
+        if (!checked.ok)
+            return checked;
+        const { id, base_url, format, models } = checked.value;
+        const idx = this.data.providers.findIndex((p) => p.id === id);
+        const stored = idx >= 0 ? this.data.providers[idx] : undefined;
+        const asked = req.api_key;
+        const keepKey = asked === undefined || asked === null || asked.trim() === "";
+        const row = {
+            id,
+            name: (req.name ?? "").trim() === "" ? id : (req.name ?? "").trim(),
+            note: req.note ?? "",
+            base_url,
+            request_format: format,
+            api_key: keepKey ? (stored?.api_key ?? null) : asked,
+            models,
+        };
+        if (idx >= 0)
+            this.data.providers[idx] = row;
+        else
+            this.data.providers.push(row);
+        const saved = this.save();
+        if (!saved.ok)
+            return saved;
+        return ok(this.view(row));
+    }
+    /** POST /api/providers/{id}/delete — UNTRIMMED raw path value. */
+    remove(rawId) {
+        const idx = this.data.providers.findIndex((p) => p.id === rawId);
+        if (idx < 0)
+            return notFound(`unknown provider '${rawId}'`);
+        this.data.providers.splice(idx, 1);
+        if (this.data.default_model !== null && !this.modelIds().includes(this.data.default_model)) {
+            this.data.default_model = null;
+        }
+        return this.save();
+    }
+    /** POST /api/providers/default — persist the default model id. */
+    setDefaultModel(model) {
+        this.data.default_model = model;
+        return this.save();
+    }
+}

package/dist/store/result.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `StoreResult` — how every data-store operation reports failure.
+ *
+ * The HTTP layer must reproduce the contract error strings verbatim together with
+ * their status code, so a store never throws for an expected failure: it
+ * returns `{ok:false, status, error}` and the handler turns that into
+ * `{ok:false, error}` with the status. Store *bugs* still throw.
+ */
+export interface StoreFailure {
+    ok: false;
+    /** HTTP status the contract assigns to this failure. */
+    status: number;
+    /** Verbatim contract text (`format!` template filled in). */
+    error: string;
+    /** Extra fields folded into the response body (fs/browse uses `path`). */
+    extra?: Record<string, unknown>;
+}
+export type StoreResult<T> = {
+    ok: true;
+    value: T;
+} | StoreFailure;
+export declare function ok<T>(value: T): StoreResult<T>;
+export declare function fail<T>(status: number, error: string, extra?: Record<string, unknown>): StoreResult<T>;
+export declare function badRequest<T>(error: string): StoreResult<T>;
+export declare function notFound<T>(error: string): StoreResult<T>;
+export declare function conflict<T>(error: string): StoreResult<T>;
+export declare function serverError<T>(message: string): StoreResult<T>;
+/** `Error` -> message, for the `{e}` placeholders in contract error strings. */
+export declare function errText(e: unknown): string;

package/dist/store/result.js

@@ -0,0 +1,30 @@
+/**
+ * `StoreResult` — how every data-store operation reports failure.
+ *
+ * The HTTP layer must reproduce the contract error strings verbatim together with
+ * their status code, so a store never throws for an expected failure: it
+ * returns `{ok:false, status, error}` and the handler turns that into
+ * `{ok:false, error}` with the status. Store *bugs* still throw.
+ */
+export function ok(value) {
+    return { ok: true, value };
+}
+export function fail(status, error, extra) {
+    return extra === undefined ? { ok: false, status, error } : { ok: false, status, error, extra };
+}
+export function badRequest(error) {
+    return fail(400, error);
+}
+export function notFound(error) {
+    return fail(404, error);
+}
+export function conflict(error) {
+    return fail(409, error);
+}
+export function serverError(message) {
+    return fail(500, message);
+}
+/** `Error` -> message, for the `{e}` placeholders in contract error strings. */
+export function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/store/session-id.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Session / workspace path rules (`src/workspaces.rs:555-660`).
+ *
+ * The workspace segment of an id is ALWAYS a registry lookup, never a path
+ * component; the session segment is sanitized and then parent-verified, so a
+ * crafted id cannot escape the registered workspace directory. These functions
+ * are pure — the stores own the filesystem side.
+ */
+import { type PlatformInput } from "@celestea/tools";
+/** The host's platform, injectable in tests (the W885 win32 seam). */
+export type PathInput = PlatformInput;
+export type PathInputLike = PlatformInput | string | undefined;
+/** `dirname` under the call's platform. */
+export declare function parentDir(path: string, input?: PathInputLike): string;
+/** `basename` under the call's platform. */
+export declare function baseName(path: string, input?: PathInputLike): string;
+/** The filesystem root of `path` (`/`, `C:\\`, `\\\\\\\\server\\\\share\\\\`). */
+export declare function rootOf(path: string, input?: PathInputLike): string;
+/** Absolute per the call's platform (Windows drive letters included). */
+export declare function isAbsolutePath(path: string, input?: PathInputLike): boolean;
+/** Separators / control chars / whitespace -> '_'; CJK and letters survive. */
+export declare function sanitizeComponent(s: string): string;
+export interface ParsedSessionId {
+    workspace: string;
+    session: string;
+    /** Canonical `<workspace>/<session>` after sanitization. */
+    id: string;
+}
+/**
+ * Split `<workspace>/<session>`: exactly one '/', both sides non-empty, the
+ * session half separator-free after sanitization and never a hidden name.
+ */
+export declare function parseSessionId(raw: string): ParsedSessionId | null;
+/** `"<secs>.<nanos>"` — the creation / trash suffix (`now_ts`). */
+export declare function timestampSuffix(nowMs: number): string;
+/** `<sanitized title>-<secs>.<nanos>` — the session directory name. */
+export declare function sessionDirName(title: string, nowMs: number): string;
+/**
+ * W779 T2 — the display name of a session DIRECTORY.
+ *
+ * A directory is `<sanitized title>-<secs>.<nanos>` (and `uniqueDir` may append
+ * `-N`), a uniqueness trick that must never reach the GUI:
+ *   main-1789192174.492000000 -> main
+ *   v2-1-1700000000.0-2       -> v2-1
+ *   plain                     -> plain        (nothing to strip)
+ *   报告-2024                  -> 报告-2024     (digits, but not a timestamp)
+ * A name that is ONLY a suffix keeps itself instead of becoming "".
+ */
+export declare function stripCreationSuffix(name: string): string;
+/** Folder basename, or null when the path has no usable last component. */
+export declare function workspaceBasename(path: string, input?: PathInputLike): string | null;
+/**
+ * W791: the two hidden sibling directories a session can be MOVED into.
+ *
+ * They live here (the session-directory vocabulary module) rather than in
+ * `session-ops.ts` because BOTH sides need them: the mover writes into them, and
+ * the scanner (`SessionsStore.listArchived`) reads `<ws>/.celestea-archived/`
+ * back. Importing the mover from the scanner would make the two modules
+ * circular, which the repo's dependency gate forbids.
+ *
+ * The names never change: a rename would orphan every archived session on disk.
+ */
+export declare const ARCHIVED_DIR = ".celestea-archived";
+export declare const TRASH_DIR = ".celestea-trash";
+/**
+ * W877 (slice A) — the workspace-level `.celestea/` container.
+ *
+ * Slice A sank NEW session dirs into `<ws>/.celestea/sessions/`; W880 moves the
+ * canonical container OUT of the workspace into `CELESTEA_HOME`, so this path is
+ * now only the MIDDLE read fallback (dual-read compatibility with real data
+ * written by slice A).
+ */
+export declare const CELESTEA_DIR = ".celestea";
+export declare const SESSIONS_SUBDIR = "sessions";
+/** W880 archive sub-container (under `workspaceHome`). */
+export declare const ARCHIVE_SUBDIR = "archive";
+/** W880 trash sub-container (under `workspaceHome`). */
+export declare const TRASH_SUBDIR = "trash";
+/** W880 workspace prompt-registry file name. */
+export declare const PROMPTS_FILE = "prompts.json";
+/** W880 run_code transient-program sub-container. */
+export declare const RUN_CODE_SUBDIR = "run-code";
+/** W880 canonical live-session root: `<CELESTEA_HOME>/workspaces/<ws>/sessions`. */
+export declare function sessionsRoot(wsPath: string, input?: PathInputLike): string;
+/** W877 transitional root: `<ws>/.celestea/sessions`. */
+export declare function legacySessionsRoot(wsPath: string, input?: PathInputLike): string;
+/**
+ * The physical roots a live session may occupy, canonical FIRST:
+ * `<home>/.../sessions` -> `<ws>/.celestea/sessions` -> `<ws>`.
+ *
+ * Pure — the caller owns the filesystem side. `resolve()` uses the first
+ * existing candidate and falls back to the canonical root when none exists (so
+ * the write side stays consistent); `list()` scans all three and lets the
+ * canonical row shadow a same-named legacy one.
+ */
+export declare function sessionRoots(wsPath: string, input?: PathInputLike): string[];
+/** `dir` under every live-session root, canonical FIRST. */
+export declare function liveDirCandidates(wsPath: string, dir: string, input?: PathInputLike): string[];
+/** Archive roots, canonical FIRST: `home/archive` -> `.celestea/archive` -> `.celestea-archived`. */
+export declare function archiveRoots(wsPath: string, input?: PathInputLike): string[];
+/** `dir` under every archive root, canonical FIRST. */
+export declare function archiveDirCandidates(wsPath: string, dir: string, input?: PathInputLike): string[];
+/** Trash roots, canonical FIRST. */
+export declare function trashRoots(wsPath: string, input?: PathInputLike): string[];
+/** Workspace prompt-registry candidates, canonical FIRST (write target = `[0]`). */
+export declare function promptsFileCandidates(wsPath: string, input?: PathInputLike): string[];
+/** A hidden name can never become a visible session/workspace directory. */
+export declare function isHiddenName(name: string): boolean;
+/** Workspace rename validation (`validate_workspace_name`). */
+export declare function validateWorkspaceName(raw: string): {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** The host `isAbsolute` (kept exported for pre-W885 callers). */
+export declare function isAbsolute(path: string): boolean;
+export type { PlatformInput };

package/dist/store/session-id.js

@@ -0,0 +1,220 @@
+/**
+ * Session / workspace path rules (`src/workspaces.rs:555-660`).
+ *
+ * The workspace segment of an id is ALWAYS a registry lookup, never a path
+ * component; the session segment is sanitized and then parent-verified, so a
+ * crafted id cannot escape the registered workspace directory. These functions
+ * are pure — the stores own the filesystem side.
+ */
+import { pathApi } from "@celestea/tools";
+import { workspaceHome } from "./celestea-home.js";
+/**
+ * W885 — collapse an input that may be a whole [PlatformInput] or a bare
+ * platform id (the pre-W885 signatures took neither, so both are additive).
+ */
+function platformOf(input) {
+    if (input === undefined)
+        return process.platform;
+    return typeof input === "string" ? input : (input.platform ?? process.platform);
+}
+/** The path implementation of this call's platform (win32 in a win32 test). */
+function apiOf(input) {
+    return pathApi(platformOf(input));
+}
+/** `<a>/<b>` under the call's platform, never string concatenation (W883 E1/E2). */
+function under(input, base, ...segments) {
+    return apiOf(input).join(base, ...segments);
+}
+/** `dirname` under the call's platform. */
+export function parentDir(path, input = undefined) {
+    return apiOf(input).dirname(path);
+}
+/** `basename` under the call's platform. */
+export function baseName(path, input = undefined) {
+    return apiOf(input).basename(path);
+}
+/** The filesystem root of `path` (`/`, `C:\\`, `\\\\\\\\server\\\\share\\\\`). */
+export function rootOf(path, input = undefined) {
+    return apiOf(input).parse(path).root;
+}
+/** Absolute per the call's platform (Windows drive letters included). */
+export function isAbsolutePath(path, input = undefined) {
+    return apiOf(input).isAbsolute(path);
+}
+/** Separators / control chars / whitespace -> '_'; CJK and letters survive. */
+export function sanitizeComponent(s) {
+    let out = "";
+    for (const ch of s) {
+        const code = ch.codePointAt(0) ?? 0;
+        const isControl = code < 0x20 || (code >= 0x7f && code <= 0x9f);
+        const isSeparator = ch === "/" || ch === "\\";
+        out += isSeparator || isControl || /\s/u.test(ch) ? "_" : ch;
+    }
+    return out;
+}
+/**
+ * Split `<workspace>/<session>`: exactly one '/', both sides non-empty, the
+ * session half separator-free after sanitization and never a hidden name.
+ */
+export function parseSessionId(raw) {
+    const id = raw.trim();
+    if (id === "")
+        return null;
+    const slash = id.indexOf("/");
+    if (slash <= 0)
+        return null;
+    const workspace = id.slice(0, slash);
+    const rest = id.slice(slash + 1);
+    if (rest === "" || rest.includes("/"))
+        return null;
+    const session = sanitizeComponent(rest);
+    if (session === "" || session === "." || session === ".." || session.startsWith("."))
+        return null;
+    return { workspace, session, id: `${workspace}/${session}` };
+}
+/** `"<secs>.<nanos>"` — the creation / trash suffix (`now_ts`). */
+export function timestampSuffix(nowMs) {
+    const secs = Math.floor(nowMs / 1000);
+    const nanos = Math.floor((nowMs - secs * 1000) * 1e6);
+    return `${secs}.${nanos}`;
+}
+/** `<sanitized title>-<secs>.<nanos>` — the session directory name. */
+export function sessionDirName(title, nowMs) {
+    return `${sanitizeComponent(title)}-${timestampSuffix(nowMs)}`;
+}
+/** The creation tail [`stripCreationSuffix`] removes: `-<secs>.<nanos>[-<n>]`. */
+const CREATION_SUFFIX = /-\d+\.\d+(-\d+)?$/;
+/**
+ * W779 T2 — the display name of a session DIRECTORY.
+ *
+ * A directory is `<sanitized title>-<secs>.<nanos>` (and `uniqueDir` may append
+ * `-N`), a uniqueness trick that must never reach the GUI:
+ *   main-1789192174.492000000 -> main
+ *   v2-1-1700000000.0-2       -> v2-1
+ *   plain                     -> plain        (nothing to strip)
+ *   报告-2024                  -> 报告-2024     (digits, but not a timestamp)
+ * A name that is ONLY a suffix keeps itself instead of becoming "".
+ */
+export function stripCreationSuffix(name) {
+    const stripped = name.replace(CREATION_SUFFIX, "");
+    return stripped === "" ? name : stripped;
+}
+/** Folder basename, or null when the path has no usable last component. */
+export function workspaceBasename(path, input = undefined) {
+    const base = baseName(path, input);
+    return base === "" || base === "/" || base === "\\" ? null : base;
+}
+/**
+ * W791: the two hidden sibling directories a session can be MOVED into.
+ *
+ * They live here (the session-directory vocabulary module) rather than in
+ * `session-ops.ts` because BOTH sides need them: the mover writes into them, and
+ * the scanner (`SessionsStore.listArchived`) reads `<ws>/.celestea-archived/`
+ * back. Importing the mover from the scanner would make the two modules
+ * circular, which the repo's dependency gate forbids.
+ *
+ * The names never change: a rename would orphan every archived session on disk.
+ */
+export const ARCHIVED_DIR = ".celestea-archived";
+export const TRASH_DIR = ".celestea-trash";
+/**
+ * W877 (slice A) — the workspace-level `.celestea/` container.
+ *
+ * Slice A sank NEW session dirs into `<ws>/.celestea/sessions/`; W880 moves the
+ * canonical container OUT of the workspace into `CELESTEA_HOME`, so this path is
+ * now only the MIDDLE read fallback (dual-read compatibility with real data
+ * written by slice A).
+ */
+export const CELESTEA_DIR = ".celestea";
+export const SESSIONS_SUBDIR = "sessions";
+/** W880 archive sub-container (under `workspaceHome`). */
+export const ARCHIVE_SUBDIR = "archive";
+/** W880 trash sub-container (under `workspaceHome`). */
+export const TRASH_SUBDIR = "trash";
+/** W880 workspace prompt-registry file name. */
+export const PROMPTS_FILE = "prompts.json";
+/** W880 run_code transient-program sub-container. */
+export const RUN_CODE_SUBDIR = "run-code";
+/** W880 canonical live-session root: `<CELESTEA_HOME>/workspaces/<ws>/sessions`. */
+export function sessionsRoot(wsPath, input = undefined) {
+    return under(input, workspaceHome(wsPath, inputOf(input)), SESSIONS_SUBDIR);
+}
+/** W877 transitional root: `<ws>/.celestea/sessions`. */
+export function legacySessionsRoot(wsPath, input = undefined) {
+    return under(input, wsPath, CELESTEA_DIR, SESSIONS_SUBDIR);
+}
+/**
+ * The [PlatformInput] form of a [PathInputLike]: a bare `"win32"` has to become
+ * an input object before it can reach `celestea-home`, which resolves its own
+ * per-platform defaults (and `homedir` matters for the win32 branch).
+ */
+function inputOf(input) {
+    if (input === undefined)
+        return {};
+    if (typeof input === "string")
+        return { platform: input };
+    return input;
+}
+/**
+ * The physical roots a live session may occupy, canonical FIRST:
+ * `<home>/.../sessions` -> `<ws>/.celestea/sessions` -> `<ws>`.
+ *
+ * Pure — the caller owns the filesystem side. `resolve()` uses the first
+ * existing candidate and falls back to the canonical root when none exists (so
+ * the write side stays consistent); `list()` scans all three and lets the
+ * canonical row shadow a same-named legacy one.
+ */
+export function sessionRoots(wsPath, input = undefined) {
+    return [sessionsRoot(wsPath, input), legacySessionsRoot(wsPath, input), wsPath];
+}
+/** `dir` under every live-session root, canonical FIRST. */
+export function liveDirCandidates(wsPath, dir, input = undefined) {
+    return sessionRoots(wsPath, input).map((root) => under(input, root, dir));
+}
+/** Archive roots, canonical FIRST: `home/archive` -> `.celestea/archive` -> `.celestea-archived`. */
+export function archiveRoots(wsPath, input = undefined) {
+    return [
+        under(input, workspaceHome(wsPath, inputOf(input)), ARCHIVE_SUBDIR),
+        under(input, wsPath, CELESTEA_DIR, ARCHIVE_SUBDIR),
+        under(input, wsPath, ARCHIVED_DIR),
+    ];
+}
+/** `dir` under every archive root, canonical FIRST. */
+export function archiveDirCandidates(wsPath, dir, input = undefined) {
+    return archiveRoots(wsPath, input).map((root) => under(input, root, dir));
+}
+/** Trash roots, canonical FIRST. */
+export function trashRoots(wsPath, input = undefined) {
+    return [
+        under(input, workspaceHome(wsPath, inputOf(input)), TRASH_SUBDIR),
+        under(input, wsPath, CELESTEA_DIR, TRASH_SUBDIR),
+        under(input, wsPath, TRASH_DIR),
+    ];
+}
+/** Workspace prompt-registry candidates, canonical FIRST (write target = `[0]`). */
+export function promptsFileCandidates(wsPath, input = undefined) {
+    return [
+        under(input, workspaceHome(wsPath, inputOf(input)), PROMPTS_FILE),
+        under(input, wsPath, CELESTEA_DIR, PROMPTS_FILE),
+        under(input, wsPath, ".celestea-prompts.json"),
+    ];
+}
+/** A hidden name can never become a visible session/workspace directory. */
+export function isHiddenName(name) {
+    return name === "" || name === "." || name === ".." || name.startsWith(".");
+}
+/** Workspace rename validation (`validate_workspace_name`). */
+export function validateWorkspaceName(raw) {
+    if (raw.trim() === "")
+        return { ok: false, error: "workspace name must not be empty" };
+    const name = sanitizeComponent(raw);
+    if (name === "")
+        return { ok: false, error: "workspace name must not be empty" };
+    if (name === "." || name === "..")
+        return { ok: false, error: `invalid workspace name '${raw}'` };
+    return { ok: true, name };
+}
+/** The host `isAbsolute` (kept exported for pre-W885 callers). */
+export function isAbsolute(path) {
+    return isAbsolutePath(path);
+}

package/dist/store/session-meta.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `<session-dir>/session.json` — the optional Studio session metadata
+ * (`contracts/data-files/session.schema.json`).
+ *
+ * The engine NEVER reads this file; only `POST /api/sessions` writes it (and
+ * only when `title` and/or `model` and/or `prompt` and/or `mode` is non-empty),
+ * `rename`/`branch` re-write it (see W779 below), and `activate`/`compact` honor
+ * its `model` override. Missing or corrupt files are tolerated (`None`), never
+ * repaired.
+ *
+ * W779 T2: `title` joins them — the ORIGINAL, un-sanitized session title (CJK,
+ * spaces and all), so the GUI can show `我的 会话` instead of the directory name
+ * `我的_会话-1700000000.0`. `POST /api/sessions` always has a title, so every
+ * session created from now on carries one; the field is optional on read, and a
+ * session without it falls back to the de-suffixed directory name.
+ *
+ * W729 (P0): `mode` joins `model`/`prompt` as a creation-time session property.
+ * K8: the default mode is *not* written — the KEY never appears for a session
+ * that did not ask for one. W779 T2 adds `title`, so the file itself now always
+ * exists; K8's guarantee is per-key (no `mode` key), not per-file.
+ */
+import { type SessionMode } from "./mode.js";
+export declare const SESSION_META = "session.json";
+export interface SessionMeta {
+    /**
+     * W779 T2: the display name, verbatim as the user typed it. Absent = the
+     * caller falls back to the directory name without its creation suffix.
+     */
+    title?: string;
+    model?: string;
+    prompt?: string;
+    /** Declared session mode; ABSENT = `standard` and no key on disk (K8). */
+    mode?: SessionMode;
+}
+/**
+ * Read the metadata; a corrupt file behaves exactly like a missing one, and a
+ * `mode` that is not a declared literal is dropped (never repaired on disk).
+ */
+export declare function readSessionMeta(dir: string): SessionMeta | null;
+/** Any of `title`/`model`/`prompt`/`mode` non-empty -> write; all empty -> no file. */
+export declare function writeSessionMeta(dir: string, meta: SessionMeta): void;