@celestea/core 2.7.1

package/dist/projection.js

@@ -0,0 +1,168 @@
+/**
+ * The engine's `derive_messages` projection — a 1:1 port of
+ * `crates/session/src/log.rs:73-204`.
+ *
+ * A2 (W746): this algorithm lives in CORE, not in the L1 implementation
+ * package. `SessionLog.deriveMessages()` is a seam method, so the projection
+ * has to be part of the seam: an implementation that returns `[]` (or that
+ * re-implements the rules slightly differently) is a silent history loss, not
+ * an "alternative implementation". `@celestea/session` re-exports these
+ * functions; backends built with [projectingSessionLog] get them for free.
+ *
+ * Rules (all of them are contract, each pinned by a unit test):
+ *   - `TurnStart` / `TurnEnd` are structural markers, never projected;
+ *   - `ThinkingDelta` is replay-only decoration (W252), never projected;
+ *   - `ToolCall` rows are ACCUMULATED, not projected: consecutive calls merge
+ *     into ONE assistant message carrying one `tool_call` content per call
+ *     (LLM protocols require all tool calls of a turn in a single message);
+ *   - the accumulator is flushed before any other event, and after the last
+ *     event;
+ *   - rows with `parent_id` (W255 run_code sub-calls) stay in the log for
+ *     audit/replay but never reach the model: both the call and its result are
+ *     skipped — the outer run_code round trip is all the model sees;
+ *   - `ToolResult` projects to a tool message whose text is `"Error: {err}"`
+ *     when the error is a non-empty string, otherwise the serde_json text of
+ *     the value (`"null"` when absent).
+ *
+ * `balance_tool_calls` (W267) then makes the projection protocol-valid: every
+ * assistant tool_calls message must be followed by one tool message per call.
+ */
+import { assistantText, attachmentRefsOfValue, toolCallIds, toolResultMessage, toolResultWithImages, userMessage, userMessageWithImages, } from "./message.js";
+import { toolSurfaceText } from "./tool-surface.js";
+/** W267 synthetic result text — byte-for-byte the engine's string (b046564). */
+export const CANCELLED_TOOL_CALL_TEXT = "Error: tool call was cancelled before execution (no result recorded)";
+/** The model-visible history of a session log (the engine's `derive_messages_from`). */
+export function deriveMessagesFrom(events) {
+    const messages = [];
+    const pending = [];
+    for (const event of events) {
+        if (event.type === "tool_call") {
+            // Sub-call rows (parent_id present) are audit-only.
+            if (event.parent_id === undefined) {
+                pending.push({ id: event.id, name: event.name, args: event.args });
+            }
+            continue;
+        }
+        flushToolCalls(messages, pending);
+        const message = projectEvent(event);
+        if (message !== null)
+            messages.push(message);
+    }
+    // Trailing tool calls (no following event) still need flushing.
+    flushToolCalls(messages, pending);
+    balanceToolCalls(messages);
+    return messages;
+}
+/**
+ * Flush accumulated tool calls as ONE assistant message (`flush_tool_calls`).
+ * It drains the accumulator, mirroring the engine's `std::mem::take`.
+ */
+export function flushToolCalls(messages, pending) {
+    if (pending.length === 0)
+        return;
+    const calls = pending.splice(0, pending.length);
+    messages.push({
+        role: "assistant",
+        content: calls.map((call) => ({ type: "tool_call", content: call })),
+        tool_call_id: null,
+    });
+}
+/**
+ * Project one non-tool-call event (`project`). Returns null for the events the
+ * model never sees.
+ */
+export function projectEvent(event) {
+    switch (event.type) {
+        case "user_message":
+            // W804 §4.2A: attachments become image content blocks; with none the
+            // construct is byte-identical to the pre-W804 userMessage.
+            return event.attachments !== undefined && event.attachments.length > 0
+                ? userMessageWithImages(event.text, event.attachments)
+                : userMessage(event.text);
+        case "assistant_message":
+            return assistantText(event.text);
+        case "tool_result":
+            if (event.parent_id !== undefined)
+                return null; // W255 sub-call result
+            // W804 §6.4: the tool value's attachments (read_image) become image blocks
+            // on the SAME tool message; the JSON text (with the metadata) stays first.
+            return toolResultOf(event);
+        case "turn_start":
+        case "turn_end":
+        case "thinking_delta":
+            return null;
+        // W783 §7: the host's user-question audit rows describe a PAUSED turn. The
+        // model sees the outcome as the ordinary `tool_result` of
+        // `ask_user_question`, so projecting these would invent history the model
+        // never received (and would break the tool_call/tool_result pairing).
+        case "user_question":
+        case "user_answer":
+            return null;
+        case "tool_call":
+            // Legacy: unreachable!("ToolCall must be accumulated by derive_messages…")
+            throw new Error("ToolCall must be accumulated by derive_messages, not projected");
+    }
+}
+/** W804: one projected tool result — JSON text first, image references after. */
+function toolResultOf(event) {
+    // W855 (B6): the log stores the ORIGINAL value; `surface` turns it into the
+    // model-visible face (bounded preview + locator, or a truncation note).
+    const text = toolResultText(event.error, event.value, event.surface);
+    const images = attachmentRefsOfValue(event.value);
+    return images.length > 0 ? toolResultWithImages(event.id, text, images) : toolResultMessage(event.id, text);
+}
+/**
+ * The text of a projected ToolResult: error first, else the value with its
+ * `surface` applied (absent surface = the value as serde JSON, as before).
+ */
+export function toolResultText(error, value, surface) {
+    if (typeof error === "string" && error.length > 0)
+        return `Error: ${error}`;
+    return toolSurfaceText(value === undefined ? null : value, surface);
+}
+/**
+ * W267 protocol balance: every assistant `tool_calls` message is followed by
+ * one `tool` message per call id. A cancelled/interrupted turn can stop between
+ * ToolCall and ToolResult, leaving a dangling call that makes the whole history
+ * invalid for OpenAI-compatible upstreams ("insufficient tool messages
+ * following tool_calls message"). A synthetic cancelled result is inserted for
+ * each unanswered call; the log itself is untouched (audit keeps the truth).
+ *
+ * UPSTREAM PARITY NOTE: the cursor advance `i = j + inserted + 1` is ported
+ * unchanged from `crates/session/src/log.rs:149`, including its quirk — when a
+ * call message is fully answered, the message sitting right after its results
+ * is skipped by the cursor, so an unbalanced trailing call message in exactly
+ * that position is NOT balanced (see `packages/session/src/log/derive.test.ts`:
+ * `mirrors the upstream cursor quirk`). Parity with the engine is the contract
+ * here; the quirk is reported upstream rather than diverged from silently.
+ */
+export function balanceToolCalls(messages) {
+    let i = 0;
+    while (i < messages.length) {
+        const current = messages[i];
+        if (current === undefined)
+            break;
+        const callIds = toolCallIds(current);
+        if (callIds.length === 0) {
+            i += 1;
+            continue;
+        }
+        // Results must be the contiguous tool messages right after the call.
+        const answered = [];
+        let j = i + 1;
+        while (j < messages.length && messages[j]?.role === "tool") {
+            const id = messages[j]?.tool_call_id;
+            if (id !== null && id !== undefined)
+                answered.push(id);
+            j += 1;
+        }
+        let inserted = 0;
+        for (const id of callIds) {
+            if (answered.includes(id))
+                continue;
+            messages.splice(j + inserted, 0, toolResultMessage(id, CANCELLED_TOOL_CALL_TEXT));
+            inserted += 1;
+        }
+        i = j + inserted + 1;
+    }
+}

package/dist/question.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The user-question seam — L1 types only (design §4.1 A1).
+ *
+ * Three layers, exactly like the official DSH implementation:
+ *   1. **here** — the service interface, the service token, the error taxonomy
+ *      and the wire-shaped request/answer types. `core` stays L1: no
+ *      implementation, no transport, no storage.
+ *   2. the HOST (`apps/studio`) implements the service and owns the pending
+ *      table;
+ *   3. `packages/tools` consumes it through the `ask_user_question` tool, which
+ *      receives the service by CONSTRUCTION (the `runShellTool({sandbox})`
+ *      pattern) because `packages/tools` never sees a Context.
+ *
+ * Why the answer cannot travel as a message: while the tool is awaited the
+ * session's turn slot is occupied, so `POST /api/turn` becomes steering, and
+ * steering is only drained at step boundaries — a boundary the parked tool call
+ * never reaches (§2.2). The answer therefore resolves the pending promise
+ * through the waterfall's RETURN VALUE (§4.2), never through message injection.
+ *
+ * `AskUserQuestionOutcome.timed_out` is this repo's increment: DSH waits without
+ * any TTL, while §6 gives the wait a maximum and returns an EMPTY answer set
+ * rather than deciding for the model.
+ */
+/** One selectable answer offered to the user. */
+export interface AskUserQuestionOption {
+    /** User-facing label. */
+    label: string;
+    /** Optional extra context rendered by capable UIs. */
+    description?: string;
+}
+/**
+ * A caller-declared presentation intent. It changes presentation only, never the
+ * protocol: the answer encoding is identical with or without one, so a UI that
+ * does not know the tag renders the generic option list (§3.3).
+ */
+export interface AskUserQuestionIntent {
+    /** A plan submitted for review: `detail` carries the plan, `approve` the verdict. */
+    kind: "plan-review";
+    /**
+     * The option label that approves the plan; every other option declines it.
+     * Named rather than positional so no UI infers the verdict from option order.
+     */
+    approve: string;
+}
+/** One question in a user-questions request. */
+export interface AskUserQuestionItem {
+    /** Stable caller-provided question id, echoed in the answer. */
+    id: string;
+    /** The question to display. */
+    question: string;
+    /** Optional supporting detail, kept OUT of option labels (§3.2 rule 3). */
+    detail?: string;
+    /** Optional short heading. */
+    header?: string;
+    /** Optional choices; absent = free-text only. */
+    options?: AskUserQuestionOption[];
+    /** Whether more than one option may be selected. Defaults to single-select. */
+    multiSelect?: boolean;
+    /** Optional presentation intent. */
+    intent?: AskUserQuestionIntent;
+}
+/** Answer to one question. `selected` holds LABELS, never indices (§3.2 rule 1). */
+export interface AskUserQuestionAnswerItem {
+    id: string;
+    selected: string[];
+    /** Optional free-text answer, co-existing with `selected`. */
+    custom?: string;
+}
+/** The human's answer, or the empty set a timeout returns (§6.3). */
+export interface AskUserQuestionOutcome {
+    answers: AskUserQuestionAnswerItem[];
+    /** `true` = the wait expired; the system decided nothing on the model's behalf. */
+    timed_out: boolean;
+}
+/**
+ * One request to the answerer waterfall.
+ *
+ * There is no `sessionId` here on purpose: the service is composed PER SESSION
+ * (the host builds one instance for each generation), so the asking session is
+ * already the instance's own identity and can never be spoofed by the caller.
+ */
+export interface AskUserQuestionRequest {
+    questions: AskUserQuestionItem[];
+    /**
+     * Optional maximum wait in ms; clamped by [askTimeoutMs] (absent/non-positive
+     * = [DEFAULT_ASK_TIMEOUT_MS]). Never means "wait forever".
+     */
+    timeoutMs?: number;
+    /** Lifetime of the wait: aborting it rejects with `ASK_ABORTED`. */
+    signal?: AbortSignal;
+}
+/** The service seam the `ask_user_question` tool consumes. */
+export interface UserQuestionService {
+    /**
+     * Ask the answerer waterfall and wait for the human's answer.
+     *
+     * @throws {UserQuestionError} `EMPTY_QUESTIONS` / `BAD_INTENT` on a malformed
+     *   request, `DELEGATED_CALLER` when a sub-agent asks, `CALLER_NOT_LIVE` when
+     *   the asking generation is gone, `ASK_ABORTED` when the signal aborted,
+     *   `NO_PROVIDER` when no answerer claimed the request.
+     */
+    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionOutcome>;
+}
+/** Well-known token for the user-question service (host-provided). */
+export declare const USER_QUESTION_SERVICE = "celestea.core.UserQuestionService";
+/**
+ * The waterfall event a request travels on. Answerers receive
+ * `(request, next)`: return an outcome to CLAIM the request, call `next()` to
+ * delegate to the next layer (§5.2).
+ */
+export declare const USER_QUESTION_REQUEST_EVENT = "user-questions/request";
+/** The stable error taxonomy of §5.3 (the DSH code set). */
+export declare const USER_QUESTION_ERROR_CODES: readonly ["ASK_ABORTED", "ASK_CANCELLED", "BAD_INTENT", "CALLER_NOT_LIVE", "DELEGATED_CALLER", "EMPTY_QUESTIONS", "NO_PROVIDER"];
+export type UserQuestionErrorCode = (typeof USER_QUESTION_ERROR_CODES)[number];
+/** A user-question failure carrying its stable code. */
+export declare class UserQuestionError extends Error {
+    readonly code: UserQuestionErrorCode;
+    constructor(message: string, code: UserQuestionErrorCode, options?: ErrorOptions);
+}
+/**
+ * Who is asking. An OWNED child agent has no human answerer and would block
+ * forever, so it is refused instead of being allowed to wait (§5.3).
+ *
+ * This repo has no agent-object registry (DSH resolves `ctx.get("agents")`), so
+ * ownership is expressed as the async scope the worker driver enters around
+ * every turn it drives: a root turn runs outside it, a driven worker turn inside
+ * it. That is the same boundary — runtime ownership, not durable session
+ * lineage.
+ */
+export type AskUserCaller = {
+    kind: "root";
+} | {
+    kind: "delegated";
+    owner: string | null;
+};
+/** The implicit caller of any turn that did not enter [delegatedCallerScope]. */
+export declare const ROOT_ASK_CALLER: AskUserCaller;
+/** The caller of the turn currently running on this async context. */
+export declare function currentAskUserCaller(): AskUserCaller;
+/** Run one driven (owned) agent turn: everything inside is a delegated caller. */
+export declare function delegatedCallerScope<T>(owner: string | null, fn: () => Promise<T>): Promise<T>;
+/** Default maximum wait for an answer (ms). */
+export declare const DEFAULT_ASK_TIMEOUT_MS = 300000;
+/** Hard ceiling for the tool's `timeout_ms` override (ms). */
+export declare const MAX_ASK_TIMEOUT_MS = 3600000;
+/**
+ * Clamp a requested wait into `[1, MAX_ASK_TIMEOUT_MS]`. An absent, non-finite or
+ * non-positive request means the default — never "wait forever".
+ *
+ * W834 F06 (R3 batch A): the lower bound is applied AFTER the floor. Flooring
+ * first let a request in (0, 1) — e.g. `timeout_ms: 0.5` — become 0, and
+ * `setTimeout(0)` expired the question before a human could answer it.
+ */
+export declare function askTimeoutMs(requested?: number): number;

package/dist/question.js

@@ -0,0 +1,82 @@
+/**
+ * The user-question seam — L1 types only (design §4.1 A1).
+ *
+ * Three layers, exactly like the official DSH implementation:
+ *   1. **here** — the service interface, the service token, the error taxonomy
+ *      and the wire-shaped request/answer types. `core` stays L1: no
+ *      implementation, no transport, no storage.
+ *   2. the HOST (`apps/studio`) implements the service and owns the pending
+ *      table;
+ *   3. `packages/tools` consumes it through the `ask_user_question` tool, which
+ *      receives the service by CONSTRUCTION (the `runShellTool({sandbox})`
+ *      pattern) because `packages/tools` never sees a Context.
+ *
+ * Why the answer cannot travel as a message: while the tool is awaited the
+ * session's turn slot is occupied, so `POST /api/turn` becomes steering, and
+ * steering is only drained at step boundaries — a boundary the parked tool call
+ * never reaches (§2.2). The answer therefore resolves the pending promise
+ * through the waterfall's RETURN VALUE (§4.2), never through message injection.
+ *
+ * `AskUserQuestionOutcome.timed_out` is this repo's increment: DSH waits without
+ * any TTL, while §6 gives the wait a maximum and returns an EMPTY answer set
+ * rather than deciding for the model.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Well-known token for the user-question service (host-provided). */
+export const USER_QUESTION_SERVICE = "celestea.core.UserQuestionService";
+/**
+ * The waterfall event a request travels on. Answerers receive
+ * `(request, next)`: return an outcome to CLAIM the request, call `next()` to
+ * delegate to the next layer (§5.2).
+ */
+export const USER_QUESTION_REQUEST_EVENT = "user-questions/request";
+/** The stable error taxonomy of §5.3 (the DSH code set). */
+export const USER_QUESTION_ERROR_CODES = [
+    "ASK_ABORTED",
+    "ASK_CANCELLED",
+    "BAD_INTENT",
+    "CALLER_NOT_LIVE",
+    "DELEGATED_CALLER",
+    "EMPTY_QUESTIONS",
+    "NO_PROVIDER",
+];
+/** A user-question failure carrying its stable code. */
+export class UserQuestionError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.name = "UserQuestionError";
+        this.code = code;
+    }
+}
+/** The implicit caller of any turn that did not enter [delegatedCallerScope]. */
+export const ROOT_ASK_CALLER = { kind: "root" };
+const callerScope = new AsyncLocalStorage();
+/** The caller of the turn currently running on this async context. */
+export function currentAskUserCaller() {
+    return callerScope.getStore() ?? ROOT_ASK_CALLER;
+}
+/** Run one driven (owned) agent turn: everything inside is a delegated caller. */
+export function delegatedCallerScope(owner, fn) {
+    return callerScope.run({ kind: "delegated", owner }, fn);
+}
+// ---------------------------------------------------------------------------
+// The wait budget (§6.4)
+// ---------------------------------------------------------------------------
+/** Default maximum wait for an answer (ms). */
+export const DEFAULT_ASK_TIMEOUT_MS = 300000;
+/** Hard ceiling for the tool's `timeout_ms` override (ms). */
+export const MAX_ASK_TIMEOUT_MS = 3600000;
+/**
+ * Clamp a requested wait into `[1, MAX_ASK_TIMEOUT_MS]`. An absent, non-finite or
+ * non-positive request means the default — never "wait forever".
+ *
+ * W834 F06 (R3 batch A): the lower bound is applied AFTER the floor. Flooring
+ * first let a request in (0, 1) — e.g. `timeout_ms: 0.5` — become 0, and
+ * `setTimeout(0)` expired the question before a human could answer it.
+ */
+export function askTimeoutMs(requested) {
+    if (requested === undefined || !Number.isFinite(requested) || requested <= 0)
+        return DEFAULT_ASK_TIMEOUT_MS;
+    return Math.max(1, Math.min(Math.floor(requested), MAX_ASK_TIMEOUT_MS));
+}

package/dist/redact.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Secret redaction for golden fixtures.
+ *
+ * HARD REQUIREMENT (P0): no exported fixture may contain an api key / token in
+ * cleartext. Redaction is applied to every byte the exporter writes and the
+ * result is verified afterwards (see RedactionReport.leaksAfter).
+ */
+export interface RedactionRule {
+    id: string;
+    re: RegExp;
+    replace: string;
+}
+export interface RedactionReport {
+    replacements: number;
+    byRule: Record<string, number>;
+    secretsRegistered: number;
+    /** Credentials discovered in credential contexts and propagated globally. */
+    secretsDiscovered?: number;
+    leaksAfter: string[];
+}
+/** Token shapes that are secrets regardless of where they came from. */
+export declare const DEFAULT_RULES: RedactionRule[];
+export interface Redactor {
+    redact(text: string): string;
+    report(): RedactionReport;
+    /** Secrets discovered in credential contexts while redacting (propagated globally). */
+    dynamicSecrets(): string[];
+    /** Throws when a registered secret or a generic token shape survives. */
+    assertClean(text: string, where: string): void;
+}
+export declare function createRedactor(knownSecrets: readonly string[], extraRules?: readonly RedactionRule[]): Redactor;
+/**
+ * Collect candidate secrets from read-only sources (providers.json keys, an
+ * npm auth token, environment values). Never logs them.
+ */
+export declare function collectKnownSecrets(input: {
+    providersJson?: unknown;
+    npmrc?: string;
+    env?: NodeJS.ProcessEnv;
+}): string[];

package/dist/redact.js

@@ -0,0 +1,185 @@
+/**
+ * Secret redaction for golden fixtures.
+ *
+ * HARD REQUIREMENT (P0): no exported fixture may contain an api key / token in
+ * cleartext. Redaction is applied to every byte the exporter writes and the
+ * result is verified afterwards (see RedactionReport.leaksAfter).
+ */
+const PLACEHOLDER = "<REDACTED>";
+/** Token shapes that are secrets regardless of where they came from. */
+export const DEFAULT_RULES = [
+    // NOTE: no leading \b on the token rules. Session logs embed JSON escapes as
+    // literal text ("...\nsk-<key>..."), so a preceding "n" is a word character
+    // and a \b boundary would silently skip a real key. Over-redaction is the
+    // safe direction here.
+    { id: "openai-sk", re: /sk-[A-Za-z0-9_-]{16,}(?![A-Za-z0-9_-])/g, replace: PLACEHOLDER },
+    { id: "npm-token", re: /npm_[A-Za-z0-9]{30,}/g, replace: PLACEHOLDER },
+    { id: "github-token", re: /(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, replace: PLACEHOLDER },
+    { id: "bearer", re: /(Bearer)\s+[A-Za-z0-9._~+/=-]{16,}/g, replace: "$1 " + PLACEHOLDER },
+    { id: "authorization-header", re: /("(?:authorization|x-api-key|api[_-]?key)"\s*:\s*")([^"\\]{8,})(")/gi, replace: "$1" + PLACEHOLDER + "$3" },
+    // W824 F01: JSON-quoted credential values. The key CLOSING quote sits between
+    // the credential word and the colon, so credential-assignment (name\s*[=:]\s*value)
+    // can never match a form like "token":"...". Match the quoted key form explicitly;
+    // the name set is the credential suffixes only (the authorization-header rule above
+    // owns authorization/api[_-]key, and dropping the broad "auth" fragment here keeps a
+    // JSON field such as "author":"..." intact).
+    { id: "json-credential", re: /("(?:[A-Za-z0-9_]*(?:token|secret|passwd|password|apikey|api_key)[A-Za-z0-9_]*)"\s*:\s*")((?:[^"\\]|\\.){12,})(")/gi, replace: "$1" + PLACEHOLDER + "$3" },
+    { id: "env-assignment", re: /([A-Z0-9_]*(?:API_KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*\s*=\s*)("?)([^\s"'\\]{8,})\2/g, replace: "$1$2" + PLACEHOLDER + "$2" },
+    { id: "aws-key", re: /AKIA[0-9A-Z]{16}/g, replace: PLACEHOLDER },
+    // Cookie / Set-Cookie header values (a live session cookie is a credential).
+    { id: "cookie-header", re: /((?:set-)?cookie\s*:\s*)([^\r\n"'\\]{8,})/gi, replace: "$1" + PLACEHOLDER },
+    // Service-issued bearer tokens such as `dsh-auth-<token>`.
+    { id: "service-auth-token", re: /-auth-[A-Za-z0-9_-]{12,}/g, replace: "-auth-" + PLACEHOLDER },
+    // Any `...token=<value>` / `...key=<value>` / `...secret=<value>` assignment
+    // with a token-shaped (12+ char) value. Prose like `?token=...` stays intact.
+    { id: "credential-assignment", re: /(\b[A-Za-z0-9_]*(?:token|secret|passwd|password|apikey|api_key|auth)[A-Za-z0-9_]*\s*[=:]\s*)([A-Za-z0-9_\-.]{12,})/gi, replace: "$1" + PLACEHOLDER },
+    // NOTE: no generic `_authToken=<value>` rule on purpose. Session logs contain
+    // sed regex prose such as `s/(_authToken=)[A-Za-z0-9._-]+/.../`; the real
+    // npm token is caught by the npm-token rule and by the registered-secret pass
+    // (collectKnownSecrets reads ~/.npmrc).
+];
+/**
+ * Credential contexts. Any token-shaped (16+ char) substring found inside one
+ * of these regions is registered as a dynamic secret and then redacted
+ * EVERYWHERE — so an alias such as `T=<token>` (a shell variable holding a
+ * cookie value) cannot survive just because its own context is not
+ * credential-shaped.
+ */
+const CREDENTIAL_CONTEXTS = [
+    /(?:set-)?cookie\s*:\s*([^\r\n"'\\]{8,})/gi,
+    /authorization\s*:\s*([^\r\n"'\\]{8,})/gi,
+    /bearer\s+([A-Za-z0-9._~+/=-]{8,})/gi,
+    /\b[A-Za-z0-9_]*(?:token|secret|password|passwd|apikey|api_key|auth)[A-Za-z0-9_]*\s*[=:]\s*("?)([A-Za-z0-9_\-.+/=]{8,})\1/gi,
+    /(sk-[A-Za-z0-9_-]{16,})/g,
+    /(-auth-[A-Za-z0-9_-]{12,})/g,
+    /(npm_[A-Za-z0-9]{30,})/g,
+];
+const TOKENISH = /[A-Za-z0-9_\-.+/=]{16,}/g;
+export function createRedactor(knownSecrets, extraRules = []) {
+    const rules = [...extraRules, ...DEFAULT_RULES];
+    const byRule = {};
+    let replacements = 0;
+    // Exact registered secrets first (longest first so overlapping values are safe).
+    const secrets = [...new Set(knownSecrets.filter((s) => typeof s === "string" && s.length >= 8))].sort((a, b) => b.length - a.length);
+    const dynamic = new Set();
+    /** Discover credential-shaped values in the text and register them globally. */
+    function discover(text) {
+        for (const re of CREDENTIAL_CONTEXTS) {
+            re.lastIndex = 0;
+            for (const m of text.matchAll(re)) {
+                for (let g = 1; g < m.length; g++) {
+                    const region = m[g];
+                    if (typeof region !== "string")
+                        continue;
+                    TOKENISH.lastIndex = 0;
+                    for (const tok of region.matchAll(TOKENISH)) {
+                        const v = tok[0];
+                        if (v.length >= 16 && !v.includes(PLACEHOLDER))
+                            dynamic.add(v);
+                    }
+                }
+            }
+        }
+    }
+    function redact(text) {
+        discover(text);
+        let out = text;
+        const allSecrets = [...new Set([...secrets, ...dynamic])].sort((a, b) => b.length - a.length);
+        for (const secret of allSecrets) {
+            if (!out.includes(secret))
+                continue;
+            const parts = out.split(secret);
+            const hits = parts.length - 1;
+            if (hits > 0) {
+                replacements += hits;
+                byRule["registered-secret"] = (byRule["registered-secret"] ?? 0) + hits;
+                out = parts.join(PLACEHOLDER);
+            }
+        }
+        for (const rule of rules) {
+            rule.re.lastIndex = 0;
+            out = out.replace(rule.re, (...args) => {
+                replacements += 1;
+                byRule[rule.id] = (byRule[rule.id] ?? 0) + 1;
+                // args = [match, g1, g2, ..., offset, string]; $1..$n are the groups.
+                const groups = args.slice(1, -2);
+                let replacement = rule.replace;
+                // Descending so $1 cannot clobber the prefix of $10.
+                for (let i = groups.length; i >= 1; i--) {
+                    replacement = replacement.split(`$${i}`).join(groups[i - 1] ?? "");
+                }
+                return replacement;
+            });
+        }
+        return out;
+    }
+    function leaksAfter(text) {
+        // A placeholder is by definition not a leak. Replace it with a SPACE (not
+        // an empty string) so removing it cannot glue neighbouring text into a
+        // fake match for value-shaped rules like `KEY=<value>`.
+        const probe = text.split(PLACEHOLDER).join(" ");
+        const leaks = [];
+        for (const secret of secrets)
+            if (probe.includes(secret))
+                leaks.push("registered-secret");
+        for (const secret of dynamic)
+            if (probe.includes(secret))
+                leaks.push("discovered-secret");
+        for (const rule of rules) {
+            rule.re.lastIndex = 0;
+            if (rule.re.test(probe))
+                leaks.push(rule.id);
+            rule.re.lastIndex = 0;
+        }
+        return [...new Set(leaks)];
+    }
+    return {
+        redact,
+        report() {
+            return { replacements, byRule, secretsRegistered: secrets.length, secretsDiscovered: dynamic.size, leaksAfter: [] };
+        },
+        dynamicSecrets() {
+            return [...dynamic];
+        },
+        assertClean(text, where) {
+            const leaks = leaksAfter(text);
+            if (leaks.length > 0) {
+                throw new Error(`secret leak in ${where}: ${leaks.join(", ")}`);
+            }
+        },
+    };
+}
+/**
+ * Collect candidate secrets from read-only sources (providers.json keys, an
+ * npm auth token, environment values). Never logs them.
+ */
+export function collectKnownSecrets(input) {
+    const out = [];
+    const providers = input.providersJson;
+    if (providers !== null && typeof providers === "object" && "providers" in providers) {
+        const list = providers.providers;
+        if (Array.isArray(list)) {
+            for (const p of list) {
+                if (p !== null && typeof p === "object" && "api_key" in p) {
+                    const key = p.api_key;
+                    if (typeof key === "string" && key.trim().length >= 8)
+                        out.push(key);
+                }
+            }
+        }
+    }
+    if (input.npmrc) {
+        for (const m of input.npmrc.matchAll(/_authToken\s*=\s*(\S+)/g)) {
+            const tok = m[1];
+            if (tok && tok.length >= 8)
+                out.push(tok);
+        }
+    }
+    const env = input.env ?? {};
+    for (const name of ["CELESTEA_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY"]) {
+        const v = env[name];
+        if (typeof v === "string" && v.trim().length >= 8)
+            out.push(v.trim());
+    }
+    return out;
+}

package/dist/repo.d.ts

@@ -0,0 +1,14 @@
+/** Locate the repository root (the directory holding pnpm-workspace.yaml). */
+export declare function repoRoot(from?: string): string;
+/**
+ * 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 declare function contractsDir(): string;
+export declare function contractPath(...parts: string[]): string;
+export declare function fixturePath(...parts: string[]): string;
+export declare function reportPath(...parts: string[]): string;