@celestea/core 2.7.1

package/dist/session-event.js

@@ -0,0 +1,425 @@
+/**
+ * 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 { isRecord, serdeJsonString } from "./json.js";
+import { isImageRef, normalizeImageRef } from "./message.js";
+import { SESSION_EVENT_ORIGINS, SESSION_EVENT_TYPES } from "./types.js";
+/** `TurnOutcome::default()` — legacy `turn_end` rows read as completed. */
+export const DEFAULT_TURN_OUTCOME = "completed";
+/** The outcome of a row, with the legacy default applied. */
+export function effectiveOutcome(o) {
+    return o === undefined ? DEFAULT_TURN_OUTCOME : o;
+}
+/** Normalized outcome label (TurnOutcome -> the 5 SSE/statusline phases). */
+export function outcomePhase(o) {
+    const e = effectiveOutcome(o);
+    return typeof e === "string" ? e : "error";
+}
+/** `"{kind}: {message}"` for the error variant, null otherwise. */
+export function outcomeError(o) {
+    const e = effectiveOutcome(o);
+    return typeof e === "string" ? null : `${e.error.kind}: ${e.error.message}`;
+}
+/** The error payload of the error variant, null otherwise. */
+export function outcomeErrorParts(o) {
+    const e = effectiveOutcome(o);
+    return typeof e === "string" ? null : e.error;
+}
+export function isTurnOutcome(v) {
+    if (typeof v === "string")
+        return ["completed", "cancelled", "step_limit", "interrupted"].includes(v);
+    if (isRecord(v) && isRecord(v["error"])) {
+        const e = v["error"];
+        return typeof e["kind"] === "string" && typeof e["message"] === "string";
+    }
+    return false;
+}
+export function isSessionEventType(t) {
+    return SESSION_EVENT_TYPES.includes(t);
+}
+/** Validate one decoded JSON value against the SessionEvent contract. */
+export function validateSessionEvent(raw) {
+    if (!isRecord(raw))
+        return { ok: false, errors: ["event is not a JSON object"] };
+    const type = raw["type"];
+    if (typeof type !== "string")
+        return { ok: false, errors: ["missing string field `type`"] };
+    if (!isSessionEventType(type))
+        return { ok: false, errors: [`unknown event type '${type}'`] };
+    const errors = [];
+    switch (type) {
+        case "turn_start":
+            requireString(raw, "id", errors);
+            break;
+        case "turn_end":
+            requireString(raw, "id", errors);
+            if (raw["outcome"] !== undefined && raw["outcome"] !== null && !isTurnOutcome(raw["outcome"])) {
+                errors.push("field 'outcome' is not a valid TurnOutcome");
+            }
+            break;
+        case "user_message":
+            requireString(raw, "text", errors);
+            // W804 §4.2C: the ONLY extra field, optional and serde-shaped (null == absent).
+            optionalAttachments(raw, "attachments", errors);
+            // W888: a closed origin whitelist. An UNKNOWN value is a hard error (never a
+            // silent fallback to 'user'): the projection branches on it, so a typo would
+            // otherwise smuggle an injected row through as if the human had typed it.
+            optionalOrigin(raw, "origin", errors);
+            break;
+        case "assistant_message":
+        case "thinking_delta":
+            requireString(raw, "text", errors);
+            break;
+        case "tool_call":
+            requireString(raw, "id", errors);
+            requireString(raw, "name", errors);
+            requirePresent(raw, "args", errors);
+            optionalString(raw, "parent_id", errors);
+            break;
+        case "tool_result":
+            requireString(raw, "id", errors);
+            // value / error are `Option<_>`: absent == null (serde treats Option
+            // fields as optional), so only their type is checked when present.
+            if (raw["error"] !== undefined && raw["error"] !== null && typeof raw["error"] !== "string") {
+                errors.push("field 'error' must be string|null");
+            }
+            optionalString(raw, "parent_id", errors);
+            // W855 (B6): the model-face descriptor is optional; a malformed one is an
+            // error (it would silently change the model context on replay).
+            optionalSurface(raw, "surface", errors);
+            break;
+        // W783: the two host-side user-question rows. `questions` / `answers` are
+        // required and must be arrays; the timing fields are optional numbers.
+        case "user_question":
+            requireString(raw, "id", errors);
+            requireArray(raw, "questions", errors);
+            optionalNumber(raw, "expires_at", errors);
+            optionalNumber(raw, "timeout_ms", errors);
+            break;
+        case "user_answer":
+            requireString(raw, "id", errors);
+            requireArray(raw, "answers", errors);
+            optionalBoolean(raw, "timed_out", errors);
+            break;
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, event: normalizeSessionEvent(raw, type) };
+}
+/** Parse one JSONL row; a failure is the caller's torn-tail signal. */
+export function parseSessionEvent(line) {
+    let decoded;
+    try {
+        decoded = JSON.parse(line);
+    }
+    catch (e) {
+        return { ok: false, errors: [e instanceof Error ? e.message : String(e)] };
+    }
+    return validateSessionEvent(decoded);
+}
+/** `Option<T>` normalisation: a JSON `null` is `None`, i.e. absent. */
+function normalizeSessionEvent(raw, type) {
+    if (type === "tool_call") {
+        const ev = {
+            type,
+            id: raw["id"],
+            name: raw["name"],
+            args: raw["args"],
+        };
+        const parent = nullableString(raw["parent_id"]);
+        if (parent !== undefined)
+            ev.parent_id = parent;
+        return ev;
+    }
+    if (type === "tool_result") {
+        const ev = {
+            type,
+            id: raw["id"],
+            value: raw["value"],
+            error: nullableString(raw["error"]) ?? null,
+        };
+        const parent = nullableString(raw["parent_id"]);
+        if (parent !== undefined)
+            ev.parent_id = parent;
+        // W855 (B6): `null` normalises to absent, like `parent_id`.
+        const surface = raw["surface"];
+        if (surface !== undefined && surface !== null)
+            ev.surface = surface;
+        return ev;
+    }
+    if (type === "user_question") {
+        // Optional timing fields are OMITTED when absent, exactly like `parent_id`
+        // (the row is host-written, so its own writer defines the byte shape).
+        const ev = { type, id: raw["id"], questions: raw["questions"] };
+        const expires = optionalNumberValue(raw["expires_at"]);
+        if (expires !== undefined)
+            ev.expires_at = expires;
+        const timeout = optionalNumberValue(raw["timeout_ms"]);
+        if (timeout !== undefined)
+            ev.timeout_ms = timeout;
+        return ev;
+    }
+    if (type === "user_answer") {
+        const ev = { type, id: raw["id"], answers: raw["answers"] };
+        if (typeof raw["timed_out"] === "boolean")
+            ev.timed_out = raw["timed_out"];
+        return ev;
+    }
+    if (type === "turn_end") {
+        // `#[serde(default)]` fills the missing outcome, so the in-memory event
+        // ALWAYS carries one (a legacy row reads as completed).
+        return { type, id: raw["id"], outcome: effectiveOutcome(raw["outcome"]) };
+    }
+    // W804 §4.2C: an EXPLICIT user_message branch. Without it the generic
+    // fallthrough would outlive this change, but the moment the row gains a field
+    // the codec must own its normalization (field whitelist, null -> omitted).
+    if (type === "user_message") {
+        const ev = { type, text: raw["text"] };
+        const refs = attachmentList(raw["attachments"]);
+        if (refs.length > 0)
+            ev.attachments = refs;
+        // W888: null normalises to absent (like parent_id); 'user' is the default
+        // and is OMITTED so the common row stays byte-identical to pre-W888.
+        const origin = originValue(raw["origin"]);
+        if (origin !== undefined && origin !== "user")
+            ev.origin = origin;
+        return ev;
+    }
+    return raw;
+}
+/** Attachment array validation: null == absent; each item must be an ImageRef. */
+function optionalAttachments(raw, name, errors) {
+    const v = raw[name];
+    if (v === undefined || v === null)
+        return;
+    if (!Array.isArray(v)) {
+        errors.push(`field '${name}' must be an array when present`);
+        return;
+    }
+    for (const item of v) {
+        if (!isImageRef(item))
+            errors.push(`field '${name}' items must be ImageRef objects`);
+    }
+}
+/** Normalize a decoded attachment list: invalid items are dropped; [] means absent. */
+function attachmentList(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        const ref = normalizeImageRef(item);
+        if (ref !== null)
+            out.push(ref);
+    }
+    return out;
+}
+/**
+ * serde-exact ImageRef writer: field order attachment_id, media_type, width,
+ * height, name?, original?; a None optional is omitted, never written as null.
+ */
+function serializeAttachmentRef(ref) {
+    const parts = [
+        `"attachment_id":${JSON.stringify(ref.attachment_id)}`,
+        `"media_type":${JSON.stringify(ref.media_type)}`,
+        `"width":${JSON.stringify(ref.width)}`,
+        `"height":${JSON.stringify(ref.height)}`,
+    ];
+    if (ref.name !== undefined)
+        parts.push(`"name":${JSON.stringify(ref.name)}`);
+    if (ref.original !== undefined) {
+        const o = ref.original;
+        parts.push(`"original":{"width":${JSON.stringify(o.width)},"height":${JSON.stringify(o.height)},"bytes":${JSON.stringify(o.bytes)},"media_type":${JSON.stringify(o.media_type)}}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+function nullableString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+function requireString(raw, name, errors) {
+    if (typeof raw[name] !== "string")
+        errors.push(`field '${name}' must be a string`);
+}
+function requirePresent(raw, name, errors) {
+    if (!(name in raw))
+        errors.push(`field '${name}' is required`);
+}
+function requireArray(raw, name, errors) {
+    if (!Array.isArray(raw[name]))
+        errors.push(`field '${name}' must be an array`);
+}
+function optionalNumber(raw, name, errors) {
+    const v = raw[name];
+    if (v !== undefined && v !== null && (typeof v !== "number" || !Number.isFinite(v))) {
+        errors.push(`field '${name}' must be a number when present`);
+    }
+}
+function optionalNumberValue(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+function optionalBoolean(raw, name, errors) {
+    const v = raw[name];
+    if (v !== undefined && v !== null && typeof v !== "boolean") {
+        errors.push(`field '${name}' must be a boolean when present`);
+    }
+}
+function optionalString(raw, name, errors) {
+    const v = raw[name];
+    if (v !== undefined && v !== null && typeof v !== "string") {
+        errors.push(`field '${name}' must be a string when present`);
+    }
+}
+/** W888: validate the optional `origin` against the closed whitelist. */
+function optionalOrigin(raw, name, errors) {
+    const v = raw[name];
+    if (v === undefined || v === null)
+        return;
+    if (typeof v !== "string" || !SESSION_EVENT_ORIGINS.includes(v)) {
+        errors.push("field '" + name + "' must be one of: " + SESSION_EVENT_ORIGINS.join(", "));
+    }
+}
+/** W888: a valid origin, or undefined (absent/null/invalid -> omitted). */
+function originValue(v) {
+    return typeof v === "string" && SESSION_EVENT_ORIGINS.includes(v) ? v : undefined;
+}
+/** W855 (B6): the optional model-face descriptor on a `tool_result` row. */
+function optionalSurface(raw, name, errors) {
+    const v = raw[name];
+    if (v === undefined || v === null)
+        return;
+    if (!isRecord(v)) {
+        errors.push(`field '${name}' must be an object when present`);
+        return;
+    }
+    if (v["kind"] === "omitted") {
+        for (const n of ["omitted_bytes", "total_bytes", "head_bytes", "tail_bytes"]) {
+            requirePresent(v, n, errors);
+            optionalNumber(v, n, errors);
+        }
+        for (const s of ["locator", "retrieval_hint"]) {
+            requirePresent(v, s, errors);
+            optionalString(v, s, errors);
+        }
+        return;
+    }
+    if (v["kind"] === "truncation") {
+        requirePresent(v, "note", errors);
+        optionalString(v, "note", errors);
+        return;
+    }
+    errors.push(`field '${name}.kind' must be "omitted" or "truncation"`);
+}
+/**
+ * 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 function serializeSessionEvent(ev) {
+    const parts = [`"type":${JSON.stringify(ev.type)}`];
+    switch (ev.type) {
+        case "turn_start":
+            parts.push(`"id":${JSON.stringify(ev.id)}`);
+            break;
+        case "turn_end":
+            parts.push(`"id":${JSON.stringify(ev.id)}`);
+            parts.push(`"outcome":${serializeOutcome(ev.outcome)}`);
+            break;
+        case "user_message":
+            parts.push(`"text":${JSON.stringify(ev.text)}`);
+            // W804 §4.2C (highest-risk site): serializeSessionEvent is hand-written
+            // per field. attachments MUST have an explicit branch or /compact's atomic
+            // log rewrite silently drops every image reference.
+            if (ev.attachments !== undefined && ev.attachments.length > 0) {
+                parts.push(`"attachments":[${ev.attachments.map(serializeAttachmentRef).join(",")}]`);
+            }
+            // W888: omit 'user' (the default) so a pre-W888 row keeps its exact bytes.
+            if (ev.origin !== undefined && ev.origin !== "user")
+                parts.push(`"origin":${JSON.stringify(ev.origin)}`);
+            break;
+        case "assistant_message":
+        case "thinking_delta":
+            parts.push(`"text":${JSON.stringify(ev.text)}`);
+            break;
+        case "tool_call":
+            parts.push(`"id":${JSON.stringify(ev.id)}`);
+            parts.push(`"name":${JSON.stringify(ev.name)}`);
+            parts.push(`"args":${serdeJsonString(ev.args)}`);
+            if (ev.parent_id !== undefined && ev.parent_id !== null)
+                parts.push(`"parent_id":${JSON.stringify(ev.parent_id)}`);
+            break;
+        case "tool_result":
+            parts.push(`"id":${JSON.stringify(ev.id)}`);
+            parts.push(`"value":${serdeJsonString(ev.value === undefined ? null : ev.value)}`);
+            parts.push(`"error":${ev.error === undefined || ev.error === null ? "null" : JSON.stringify(ev.error)}`);
+            if (ev.parent_id !== undefined && ev.parent_id !== null)
+                parts.push(`"parent_id":${JSON.stringify(ev.parent_id)}`);
+            // W855 (B6): the model-face descriptor, omitted when absent (old rows keep
+            // their byte shape).
+            if (ev.surface !== undefined)
+                parts.push(`"surface":${serializeToolSurface(ev.surface)}`);
+            break;
+        // W783: tag first, then the fields in declaration order; the optional ones
+        // are omitted when absent (never written as null).
+        case "user_question":
+            parts.push(`"id":${JSON.stringify(ev.id)}`);
+            parts.push(`"questions":${serdeJsonString(ev.questions)}`);
+            if (ev.expires_at !== undefined)
+                parts.push(`"expires_at":${JSON.stringify(ev.expires_at)}`);
+            if (ev.timeout_ms !== undefined)
+                parts.push(`"timeout_ms":${JSON.stringify(ev.timeout_ms)}`);
+            break;
+        case "user_answer":
+            parts.push(`"id":${JSON.stringify(ev.id)}`);
+            parts.push(`"answers":${serdeJsonString(ev.answers)}`);
+            if (ev.timed_out !== undefined)
+                parts.push(`"timed_out":${JSON.stringify(ev.timed_out)}`);
+            break;
+    }
+    return `{${parts.join(",")}}`;
+}
+/** W855 (B6): the `surface` object, field order fixed (declaration order). */
+function serializeToolSurface(surface) {
+    if (surface.kind === "omitted") {
+        return ('{"kind":"omitted","omitted_bytes":' +
+            JSON.stringify(surface.omitted_bytes) +
+            ',"total_bytes":' +
+            JSON.stringify(surface.total_bytes) +
+            ',"locator":' +
+            JSON.stringify(surface.locator) +
+            ',"retrieval_hint":' +
+            JSON.stringify(surface.retrieval_hint) +
+            ',"head_bytes":' +
+            JSON.stringify(surface.head_bytes) +
+            ',"tail_bytes":' +
+            JSON.stringify(surface.tail_bytes) +
+            "}");
+    }
+    return '{"kind":"truncation","note":' + JSON.stringify(surface.note) + "}";
+}
+/** `TurnOutcome` serde shape: `"completed"` | … | `{"error":{"kind","message"}}`. */
+function serializeOutcome(o) {
+    const e = effectiveOutcome(o);
+    if (typeof e === "string")
+        return JSON.stringify(e);
+    return `{"error":{"kind":${JSON.stringify(e.error.kind)},"message":${JSON.stringify(e.error.message)}}}`;
+}

package/dist/session-log.d.ts

@@ -0,0 +1,71 @@
+/**
+ * SessionLog seam — the `SessionLog` trait of
+ * `crates/core/src/session_log.rs:87-99`.
+ *
+ * The log is the single source of truth for a conversation: it records
+ * SessionEvents in insertion order and derives the model-visible history on
+ * demand. `packages/session` provides the in-memory and JSONL-backed
+ * implementations and registers one as a plugin; `core` never imports them
+ * (dependency direction: session -> core).
+ *
+ * A2 (W746): the seam now also owns the two things every implementation used to
+ * have to re-implement — the projection ([deriveMessagesFrom]) and the turn-id
+ * math ([formatTurnId] / [maxTurnNumber]). A backend only owns STORAGE
+ * ([EventStore]) and hands it to [projectingSessionLog]; the store type rejects a
+ * backend that ships its own `deriveMessages`, so the "legal-looking log with an
+ * empty history" that `packages/workers/src/log.ts` used to be is no longer
+ * expressible.
+ */
+import type { Message } from "./message.js";
+import type { SessionEvent } from "./types.js";
+export interface SessionLog {
+    /** Append one event (insertion order is the contract). */
+    append(event: SessionEvent): void;
+    /** A copy of the recorded events, in insertion order. */
+    events(): SessionEvent[];
+    /** The model-visible projection of [events]. */
+    deriveMessages(): Message[];
+    /** Drop every event (the turn-id counter never resets in the in-memory log). */
+    clear(): void;
+    /**
+     * Allocate the next unique turn id (`"turn-<n>"`, monotonic). The LOG owns
+     * the counter — not the agent loop — so ids never repeat across loop
+     * instances, and a persistent log restores its counter from the max turn id
+     * replayed from disk.
+     */
+    nextTurnId(): string;
+}
+/** Well-known token for the session log service in a Context. */
+export declare const SESSION_LOG_SERVICE = "celestea.core.SessionLog";
+/**
+ * The storage backend a SessionLog is built on: events in, events out. Neither
+ * the projection nor the turn ids are the store's business.
+ *
+ * `deriveMessages?: never` is the point of the type. The projection is core's
+ * ([deriveMessagesFrom]), so a store that ships its own `deriveMessages` — above
+ * all one that returns `[]` — is not assignable to [projectingSessionLog]. That
+ * is what makes the empty-history log `packages/workers/src/log.ts` used to be a
+ * type error instead of a plausible-looking alternative implementation.
+ */
+export interface EventStore {
+    /** Append one event (insertion order is the contract). */
+    append(event: SessionEvent): void;
+    /** A copy of the recorded events, in insertion order. */
+    events(): SessionEvent[];
+    /** Drop every event. */
+    clear(): void;
+    /** Refused: the projection is the seam's, never the store's (A2). */
+    deriveMessages?: never;
+}
+/** An in-memory event store (the trivial backend, and the default one). */
+export declare function memoryEventStore(): EventStore;
+/**
+ * Build a `SessionLog` over a store: core owns the projection and the ids, the
+ * store owns persistence.
+ *
+ * The counter starts at `maxTurnNumber(store.events()) + 1` — 0 for an empty
+ * store, and beyond every id already on disk for a replayed one (so a restart
+ * never reuses an id) — and never resets, not even on `clear()` (ids stay
+ * unique for the life of the log).
+ */
+export declare function projectingSessionLog(store: EventStore): SessionLog;

package/dist/session-log.js

@@ -0,0 +1,66 @@
+/**
+ * SessionLog seam — the `SessionLog` trait of
+ * `crates/core/src/session_log.rs:87-99`.
+ *
+ * The log is the single source of truth for a conversation: it records
+ * SessionEvents in insertion order and derives the model-visible history on
+ * demand. `packages/session` provides the in-memory and JSONL-backed
+ * implementations and registers one as a plugin; `core` never imports them
+ * (dependency direction: session -> core).
+ *
+ * A2 (W746): the seam now also owns the two things every implementation used to
+ * have to re-implement — the projection ([deriveMessagesFrom]) and the turn-id
+ * math ([formatTurnId] / [maxTurnNumber]). A backend only owns STORAGE
+ * ([EventStore]) and hands it to [projectingSessionLog]; the store type rejects a
+ * backend that ships its own `deriveMessages`, so the "legal-looking log with an
+ * empty history" that `packages/workers/src/log.ts` used to be is no longer
+ * expressible.
+ */
+import { deriveMessagesFrom } from "./projection.js";
+import { formatTurnId, maxTurnNumber } from "./turn-id.js";
+/** Well-known token for the session log service in a Context. */
+export const SESSION_LOG_SERVICE = "celestea.core.SessionLog";
+/** An in-memory event store (the trivial backend, and the default one). */
+export function memoryEventStore() {
+    let recorded = [];
+    return {
+        append(event) {
+            recorded.push(event);
+        },
+        events() {
+            return [...recorded];
+        },
+        clear() {
+            recorded = [];
+        },
+    };
+}
+/**
+ * Build a `SessionLog` over a store: core owns the projection and the ids, the
+ * store owns persistence.
+ *
+ * The counter starts at `maxTurnNumber(store.events()) + 1` — 0 for an empty
+ * store, and beyond every id already on disk for a replayed one (so a restart
+ * never reuses an id) — and never resets, not even on `clear()` (ids stay
+ * unique for the life of the log).
+ */
+export function projectingSessionLog(store) {
+    let turnCounter = maxTurnNumber(store.events()) + 1;
+    return {
+        append(event) {
+            store.append(event);
+        },
+        events() {
+            return store.events();
+        },
+        deriveMessages() {
+            return deriveMessagesFrom(store.events());
+        },
+        clear() {
+            store.clear();
+        },
+        nextTurnId() {
+            return formatTurnId(turnCounter++);
+        },
+    };
+}

package/dist/skill-catalog.d.ts

@@ -0,0 +1,29 @@
+/**
+ * W884 — the skill CATALOG: the "resident" half of progressive disclosure.
+ *
+ * W882 owns discovery + the frontmatter contract; the tool (`load_skill`) owns
+ * the body-on-demand half. This module owns the third piece: the compact,
+ * name + description ONLY listing that is injected into the conversation at
+ * every turn start. The body is NEVER here.
+ *
+ * Cost rules (the whole point of the split):
+ *   - ZERO rows when the workspace declares no skill (a workspace without
+ *     skills pays nothing);
+ *   - a description longer than [SKILL_CATALOG_DESCRIPTION_MAX] is truncated
+ *     (W879);
+ *   - at most [SKILL_CATALOG_MAX] entries, name-sorted (the listing already is),
+ *     with the omitted count stated so a truncation is never silent.
+ */
+import type { CelesteaHomeInput } from "./celestea-home.js";
+import { type SkillIo, type SkillListing } from "./skills.js";
+/** Maximum number of skills the injected catalog lists. */
+export declare const SKILL_CATALOG_MAX = 32;
+/** Maximum description length inside the catalog, in characters (W879). */
+export declare const SKILL_CATALOG_DESCRIPTION_MAX = 200;
+/**
+ * Render the catalog text of one discovery listing. PURE. Returns `null` when
+ * there is nothing to announce, so the caller injects NOTHING (zero cost).
+ */
+export declare function renderSkillCatalog(listing: SkillListing): string | null;
+/** Discover the two layers of `wsPath` and render their catalog (or null). */
+export declare function skillCatalogOf(wsPath: string, input?: CelesteaHomeInput, io?: SkillIo): string | null;

package/dist/skill-catalog.js

@@ -0,0 +1,52 @@
+/**
+ * W884 — the skill CATALOG: the "resident" half of progressive disclosure.
+ *
+ * W882 owns discovery + the frontmatter contract; the tool (`load_skill`) owns
+ * the body-on-demand half. This module owns the third piece: the compact,
+ * name + description ONLY listing that is injected into the conversation at
+ * every turn start. The body is NEVER here.
+ *
+ * Cost rules (the whole point of the split):
+ *   - ZERO rows when the workspace declares no skill (a workspace without
+ *     skills pays nothing);
+ *   - a description longer than [SKILL_CATALOG_DESCRIPTION_MAX] is truncated
+ *     (W879);
+ *   - at most [SKILL_CATALOG_MAX] entries, name-sorted (the listing already is),
+ *     with the omitted count stated so a truncation is never silent.
+ */
+import { readLayers } from "./celestea-sources.js";
+import { listSkills, nodeSkillIo } from "./skills.js";
+/** Maximum number of skills the injected catalog lists. */
+export const SKILL_CATALOG_MAX = 32;
+/** Maximum description length inside the catalog, in characters (W879). */
+export const SKILL_CATALOG_DESCRIPTION_MAX = 200;
+/** The catalog header: how to load a body, and what is deliberately absent. */
+const CATALOG_HEADER = "Skills available in this workspace (call the load_skill tool with a name to load one's full instructions before doing a task it covers; a skill's own files — references/, scripts/ — are NOT inlined, read them yourself with read_file):";
+/** Truncate on a code-point boundary and mark the cut. */
+function clip(text) {
+    const chars = [...text];
+    if (chars.length <= SKILL_CATALOG_DESCRIPTION_MAX)
+        return text;
+    return chars.slice(0, SKILL_CATALOG_DESCRIPTION_MAX).join("") + "…";
+}
+function catalogLine(skill) {
+    return "- " + skill.name + ": " + clip(skill.description);
+}
+/**
+ * Render the catalog text of one discovery listing. PURE. Returns `null` when
+ * there is nothing to announce, so the caller injects NOTHING (zero cost).
+ */
+export function renderSkillCatalog(listing) {
+    if (listing.skills.length === 0)
+        return null;
+    const shown = listing.skills.slice(0, SKILL_CATALOG_MAX);
+    const lines = [CATALOG_HEADER, ...shown.map(catalogLine)];
+    const omitted = listing.skills.length - shown.length;
+    if (omitted > 0)
+        lines.push("- (+" + omitted + " more skills not listed; the listing is name-sorted)");
+    return lines.join("\n");
+}
+/** Discover the two layers of `wsPath` and render their catalog (or null). */
+export function skillCatalogOf(wsPath, input = {}, io = nodeSkillIo) {
+    return renderSkillCatalog(listSkills(readLayers(wsPath, input), io));
+}