@celestea/core 2.7.1

package/dist/stream.js

@@ -0,0 +1,52 @@
+/**
+ * The LLM request/stream seam payloads — ports of
+ * `crates/core/src/message.rs:65-153` (ModelRequest / StreamEvent / LlmError).
+ *
+ * `StreamEvent` is what a provider adapter yields: incremental deltas for the
+ * UI, then exactly one authoritative terminal event. Terminal variants never
+ * follow each other (`Done` after `Failed`/`Interrupted` is a contract
+ * violation), because the engine's five TurnOutcome states are derived from
+ * which terminal event arrived.
+ *
+ * A1 (W746): this module is the SINGLE source of the LLM vocabulary. Provider
+ * packages (`@celestea/llm`) re-export these symbols instead of redeclaring
+ * them, so `instanceof LlmError` and every structural type agree across
+ * packages. `LlmError` here carries the structured classification TS needs
+ * (see the class doc).
+ */
+export const STREAM_EVENT_KINDS = ["text", "thinking", "usage", "done", "failed", "interrupted"];
+/**
+ * `LlmError` — the provider-facing failure (`LlmError(String)` in the legacy engine).
+ *
+ * The semantics ride the canonical `llm timeout: …` message prefix; TS adds the
+ * machine-readable fields on top of the unchanged text:
+ * `kind` (the turn-outcome kind a caller should report), `isTimeout` +
+ * `timeoutStage`, `httpStatus` and `retryable` (the conservative default pair
+ * is `(null, false)`: a failure with no evidence of being transient is a
+ * local/configuration problem, not something to retry).
+ */
+export class LlmError extends Error {
+    /** Turn-outcome kind this failure maps to. */
+    kind;
+    /** True for any timeout; the message then carries the canonical prefix. */
+    isTimeout;
+    /** Which guard tripped, when the failure was a timeout. */
+    timeoutStage;
+    /** HTTP status of the failing response; `null` when none was received. */
+    httpStatus;
+    /** True for transient causes (timeouts, transport, 408/425/429/5xx). */
+    retryable;
+    constructor(message, kind = "generate", options) {
+        super(message);
+        this.name = "LlmError";
+        this.kind = kind;
+        this.isTimeout = options?.isTimeout ?? false;
+        this.timeoutStage = options?.timeoutStage ?? null;
+        this.httpStatus = options?.httpStatus ?? null;
+        this.retryable = options?.retryable ?? false;
+    }
+}
+/** True for the two terminal variants (no further event may follow). */
+export function isTerminalStreamEvent(ev) {
+    return ev.kind === "done" || ev.kind === "failed" || ev.kind === "interrupted";
+}

package/dist/tool-surface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * W855 (B6): the MODEL-VISIBLE FACE of a tool result, derived at READ time.
+ *
+ * The session log stores the ORIGINAL `tool_result.value`; the face (a bounded
+ * head/tail window + locator, or a tool-authored truncation note) is produced
+ * HERE by the projection. Keeping the pure rendering in core is what lets
+ * `projection.ts` render it without importing the L1 retention policy.
+ *
+ * The primitives were moved out of `packages/agent-loop/src/retention.ts`
+ * (W846/W855) unchanged, so the live and replayed faces stay byte-identical.
+ */
+import type { ToolResultSurface } from "./types.js";
+/** Longest prefix of text within maxBytes, never splitting a code point. */
+export declare function cutPrefixCodePoints(text: string, maxBytes: number): string;
+/** Longest suffix of text within maxBytes, never splitting a code point. */
+export declare function cutSuffixCodePoints(text: string, maxBytes: number): string;
+export interface RetainedText {
+    head: string;
+    tail: string;
+    keptBytes: number;
+    omittedBytes: number;
+    totalBytes: number;
+}
+/** Head+tail window over text (code-point safe) with the EXACT omitted count. */
+export declare function retainHeadTail(text: string, headBytes: number, tailBytes: number): RetainedText;
+/** The standardized omission clause + the tool-shaped retrieval instruction. */
+export declare function formatOmissionNotice(surface: Extract<ToolResultSurface, {
+    kind: "omitted";
+}>): string;
+/** Bounded head/tail window + notice (the model-visible face of an omission). */
+export declare function renderOmittedText(text: string, surface: Extract<ToolResultSurface, {
+    kind: "omitted";
+}>): string;
+/**
+ * The RAW face of one tool value: the bounded/annotated string when a surface is
+ * present, else the value untouched. SSE/replay frames and the Studio transcript
+ * use exactly this, so a live frame and its replay agree.
+ */
+export declare function toolSurfaceValue(value: unknown, surface?: ToolResultSurface): unknown;
+/**
+ * The model-PROJECTED TEXT of one tool value with its surface applied. The
+ * projection has ALWAYS JSON-encoded the value (`serdeJsonString`), so a
+ * surface-less string stays `"hello"`; a surfaced one encodes its RAW face.
+ */
+export declare function toolSurfaceText(value: unknown, surface?: ToolResultSurface): string;

package/dist/tool-surface.js

@@ -0,0 +1,98 @@
+/**
+ * W855 (B6): the MODEL-VISIBLE FACE of a tool result, derived at READ time.
+ *
+ * The session log stores the ORIGINAL `tool_result.value`; the face (a bounded
+ * head/tail window + locator, or a tool-authored truncation note) is produced
+ * HERE by the projection. Keeping the pure rendering in core is what lets
+ * `projection.ts` render it without importing the L1 retention policy.
+ *
+ * The primitives were moved out of `packages/agent-loop/src/retention.ts`
+ * (W846/W855) unchanged, so the live and replayed faces stay byte-identical.
+ */
+import { serdeJsonString } from "./json.js";
+/** Longest prefix of text within maxBytes, never splitting a code point. */
+export function cutPrefixCodePoints(text, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    let used = 0;
+    let out = "";
+    for (const ch of text) {
+        const n = Buffer.byteLength(ch, "utf8");
+        if (used + n > maxBytes)
+            break;
+        used += n;
+        out += ch;
+    }
+    return out;
+}
+/** Longest suffix of text within maxBytes, never splitting a code point. */
+export function cutSuffixCodePoints(text, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    let used = 0;
+    let out = "";
+    const chars = Array.from(text);
+    for (let i = chars.length - 1; i >= 0; i -= 1) {
+        const ch = chars[i] ?? "";
+        const n = Buffer.byteLength(ch, "utf8");
+        if (used + n > maxBytes)
+            break;
+        used += n;
+        out = ch + out;
+    }
+    return out;
+}
+/** Head+tail window over text (code-point safe) with the EXACT omitted count. */
+export function retainHeadTail(text, headBytes, tailBytes) {
+    const totalBytes = Buffer.byteLength(text, "utf8");
+    if (totalBytes <= headBytes + tailBytes) {
+        return { head: text, tail: "", keptBytes: totalBytes, omittedBytes: 0, totalBytes };
+    }
+    const head = cutPrefixCodePoints(text, headBytes);
+    const tail = cutSuffixCodePoints(text, tailBytes);
+    const keptBytes = Buffer.byteLength(head, "utf8") + Buffer.byteLength(tail, "utf8");
+    return { head, tail, keptBytes, omittedBytes: totalBytes - keptBytes, totalBytes };
+}
+/** The standardized omission clause + the tool-shaped retrieval instruction. */
+export function formatOmissionNotice(surface) {
+    return ("[omitted] " +
+        String(surface.omitted_bytes) +
+        " of " +
+        String(surface.total_bytes) +
+        " bytes kept out of the model context by the tool-result budget; full text: " +
+        surface.locator +
+        " (" +
+        surface.retrieval_hint +
+        ")");
+}
+/** Bounded head/tail window + notice (the model-visible face of an omission). */
+export function renderOmittedText(text, surface) {
+    const window = retainHeadTail(text, surface.head_bytes, surface.tail_bytes);
+    const notice = formatOmissionNotice(surface);
+    if (window.tail === "")
+        return window.head + "\n" + notice;
+    return window.head + "\n...\n" + window.tail + "\n" + notice;
+}
+/**
+ * The RAW face of one tool value: the bounded/annotated string when a surface is
+ * present, else the value untouched. SSE/replay frames and the Studio transcript
+ * use exactly this, so a live frame and its replay agree.
+ */
+export function toolSurfaceValue(value, surface) {
+    if (surface === undefined)
+        return value;
+    const text = typeof value === "string" ? value : serdeJsonString(value === undefined ? null : value);
+    if (surface.kind === "omitted")
+        return renderOmittedText(text, surface);
+    return text === "" ? surface.note : text + "\n" + surface.note;
+}
+/**
+ * The model-PROJECTED TEXT of one tool value with its surface applied. The
+ * projection has ALWAYS JSON-encoded the value (`serdeJsonString`), so a
+ * surface-less string stays `"hello"`; a surfaced one encodes its RAW face.
+ */
+export function toolSurfaceText(value, surface) {
+    if (surface === undefined)
+        return serdeJsonString(value === undefined ? null : value);
+    return serdeJsonString(toolSurfaceValue(value, surface));
+}

package/dist/tool.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Tool + ToolGuard seams — port of `crates/core/src/tool.rs`.
+ *
+ * A guard is the "waterfall" step of dispatch: it may Allow, Deny or Ask, and
+ * the first non-Allow decision short-circuits the chain. The registry runs the
+ * guard chain and then the tool, capturing errors instead of throwing.
+ *
+ * `ToolDecision` keeps the P0 TS shape (`{kind:"allow"}` / `{kind:"deny",reason}`
+ * / `{kind:"ask",reason}`) declared in `./types.ts` — it is the contract the
+ * tools package and the API surface already use, and it is the same three
+ * variants as the engine's enum.
+ */
+import type { ToolDecision, ToolResultSurface, ToolSpec } from "./types.js";
+export interface ToolInput {
+    call_id: string;
+    name: string;
+    args: unknown;
+}
+/** `Tool::execute_with` result: canonical value + optional authored rendering. */
+export interface ToolExecOutcome {
+    value: unknown;
+    render: string | null;
+    /**
+     * W855 (B6): a tool-authored MODEL-FACE descriptor (e.g. `read_file`'s
+     * truncation note). Unlike `render` (display-only, never projected), this is
+     * persisted on the `tool_result` log row and applied by the projection.
+     */
+    surface?: ToolResultSurface;
+}
+export interface ToolOutput {
+    call_id: string;
+    /** Canonical, machine-readable result value. Never a display rendering. */
+    value: unknown;
+    /** Human-readable rendering, decoupled from the canonical value. */
+    render: string | null;
+    error: string | null;
+    /** The guard verdict for this dispatch (null when no guard ran). */
+    decision: ToolDecision | null;
+    /** W855 (B6): the model-face descriptor carried through dispatch (optional). */
+    surface?: ToolResultSurface;
+}
+export interface Tool {
+    spec(): ToolSpec;
+    execute(args: unknown): Promise<unknown>;
+    /**
+     * W255 run_code: tools that need the caller-assigned `call_id` (run_code
+     * embeds it in `<parent>:c<n>` sub-call ids) or that author their own
+     * `render` override this; the default delegates to `execute`.
+     */
+    executeWith?(input: ToolInput): Promise<ToolExecOutcome>;
+}
+export interface ToolGuard {
+    /**
+     * `ToolGuard::check`. Note the guard chain collects the FIRST
+     * non-Allow verdict, so a later Allow never un-denies an earlier Deny.
+     */
+    check(input: ToolInput): Promise<ToolDecision>;
+}
+export interface ToolRegistry {
+    register(tool: Tool): void;
+    addGuard(guard: ToolGuard): void;
+    get(name: string): Tool | undefined;
+    /**
+     * The model-facing specs. The registry's own order is by name, exactly like
+     * `ToolRegistry::schemas` (crates/tools/src/registry.rs); a disclosure
+     * decorator may re-project it into a **stable disclosure order** (baseline
+     * first, newly disclosed names appended) so the prompt prefix stays
+     * append-only across a session. The order is NOT part of the contract (only
+     * the name set is), so a decorator is free to choose it.
+     */
+    schemas(): ToolSpec[];
+    /** Run the guard chain, then the tool. Errors are captured, not thrown. */
+    dispatch(input: ToolInput): Promise<ToolOutput>;
+}
+/** Well-known tokens for the tool services in a Context. */
+export declare const TOOL_REGISTRY_SERVICE = "celestea.core.ToolRegistry";
+export declare const TOOL_GUARD_SERVICE = "celestea.core.ToolGuard";

package/dist/tool.js

@@ -0,0 +1,15 @@
+/**
+ * Tool + ToolGuard seams — port of `crates/core/src/tool.rs`.
+ *
+ * A guard is the "waterfall" step of dispatch: it may Allow, Deny or Ask, and
+ * the first non-Allow decision short-circuits the chain. The registry runs the
+ * guard chain and then the tool, capturing errors instead of throwing.
+ *
+ * `ToolDecision` keeps the P0 TS shape (`{kind:"allow"}` / `{kind:"deny",reason}`
+ * / `{kind:"ask",reason}`) declared in `./types.ts` — it is the contract the
+ * tools package and the API surface already use, and it is the same three
+ * variants as the engine's enum.
+ */
+/** Well-known tokens for the tool services in a Context. */
+export const TOOL_REGISTRY_SERVICE = "celestea.core.ToolRegistry";
+export const TOOL_GUARD_SERVICE = "celestea.core.ToolGuard";

package/dist/turn-id.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Turn id ownership and arithmetic (session_log.rs:94-98).
+ *
+ * A2 (W746): the turn-id math lives in CORE, next to the `SessionLog` seam that
+ * promises it. `SessionLog.nextTurnId()` is a seam method, so `formatTurnId` /
+ * `nextTurnNumber` cannot be private to one implementation package: every
+ * backend must mint the same ids, and `packages/session` re-exports these.
+ *
+ * The LOG owns the counter, not the loop: next_turn_number only recognises the
+ * `turn-<n>` prefix and restores its counter from the max replayed id, so ids
+ * are monotonic and never reused after a restart.
+ */
+import type { SessionEvent } from "./types.js";
+export declare function parseTurnNumber(id: string): number | null;
+export declare function formatTurnId(n: number): string;
+/** Max turn-<n> seen in the log; -1 when none. */
+export declare function maxTurnNumber(events: readonly SessionEvent[]): number;
+/** The next id the log would allocate. */
+export declare function nextTurnId(events: readonly SessionEvent[]): string;
+/**
+ * The engine's `next_turn_number` (persistent.rs:391-402): max `turn-<n>` in the
+ * log plus one, or 0 when the log holds no such id. Legacy ids (e.g. `"t1"`) are
+ * ignored, so a replayed counter never collides with an id already on disk.
+ */
+export declare function nextTurnNumber(events: readonly SessionEvent[]): number;
+export interface TurnIdAudit {
+    ids: string[];
+    nonMonotonic: Array<{
+        index: number;
+        previous: string;
+        current: string;
+    }>;
+    duplicates: string[];
+    malformed: string[];
+}
+/** Verify the monotonicity + uniqueness contract of turn_start ids. */
+export declare function auditTurnIds(events: readonly SessionEvent[]): TurnIdAudit;

package/dist/turn-id.js

@@ -0,0 +1,76 @@
+/**
+ * Turn id ownership and arithmetic (session_log.rs:94-98).
+ *
+ * A2 (W746): the turn-id math lives in CORE, next to the `SessionLog` seam that
+ * promises it. `SessionLog.nextTurnId()` is a seam method, so `formatTurnId` /
+ * `nextTurnNumber` cannot be private to one implementation package: every
+ * backend must mint the same ids, and `packages/session` re-exports these.
+ *
+ * The LOG owns the counter, not the loop: next_turn_number only recognises the
+ * `turn-<n>` prefix and restores its counter from the max replayed id, so ids
+ * are monotonic and never reused after a restart.
+ */
+const TURN_ID = /^turn-(\d+)$/;
+export function parseTurnNumber(id) {
+    const m = TURN_ID.exec(id);
+    if (!m || m[1] === undefined)
+        return null;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isSafeInteger(n) ? n : null;
+}
+export function formatTurnId(n) {
+    return `turn-${n}`;
+}
+/** Max turn-<n> seen in the log; -1 when none. */
+export function maxTurnNumber(events) {
+    let max = -1;
+    for (const ev of events) {
+        if (ev.type !== "turn_start" && ev.type !== "turn_end")
+            continue;
+        const n = parseTurnNumber(ev.id);
+        if (n !== null && n > max)
+            max = n;
+    }
+    return max;
+}
+/** The next id the log would allocate. */
+export function nextTurnId(events) {
+    return formatTurnId(nextTurnNumber(events));
+}
+/**
+ * The engine's `next_turn_number` (persistent.rs:391-402): max `turn-<n>` in the
+ * log plus one, or 0 when the log holds no such id. Legacy ids (e.g. `"t1"`) are
+ * ignored, so a replayed counter never collides with an id already on disk.
+ */
+export function nextTurnNumber(events) {
+    return maxTurnNumber(events) + 1;
+}
+/** Verify the monotonicity + uniqueness contract of turn_start ids. */
+export function auditTurnIds(events) {
+    const ids = [];
+    const seen = new Set();
+    const duplicates = [];
+    const malformed = [];
+    const nonMonotonic = [];
+    let previous = -1;
+    let previousId = "";
+    for (const ev of events) {
+        if (ev.type !== "turn_start")
+            continue;
+        ids.push(ev.id);
+        if (seen.has(ev.id))
+            duplicates.push(ev.id);
+        seen.add(ev.id);
+        const n = parseTurnNumber(ev.id);
+        if (n === null) {
+            malformed.push(ev.id);
+            continue;
+        }
+        if (n <= previous) {
+            nonMonotonic.push({ index: ids.length - 1, previous: previousId, current: ev.id });
+        }
+        previous = n;
+        previousId = ev.id;
+    }
+    return { ids, nonMonotonic, duplicates, malformed };
+}