celestea-agent 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/args.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `celestea` CLI argument parsing (H) — pure and unit-testable.
+ *
+ * Supported:
+ *   celestea web [--port N] [--bind ADDR] [--no-open] [--token SECRET]
+ *   celestea --version | -v
+ *   celestea --help | -h
+ *
+ * Unknown flags/commands are an explicit error (never silently ignored), so a
+ * typo cannot start a server on the wrong port.
+ */
+export declare const DEFAULT_PORT = 3777;
+export declare const DEFAULT_BIND = "127.0.0.1";
+export type CliCommand = "web" | "version" | "help";
+export interface WebOptions {
+    port: number;
+    bind: string;
+    open: boolean;
+    /** H-security: bearer token; `undefined` = fall back to CELESTEA_AUTH_TOKEN. */
+    token?: string;
+}
+export type ParseResult = {
+    ok: true;
+    command: "web";
+    options: WebOptions;
+} | {
+    ok: true;
+    command: "version";
+} | {
+    ok: true;
+    command: "help";
+} | {
+    ok: false;
+    error: string;
+};
+/** The argv after the program name, e.g. `["web", "--port", "8080"]`. */
+export declare function parseArgs(argv: readonly string[]): ParseResult;
+export declare const HELP_TEXT: string;

package/dist/args.js

@@ -0,0 +1,94 @@
+/**
+ * `celestea` CLI argument parsing (H) — pure and unit-testable.
+ *
+ * Supported:
+ *   celestea web [--port N] [--bind ADDR] [--no-open] [--token SECRET]
+ *   celestea --version | -v
+ *   celestea --help | -h
+ *
+ * Unknown flags/commands are an explicit error (never silently ignored), so a
+ * typo cannot start a server on the wrong port.
+ */
+export const DEFAULT_PORT = 3777;
+export const DEFAULT_BIND = "127.0.0.1";
+/** Parse `--port N` / `--port=N`; a non-integer or out-of-range port is an error. */
+function parsePort(raw) {
+    const port = Number.parseInt(raw, 10);
+    if (!Number.isInteger(port) || port < 0 || port > 65535 || String(port) !== raw.trim()) {
+        return { error: `--port must be an integer between 0 and 65535 (got ${JSON.stringify(raw)})` };
+    }
+    return { port };
+}
+/** The argv after the program name, e.g. `["web", "--port", "8080"]`. */
+export function parseArgs(argv) {
+    const rest = [...argv];
+    const first = rest.shift();
+    if (first === undefined || first === "--help" || first === "-h")
+        return { ok: true, command: "help" };
+    if (first === "--version" || first === "-v")
+        return { ok: true, command: "version" };
+    if (first !== "web")
+        return { ok: false, error: `unknown command ${JSON.stringify(first)} (expected "web")` };
+    const options = { port: DEFAULT_PORT, bind: DEFAULT_BIND, open: true };
+    while (rest.length > 0) {
+        const flag = rest.shift();
+        if (flag === "--no-open") {
+            options.open = false;
+            continue;
+        }
+        if (flag === "--port" || flag.startsWith("--port=")) {
+            const raw = flag.includes("=") ? flag.slice("--port=".length) : rest.shift();
+            if (raw === undefined)
+                return { ok: false, error: "--port requires a value" };
+            const parsed = parsePort(raw);
+            if ("error" in parsed)
+                return { ok: false, error: parsed.error };
+            options.port = parsed.port;
+            continue;
+        }
+        if (flag === "--bind" || flag.startsWith("--bind=")) {
+            const raw = flag.includes("=") ? flag.slice("--bind=".length) : rest.shift();
+            if (raw === undefined || raw.trim() === "")
+                return { ok: false, error: "--bind requires a non-empty value" };
+            options.bind = raw.trim();
+            continue;
+        }
+        if (flag === "--token" || flag.startsWith("--token=")) {
+            const raw = flag.includes("=") ? flag.slice("--token=".length) : rest.shift();
+            if (raw === undefined || raw.trim() === "")
+                return { ok: false, error: "--token requires a non-empty value" };
+            options.token = raw.trim();
+            continue;
+        }
+        return { ok: false, error: `unknown option ${JSON.stringify(flag)}` };
+    }
+    return { ok: true, command: "web", options };
+}
+export const HELP_TEXT = [
+    "celestea — Celestea Studio agent (web UI + HTTP API)",
+    "",
+    "Usage:",
+    "  celestea web [--port N] [--bind ADDR] [--no-open] [--token SECRET]",
+    "  celestea --version",
+    "  celestea --help",
+    "",
+    "Options:",
+    `  --port N      HTTP port (default ${DEFAULT_PORT}; 0 = an ephemeral free port)`,
+    `  --bind ADDR   Bind address (default ${DEFAULT_BIND}).`,
+    "  --no-open     Do not open the browser",
+    "  --token SEC   Require this bearer token on every /api/* request except",
+    "                /api/health (also read from CELESTEA_AUTH_TOKEN).",
+    "                Browser: open http://<host>:<port>/auth/token?token=<SEC> once",
+    "                to set the HttpOnly session cookie, then use the UI normally.",
+    "",
+    "WARNING — a non-loopback --bind (0.0.0.0 / :: / a public IP) is NOT just",
+    "'the web UI': it exposes FULL unauthenticated control of this machine:",
+    "  · POST /api/exec runs arbitrary shell commands as this user;",
+    "  · GET /api/fs/list reads any directory;",
+    "  · every agent endpoint (turn, tools, sessions) is reachable.",
+    "Such a bind is REFUSED unless a token is configured. Prefer --bind 127.0.0.1",
+    "behind nginx (which owns the browser login gate).",
+    "",
+    "Data root: $CELESTEA_HOME (else $XDG_DATA_HOME/celestea, else ~/.celestea).",
+    "Set the model + API key in <data root>/providers.json, or via CELESTEA_API_KEY.",
+].join("\n");

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `celestea-agent` — the published CLI + cross-platform launch helpers (H).
+ *
+ * The executable is `dist/main.js` (bin: `celestea`); the pure helpers are
+ * exported so the platform branches are unit-tested without a real browser.
+ */
+export * from "./args.js";
+export * from "./open-browser.js";
+export * from "./paths.js";
+export * from "./sandbox-note.js";
+export * from "./web.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `celestea-agent` — the published CLI + cross-platform launch helpers (H).
+ *
+ * The executable is `dist/main.js` (bin: `celestea`); the pure helpers are
+ * exported so the platform branches are unit-tested without a real browser.
+ */
+export * from "./args.js";
+export * from "./open-browser.js";
+export * from "./paths.js";
+export * from "./sandbox-note.js";
+export * from "./web.js";

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** The installed package's own version (a release tag, never a git describe). */
+export declare function readVersion(from?: string): string;

package/dist/main.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * `celestea` — the published CLI entry (H).
+ *
+ * `celestea web` boots the studio HTTP server (shared with the source entry via
+ * `@celestea/studio`); `--version`/`--help` are pure. A parse error exits 2
+ * with the usage line, never a silent start.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { HELP_TEXT, parseArgs } from "./args.js";
+import { runWeb } from "./web.js";
+/** The installed package's own version (a release tag, never a git describe). */
+export function readVersion(from = import.meta.url) {
+    try {
+        const path = fileURLToPath(new URL("../package.json", from));
+        const doc = JSON.parse(readFileSync(path, "utf8"));
+        return typeof doc.version === "string" ? doc.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const parsed = parseArgs(process.argv.slice(2));
+if (!parsed.ok) {
+    console.error("celestea: " + parsed.error);
+    console.error("Run 'celestea --help' for usage.");
+    process.exit(2);
+}
+if (parsed.command === "help") {
+    console.log(HELP_TEXT);
+}
+else if (parsed.command === "version") {
+    console.log(readVersion());
+}
+else {
+    try {
+        runWeb(parsed.options);
+    }
+    catch (e) {
+        console.error("[celestea] FATAL: " + (e instanceof Error ? e.message : String(e)));
+        process.exit(1);
+    }
+}

package/dist/open-browser.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Open the operator's browser at `url` (H) — the cross-platform seam.
+ *
+ * Reuses the W885 platform primitives (`isWindows`, `whichInPath`) instead of
+ * hard-coding a per-OS branch, and takes `platform` / `env` / `spawn` as
+ * arguments so the Windows path is unit-testable on this Linux host (the host
+ * is never asked).
+ *
+ * Command per platform:
+ *   win32  -> `cmd /d /s /c start "" <url>`  (start is a cmd builtin; the empty
+ *             title argument keeps a quoted URL from being read as a title)
+ *   darwin -> `open <url>`
+ *   other  -> `xdg-open <url>` (the freedesktop opener; absent on a headless
+ *             box, which is reported, never a crash)
+ */
+export interface OpenBrowserInput {
+    platform?: NodeJS.Platform | string;
+    env?: Record<string, string | undefined>;
+    /** Injected launcher (tests capture argv; default: `node:child_process`). */
+    spawn?: (command: string, args: readonly string[], detached: boolean) => void;
+    /** Injected existence check for the opener binary (tests). */
+    which?: (bin: string) => string | null;
+}
+export type OpenBrowserResult = {
+    opened: true;
+    command: string;
+    args: readonly string[];
+} | {
+    opened: false;
+    reason: string;
+};
+/** The opener command + argv for `url` on `platform` (pure). */
+export declare function openerFor(url: string, platform: string): {
+    command: string;
+    args: readonly string[];
+};
+/**
+ * Open `url`. Never throws: a missing opener (headless Linux, minimal
+ * container) returns `{opened:false}` so the caller can print the URL instead.
+ */
+export declare function openBrowser(url: string, input?: OpenBrowserInput): OpenBrowserResult;

package/dist/open-browser.js

@@ -0,0 +1,47 @@
+/**
+ * Open the operator's browser at `url` (H) — the cross-platform seam.
+ *
+ * Reuses the W885 platform primitives (`isWindows`, `whichInPath`) instead of
+ * hard-coding a per-OS branch, and takes `platform` / `env` / `spawn` as
+ * arguments so the Windows path is unit-testable on this Linux host (the host
+ * is never asked).
+ *
+ * Command per platform:
+ *   win32  -> `cmd /d /s /c start "" <url>`  (start is a cmd builtin; the empty
+ *             title argument keeps a quoted URL from being read as a title)
+ *   darwin -> `open <url>`
+ *   other  -> `xdg-open <url>` (the freedesktop opener; absent on a headless
+ *             box, which is reported, never a crash)
+ */
+import { isWindows, whichInPath } from "@celestea/tools";
+/** The opener command + argv for `url` on `platform` (pure). */
+export function openerFor(url, platform) {
+    if (isWindows(platform))
+        return { command: "cmd", args: ["/d", "/s", "/c", "start", "", url] };
+    if (platform === "darwin")
+        return { command: "open", args: [url] };
+    return { command: "xdg-open", args: [url] };
+}
+/**
+ * Open `url`. Never throws: a missing opener (headless Linux, minimal
+ * container) returns `{opened:false}` so the caller can print the URL instead.
+ */
+export function openBrowser(url, input = {}) {
+    const platform = input.platform ?? process.platform;
+    const env = input.env ?? process.env;
+    const { command, args } = openerFor(url, platform);
+    const which = input.which ?? ((bin) => whichInPath(bin, platform, env));
+    if (which(command) === null)
+        return { opened: false, reason: `${command} not found on PATH` };
+    const launch = input.spawn ??
+        ((cmd, argv, detached) => {
+            // Lazy import keeps this module pure for the unit tests that inject spawn.
+            void import("node:child_process").then(({ spawn }) => {
+                const child = spawn(cmd, [...argv], { detached, stdio: "ignore" });
+                child.on("error", () => { });
+                child.unref();
+            });
+        });
+    launch(command, args, true);
+    return { opened: true, command, args };
+}

package/dist/paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI path/guidance resolution (H) — the cross-platform data root.
+ *
+ * The CLI never hard-codes `/var/lib` or a checkout path: the data root comes
+ * from `celesteaHome()` (W880: `$CELESTEA_HOME` -> XDG -> `~/.celestea` ->
+ * `%USERPROFILE%\.celestea`), and every file under it is derived from there.
+ */
+export interface CliPaths {
+    home: string;
+    workspacesFile: string;
+    providersFile: string;
+    promptsFile: string;
+}
+/** Every path the studio reads, rooted at the cross-platform data home. */
+export declare function cliPaths(env?: NodeJS.ProcessEnv, home?: string): CliPaths;
+/**
+ * The first-run guidance lines. `hasApiKey` is the secret-free fact the engine
+ * view already computed; when it is false the operator gets an actionable
+ * message instead of a silent failure at the first turn.
+ */
+export declare function firstRunGuidance(paths: CliPaths, hasApiKey: boolean): string[];

package/dist/paths.js

@@ -0,0 +1,33 @@
+/**
+ * CLI path/guidance resolution (H) — the cross-platform data root.
+ *
+ * The CLI never hard-codes `/var/lib` or a checkout path: the data root comes
+ * from `celesteaHome()` (W880: `$CELESTEA_HOME` -> XDG -> `~/.celestea` ->
+ * `%USERPROFILE%\.celestea`), and every file under it is derived from there.
+ */
+import { celesteaHome } from "@celestea/core";
+import { join } from "node:path";
+/** Every path the studio reads, rooted at the cross-platform data home. */
+export function cliPaths(env = process.env, home = celesteaHome({ env })) {
+    return {
+        home,
+        workspacesFile: join(home, "workspaces.json"),
+        providersFile: join(home, "providers.json"),
+        promptsFile: join(home, "prompts.json"),
+    };
+}
+/**
+ * The first-run guidance lines. `hasApiKey` is the secret-free fact the engine
+ * view already computed; when it is false the operator gets an actionable
+ * message instead of a silent failure at the first turn.
+ */
+export function firstRunGuidance(paths, hasApiKey) {
+    if (hasApiKey)
+        return [];
+    return [
+        "no model API key is configured — the UI will start, but a turn cannot run yet.",
+        `  1. create ${paths.providersFile} (mode 0600) with a provider row, or`,
+        "  2. export CELESTEA_API_KEY=<your key> (and optionally CELESTEA_BASE_URL / CELESTEA_MODEL).",
+        "  See GET /api/providers for the expected shape; the key is never logged.",
+    ];
+}

package/dist/sandbox-note.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The startup sandbox note (H) — say the security posture out loud.
+ *
+ * `selectSandboxDetailed` is the SAME policy the engine composes per session, so
+ * the CLI reports the provider that will actually run commands. On Windows (no
+ * bwrap) or a Linux host without bwrap this is the userspace provider, and the
+ * note states the degradation and the `CELESTEA_SANDBOX_FALLBACK` value instead
+ * of pretending isolation is on.
+ */
+import { type HostProbe } from "@celestea/tools";
+export interface SandboxNoteInput {
+    env?: NodeJS.ProcessEnv;
+    /** Injected host probe (tests); default: the memoized real probe. */
+    probe?: HostProbe;
+}
+/** One human line describing the sandbox decision (never throws on `fail`). */
+export declare function sandboxStartupNote(input?: SandboxNoteInput): string;

package/dist/sandbox-note.js

@@ -0,0 +1,32 @@
+/**
+ * The startup sandbox note (H) — say the security posture out loud.
+ *
+ * `selectSandboxDetailed` is the SAME policy the engine composes per session, so
+ * the CLI reports the provider that will actually run commands. On Windows (no
+ * bwrap) or a Linux host without bwrap this is the userspace provider, and the
+ * note states the degradation and the `CELESTEA_SANDBOX_FALLBACK` value instead
+ * of pretending isolation is on.
+ */
+import { ENV_SANDBOX_FALLBACK, fallbackMode, selectSandboxDetailed } from "@celestea/tools";
+/** One human line describing the sandbox decision (never throws on `fail`). */
+export function sandboxStartupNote(input = {}) {
+    const env = input.env ?? process.env;
+    let mode;
+    try {
+        mode = fallbackMode(env);
+    }
+    catch {
+        return `sandbox: invalid ${ENV_SANDBOX_FALLBACK} — refusing to guess (see the docs)`;
+    }
+    let selection;
+    try {
+        selection = selectSandboxDetailed({ env, ...(input.probe === undefined ? {} : { probe: input.probe }) });
+    }
+    catch (e) {
+        return `sandbox: refusing to execute — ${e instanceof Error ? e.message : String(e)}`;
+    }
+    if (selection.provider === "bwrap" && !selection.degraded) {
+        return "sandbox: bwrap (namespaces + private tmp; network isolated unless granted)";
+    }
+    return `sandbox: DEGRADED to userspace — ${selection.reason ?? "bwrap unavailable"} (${ENV_SANDBOX_FALLBACK}=${mode})`;
+}

package/dist/web.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `celestea web` (H) — start the studio and (by default) open the browser.
+ *
+ * The HTTP server itself is `startStudioServer` from `@celestea/studio`, so
+ * this command owns only: the data-root paths, the startup banner (sandbox +
+ * first-run guidance), the browser hand-off, and the signal wiring.
+ */
+import { type StudioServerHandle, type StudioServerOptions } from "@celestea/studio";
+import type { WebOptions } from "./args.js";
+import { openBrowser } from "./open-browser.js";
+export interface RunWebDeps {
+    env?: NodeJS.ProcessEnv;
+    /** Injected server start (tests); default: the real `startStudioServer`. */
+    start?: (options: StudioServerOptions) => StudioServerHandle;
+    /** Injected opener (tests); default: the real `openBrowser`. */
+    open?: typeof openBrowser;
+    /** Injected contract gate (tests); default: the real one. */
+    verify?: () => void;
+    /** Injected signal registrar (tests); default: `process.on`. */
+    onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
+}
+export interface RunWebResult {
+    handle: StudioServerHandle;
+    url: string;
+    guidance: string[];
+}
+/** Start the server; returns the handle plus the lines already printed. */
+export declare function runWeb(options: WebOptions, deps?: RunWebDeps): RunWebResult;

package/dist/web.js

@@ -0,0 +1,58 @@
+/**
+ * `celestea web` (H) — start the studio and (by default) open the browser.
+ *
+ * The HTTP server itself is `startStudioServer` from `@celestea/studio`, so
+ * this command owns only: the data-root paths, the startup banner (sandbox +
+ * first-run guidance), the browser hand-off, and the signal wiring.
+ */
+import { verifyContractsAtStartup } from "@celestea/core";
+import { isLoopbackBind, loadStudioConfig, startStudioServer } from "@celestea/studio";
+import { openBrowser } from "./open-browser.js";
+import { cliPaths, firstRunGuidance } from "./paths.js";
+import { sandboxStartupNote } from "./sandbox-note.js";
+/** Start the server; returns the handle plus the lines already printed. */
+export function runWeb(options, deps = {}) {
+    const env = deps.env ?? process.env;
+    const paths = cliPaths(env);
+    const verify = deps.verify ?? verifyContractsAtStartup;
+    verify();
+    const config = loadStudioConfig({
+        env,
+        paths: { workspacesFile: paths.workspacesFile, providersFile: paths.providersFile, promptsFile: paths.promptsFile },
+        // H-security: --token wins; else CELESTEA_AUTH_TOKEN. A non-loopback bind
+        // with neither is refused inside startStudioServer (never a silent hole).
+        ...(options.token === undefined ? {} : { authToken: options.token }),
+    });
+    const start = deps.start ?? startStudioServer;
+    const handle = start({ port: options.port, hostname: options.bind, config, env });
+    const url = `http://${options.bind === "0.0.0.0" ? "127.0.0.1" : options.bind}:${handle.port}/`;
+    console.log("[celestea] data root: " + paths.home);
+    console.log("[celestea] " + sandboxStartupNote({ env }));
+    if (config.authToken !== null) {
+        console.log("[celestea] api token: required on every /api/* request except /api/health");
+        // Never echo the secret: print the bootstrap URL with a placeholder.
+        const shown = options.bind === "0.0.0.0" || options.bind === "::" ? "127.0.0.1" : options.bind;
+        console.log(`[celestea] browser: open http://${shown}:${handle.port}/auth/token?token=<your-token> once to sign in`);
+        if (!isLoopbackBind(options.bind)) {
+            console.log("[celestea] WARNING: non-loopback + plain HTTP — the token and its cookie travel in cleartext; put TLS (nginx) in front for anything beyond a trusted network");
+        }
+    }
+    // The composed engine injects the providers.json key into this env in memory;
+    // reading the env AFTER start therefore reflects both sources, without ever
+    // printing the secret.
+    const hasApiKey = (env[config.apiKeyEnv] ?? "").trim() !== "";
+    const guidance = firstRunGuidance(paths, hasApiKey);
+    for (const line of guidance)
+        console.log("[celestea] " + line);
+    if (options.open) {
+        const opened = (deps.open ?? openBrowser)(url);
+        console.log(opened.opened ? `[celestea] opened ${url}` : `[celestea] could not open a browser (${opened.reason}); open ${url}`);
+    }
+    else {
+        console.log("[celestea] open " + url);
+    }
+    const onSignal = deps.onSignal ?? ((signal, handler) => void process.on(signal, handler));
+    for (const signal of ["SIGINT", "SIGTERM"])
+        onSignal(signal, () => void handle.stop(signal));
+    return { handle, url, guidance };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "celestea-agent",
+  "version": "2.7.1",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "description": "Celestea Studio agent — web UI + HTTP API, one command",
+  "bin": {
+    "celestea": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@celestea/studio": "2.7.1",
+    "@celestea/core": "2.7.1",
+    "@celestea/tools": "2.7.1"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/make-bin-executable.mjs dist/main.js"
+  }
+}