@celestea/studio 2.7.1

package/dist/store/workspaces.js

@@ -0,0 +1,228 @@
+/**
+ * `workspaces.json` (v2) registry store — `contracts/data-files/workspaces.schema.json`,
+ * `src/workspaces.rs:122-140,794-970`.
+ *
+ * Frozen format facts honored here:
+ *   - NO version field; the workspace KEY is the registered path's folder
+ *     basename and is never stored;
+ *   - v1 `{"name":…}` rows are tolerated and ignored; `active_session` is
+ *     rewritten to the basename on load (idempotent);
+ *   - unknown fields are tolerated, a malformed file is a HARD error (the
+ *     unreadable registry is never overwritten with an empty one);
+ *   - write = pretty JSON -> `<file>.json.tmp` -> rename (atomic, no fsync).
+ */
+import { renameSync } from "node:fs";
+import { resolve } from "node:path";
+import { writeJsonAtomic, isDirectory, isFile, listEntries, readJsonIfExists } from "./fs-json.js";
+import { badRequest, conflict, errText, fail, notFound, ok, serverError } from "./result.js";
+import { sessionRoots, workspaceBasename } from "./session-id.js";
+export const SESSION_FILE = "cli-main.jsonl";
+function parseEntry(row) {
+    if (typeof row !== "object" || row === null)
+        return null;
+    const path = row["path"];
+    return typeof path === "string" && path !== "" ? { path } : null;
+}
+function parseRegistry(raw) {
+    const rec = (typeof raw === "object" && raw !== null ? raw : {});
+    const rows = Array.isArray(rec["workspaces"]) ? rec["workspaces"] : [];
+    const workspaces = [];
+    for (const row of rows) {
+        const entry = parseEntry(row);
+        if (entry !== null)
+            workspaces.push(entry);
+    }
+    const active = rec["active_session"];
+    return { workspaces, active_session: typeof active === "string" && active !== "" ? active : null };
+}
+/** Duplicate folder names make the workspace key ambiguous: hard error. */
+function assertUniqueBasenames(workspaces) {
+    const seen = new Map();
+    for (const w of workspaces) {
+        const base = workspaceBasename(w.path) ?? w.path;
+        const other = seen.get(base);
+        if (other !== undefined && other !== w.path) {
+            throw new Error(`two workspaces resolve to the same folder name '${base}' (workspace keys must be unique basenames; rename one folder)`);
+        }
+        seen.set(base, w.path);
+    }
+}
+function loadRegistry(file) {
+    const out = readJsonIfExists(file);
+    if (!out.exists)
+        return { workspaces: [], active_session: null };
+    if (out.error !== undefined)
+        throw new Error(`workspaces.json '${file}' is malformed: ${out.error}`);
+    const data = parseRegistry(out.value);
+    assertUniqueBasenames(data.workspaces);
+    return data;
+}
+/**
+ * W815-9: a registered path is stored normalized (absolute, no trailing slash).
+ * `register` used to keep whatever the client sent, so `/tmp/foo/` made the
+ * rename target `/tmp/foo/bar` — a child of the source folder (EINVAL).
+ */
+function normalizeWorkspacePath(path) {
+    return resolve(path);
+}
+export class WorkspacesStore {
+    file;
+    data;
+    constructor(file) {
+        this.file = file;
+        this.data = loadRegistry(file);
+    }
+    /** Snapshot of the registry (callers must not mutate it). */
+    registry() {
+        return { workspaces: this.data.workspaces.map((w) => ({ ...w })), active_session: this.data.active_session };
+    }
+    activeSession() {
+        return this.data.active_session;
+    }
+    workspacePath(name) {
+        return this.data.workspaces.find((w) => workspaceBasename(w.path) === name)?.path;
+    }
+    persist() {
+        try {
+            writeJsonAtomic(this.file, { workspaces: this.data.workspaces, active_session: this.data.active_session });
+            return ok(undefined);
+        }
+        catch (e) {
+            return serverError(errText(e));
+        }
+    }
+    /** Persist `active_session`; the caller owns the 500 wording. */
+    setActiveSession(id) {
+        this.data.active_session = id;
+        return this.persist();
+    }
+    /**
+     * Count LIVE session dirs of a workspace across EVERY layer (W880): the
+     * canonical `<CELESTEA_HOME>/.../sessions`, the slice-A
+     * `<ws>/.celestea/sessions` and the oldest workspace root. A name present in
+     * more than one layer is counted ONCE (the canonical copy wins), matching
+     * `SessionsStore.list()`; missing a layer is how the GUI's workspace session
+     * count silently drops to 0.
+     */
+    countSessions(path) {
+        const seen = new Set();
+        for (const root of sessionRoots(path)) {
+            for (const e of listEntries(root)) {
+                if (!e.isDir || e.name.startsWith(".") || seen.has(e.name))
+                    continue;
+                if (isFile(`${root}/${e.name}/${SESSION_FILE}`))
+                    seen.add(e.name);
+            }
+        }
+        return seen.size;
+    }
+    view() {
+        return {
+            workspaces: this.data.workspaces.map((w) => {
+                const name = workspaceBasename(w.path) ?? w.path;
+                return { name, path: w.path, sessions: this.countSessions(w.path) };
+            }),
+            active_session: this.data.active_session,
+        };
+    }
+    /** POST /api/workspaces — register only; the folder is never touched. */
+    register(rawPath) {
+        const asked = rawPath.trim();
+        if (asked === "")
+            return badRequest("path must not be empty");
+        if (!asked.startsWith("/"))
+            return badRequest(`path '${asked}' must be absolute`);
+        // W815-9: canonicalize before storing (see `normalizeWorkspacePath`).
+        const path = normalizeWorkspacePath(asked);
+        if (!isDirectory(path))
+            return badRequest(`path '${path}' is not an existing directory`);
+        const base = workspaceBasename(path);
+        if (base === null)
+            return badRequest(`path '${path}' has no folder name`);
+        const existing = this.data.workspaces.find((w) => w.path === path);
+        if (existing !== undefined)
+            return conflict(`path '${path}' is already registered as workspace '${base}'`);
+        const clash = this.data.workspaces.find((w) => workspaceBasename(w.path) === base);
+        if (clash !== undefined) {
+            return conflict(`workspace '${base}' already exists (folder '${path}' and '${clash.path}' share the same folder name; rename one folder first)`);
+        }
+        this.data.workspaces.push({ path });
+        const saved = this.persist();
+        if (!saved.ok)
+            return saved;
+        return ok(base);
+    }
+    /** POST /api/workspaces/{name}/delete — deregister only. */
+    deregister(name) {
+        const idx = this.data.workspaces.findIndex((w) => workspaceBasename(w.path) === name);
+        if (idx < 0)
+            return notFound(`unknown workspace '${name}'`);
+        const [removed] = this.data.workspaces.splice(idx, 1);
+        if (this.data.active_session !== null && this.data.active_session.split("/")[0] === name) {
+            this.data.active_session = null;
+        }
+        void removed;
+        return this.persist();
+    }
+    batchDelete(names) {
+        let deleted = 0;
+        const failed = [];
+        for (const name of names) {
+            const res = this.deregister(name);
+            if (res.ok)
+                deleted += 1;
+            else
+                failed.push({ name, error: res.error });
+        }
+        return { deleted, failed };
+    }
+    /** POST /api/workspaces/{name}/rename — really renames the FOLDER. */
+    renameWorkspace(name, newName) {
+        const idx = this.data.workspaces.findIndex((w) => workspaceBasename(w.path) === name);
+        if (idx < 0)
+            return notFound(`unknown workspace '${name}'`);
+        const row = this.data.workspaces[idx];
+        if (row === undefined)
+            return notFound(`unknown workspace '${name}'`);
+        if (this.data.workspaces.some((w) => workspaceBasename(w.path) === newName)) {
+            return conflict(`workspace '${newName}' already exists`);
+        }
+        // W815-9: normalize a legacy row's path before deriving the sibling target.
+        const from = normalizeWorkspacePath(row.path);
+        row.path = from;
+        const parent = from.slice(0, from.lastIndexOf("/")) || "/";
+        const target = `${parent === "/" ? "" : parent}/${newName}`;
+        if (target !== row.path && isDirectory(target)) {
+            return conflict(`target '${target}' already exists; rename the folder first`);
+        }
+        const previousActive = this.data.active_session;
+        try {
+            renameSync(from, target);
+        }
+        catch (e) {
+            return fail(500, `move failed: ${errText(e)}`);
+        }
+        row.path = target;
+        if (this.data.active_session !== null) {
+            const [ws, sess] = this.data.active_session.split("/");
+            if (ws === name && sess !== undefined)
+                this.data.active_session = `${newName}/${sess}`;
+        }
+        const saved = this.persist();
+        if (!saved.ok) {
+            // W815-10: the registry is the source of truth and it did NOT accept the
+            // move — undo the folder rename and the in-memory row so disk and memory
+            // cannot diverge (the retired backend's rollback, restored).
+            row.path = from;
+            this.data.active_session = previousActive;
+            try {
+                renameSync(target, from);
+            }
+            catch (e) {
+                return fail(500, `${saved.error}; rollback failed: ${errText(e)}`);
+            }
+            return saved;
+        }
+        return saved;
+    }
+}

package/dist/user-questions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The host's user-question service (W783 §4.1, §5, §6).
+ *
+ * One instance per composed session generation, all sharing the process-wide
+ * [QuestionRegistry]: the service validates the request, parks a
+ * [PendingQuestion], publishes the `question` SSE frame and then awaits the
+ * ASYNC answerer waterfall. The parked promise is what the tool call is waiting
+ * on, so an answer resolves it directly (§4.2) instead of being injected as a
+ * message — the injection path is exactly the deadlock §2.2 documents.
+ *
+ * The three increments over the official implementation:
+ *   - **maximum wait** (§6): an absolute `expires_at` judged at read time plus a
+ *     `setTimeout` that actively settles the parked promise. Neither half alone
+ *     is enough: the deadline survives a restart and answers "how long is left",
+ *     while the timer is what stops a tool from hanging forever.
+ *   - **timeout decides nothing** (§6.3): `{answers: [], timed_out: true}`. No
+ *     default option is selected and the turn is not ended — the tool
+ *     description tells the model to carry on with its own judgement.
+ *   - **sub-agent guard** (§5.3): a worker-driven turn throws `DELEGATED_CALLER`
+ *     instead of parking forever with no human on the other end.
+ */
+import { type AskUserQuestionAnswerItem, type AskUserQuestionOutcome, type AskUserQuestionRequest, type EventBus } from "@celestea/core";
+import { PendingQuestion, type QuestionRegistry } from "./question-registry.js";
+/** What the service needs from the host (all injected — no Context lookups). */
+export interface UserQuestionServiceOptions {
+    registry: QuestionRegistry;
+    /** The session's event bus (`runWaterfallAsync` dispatches to answerers). */
+    bus: EventBus;
+    /** The session asking; `null` = the detached generation. */
+    sessionId: string | null;
+    /** Is this session's runtime instance still live? (§5.3 `CALLER_NOT_LIVE`) */
+    isLive?: () => boolean;
+    /** Publish one request to the UI (the `question` SSE frame, §9 item 9). */
+    publish?: (question: PendingQuestion) => void;
+    /**
+     * Record the request in the session log (§7 `user_question`). Absent = no
+     * persistence (the request then simply cannot be replayed after a restart).
+     */
+    record?: (question: PendingQuestion) => void;
+    /**
+     * Record how it ENDED (§7 `user_answer`). Called for BOTH paths — a real
+     * answer and a timeout — right here, because this is the single place that
+     * observes every settlement, whatever woke the question up.
+     */
+    recordAnswer?: (requestId: string, answers: AskUserQuestionAnswerItem[], timedOut: boolean) => void;
+    /** Clock override (tests pin the deadline arithmetic). */
+    now?: () => number;
+}
+/** The service the `ask_user_question` tool consumes. */
+export interface HostUserQuestionService {
+    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionOutcome>;
+    /** The unanswered questions of THIS session (§7 recovery). */
+    pending(): PendingQuestion[];
+    /** One pending question by id, or undefined. */
+    find(requestId: string): PendingQuestion | undefined;
+}
+/** Build the service of ONE composed session generation. */
+export declare function createUserQuestionService(opts: UserQuestionServiceOptions): HostUserQuestionService;

package/dist/user-questions.js

@@ -0,0 +1,157 @@
+/**
+ * The host's user-question service (W783 §4.1, §5, §6).
+ *
+ * One instance per composed session generation, all sharing the process-wide
+ * [QuestionRegistry]: the service validates the request, parks a
+ * [PendingQuestion], publishes the `question` SSE frame and then awaits the
+ * ASYNC answerer waterfall. The parked promise is what the tool call is waiting
+ * on, so an answer resolves it directly (§4.2) instead of being injected as a
+ * message — the injection path is exactly the deadlock §2.2 documents.
+ *
+ * The three increments over the official implementation:
+ *   - **maximum wait** (§6): an absolute `expires_at` judged at read time plus a
+ *     `setTimeout` that actively settles the parked promise. Neither half alone
+ *     is enough: the deadline survives a restart and answers "how long is left",
+ *     while the timer is what stops a tool from hanging forever.
+ *   - **timeout decides nothing** (§6.3): `{answers: [], timed_out: true}`. No
+ *     default option is selected and the turn is not ended — the tool
+ *     description tells the model to carry on with its own judgement.
+ *   - **sub-agent guard** (§5.3): a worker-driven turn throws `DELEGATED_CALLER`
+ *     instead of parking forever with no human on the other end.
+ */
+import { askTimeoutMs, currentAskUserCaller, USER_QUESTION_REQUEST_EVENT, UserQuestionError, } from "@celestea/core";
+import { PendingQuestion } from "./question-registry.js";
+/** The rejection an empty question list produces (§5.3 `EMPTY_QUESTIONS`). */
+function emptyQuestions() {
+    return new UserQuestionError("ask_user_question requires at least one question", "EMPTY_QUESTIONS");
+}
+/** The rejection a non-root (owned) caller produces (§5.3 `DELEGATED_CALLER`). */
+function delegatedCaller(owner) {
+    const who = owner === null ? "another live agent" : `agent '${owner}'`;
+    return new UserQuestionError(`human interaction is unavailable while the calling agent is owned by ${who}; `
+        + "include the unresolved question or decision in the child agent's final result", "DELEGATED_CALLER");
+}
+/** The rejection a dead asking generation produces (§5.3 `CALLER_NOT_LIVE`). */
+function callerNotLive() {
+    return new UserQuestionError("human interaction requires the exact live calling generation", "CALLER_NOT_LIVE");
+}
+/** The rejection an unanswered waterfall produces (§5.3 `NO_PROVIDER`). */
+function noAnswerer() {
+    return new UserQuestionError("no user-questions answerer accepted the request", "NO_PROVIDER");
+}
+/**
+ * `intent` asserts two things the types cannot (§3.3): the named `approve` label
+ * is one of THIS question's options, and a plan-review carries the plan it
+ * reviews. Either gap would show the user a choice the asker never offered — or
+ * an approval of something invisible — so it is caught here, at the asker.
+ */
+function validateIntent(question) {
+    const intent = question.intent;
+    if (intent === undefined)
+        return;
+    if (!(question.options ?? []).some((option) => option.label === intent.approve)) {
+        throw new UserQuestionError(`question ${question.id} declares intent ${intent.kind} whose approve label ${JSON.stringify(intent.approve)} names none of its options`, "BAD_INTENT");
+    }
+    if (question.detail === undefined) {
+        throw new UserQuestionError(`question ${question.id} declares intent ${intent.kind} without the detail it reviews`, "BAD_INTENT");
+    }
+}
+/** Run every request-shape check that must fail BEFORE a question is parked. */
+function validateRequest(request) {
+    if (request.questions.length === 0)
+        throw emptyQuestions();
+    for (const question of request.questions)
+        validateIntent(question);
+}
+/** The service body: validate, park, dispatch, settle (§5.1/§5.2/§6). */
+class HostUserQuestions {
+    opts;
+    now;
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? Date.now;
+    }
+    pending() {
+        return this.opts.registry.ofSession(this.opts.sessionId);
+    }
+    find(requestId) {
+        return this.opts.registry.get(requestId);
+    }
+    async ask(request) {
+        if (request.signal?.aborted === true)
+            throw new UserQuestionError("ask_user_question was aborted before the user answered", "ASK_ABORTED");
+        validateRequest(request);
+        this.assertCaller();
+        const timeoutMs = askTimeoutMs(request.timeoutMs);
+        const question = this.park(request, timeoutMs);
+        try {
+            const outcome = await this.dispatch(question);
+            // §7: the log records how it ended BEFORE the tool resumes, so a replay
+            // can tell a real answer from the §6.3 expiry without any timer.
+            this.opts.recordAnswer?.(question.requestId, outcome.answers, outcome.timed_out);
+            return outcome;
+        }
+        finally {
+            // Every exit path unregisters: a settled question is never listed again.
+            this.opts.registry.remove(question.requestId);
+        }
+    }
+    /** §5.3: only an unowned root turn has a human to answer it. */
+    assertCaller() {
+        const caller = currentAskUserCaller();
+        if (caller.kind === "delegated")
+            throw delegatedCaller(caller.owner);
+        if (this.opts.isLive !== undefined && !this.opts.isLive())
+            throw callerNotLive();
+    }
+    /** Create the pending entry, arm both timeout tracks and announce it. */
+    park(request, timeoutMs) {
+        const question = new PendingQuestion({
+            requestId: this.opts.registry.nextRequestId(),
+            sessionId: this.opts.sessionId,
+            questions: request.questions,
+            expiresAt: this.now() + timeoutMs,
+            timeoutMs,
+            ...(request.signal === undefined ? {} : { signal: request.signal }),
+        });
+        this.opts.registry.add(question);
+        // The ACTIVE half of the double track (§6.1) — without it a tool whose
+        // answer never arrives would hang for the life of the process.
+        question.armTimer(this.now);
+        this.opts.publish?.(question);
+        this.opts.record?.(question);
+        return question;
+    }
+    /**
+     * Hand the parked question to the answerer waterfall.
+     *
+     * The BOTTOM of the chain awaits the pending question, because in this host
+     * the human is out of process: the browser answers over
+     * `POST /api/questions/{id}/answer` and that resolves this very promise. A
+     * composed layer (a plan-review presenter, a test harness) may still CLAIM the
+     * request by returning an outcome of its own without ever calling `next()`.
+     *
+     * Either way the value that comes back is the human's answer, which is what
+     * lets a question be answered while the turn slot is occupied (§4.2).
+     */
+    async dispatch(question) {
+        const event = {
+            questions: [...question.questions],
+            timeoutMs: Math.max(0, question.expiresAt - this.now()),
+        };
+        try {
+            return await this.opts.bus.runWaterfallAsync(USER_QUESTION_REQUEST_EVENT, event, () => question.result);
+        }
+        catch (error) {
+            // A layer that delegated the SERVICE's own question left nobody to answer
+            // it: report the seam as unclaimed rather than leaking the sentinel.
+            if (question.isDelegation(error))
+                throw noAnswerer();
+            throw error;
+        }
+    }
+}
+/** Build the service of ONE composed session generation. */
+export function createUserQuestionService(opts) {
+    return new HostUserQuestions(opts);
+}

package/dist/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * W887 + H: the studio's version string, resolvable BOTH in the source checkout
+ * and from a globally installed package.
+ *
+ * The single source of truth is `scripts/version.mjs` (git tag). That file only
+ * exists in the checkout, so it is imported DYNAMICALLY: a source run gets the
+ * git-derived version, an installed package (no checkout, no git) falls back to
+ * its own `package.json` version. A missing toolchain degrades instead of
+ * failing module load, and the answer is cached after the first resolution.
+ */
+/** The git-derived version in a checkout, else the package version. */
+export declare function resolveStudioVersion(): Promise<string>;
+/** Test seam: forget the memoized answer. */
+export declare function resetStudioVersionCache(): void;

package/dist/version.js

@@ -0,0 +1,52 @@
+/**
+ * W887 + H: the studio's version string, resolvable BOTH in the source checkout
+ * and from a globally installed package.
+ *
+ * The single source of truth is `scripts/version.mjs` (git tag). That file only
+ * exists in the checkout, so it is imported DYNAMICALLY: a source run gets the
+ * git-derived version, an installed package (no checkout, no git) falls back to
+ * its own `package.json` version. A missing toolchain degrades instead of
+ * failing module load, and the answer is cached after the first resolution.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cached = null;
+/** The installed package's own version — the release truth. */
+function ownPackageVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        try {
+            const doc = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (typeof doc.version === "string" && doc.version !== "")
+                return doc.version;
+        }
+        catch {
+            // No package.json here; keep walking toward the root.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return "dev";
+}
+/** The git-derived version in a checkout, else the package version. */
+export async function resolveStudioVersion() {
+    if (cached !== null)
+        return cached;
+    try {
+        // W887: the checkout-only toolchain seam, imported dynamically so an
+        // installed package (no scripts/) degrades to its package.json version.
+        const mod = (await import("../../../scripts/version.mjs"));
+        cached = mod.computeVersion().version;
+    }
+    catch {
+        cached = ownPackageVersion();
+    }
+    return cached;
+}
+/** Test seam: forget the memoized answer. */
+export function resetStudioVersionCache() {
+    cached = null;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@celestea/studio",
+  "version": "2.7.1",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "hono": "^4.13.8",
+    "@celestea/agent-loop": "2.7.1",
+    "@celestea/core": "2.7.1",
+    "@celestea/runtime": "2.7.1",
+    "@celestea/session": "2.7.1",
+    "@celestea/llm": "2.7.1",
+    "@celestea/tools": "2.7.1",
+    "@celestea/workers": "2.7.1"
+  },
+  "files": [
+    "dist",
+    "webdist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "start": "tsx src/main.ts",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/build-webdist.mjs"
+  }
+}