@celestea/core 2.7.1

package/dist/repo.js

@@ -0,0 +1,87 @@
+/** Locate the repository root (the directory holding pnpm-workspace.yaml). */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+let cached = null;
+/**
+ * H (packaging): contracts shipped INSIDE this package, resolved from the
+ * module's own location regardless of cwd.
+ *
+ * In a source checkout this file is `packages/core/src/repo.ts` / `dist/repo.js`,
+ * so `<pkg>/contracts` sits one level up from `src`/`dist`. After
+ * `npm i -g celestea-agent` the same relative walk finds
+ * `@celestea/core/contracts` (shipped via `files`), so the frozen contract
+ * files travel with the code instead of relying on the git checkout layout.
+ */
+function packagedContractsRoot(from) {
+    let dir = dirname(fileURLToPath(from));
+    for (let i = 0; i < 8; i++) {
+        const candidate = resolve(dir, "contracts");
+        // The marker is the CONTRACT DATA file, not the directory name: the source
+        // tree has a `src/contracts/` TS module directory, which must never win.
+        if (existsSync(resolve(candidate, "endpoints.json")))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** The checkout root (the dir holding `pnpm-workspace.yaml`), or null. */
+function workspaceMarkerRoot(from) {
+    let dir = dirname(fileURLToPath(from));
+    for (let i = 0; i < 12; i++) {
+        if (existsSync(resolve(dir, "pnpm-workspace.yaml")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+export function repoRoot(from = import.meta.url) {
+    if (cached)
+        return cached;
+    const workspace = workspaceMarkerRoot(from);
+    if (workspace !== null) {
+        cached = workspace;
+        return workspace;
+    }
+    // H: an INSTALLED package has no workspace marker. Fall back to the
+    // package-local contracts root's parent (still never the cwd), so a globally
+    // installed `celestea` boots the same way the checkout does.
+    const packaged = packagedContractsRoot(from);
+    if (packaged !== null) {
+        cached = dirname(packaged);
+        return cached;
+    }
+    throw new Error(`repository root not found above ${from}`);
+}
+/**
+ * Absolute path to the frozen `contracts/` directory.
+ *
+ * H: a SOURCE CHECKOUT always uses `<repo>/contracts` — the build-staged
+ * `packages/core/contracts/` is a shipping artifact and must never shadow a
+ * live edit of the repo's contracts in dev. Only an INSTALLED package (no
+ * workspace marker) reads its own bundled `contracts/`.
+ */
+export function contractsDir() {
+    const workspace = workspaceMarkerRoot(import.meta.url);
+    if (workspace !== null)
+        return resolve(workspace, "contracts");
+    const packaged = packagedContractsRoot(import.meta.url);
+    if (packaged !== null)
+        return packaged;
+    return resolve(repoRoot(), "contracts");
+}
+export function contractPath(...parts) {
+    return resolve(contractsDir(), ...parts);
+}
+export function fixturePath(...parts) {
+    return resolve(repoRoot(), "fixtures", ...parts);
+}
+export function reportPath(...parts) {
+    return resolve(repoRoot(), "reports", ...parts);
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Sandbox seam — the injected execution boundary behind `run_shell`.
+ *
+ * Parity target: `crates/tools/src/sandbox.rs` (`SandboxConfig`, `SandboxMeta`,
+ * `SandboxOutput`, `SandboxError`, `execute_sandboxed`, `spawn_sandboxed`) plus
+ * the `OsSandboxLayer` hook that lets an OS-level layer (bubblewrap / raw
+ * namespaces / seccomp) wrap the direct command without touching call sites.
+ *
+ * Why a seam in `core`: `run_shell` must be pure orchestration (argument
+ * handling, timeout/cap bookkeeping, background hand-off) and must never know
+ * *how* isolation is achieved. Implementations are plugins: P2b ships the
+ * userspace implementation in `@celestea/tools`; the real OS isolation lands in
+ * P2c behind this exact interface (ARCHITECTURE.md §3.1, §7.4).
+ *
+ * Invariants kept from the legacy engine:
+ * - the effective isolation mode travels *inside* every result (`SandboxMeta`):
+ *   a caller never infers the isolation level, and silent degradation stays
+ *   visible;
+ * - every failure is a structured `SandboxError` — `run_shell-sandbox: code=<k>
+ *   msg="<quoted>"` — never a bare string, never a thrown non-Error;
+ * - a kill deadline is enforced for foreground runs; background runs carry no
+ *   call-level deadline (they outlive the turn) and are reaped by the caller.
+ */
+import type { Readable, Writable } from "node:stream";
+/** Effective isolation mode of one run ("bwrap" | "raw" | "userspace" | …). */
+export interface SandboxMeta {
+    /** Provider that actually executed the command. */
+    provider: string;
+    /** W6: effective `RLIMIT_CPU` in seconds for this run (absent = not reported). */
+    cpu_sec?: number;
+    /** true when the child ran in an isolated network namespace. */
+    net_isolated: boolean;
+    /** true when /tmp was a sandbox-private tmpfs. */
+    tmp_private: boolean;
+    /** true when a seccomp syscall whitelist was applied. */
+    seccomp: boolean;
+}
+/** The userspace (no OS isolation) mode: everything reported, nothing hidden. */
+export declare const USERSPACE_SANDBOX_META: SandboxMeta;
+/** Tuning knobs every sandbox implementation honours (`SandboxConfig`). */
+export interface SandboxConfig {
+    /** Kill deadline when the call passes no `timeoutMs`. */
+    timeoutMs: number;
+    /** Upper bound accepted for a per-call `timeoutMs`. */
+    maxTimeoutMs: number;
+    /** W6: upper bound accepted for a per-call `cpuSec` (env `CELESTEA_SHELL_MAX_CPU_SEC`). */
+    maxCpuSec: number;
+    /** Per-stream (stdout / stderr) capture cap in bytes. */
+    maxOutputBytes: number;
+    /** Fixed workdir: the default cwd of every command. */
+    workdir: string;
+    /** Canonical prefix every resolved workdir must stay inside. */
+    root: string;
+    /**
+     * W880: absolute directory the `run_code` broker writes its transient program
+     * files into. It lives OUTSIDE the workspace now (under `CELESTEA_HOME`), so
+     * the bwrap provider must bind it into the namespace or the child cannot read
+     * the program it was told to run.
+     */
+    programDir: string;
+    /** Deliberate operator env injected on top of the allowlist. */
+    extraEnv: ReadonlyArray<readonly [string, string]>;
+}
+/** Terminal state of a child process. */
+export interface SandboxExit {
+    code: number | null;
+    signal: string | null;
+}
+/**
+ * A spawned child, uniform across providers. `stdout`/`stderr` are the drains
+ * the caller (process registry) owns; `wait()` resolves once the child has
+ * exited *and* its pipes are closed, so buffered output is never lost.
+ */
+export interface SandboxChild {
+    readonly pid: number | null;
+    readonly stdin: Writable | null;
+    readonly stdout: Readable | null;
+    readonly stderr: Readable | null;
+    wait(): Promise<SandboxExit>;
+    /** SIGTERM the process tree (best effort). */
+    terminate(): void;
+    /** SIGKILL the process tree (best effort). */
+    kill(): void;
+}
+/**
+ * F4: per-call address-space exemption.
+ *
+ * Modern Chromium reserves an enormous VIRTUAL address space; under a 2GiB
+ * `RLIMIT_AS` it dies with SIGTRAP before it can log anything (measured:
+ * 2/3/4/8/16/32GiB all die, 64GiB lives). Setting this on ONE call omits
+ * `RLIMIT_AS` and NOTHING ELSE — CPU/NPROC/FSIZE/NOFILE/CORE still apply.
+ *
+ * Absent/undefined = the historical behaviour (address space limited).
+ * Deliberately NOT surfaced in `SandboxMeta`: the model-visible contract stays
+ * the four fields it was just reduced to; the tool layer states the exemption
+ * in its own result.
+ */
+export interface SandboxAddressSpaceOptions {
+    noAddressSpaceLimit?: boolean;
+}
+export interface SandboxRunRequest extends SandboxAddressSpaceOptions {
+    command: string;
+    /** Optional per-call cwd; must exist inside `config.root`. */
+    workdir?: string;
+    /** Optional per-call kill deadline, bounded by `config.maxTimeoutMs`. */
+    timeoutMs?: number;
+    /** W6: optional per-call `RLIMIT_CPU` in seconds, clamped to `config.maxCpuSec`. */
+    cpuSec?: number;
+}
+export interface SandboxSpawnRequest extends SandboxAddressSpaceOptions {
+    command: string;
+    workdir?: string;
+    /** W6: optional per-call `RLIMIT_CPU` in seconds, clamped to `config.maxCpuSec`. */
+    cpuSec?: number;
+}
+/** Result of a foreground run: capped streams + exit code + effective mode. */
+export interface SandboxRunResult {
+    stdout: string;
+    stderr: string;
+    exit_code: number | null;
+    /** W6: terminating signal when the child was killed (SIGXCPU/SIGKILL on a CPU cap). */
+    signal?: string | null;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    sandbox: SandboxMeta;
+}
+/** A detached background child plus the mode it was spawned under. */
+export interface SandboxSpawned {
+    child: SandboxChild;
+    sandbox: SandboxMeta;
+}
+/**
+ * W885: the inputs a `run_code` broker needs to quote its interpreter line for
+ * the shell that will actually carry it. Structural on purpose — `core` is the
+ * dependency-free leaf and cannot import the tools implementation — and
+ * OPTIONAL: an absent field means the host default (the `celestea-home.ts`
+ * defaulting rule).
+ */
+export interface SandboxShellLookup {
+    /** `process.platform` equivalent. */
+    platform?: NodeJS.Platform | string;
+    /** `process.env` equivalent. */
+    env?: Record<string, string | undefined>;
+    /** PATH lookup seam (bare executable name -> absolute path or null). */
+    which?: (bin: string) => string | null;
+    /** Existence check for absolute candidate paths. */
+    exists?: (path: string) => boolean;
+}
+/**
+ * The execution boundary. `run` is the foreground path (deadline enforced,
+ * stdio captured); `spawn` is the background path (no deadline, stdin piped so
+ * `process_control` can write lines).
+ */
+export interface Sandbox {
+    readonly config: SandboxConfig;
+    /**
+     * W885: the platform/shell view this provider runs commands under. Absent =
+     * host defaults; tests inject a win32 view to exercise the Windows branch.
+     */
+    readonly shell?: SandboxShellLookup;
+    run(req: SandboxRunRequest): Promise<SandboxRunResult>;
+    spawn(req: SandboxSpawnRequest): Promise<SandboxSpawned>;
+}
+/** Stable error kinds (mirrors the engine's `SandboxError::code`). */
+export type SandboxErrorKind = "timeout" | "workdir" | "arg" | "config" | "spawn";
+/** Stable prefix of every structured sandbox error (contract, not decoration). */
+export declare const SANDBOX_ERROR_PREFIX = "run_shell-sandbox";
+/** Escape + truncate a message so the one-line error contract stays parseable. */
+export declare function quoteSandboxMessage(message: string): string;
+/**
+ * Structured sandbox failure. `message` is the contract string
+ * `run_shell-sandbox: code=<kind> msg="<quoted>"`; `detail` carries the
+ * machine-readable extras (pid, captured byte counts, requested workdir, …).
+ */
+export declare class SandboxError extends Error {
+    readonly kind: SandboxErrorKind;
+    readonly detail: Readonly<Record<string, unknown>>;
+    constructor(kind: SandboxErrorKind, message: string, detail?: Record<string, unknown>);
+}
+export declare function isSandboxError(value: unknown): value is SandboxError;
+/** Well-known token for the sandbox service in a Context. */
+export declare const SANDBOX_SERVICE = "celestea.core.Sandbox";

package/dist/sandbox.js

@@ -0,0 +1,78 @@
+/**
+ * Sandbox seam — the injected execution boundary behind `run_shell`.
+ *
+ * Parity target: `crates/tools/src/sandbox.rs` (`SandboxConfig`, `SandboxMeta`,
+ * `SandboxOutput`, `SandboxError`, `execute_sandboxed`, `spawn_sandboxed`) plus
+ * the `OsSandboxLayer` hook that lets an OS-level layer (bubblewrap / raw
+ * namespaces / seccomp) wrap the direct command without touching call sites.
+ *
+ * Why a seam in `core`: `run_shell` must be pure orchestration (argument
+ * handling, timeout/cap bookkeeping, background hand-off) and must never know
+ * *how* isolation is achieved. Implementations are plugins: P2b ships the
+ * userspace implementation in `@celestea/tools`; the real OS isolation lands in
+ * P2c behind this exact interface (ARCHITECTURE.md §3.1, §7.4).
+ *
+ * Invariants kept from the legacy engine:
+ * - the effective isolation mode travels *inside* every result (`SandboxMeta`):
+ *   a caller never infers the isolation level, and silent degradation stays
+ *   visible;
+ * - every failure is a structured `SandboxError` — `run_shell-sandbox: code=<k>
+ *   msg="<quoted>"` — never a bare string, never a thrown non-Error;
+ * - a kill deadline is enforced for foreground runs; background runs carry no
+ *   call-level deadline (they outlive the turn) and are reaped by the caller.
+ */
+/** The userspace (no OS isolation) mode: everything reported, nothing hidden. */
+export const USERSPACE_SANDBOX_META = {
+    provider: "userspace",
+    net_isolated: false,
+    tmp_private: false,
+    seccomp: false,
+};
+/** Stable prefix of every structured sandbox error (contract, not decoration). */
+export const SANDBOX_ERROR_PREFIX = "run_shell-sandbox";
+/** Escape + truncate a message so the one-line error contract stays parseable. */
+export function quoteSandboxMessage(message) {
+    let out = "";
+    let count = 0;
+    for (const ch of message) {
+        if (count >= 512)
+            break;
+        count += 1;
+        const cp = ch.codePointAt(0) ?? 0;
+        if (ch === "\\")
+            out += "\\\\";
+        else if (ch === '"')
+            out += '\\"';
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (cp < 0x20)
+            out += `\\u{${cp.toString(16)}}`;
+        else
+            out += ch;
+    }
+    return out;
+}
+/**
+ * Structured sandbox failure. `message` is the contract string
+ * `run_shell-sandbox: code=<kind> msg="<quoted>"`; `detail` carries the
+ * machine-readable extras (pid, captured byte counts, requested workdir, …).
+ */
+export class SandboxError extends Error {
+    kind;
+    detail;
+    constructor(kind, message, detail = {}) {
+        super(`${SANDBOX_ERROR_PREFIX}: code=${kind} msg="${quoteSandboxMessage(message)}"`);
+        this.name = "SandboxError";
+        this.kind = kind;
+        this.detail = detail;
+    }
+}
+export function isSandboxError(value) {
+    return value instanceof SandboxError;
+}
+/** Well-known token for the sandbox service in a Context. */
+export const SANDBOX_SERVICE = "celestea.core.Sandbox";

package/dist/session-event.d.ts

@@ -0,0 +1,57 @@
+/**
+ * SessionEvent codec — the serde-exact JSONL row contract of
+ * `crates/core/src/session_log.rs:44-85`.
+ *
+ * Wire rules (all of them are contract):
+ *   - internally tagged enum: the `type` key comes FIRST, then the fields in
+ *     declaration order (`id`, `outcome` / `id`, `name`, `args`, `parent_id`);
+ *   - `parent_id` is `Option<String>` with `skip_serializing_if = "Option::is_none"`,
+ *     so it is omitted when absent (pre-W255 byte shape) — but a JSON `null`
+ *     also deserializes to `None`;
+ *   - `value` / `error` are `Option<…>` without skip: they are ALWAYS written
+ *     and become `null` when absent;
+ *   - `TurnEnd.outcome` has `#[serde(default)]`: a legacy row without it reads
+ *     as `"completed"` and is re-written WITH the field;
+ *   - unknown fields are ignored; a missing required field or an unknown
+ *     `type` is a parse error (the caller then treats the row as a torn tail);
+ *   - `args` / `value` ride through `serde_json::Value`, so their object keys
+ *     are re-serialized in sorted order (see `serdeJsonString`).
+ */
+import { type SessionEvent, type SessionEventType, type TurnOutcome } from "./types.js";
+export type ValidateResult = {
+    ok: true;
+    event: SessionEvent;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** `TurnOutcome::default()` — legacy `turn_end` rows read as completed. */
+export declare const DEFAULT_TURN_OUTCOME: TurnOutcome;
+/** The outcome of a row, with the legacy default applied. */
+export declare function effectiveOutcome(o: TurnOutcome | undefined): TurnOutcome;
+/** Normalized outcome label (TurnOutcome -> the 5 SSE/statusline phases). */
+export declare function outcomePhase(o: TurnOutcome | undefined): string;
+/** `"{kind}: {message}"` for the error variant, null otherwise. */
+export declare function outcomeError(o: TurnOutcome | undefined): string | null;
+/** The error payload of the error variant, null otherwise. */
+export declare function outcomeErrorParts(o: TurnOutcome | undefined): {
+    kind: string;
+    message: string;
+} | null;
+export declare function isTurnOutcome(v: unknown): v is TurnOutcome;
+export declare function isSessionEventType(t: string): t is SessionEventType;
+/** Validate one decoded JSON value against the SessionEvent contract. */
+export declare function validateSessionEvent(raw: unknown): ValidateResult;
+/** Parse one JSONL row; a failure is the caller's torn-tail signal. */
+export declare function parseSessionEvent(line: string): ValidateResult;
+/**
+ * Serialize one event exactly like `serde_json::to_string(&SessionEvent)`:
+ * the `type` tag first, then the fields in declaration order, `parent_id`
+ * omitted when None, `value` / `error` always present (null when None), and
+ * `outcome` always present (legacy rows are normalised to `"completed"`).
+ *
+ * The event struct order is preserved (serde writes struct fields in
+ * declaration order); only the `Value`-typed fields (`args`, `value`) go
+ * through the sorted-key `serdeJsonString`, exactly like serde_json's BTreeMap.
+ */
+export declare function serializeSessionEvent(ev: SessionEvent): string;