@celestea/core 2.7.1

package/dist/agent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * AgentLoop seam — port of `crates/core/src/agent.rs`.
+ *
+ * The loop drives one user turn against a Context: append to the session log,
+ * step the model, dispatch tool calls, write the final assistant message. The
+ * concrete loop lives in packages/agent-loop and is plugged in at compose time.
+ */
+import type { Context } from "./context.js";
+import type { ImageRef } from "./message.js";
+import type { ModelRequest } from "./stream.js";
+export interface AgentConfig {
+    model: string;
+    system_prompt: string;
+    max_steps: number;
+    max_parallel_tool_calls: number;
+    /** Model context window in tokens; 0 disables context trimming. */
+    context_window_tokens: number;
+    /** Trim factor (0..=1) of the window that triggers old-message trimming. */
+    context_trim_threshold: number;
+    /** How many most-recent messages to keep when trimming (plus system). */
+    context_keep_recent: number;
+}
+/** The engine's `AgentConfig::default()` — values are contract (identity prompt included). */
+export declare function defaultAgentConfig(): AgentConfig;
+export declare class AgentError extends Error {
+    constructor(message: string);
+}
+export interface AgentLoop {
+    /**
+     * Drive one user turn; rejects with [AgentError] on a terminal failure.
+     *
+     * W804: `attachments` are content-addressed image references for THIS
+     * turn's user message. The loop writes them onto the `user_message` row; the
+     * bytes never enter the log. Omitted/empty => the pre-W804 row byte for byte.
+     *
+     * W855 (C8): `userInput === null` means "this turn has NO input of its own" —
+     * the content is whatever the turn-start drain already injected (a queued
+     * `next-turn` lane message or a mailbox receipt). The loop then writes NO
+     * `user_message` row for the input, so an autowake turn never fabricates an
+     * empty user bubble. `null` is not `""`: the host rejects empty text
+     * (`input must not be empty`) and `""` is reserved for image-only turns
+     * (W804, `""` + attachments).
+     */
+    runTurn(ctx: Context, userInput: string | null, attachments?: readonly ImageRef[]): Promise<void>;
+}
+/**
+ * Optional `AgentLoop` capability (W725): hand back the EXACT request the next
+ * step would build for `ctx` — system prompt, post-trim history and tool
+ * schemas, i.e. the very object the loop hands to `Llm.generate`.
+ *
+ * It exists so a read-only context viewer (the host's "what does the model see
+ * right now" pane) reads the engine's own assembly instead of re-deriving it:
+ * a second trim/derive implementation would drift from the loop.
+ */
+export interface AgentLoopContextSnapshot {
+    contextSnapshot(ctx: Context): ModelRequest;
+}
+/**
+ * `contextSnapshot()` of a loop, or null when it does not implement the
+ * capability (test doubles / scripted loops). Never throws: a missing
+ * capability is a "no snapshot available", not a broken turn.
+ */
+export declare function contextSnapshotOf(loop: unknown, ctx: Context): ModelRequest | null;
+/** Well-known token for the agent loop service in a Context. */
+export declare const AGENT_LOOP_SERVICE = "celestea.core.AgentLoop";

package/dist/agent.js

@@ -0,0 +1,36 @@
+/**
+ * AgentLoop seam — port of `crates/core/src/agent.rs`.
+ *
+ * The loop drives one user turn against a Context: append to the session log,
+ * step the model, dispatch tool calls, write the final assistant message. The
+ * concrete loop lives in packages/agent-loop and is plugged in at compose time.
+ */
+/** The engine's `AgentConfig::default()` — values are contract (identity prompt included). */
+export function defaultAgentConfig() {
+    return {
+        model: "deepseek-chat",
+        system_prompt: "You are celestea, an AI agent. You are concise, accurate and direct.",
+        max_steps: 16,
+        max_parallel_tool_calls: 4,
+        context_window_tokens: 65_536,
+        context_trim_threshold: 0.8,
+        context_keep_recent: 10,
+    };
+}
+export class AgentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentError";
+    }
+}
+/**
+ * `contextSnapshot()` of a loop, or null when it does not implement the
+ * capability (test doubles / scripted loops). Never throws: a missing
+ * capability is a "no snapshot available", not a broken turn.
+ */
+export function contextSnapshotOf(loop, ctx) {
+    const fn = loop?.contextSnapshot;
+    return typeof fn === "function" ? fn.call(loop, ctx) : null;
+}
+/** Well-known token for the agent loop service in a Context. */
+export const AGENT_LOOP_SERVICE = "celestea.core.AgentLoop";

package/dist/celestea-home.d.ts

@@ -0,0 +1,63 @@
+/**
+ * CELESTEA_HOME — the cross-platform data root (W880).
+ *
+ * Every celestea artifact used to live inside the workspace: session dirs, the
+ * archive / trash siblings, the workspace prompt registry and run_code's
+ * transient programs. That pollutes the user's repository (a `git add -A` could
+ * commit private conversations) and ignores the OS conventions. W880 moves ALL of
+ * it into one data root, resolved with the order the established agent CLIs use
+ * (Claude Code `~/.claude`, Codex `~/.codex`, Gemini CLI `~/.gemini`):
+ *
+ *   1. `$CELESTEA_HOME`                    — explicit override; production systemd
+ *                                            pins `/var/lib/celestea-agent` (the FHS
+ *                                            `/var/lib/<service>` location);
+ *   2. `$XDG_DATA_HOME/celestea` (Linux)   — XDG Base Directory, the ask behind
+ *                                            anthropics/claude-code#1455;
+ *   3. `~/.celestea`                       — Linux/macOS default, the de-facto
+ *                                            standard of the agent CLIs;
+ *   4. `%USERPROFILE%\.celestea` (Windows) — Windows default.
+ *
+ * This module is PURE: it reads the injected `env` / `platform` / `homedir`
+ * (defaulting to the process), never the filesystem, so the whole order is a
+ * unit-testable function. The layout under the root is
+ *
+ *   <home>/workspaces/<workspace-folder>/{sessions,archive,trash,run-code}/
+ *   <home>/workspaces/<workspace-folder>/prompts.json
+ *
+ * `<workspace-folder>` is the same key `workspaces.json` uses (the registered
+ * path's basename; see `apps/studio/src/store/workspaces.ts`).
+ */
+/** Env var: explicit data-root override (highest priority). */
+export declare const CELESTEA_HOME_ENV = "CELESTEA_HOME";
+/** Folder under `$XDG_DATA_HOME` on Linux. */
+export declare const CELESTEA_DATA_DIR = "celestea";
+/** Folder under the data root that holds every workspace's container. */
+export declare const CELESTEA_WORKSPACES_DIR = "workspaces";
+/** Live-session sub-container. */
+export declare const CELESTEA_SESSIONS_DIR = "sessions";
+/** Archived-session sub-container. */
+export declare const CELESTEA_ARCHIVE_DIR = "archive";
+/** Trashed-session sub-container. */
+export declare const CELESTEA_TRASH_DIR = "trash";
+/** run_code's transient program sub-container. */
+export declare const CELESTEA_RUN_CODE_DIR = "run-code";
+/** Workspace-scoped prompt registry file name. */
+export declare const CELESTEA_PROMPTS_FILE = "prompts.json";
+/** Everything `celesteaHome` may depend on, injectable for tests. */
+export interface CelesteaHomeInput {
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform | string;
+    homedir?: string;
+}
+/** The folder name that keys a workspace (same rule as `workspaces.json`). */
+export declare function workspaceFolderName(wsPath: string, platform?: string): string;
+/**
+ * Resolve the celestea data root. First hit wins:
+ * `$CELESTEA_HOME` -> `$XDG_DATA_HOME/celestea` (Linux) -> `~/.celestea`
+ * (Linux/macOS) -> `%USERPROFILE%\.celestea` (Windows).
+ */
+export declare function celesteaHome(input?: CelesteaHomeInput): string;
+/** `<home>/workspaces/<workspace-folder>` — this workspace's container. */
+export declare function workspaceHome(wsPath: string, input?: CelesteaHomeInput): string;
+/** `<workspaceHome>/<sub>` — one of the fixed sub-containers. */
+export declare function workspaceSubdir(wsPath: string, sub: string, input?: CelesteaHomeInput): string;

package/dist/celestea-home.js

@@ -0,0 +1,96 @@
+/**
+ * CELESTEA_HOME — the cross-platform data root (W880).
+ *
+ * Every celestea artifact used to live inside the workspace: session dirs, the
+ * archive / trash siblings, the workspace prompt registry and run_code's
+ * transient programs. That pollutes the user's repository (a `git add -A` could
+ * commit private conversations) and ignores the OS conventions. W880 moves ALL of
+ * it into one data root, resolved with the order the established agent CLIs use
+ * (Claude Code `~/.claude`, Codex `~/.codex`, Gemini CLI `~/.gemini`):
+ *
+ *   1. `$CELESTEA_HOME`                    — explicit override; production systemd
+ *                                            pins `/var/lib/celestea-agent` (the FHS
+ *                                            `/var/lib/<service>` location);
+ *   2. `$XDG_DATA_HOME/celestea` (Linux)   — XDG Base Directory, the ask behind
+ *                                            anthropics/claude-code#1455;
+ *   3. `~/.celestea`                       — Linux/macOS default, the de-facto
+ *                                            standard of the agent CLIs;
+ *   4. `%USERPROFILE%\.celestea` (Windows) — Windows default.
+ *
+ * This module is PURE: it reads the injected `env` / `platform` / `homedir`
+ * (defaulting to the process), never the filesystem, so the whole order is a
+ * unit-testable function. The layout under the root is
+ *
+ *   <home>/workspaces/<workspace-folder>/{sessions,archive,trash,run-code}/
+ *   <home>/workspaces/<workspace-folder>/prompts.json
+ *
+ * `<workspace-folder>` is the same key `workspaces.json` uses (the registered
+ * path's basename; see `apps/studio/src/store/workspaces.ts`).
+ */
+import { homedir as osHomedir } from "node:os";
+import { posix, win32 } from "node:path";
+/** Env var: explicit data-root override (highest priority). */
+export const CELESTEA_HOME_ENV = "CELESTEA_HOME";
+/** Folder under `$XDG_DATA_HOME` on Linux. */
+export const CELESTEA_DATA_DIR = "celestea";
+/** Folder under the data root that holds every workspace's container. */
+export const CELESTEA_WORKSPACES_DIR = "workspaces";
+/** Live-session sub-container. */
+export const CELESTEA_SESSIONS_DIR = "sessions";
+/** Archived-session sub-container. */
+export const CELESTEA_ARCHIVE_DIR = "archive";
+/** Trashed-session sub-container. */
+export const CELESTEA_TRASH_DIR = "trash";
+/** run_code's transient program sub-container. */
+export const CELESTEA_RUN_CODE_DIR = "run-code";
+/** Workspace-scoped prompt registry file name. */
+export const CELESTEA_PROMPTS_FILE = "prompts.json";
+/** The path implementation of a platform (deterministic across hosts in tests). */
+function pathApi(platform) {
+    return platform === "win32" ? win32 : posix;
+}
+/** A non-blank, trimmed env value; `undefined` when unset or blank. */
+function envValue(env, name) {
+    const raw = env[name];
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** The folder name that keys a workspace (same rule as `workspaces.json`). */
+export function workspaceFolderName(wsPath, platform = process.platform) {
+    const base = pathApi(platform).basename(wsPath);
+    return base === "" || base === "/" ? wsPath : base;
+}
+/**
+ * Resolve the celestea data root. First hit wins:
+ * `$CELESTEA_HOME` -> `$XDG_DATA_HOME/celestea` (Linux) -> `~/.celestea`
+ * (Linux/macOS) -> `%USERPROFILE%\.celestea` (Windows).
+ */
+export function celesteaHome(input = {}) {
+    const env = input.env ?? process.env;
+    const platform = input.platform ?? process.platform;
+    const override = envValue(env, CELESTEA_HOME_ENV);
+    if (override !== undefined)
+        return override;
+    if (platform === "win32") {
+        const profile = envValue(env, "USERPROFILE");
+        return win32.join(profile ?? input.homedir ?? osHomedir(), ".celestea");
+    }
+    if (platform === "linux") {
+        const xdg = envValue(env, "XDG_DATA_HOME");
+        if (xdg !== undefined)
+            return posix.join(xdg, CELESTEA_DATA_DIR);
+    }
+    return posix.join(input.homedir ?? osHomedir(), ".celestea");
+}
+/** `<home>/workspaces/<workspace-folder>` — this workspace's container. */
+export function workspaceHome(wsPath, input = {}) {
+    const platform = input.platform ?? process.platform;
+    return pathApi(platform).join(celesteaHome(input), CELESTEA_WORKSPACES_DIR, workspaceFolderName(wsPath, platform));
+}
+/** `<workspaceHome>/<sub>` — one of the fixed sub-containers. */
+export function workspaceSubdir(wsPath, sub, input = {}) {
+    const platform = input.platform ?? process.platform;
+    return pathApi(platform).join(workspaceHome(wsPath, input), sub);
+}

package/dist/celestea-sources.d.ts

@@ -0,0 +1,53 @@
+/**
+ * W882 — the two-layer source model for Celestea artifacts.
+ *
+ * The user decision (W882, after the W879 industry survey) is B: ONE writable
+ * global container plus an OPTIONAL, hand-maintained, READ-ONLY project source.
+ * Claude Code ships the same two layers (project `.claude/` + user `~/.claude/`),
+ * Cursor does it with `.cursor/skills/` + `~/.cursor/skills/`. The rules are:
+ *
+ *   1. PROJECT layer  = `<ws>/.celestea`         — committed with the repo, shared
+ *      by the team, maintained BY HAND. Celestea NEVER writes here.
+ *   2. GLOBAL layer   = `<home>/workspaces/<ws>` — the ONE place Celestea writes
+ *      (sessions / archive / trash / prompts / run-code, see `celestea-home.ts`).
+ *   3. `readLayers()` returns `[project, global]`: the array order IS the priority
+ *      order, so the project layer WINS on a name collision.
+ *
+ * `<ws>/.celestea/sessions/` is the W877 transitional session layout. It stays
+ * readable (see `session-id.ts` / `sessions.ts`), but the write side is the
+ * global container only. These functions are PURE: they never touch the disk, so
+ * the whole layering is unit-testable without a filesystem.
+ */
+import { type CelesteaHomeInput } from "./celestea-home.js";
+/** Folder that marks the project-level source root: `<ws>/.celestea` (read-only). */
+export declare const PROJECT_SOURCE_DIR = ".celestea";
+/** Sub-folder holding one directory per skill (both layers use the same shape). */
+export declare const SKILLS_SUBDIR = "skills";
+/** The single entry file of a skill directory. */
+export declare const SKILL_FILE_NAME = "SKILL.md";
+/** Which layer a source belongs to. `project` beats `global`. */
+export type SourceName = "project" | "global";
+/** One read layer: a priority-tagged root. */
+export interface SourceLayer {
+    readonly source: SourceName;
+    readonly root: string;
+}
+/**
+ * `<ws>/.celestea` — the project-level source root.
+ *
+ * READ-ONLY by contract: no Celestea code path may create or write under it. The
+ * user maintains it by hand and commits it with the repository.
+ */
+export declare function projectSourceRoot(wsPath: string, platform?: string): string;
+/**
+ * `<home>/workspaces/<workspace-folder>` — the global source root. This is the
+ * SAME container `workspaceHome()` resolves; the alias exists so callers talk
+ * about "layers" without depending on the `CELESTEA_HOME` layout details.
+ */
+export declare function globalSourceRoot(wsPath: string, input?: CelesteaHomeInput): string;
+/**
+ * The read layers of a workspace, HIGHEST PRIORITY FIRST: `[project, global]`.
+ * A consumer that walks the array and keeps the first hit therefore lets the
+ * project layer override the global one — reversing the array is a bug.
+ */
+export declare function readLayers(wsPath: string, input?: CelesteaHomeInput): SourceLayer[];

package/dist/celestea-sources.js

@@ -0,0 +1,61 @@
+/**
+ * W882 — the two-layer source model for Celestea artifacts.
+ *
+ * The user decision (W882, after the W879 industry survey) is B: ONE writable
+ * global container plus an OPTIONAL, hand-maintained, READ-ONLY project source.
+ * Claude Code ships the same two layers (project `.claude/` + user `~/.claude/`),
+ * Cursor does it with `.cursor/skills/` + `~/.cursor/skills/`. The rules are:
+ *
+ *   1. PROJECT layer  = `<ws>/.celestea`         — committed with the repo, shared
+ *      by the team, maintained BY HAND. Celestea NEVER writes here.
+ *   2. GLOBAL layer   = `<home>/workspaces/<ws>` — the ONE place Celestea writes
+ *      (sessions / archive / trash / prompts / run-code, see `celestea-home.ts`).
+ *   3. `readLayers()` returns `[project, global]`: the array order IS the priority
+ *      order, so the project layer WINS on a name collision.
+ *
+ * `<ws>/.celestea/sessions/` is the W877 transitional session layout. It stays
+ * readable (see `session-id.ts` / `sessions.ts`), but the write side is the
+ * global container only. These functions are PURE: they never touch the disk, so
+ * the whole layering is unit-testable without a filesystem.
+ */
+import { posix, win32 } from "node:path";
+import { workspaceHome } from "./celestea-home.js";
+/** Folder that marks the project-level source root: `<ws>/.celestea` (read-only). */
+export const PROJECT_SOURCE_DIR = ".celestea";
+/** Sub-folder holding one directory per skill (both layers use the same shape). */
+export const SKILLS_SUBDIR = "skills";
+/** The single entry file of a skill directory. */
+export const SKILL_FILE_NAME = "SKILL.md";
+/** The path implementation of a platform (deterministic across hosts in tests). */
+function pathApi(platform) {
+    return platform === "win32" ? win32 : posix;
+}
+/**
+ * `<ws>/.celestea` — the project-level source root.
+ *
+ * READ-ONLY by contract: no Celestea code path may create or write under it. The
+ * user maintains it by hand and commits it with the repository.
+ */
+export function projectSourceRoot(wsPath, platform = process.platform) {
+    return pathApi(platform).join(wsPath, PROJECT_SOURCE_DIR);
+}
+/**
+ * `<home>/workspaces/<workspace-folder>` — the global source root. This is the
+ * SAME container `workspaceHome()` resolves; the alias exists so callers talk
+ * about "layers" without depending on the `CELESTEA_HOME` layout details.
+ */
+export function globalSourceRoot(wsPath, input = {}) {
+    return workspaceHome(wsPath, input);
+}
+/**
+ * The read layers of a workspace, HIGHEST PRIORITY FIRST: `[project, global]`.
+ * A consumer that walks the array and keeps the first hit therefore lets the
+ * project layer override the global one — reversing the array is a bug.
+ */
+export function readLayers(wsPath, input = {}) {
+    const platform = input.platform ?? process.platform;
+    return [
+        { source: "project", root: projectSourceRoot(wsPath, platform) },
+        { source: "global", root: globalSourceRoot(wsPath, input) },
+    ];
+}

package/dist/context.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Context seam — port of `crates/core/src/context.rs`.
+ *
+ * A shared, token-keyed service container. Plugins provide services into it;
+ * consumers resolve services out of it. A parent chain lets an agent carry a
+ * scoped Context layered over the global one.
+ *
+ * TypeScript has no TypeId, so services are keyed by an explicit token: a
+ * well-known string (see `*_SERVICE` constants), a symbol, or a class
+ * constructor used by identity. Same semantics otherwise: a later `provide` of
+ * the same token replaces the earlier one, and `get` falls back to the parent
+ * scope.
+ */
+/** What can key a service slot. */
+export type ServiceToken<T> = string | symbol | (abstract new (...args: never[]) => T);
+export declare class Context {
+    private readonly services;
+    private readonly parent;
+    constructor(parent?: Context | null);
+    /** A fresh root context (`Context::new`). */
+    static root(): Context;
+    /** Register a service; a later registration of the same token replaces it. */
+    provide<T>(token: ServiceToken<T>, service: T): void;
+    /** Resolve a service by token, falling back to the parent scope. */
+    get<T>(token: ServiceToken<T>): T | undefined;
+    /** Resolve or throw: for call sites where a missing service is a bug. */
+    require<T>(token: ServiceToken<T>): T;
+    has<T>(token: ServiceToken<T>): boolean;
+    /** Create a child scope that falls back to this context (one per agent). */
+    scoped(): Context;
+    /** The tokens provided in THIS scope (parent services excluded). */
+    localTokens(): unknown[];
+}

package/dist/context.js

@@ -0,0 +1,55 @@
+/**
+ * Context seam — port of `crates/core/src/context.rs`.
+ *
+ * A shared, token-keyed service container. Plugins provide services into it;
+ * consumers resolve services out of it. A parent chain lets an agent carry a
+ * scoped Context layered over the global one.
+ *
+ * TypeScript has no TypeId, so services are keyed by an explicit token: a
+ * well-known string (see `*_SERVICE` constants), a symbol, or a class
+ * constructor used by identity. Same semantics otherwise: a later `provide` of
+ * the same token replaces the earlier one, and `get` falls back to the parent
+ * scope.
+ */
+function tokenKey(token) {
+    return typeof token === "string" ? `service:${token}` : token;
+}
+export class Context {
+    services = new Map();
+    parent;
+    constructor(parent = null) {
+        this.parent = parent;
+    }
+    /** A fresh root context (`Context::new`). */
+    static root() {
+        return new Context(null);
+    }
+    /** Register a service; a later registration of the same token replaces it. */
+    provide(token, service) {
+        this.services.set(tokenKey(token), service);
+    }
+    /** Resolve a service by token, falling back to the parent scope. */
+    get(token) {
+        if (this.services.has(tokenKey(token)))
+            return this.services.get(tokenKey(token));
+        return this.parent?.get(token) ?? undefined;
+    }
+    /** Resolve or throw: for call sites where a missing service is a bug. */
+    require(token) {
+        const svc = this.get(token);
+        if (svc === undefined)
+            throw new Error(`service not provided: ${String(token)}`);
+        return svc;
+    }
+    has(token) {
+        return this.get(token) !== undefined;
+    }
+    /** Create a child scope that falls back to this context (one per agent). */
+    scoped() {
+        return new Context(this);
+    }
+    /** The tokens provided in THIS scope (parent services excluded). */
+    localTokens() {
+        return [...this.services.keys()];
+    }
+}