@oxygen-agent/cli 1.987.20 → 1.1010.1

package/node_modules/@oxygen/shared/dist/linkedin-post-keywords.d.ts

@@ -0,0 +1,44 @@
+export declare const LINKEDIN_POST_KEYWORD_FIELDS: {
+    readonly all: "all_keywords";
+    readonly any: "any_keywords";
+    readonly exclude: "exclude_keywords";
+};
+/** Each "any of" keyword is one upstream search; this bounds the fan-out. */
+export declare const MAX_ANY_KEYWORDS = 5;
+export declare const MAX_ALL_KEYWORDS = 5;
+export declare const MAX_EXCLUDE_KEYWORDS = 20;
+export declare const MAX_KEYWORD_LENGTH = 100;
+export type LinkedInPostKeywordRules = {
+    /** Every one of these must appear in the post. */
+    all: string[];
+    /** At least one of these must appear in the post. */
+    any: string[];
+    /** A post containing any of these is dropped. */
+    exclude: string[];
+};
+export type LinkedInPostKeywordMatch = {
+    keep: boolean;
+    /** The "all of" and "any of" keywords found in the post, in rule order. */
+    matched: string[];
+};
+/** Trim, drop wrapping quotes and collapse inner whitespace. Case is kept for display. */
+export declare function normalizeLinkedInPostKeyword(value: string): string;
+/**
+ * Reads the three rule lists from a request (arrays, or comma-separated strings
+ * from a CLI flag). Returns null when no rule is present, so callers can keep
+ * the plain single-search path untouched.
+ */
+export declare function readLinkedInPostKeywordRules(input: Record<string, unknown>): LinkedInPostKeywordRules | null;
+/** Everything wrong with a rule set, as customer-readable sentences. Empty when valid. */
+export declare function linkedInPostKeywordRuleProblems(rules: LinkedInPostKeywordRules): string[];
+/**
+ * The keyword strings sent upstream, one search each. `search` is the caller's
+ * free-text query and leads every search; "all of" keywords follow; each "any
+ * of" keyword gets its own search. Exclusions are never sent — they are only
+ * enforced on the returned text. Empty when there is no positive keyword at all.
+ */
+export declare function linkedInPostSearchQueries(search: string | null | undefined, rules: LinkedInPostKeywordRules): string[];
+/** How many upstream searches a request fans out to (at least one). */
+export declare function linkedInPostSearchCount(input: Record<string, unknown>): number;
+/** Applies the rules to one post's text. A post with no text matches nothing positive. */
+export declare function matchLinkedInPostKeywords(text: string | null | undefined, rules: LinkedInPostKeywordRules): LinkedInPostKeywordMatch;

package/node_modules/@oxygen/shared/dist/linkedin-post-keywords.js

@@ -0,0 +1,116 @@
+// Boolean keyword rules for LinkedIn post search.
+//
+// The managed post-search endpoint takes a keyword list and documents neither
+// AND/OR semantics between entries nor any boolean syntax, so OXYGEN does not
+// rely on the provider for them. Instead:
+//
+//   - every "any of" keyword becomes its own upstream search (the "all of"
+//     keywords ride along in each one), which is what makes an OR recall-safe;
+//   - the rules are then enforced here, on the returned post text, which is
+//     what makes them exact: case-insensitive, whitespace-normalized substring
+//     matching, the same way a person scanning the post would read it.
+//
+// The provider caps searches per hour for the whole account, so the number of
+// upstream searches one request may fan out to is bounded by MAX_ANY_KEYWORDS.
+// Pure and dependency-free: the provider adapter, the pricing resolver, the
+// signal planner and the web filter rail all read the same rules.
+export const LINKEDIN_POST_KEYWORD_FIELDS = {
+    all: "all_keywords",
+    any: "any_keywords",
+    exclude: "exclude_keywords",
+};
+/** Each "any of" keyword is one upstream search; this bounds the fan-out. */
+export const MAX_ANY_KEYWORDS = 5;
+export const MAX_ALL_KEYWORDS = 5;
+export const MAX_EXCLUDE_KEYWORDS = 20;
+export const MAX_KEYWORD_LENGTH = 100;
+/** Trim, drop wrapping quotes and collapse inner whitespace. Case is kept for display. */
+export function normalizeLinkedInPostKeyword(value) {
+    return value.trim().replace(/^["'“”‘’]+|["'“”‘’]+$/g, "").replace(/\s+/g, " ").trim();
+}
+// A hyphen or dash reads as a space: LinkedIn's own search matches "founder led
+// sales" to posts that say "founder-led sales", and on 2026-09-24 all 25 posts it
+// returned for that keyword were dropped here for the hyphen alone.
+function comparable(value) {
+    return value.toLowerCase().replace(/[-\u2010-\u2015]/g, " ").replace(/\s+/g, " ");
+}
+function readTerms(value) {
+    if (value === undefined || value === null || value === "")
+        return [];
+    const raw = Array.isArray(value) ? value.map((entry) => String(entry)) : String(value).split(",");
+    const seen = new Set();
+    const terms = [];
+    for (const entry of raw) {
+        const term = normalizeLinkedInPostKeyword(entry);
+        if (!term)
+            continue;
+        const key = comparable(term);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        terms.push(term);
+    }
+    return terms;
+}
+/**
+ * Reads the three rule lists from a request (arrays, or comma-separated strings
+ * from a CLI flag). Returns null when no rule is present, so callers can keep
+ * the plain single-search path untouched.
+ */
+export function readLinkedInPostKeywordRules(input) {
+    const rules = {
+        all: readTerms(input[LINKEDIN_POST_KEYWORD_FIELDS.all]),
+        any: readTerms(input[LINKEDIN_POST_KEYWORD_FIELDS.any]),
+        exclude: readTerms(input[LINKEDIN_POST_KEYWORD_FIELDS.exclude]),
+    };
+    return rules.all.length + rules.any.length + rules.exclude.length > 0 ? rules : null;
+}
+/** Everything wrong with a rule set, as customer-readable sentences. Empty when valid. */
+export function linkedInPostKeywordRuleProblems(rules) {
+    const problems = [];
+    if (rules.any.length > MAX_ANY_KEYWORDS) {
+        problems.push(`any_keywords takes at most ${MAX_ANY_KEYWORDS} keywords; each one is a separate LinkedIn search.`);
+    }
+    if (rules.all.length > MAX_ALL_KEYWORDS)
+        problems.push(`all_keywords takes at most ${MAX_ALL_KEYWORDS} keywords.`);
+    if (rules.exclude.length > MAX_EXCLUDE_KEYWORDS)
+        problems.push(`exclude_keywords takes at most ${MAX_EXCLUDE_KEYWORDS} keywords.`);
+    const long = [...rules.all, ...rules.any, ...rules.exclude].find((term) => term.length > MAX_KEYWORD_LENGTH);
+    if (long)
+        problems.push(`Keywords must be at most ${MAX_KEYWORD_LENGTH} characters.`);
+    const excluded = new Set(rules.exclude.map(comparable));
+    const conflict = [...rules.all, ...rules.any].find((term) => excluded.has(comparable(term)));
+    if (conflict)
+        problems.push(`"${conflict}" is both required and excluded.`);
+    return problems;
+}
+/**
+ * The keyword strings sent upstream, one search each. `search` is the caller's
+ * free-text query and leads every search; "all of" keywords follow; each "any
+ * of" keyword gets its own search. Exclusions are never sent — they are only
+ * enforced on the returned text. Empty when there is no positive keyword at all.
+ */
+export function linkedInPostSearchQueries(search, rules) {
+    const base = [search?.trim() ?? "", ...rules.all].filter(Boolean);
+    if (rules.any.length === 0)
+        return base.length > 0 ? [base.join(" ")] : [];
+    return rules.any.map((term) => [...base, term].join(" "));
+}
+/** How many upstream searches a request fans out to (at least one). */
+export function linkedInPostSearchCount(input) {
+    const rules = readLinkedInPostKeywordRules(input);
+    if (!rules)
+        return 1;
+    return Math.max(1, Math.min(MAX_ANY_KEYWORDS, rules.any.length));
+}
+/** Applies the rules to one post's text. A post with no text matches nothing positive. */
+export function matchLinkedInPostKeywords(text, rules) {
+    const body = comparable(text ?? "");
+    const has = (term) => body.includes(comparable(term));
+    const matchedAll = rules.all.filter(has);
+    const matchedAny = rules.any.filter(has);
+    const keep = matchedAll.length === rules.all.length
+        && (rules.any.length === 0 || matchedAny.length > 0)
+        && !rules.exclude.some(has);
+    return { keep, matched: [...matchedAll, ...matchedAny] };
+}

package/node_modules/@oxygen/shared/dist/linkedin-sequences.d.ts

@@ -151,4 +151,100 @@ export declare function waitStepDelayMs(step: LinkedInWaitStep): number;
  * seed is derived.
  */
 export declare function renderLinkedInTemplate(template: string, values: Record<string, unknown>, options?: RenderTemplateOptions): string;
+/**
+ * LinkedIn's connection-note ceiling for a PREMIUM sending account.
+ *
+ * Basic accounts are capped lower — see {@link LINKEDIN_INVITE_NOTE_LIMIT_BASIC}.
+ * One constant, three consumers (the definition validator, the launch copy
+ * preflight and the dispatcher); they carried three independent `300`s before.
+ */
+export declare const LINKEDIN_INVITE_NOTE_LIMIT = 300;
+/**
+ * The ceiling that actually holds for a sending account whose tier we do not
+ * know, which today is every account: nothing in `sender_accounts.metadata`
+ * records a LinkedIn Premium signal.
+ *
+ * Measured on production (2026-09-20, one tenant, 30 days). Two senders, same
+ * tenant, same table:
+ *
+ *   eca988d5   notes > 200 chars:  74 sent,   1 failed,   0 length refusals
+ *   d44fe895   notes > 200 chars:   0 sent, 138 failed, 138 length refusals
+ *
+ * d44fe895 has never delivered a single noted invite over 200 characters, and
+ * the length refusal never fires below 200 on either account. Sequence f729fc2c
+ * rendered 205–238 character notes onto that sender and destroyed 138 leads at a
+ * 100% invite failure rate, because a validator that only knows the Premium
+ * ceiling let every one of them through.
+ *
+ * 200 is safe on any tier, so it is the default and the account may only be
+ * relaxed upward from evidence.
+ */
+export declare const LINKEDIN_INVITE_NOTE_LIMIT_BASIC = 200;
+/**
+ * What a LinkedIn refusal is actually ABOUT — the question the HTTP status band
+ * cannot answer.
+ *
+ * Measured on production (2026-09-21, 14 days, one tenant), a single 403 covered
+ * a sender-side allowance, an unreadable profile and a step sent to a
+ * non-connection, and all three terminated the lead as a recipient bounce. The
+ * provider's own sentence separates them; the status never could.
+ */
+export type LinkedInRefusalScope = 
+/** Our request was malformed for this account. Ours to fix; the lead is fine. */
+"oxygen_request_invalid"
+/** We could not READ the lead's profile. Not a verdict on a send. */
+ | "profile_unreadable"
+/** This sender has exhausted a LinkedIn allowance. Nothing to do with the lead. */
+ | "sender_allowance"
+/** The step needs a connection this lead has not accepted. Ours to sequence. */
+ | "relationship_required"
+/** An invite already exists for this lead. The journey is effectively running. */
+ | "already_engaged"
+/** Unrecognised. Callers MUST preserve their existing behaviour. */
+ | "unknown";
+/**
+ * Classify a LinkedIn refusal from the provider's own account of it.
+ *
+ * Deliberately a CLOSED set of anchored, full-string matches, in the same
+ * discipline as the sequence-recovery allowlists: matching vendor prose is
+ * fragile, so an unrecognised message must degrade to `unknown` and leave the
+ * caller's behaviour exactly as it was. Extending the set is an evidence-driven
+ * act — callers log what they could not classify.
+ *
+ * Pure and total; never throws.
+ */
+export declare function classifyLinkedInRefusal(input: {
+    providerType: string | null;
+    providerMessage: string | null;
+    status: number | null;
+    operation: string | null;
+}): LinkedInRefusalScope;
+/**
+ * Does this refusal scope say the LEAD is unreachable?
+ *
+ * Only `already_engaged` is genuinely about the lead, and even that one means
+ * "an invite exists", not "this person is dead". Everything else is about our
+ * request, our sender or our sequencing, and must never brand the lead.
+ */
+export declare function linkedInRefusalBlamesLead(scope: LinkedInRefusalScope): boolean;
+/**
+ * Trim a rendered connection note to a LinkedIn account's ceiling, at a word
+ * boundary.
+ *
+ * Counts CODE POINTS, matching the launch copy preflight exactly — `.length`
+ * would count an emoji or a ZWJ sequence as two or more and the two surfaces
+ * would then disagree about the same note.
+ *
+ * Cuts at the last whitespace inside the limit so the note never ends mid-word;
+ * a single unbroken run longer than the limit has no boundary to find and is cut
+ * hard, which is the only case where that can happen.
+ *
+ * Returns the note unchanged (and `truncated: false`) when it already fits, so
+ * callers can record the trim only when there was one.
+ */
+export declare function truncateLinkedInInviteNote(note: string, limit: number): {
+    note: string;
+    truncated: boolean;
+    originalLength: number;
+};
 export {};

package/node_modules/@oxygen/shared/dist/linkedin-sequences.js

@@ -73,3 +73,126 @@ export function waitStepDelayMs(step) {
 export function renderLinkedInTemplate(template, values, options) {
     return renderTemplate(template, values, options);
 }
+/**
+ * LinkedIn's connection-note ceiling for a PREMIUM sending account.
+ *
+ * Basic accounts are capped lower — see {@link LINKEDIN_INVITE_NOTE_LIMIT_BASIC}.
+ * One constant, three consumers (the definition validator, the launch copy
+ * preflight and the dispatcher); they carried three independent `300`s before.
+ */
+export const LINKEDIN_INVITE_NOTE_LIMIT = 300;
+/**
+ * The ceiling that actually holds for a sending account whose tier we do not
+ * know, which today is every account: nothing in `sender_accounts.metadata`
+ * records a LinkedIn Premium signal.
+ *
+ * Measured on production (2026-09-20, one tenant, 30 days). Two senders, same
+ * tenant, same table:
+ *
+ *   eca988d5   notes > 200 chars:  74 sent,   1 failed,   0 length refusals
+ *   d44fe895   notes > 200 chars:   0 sent, 138 failed, 138 length refusals
+ *
+ * d44fe895 has never delivered a single noted invite over 200 characters, and
+ * the length refusal never fires below 200 on either account. Sequence f729fc2c
+ * rendered 205–238 character notes onto that sender and destroyed 138 leads at a
+ * 100% invite failure rate, because a validator that only knows the Premium
+ * ceiling let every one of them through.
+ *
+ * 200 is safe on any tier, so it is the default and the account may only be
+ * relaxed upward from evidence.
+ */
+export const LINKEDIN_INVITE_NOTE_LIMIT_BASIC = 200;
+/**
+ * Classify a LinkedIn refusal from the provider's own account of it.
+ *
+ * Deliberately a CLOSED set of anchored, full-string matches, in the same
+ * discipline as the sequence-recovery allowlists: matching vendor prose is
+ * fragile, so an unrecognised message must degrade to `unknown` and leave the
+ * caller's behaviour exactly as it was. Extending the set is an evidence-driven
+ * act — callers log what they could not classify.
+ *
+ * Pure and total; never throws.
+ */
+export function classifyLinkedInRefusal(input) {
+    const message = typeof input.providerMessage === "string" ? input.providerMessage.trim() : "";
+    if (message.length === 0)
+        return "unknown";
+    // Our invite note is longer than THIS account's ceiling. The 164 rows this
+    // matched in 14 days are leads we broke, filed as dead recipients.
+    if (input.status === 400
+        && input.providerType === "provider/invalid_parameters"
+        && /^Invalid parameters: You have reached the maximum number of characters for the custom message\.$/u.test(message)) {
+        return "oxygen_request_invalid";
+    }
+    // The profile READ failed. 121 of 318 failures in 14 days were this, on
+    // `users_get` — the lookup that runs BEFORE the invite or message, so LinkedIn
+    // never saw a send at all. It can be a genuinely unreachable profile or this
+    // sender's own profile-view allowance, and the message cannot tell them apart,
+    // which is exactly why it must not terminate the lead on the first attempt.
+    if (input.status === 403
+        && input.operation === "users_get"
+        && /^Insufficient permissions: This profile can't be accessed$/u.test(message)) {
+        return "profile_unreadable";
+    }
+    if (input.status === 403
+        && input.providerType === "provider/access_restricted"
+        && /^Access restricted: You have reached the limit for custom messages\.$/u.test(message)) {
+        return "sender_allowance";
+    }
+    if (input.status === 403
+        && input.providerType === "provider/access_restricted"
+        && /^Access restricted: This user is not a relation\.$/u.test(message)) {
+        return "relationship_required";
+    }
+    if (input.status === 422
+        && input.providerType === "provider/unprocessable_entity"
+        && /^Unprocessable entity: This user has already handled a request from you in the past 3 weeks\./u.test(message)) {
+        return "already_engaged";
+    }
+    if (input.status === 409
+        && input.providerType === "provider/conflict"
+        && /^Conflict: A relation request has already been sent to this user\.$/u.test(message)) {
+        return "already_engaged";
+    }
+    return "unknown";
+}
+/**
+ * Does this refusal scope say the LEAD is unreachable?
+ *
+ * Only `already_engaged` is genuinely about the lead, and even that one means
+ * "an invite exists", not "this person is dead". Everything else is about our
+ * request, our sender or our sequencing, and must never brand the lead.
+ */
+export function linkedInRefusalBlamesLead(scope) {
+    return scope === "already_engaged";
+}
+/**
+ * Trim a rendered connection note to a LinkedIn account's ceiling, at a word
+ * boundary.
+ *
+ * Counts CODE POINTS, matching the launch copy preflight exactly — `.length`
+ * would count an emoji or a ZWJ sequence as two or more and the two surfaces
+ * would then disagree about the same note.
+ *
+ * Cuts at the last whitespace inside the limit so the note never ends mid-word;
+ * a single unbroken run longer than the limit has no boundary to find and is cut
+ * hard, which is the only case where that can happen.
+ *
+ * Returns the note unchanged (and `truncated: false`) when it already fits, so
+ * callers can record the trim only when there was one.
+ */
+export function truncateLinkedInInviteNote(note, limit) {
+    const points = [...note];
+    const originalLength = points.length;
+    if (limit <= 0 || originalLength <= limit) {
+        return { note, truncated: false, originalLength };
+    }
+    const head = points.slice(0, limit);
+    let cut = head.length;
+    while (cut > 0 && !/\s/u.test(head[cut - 1]))
+        cut -= 1;
+    // No whitespace inside the window: one unbroken run, so a hard cut is the
+    // only option left.
+    const kept = cut === 0 ? head : head.slice(0, cut);
+    return { note: kept.join("").trimEnd(), truncated: true, originalLength };
+}

package/node_modules/@oxygen/shared/dist/llm-durable-capture.d.ts

@@ -0,0 +1,24 @@
+import type { LlmTraceBody, LlmTracingClient } from "./langfuse.js";
+export type LlmCaptureTimestampLookup = {
+    type: "root";
+    id: string;
+} | {
+    type: "event";
+    key: string;
+} | {
+    type: "approval";
+    id: string;
+    phase: "requested" | "decided";
+};
+/**
+ * Langfuse v3 deduplication includes the start date. Stable ids alone do not
+ * prevent cross-day duplicates. This per-trace adapter obtains the original
+ * ledger clock without blocking runtime methods or borrowing their transaction.
+ * The underlying transport still owns identity, payloads, isolation and flush.
+ */
+export declare function withDurableLlmCapture(input: {
+    client: LlmTracingClient;
+    enabled: boolean;
+    root: LlmTraceBody;
+    readTimestamp?: ((lookup: LlmCaptureTimestampLookup) => Promise<Date | null>) | undefined;
+}): LlmTracingClient;

package/node_modules/@oxygen/shared/dist/llm-durable-capture.js

@@ -0,0 +1,89 @@
+import { log } from "./log.js";
+/**
+ * Langfuse v3 deduplication includes the start date. Stable ids alone do not
+ * prevent cross-day duplicates. This per-trace adapter obtains the original
+ * ledger clock without blocking runtime methods or borrowing their transaction.
+ * The underlying transport still owns identity, payloads, isolation and flush.
+ */
+export function withDurableLlmCapture(input) {
+    if (!input.enabled)
+        return input.client;
+    const pending = new Set();
+    const warned = new Set();
+    const missing = (stage) => {
+        if (warned.has(stage))
+            return;
+        warned.add(stage);
+        log("warn", "llm_tracing.missing_capture", { provider: "langfuse", stage, error_code: "langfuse_immutable_timestamp_unavailable" });
+    };
+    const valid = (value) => value instanceof Date && Number.isFinite(value.getTime());
+    const read = (lookup) => new Promise((resolve) => {
+        // Bounds injected readers too. A DB reader must independently bound its
+        // statement and release its own scope when a late acquisition completes.
+        const timer = setTimeout(() => resolve(null), 750);
+        timer.unref?.();
+        void Promise.resolve().then(() => input.readTimestamp?.(lookup) ?? null).then((date) => resolve(valid(date) ? date : null), () => resolve(null)).finally(() => clearTimeout(timer));
+    });
+    const seed = (startTime) => {
+        if (!valid(startTime)) {
+            missing("root_timestamp");
+            return null;
+        }
+        try {
+            input.client.trace({ ...input.root, startTime, endTime: startTime });
+        }
+        catch {
+            missing("root_emission");
+            return null;
+        }
+        return startTime;
+    };
+    // Seed synchronously when the caller already has the run/turn row. A web
+    // approval-only tracer can instead look up its root before queued children.
+    const knownRoot = valid(input.root.startTime) ? seed(input.root.startTime) : undefined;
+    const rootReady = knownRoot !== undefined ? Promise.resolve(knownRoot)
+        : read({ type: "root", id: input.root.id }).then(seed);
+    const enqueue = (action) => {
+        const task = rootReady.then(async (start) => { if (start)
+            await action(start); }).catch(() => missing("capture"));
+        pending.add(task);
+        void task.finally(() => pending.delete(task));
+    };
+    const eventLookup = (body) => {
+        const key = body.metadata?.oxygen_durable_event_key;
+        if (typeof key === "string" && key) {
+            // Auto-approval requests have a persisted approval card before an event
+            // append. The card clock is canonical for both approval capture paths.
+            const approvalKey = /^approval_(requested|decided):(.+)$/.exec(key);
+            if (approvalKey)
+                return { type: "approval", phase: approvalKey[1], id: approvalKey[2] };
+            return { type: "event", key };
+        }
+        const approval = /^apr:(requested|decided):(.+)$/.exec(body.id);
+        return approval ? { type: "approval", phase: approval[1], id: approval[2] } : null;
+    };
+    return {
+        trace: (body) => enqueue((startTime) => input.client.trace({ ...body, startTime })),
+        generation: (body) => enqueue(() => input.client.generation(body)),
+        embedding: (body) => enqueue(() => input.client.embedding(body)),
+        span: (body) => enqueue(() => input.client.span(body)),
+        event: (body) => {
+            const lookup = eventLookup(body);
+            enqueue(async () => {
+                if (!lookup) {
+                    input.client.event(body);
+                    return;
+                }
+                const startTime = valid(body.startTime) ? body.startTime : await read(lookup);
+                if (!startTime) {
+                    missing("event_timestamp");
+                    return;
+                }
+                input.client.event({ ...body, startTime });
+            });
+        },
+        score: (body) => input.client.score(body),
+        flush: async () => { await rootReady; await Promise.allSettled([...pending]); await input.client.flush(); },
+        shutdown: async () => { await rootReady; await Promise.allSettled([...pending]); await input.client.shutdown(); },
+    };
+}

package/node_modules/@oxygen/shared/dist/llm-prompts.d.ts

@@ -0,0 +1,75 @@
+export type LlmPromptRef = {
+    /** Langfuse prompt name, e.g. `copilot.system` or `table_column`. */
+    name: string;
+    /** First 12 hex chars of sha256(template); changes whenever the template does. */
+    hash: string;
+    /** True only for code-owned templates published by the prompt sync. */
+    registered: boolean;
+};
+export type LlmPromptDefinition = LlmPromptRef & {
+    registered: true;
+    template: string;
+};
+/** Deterministic content hash; object key order never changes it. */
+export declare function llmPromptHash(template: unknown): string;
+/** The Langfuse label that identifies one exact template version. */
+export declare function llmPromptLabel(hash: string): string;
+/**
+ * Declare a code-owned prompt template. Call once at module scope with the
+ * template the call site renders from. Placeholders stay literal (`{{name}}`)
+ * so the hash moves only when the instructions do, not per request.
+ */
+export declare function defineLlmPrompt(name: string, template: string): LlmPromptDefinition;
+/** Names declared twice with different templates (a catalog defect). */
+export declare function conflictingLlmPromptNames(): string[];
+/** The Langfuse-safe name shape code prompts must use. */
+export declare function isValidLlmPromptName(name: string): boolean;
+/**
+ * An AI column's prompt as the text Langfuse stores: the instruction template
+ * (placeholders unresolved) plus its output schema, so a schema change is a new
+ * prompt version too. Customer columns and code-owned helpers share it.
+ */
+export declare function aiColumnPromptTemplate(definition: {
+    prompt?: unknown;
+    outputSchema?: unknown;
+}): string;
+/** Declare a code-owned AI helper prompt (knowledge synthesis, drafts, ...). */
+export declare function defineAiColumnPrompt(name: string, definition: {
+    prompt: string;
+    outputSchema?: Record<string, unknown> | null;
+}): LlmPromptDefinition;
+/**
+ * Resolve a lazy prompt getter on a product path. Prompt identity is telemetry:
+ * a template renderer that throws must degrade to an unlinked trace, never
+ * fail the model call it describes.
+ */
+export declare function safeLlmPrompt<T extends LlmPromptRef>(getter: () => T | null): T | null;
+/** Reference a customer-authored or per-request template: metadata only. */
+export declare function llmPromptRef(name: string, template: unknown): LlmPromptRef;
+/**
+ * The registered code prompt whose template is exactly this text, if any: lets
+ * a tracer that only sees the rendered system message recognise a static
+ * template (compaction, sub-agent instructions) without importing its owner.
+ */
+export declare function findLlmPromptByTemplate(template: string): LlmPromptDefinition | undefined;
+/**
+ * The declared code prompt behind a reference, only when its template still
+ * hashes to that reference: lets the tracing client publish the exact text a
+ * generation was rendered from, and never a same-named neighbour.
+ */
+export declare function registeredLlmPrompt(ref: LlmPromptRef): LlmPromptDefinition | undefined;
+/** Every code prompt declared by the modules imported so far, sorted by name. */
+export declare function listLlmPrompts(): LlmPromptDefinition[];
+/**
+ * The prompt a Copilot/Agent model call ran on, from the exact messages sent.
+ * A main-loop call (`kind` "turn") uses the surface's versioned system
+ * template; compaction and sub-agent calls match a registered static template
+ * by the content of one of their system messages; anything else is traced by
+ * content hash only.
+ */
+export declare function llmPromptForModelCall(input: {
+    surface: "copilot" | "agent";
+    kind: string;
+    messages: unknown;
+    turnPrompt?: LlmPromptRef | null;
+}): LlmPromptRef | null;