@mux/ai 0.41.0 → 0.42.0

package/dist/prompts/index.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Normalise untrusted text by folding Unicode compatibility forms
+ * (NFKC) and stripping invisible / bidi-control code points.
+ *
+ * Single source of truth for the two places this transformation is
+ * needed:
+ *
+ * - **Output side** (internal `detectLeakReason`): applied to every
+ *   model output before matching it against canary / tag / encoded-
+ *   blob detectors. Normalising here ensures an attacker-emitted
+ *   fullwidth `<role>` or a canary split with zero-width characters
+ *   still matches.
+ *
+ * - **Input side** (`sanitizeUntrustedText` in
+ *   `src/primitives/transcripts.ts`): applied to every transcript
+ *   cue before it reaches a prompt. Normalising here prevents
+ *   payloads hidden in homoglyphs or invisible splitters from being
+ *   invisible to human reviewers while still understandable to the
+ *   model.
+ *
+ * Using the same function on both sides keeps the hygiene symmetric —
+ * any character folded / stripped on one end is folded / stripped on
+ * the other. Example transformations:
+ *
+ * - Fullwidth angle brackets (U+FF1C / U+FF1E) around a word fold to
+ *   ASCII `<` / `>` under NFKC, so a "fullwidth-tag" wrapping still
+ *   trips the tag detector.
+ * - A zero-width space (U+200B) spliced into the middle of a word is
+ *   removed, collapsing "ig + ZWSP + nore" back to "ignore".
+ * - A leading right-to-left override (U+202E) is stripped, so a
+ *   filename that would render reversed in a terminal reads forward
+ *   for the model and for any downstream substring check.
+ */
+declare function normalizeUntrustedUnicode(text: string): string;
+/**
+ * Which detector fired on a leak, or `null` when the text is clean.
+ *
+ * - `canary` — the system-prompt canary token appeared in the output.
+ *   Near-zero false-positive rate; treat as a confirmed leak.
+ * - `prompt_tag` — an XML-like tag taken from our prompt structure
+ *   appeared in the output. Low false-positive rate.
+ * - `encoded_blob` — a long run of base64- or hex-shaped characters
+ *   appeared in a field expected to hold prose. Heuristic; some false
+ *   positives on hashes or tokens in tech-content transcripts.
+ * - `unexpected_key` — the model emitted a JSON field not declared in
+ *   the schema (see {@link detectUnexpectedKeys}). Stripped silently
+ *   by zod's default `.strip()` mode; this signal surfaces the
+ *   smuggling attempt rather than letting it go unseen.
+ */
+type LeakReason = "canary" | "prompt_tag" | "encoded_blob" | "unexpected_key" | null;
+/**
+ * Returns which detector fires on `text`, or `null` if none do.
+ *
+ * Exposed alongside {@link scrubFreeTextField} so workflows can decide
+ * how to surface the signal (an `engagement-insights` summary might be
+ * suppressed silently, whereas an `ask-questions` reasoning field might
+ * be converted into a skip).
+ */
+declare function detectLeakReason(text: string | null | undefined): LeakReason;
+/**
+ * Returns true when `text` contains evidence of a system-prompt leak.
+ *
+ * Convenience wrapper around {@link detectLeakReason} preserved for
+ * readability at call sites that do not need the reason code.
+ */
+declare function detectSystemPromptLeak(text: string | null | undefined): boolean;
+/** Result of a scrub check — see {@link scrubFreeTextField}. */
+interface ScrubResult {
+    /** Original text when clean; empty string when a leak was detected. */
+    text: string;
+    /** True when a leak was detected and the text was suppressed. */
+    leaked: boolean;
+    /**
+     * Which detector fired, when a leak was detected.
+     *
+     * Useful for telemetry — operators may want to treat a `canary` hit
+     * (near-zero false-positive rate) differently from an `encoded_blob`
+     * hit (heuristic, occasional false positives).
+     */
+    reason: LeakReason;
+}
+/**
+ * Checks a free-text model output field for system-prompt leakage.
+ *
+ * When a leak is detected: emits a warning (with the reason code and
+ * caller-supplied context label) and returns an empty string so the
+ * caller can substitute a neutral placeholder appropriate to its output
+ * shape. When clean: returns the original text unchanged.
+ *
+ * Callers typically pair this with length caps on the underlying zod
+ * schema — a cap on `reasoning`/`insight` of ~400 chars makes encoded
+ * exfiltration mechanically difficult, and the scrubber catches what
+ * still fits.
+ *
+ * @param text     the raw free-text field from the model
+ * @param context  a short label used in the warning and returned
+ *                 telemetry (e.g. "ask-questions reasoning for question 3")
+ */
+declare function scrubFreeTextField(text: string | null | undefined, context: string): ScrubResult;
+/**
+ * Per-field record of a detected leak. Collected across every scrub
+ * performed inside a single workflow invocation and returned to the
+ * caller in the workflow result's `safety` field.
+ */
+interface ScrubbedFieldReport {
+    /**
+     * Identifier for the field that leaked. Format is workflow-specific
+     * (e.g. "reasoning[0]", "moment_insight[2]", "description"). Intended
+     * for debugging and observability; do not parse programmatically.
+     */
+    field: string;
+    /** Which detector fired — see {@link LeakReason}. */
+    reason: Exclude<LeakReason, null>;
+}
+/**
+ * Aggregate safety report returned from workflows that perform
+ * output-side scrubbing.
+ *
+ * Operators can use this to alert on suspected prompt-injection traffic
+ * without inspecting log warnings. Shape is stable across workflows so a
+ * single observer can consume it uniformly.
+ */
+interface SafetyReport {
+    /** `true` when at least one field was suppressed by the scrubber. */
+    leaksDetected: boolean;
+    /**
+     * One entry per suppressed field. Empty (but present) when no leaks
+     * were detected. Iteration order matches the order scrubs ran, so
+     * callers can correlate entries with workflow structure if they wish.
+     */
+    scrubbedFields: ScrubbedFieldReport[];
+}
+/**
+ * Collector helper used inside a workflow to thread a {@link SafetyReport}
+ * through multiple scrub calls without each call site having to track
+ * state. Usage:
+ *
+ *     const safety = createSafetyReporter();
+ *     const cleanReasoning = safety.scrub(raw.reasoning, "reasoning[0]");
+ *     const cleanSummary   = safety.scrub(raw.summary, "summary");
+ *     return { ..., safety: safety.report() };
+ */
+interface SafetyReporter {
+    /**
+     * Scrub `text`, record a report entry if it leaked, and return the
+     * resulting text. Mirrors {@link scrubFreeTextField} but returns the
+     * string directly for convenience at call sites that only care about
+     * the suppressed/clean text.
+     */
+    scrub: (text: string | null | undefined, field: string) => string;
+    /**
+     * Underlying scrub helper for call sites that need the full
+     * {@link ScrubResult} (e.g. to decide between "skip" and "substitute
+     * placeholder"). Recording into the aggregate report happens
+     * automatically.
+     */
+    scrubDetailed: (text: string | null | undefined, field: string) => ScrubResult;
+    /**
+     * Inspect a pre-parse object for keys that are not declared in the
+     * consuming zod schema, log + record each as `unexpected_key`, and
+     * return them so the caller can take additional action if desired.
+     *
+     * This complements zod's default `.strip()` behaviour: `.strip()`
+     * silently drops the extras on parse (which is what we want — no
+     * hard failures), while this helper surfaces the smuggling attempt
+     * so it does not go unseen.
+     *
+     * @param raw           the pre-parse model output
+     * @param expectedKeys  the keys declared by the receiving schema
+     * @param context       a short label used in the warning and report
+     *                      (e.g. "summary_metadata" or "chapters[3]")
+     * @returns             the list of keys present in `raw` but not in
+     *                      `expectedKeys`
+     */
+    recordUnexpectedKeys: (raw: unknown, expectedKeys: readonly string[], context: string) => string[];
+    /**
+     * Record a pre-computed safety signal. Used when the detection
+     * happens inside a `"use step"` boundary and the step returns the
+     * finding as a serialisable value for the workflow to aggregate.
+     *
+     * The caller is responsible for logging if desired — this method
+     * only updates the aggregate report.
+     */
+    record: (field: string, reason: Exclude<LeakReason, null>) => void;
+    /** Snapshot the current aggregate report. */
+    report: () => SafetyReport;
+}
+/**
+ * Detect top-level keys in a model-emitted object that are not declared
+ * in the expected-key list. The check is deliberately shallow — nested
+ * arrays-of-objects (chapters, momentInsights, etc.) should call this
+ * once per element.
+ *
+ * Zod's default `.strip()` mode silently drops the extras during parse;
+ * this helper does the detection the strip otherwise hides. It is
+ * exported separately so call sites can detect without necessarily
+ * going through a {@link SafetyReporter} (e.g. in tests).
+ */
+declare function detectUnexpectedKeys(raw: unknown, expectedKeys: readonly string[]): string[];
+/**
+ * Parse `rawText` as JSON and compare its top-level keys against
+ * `expectedKeys`.
+ *
+ * Returns an empty array when the text is not valid JSON (so a model
+ * that wraps its output in markdown fences or trailing whitespace does
+ * not produce spurious safety signals). Intended for use inside step
+ * functions that receive the model's raw text output but run inside
+ * a `"use step"` boundary that can't ship a {@link SafetyReporter}
+ * across — pass the returned array back as a serialisable value for
+ * the workflow to aggregate.
+ */
+declare function detectUnexpectedKeysFromRawText(rawText: string | undefined, expectedKeys: readonly string[]): string[];
+declare function createSafetyReporter(): SafetyReporter;
+
+/**
+ * A single section of a prompt, rendered as an XML-like tag.
+ */
+interface PromptSection {
+    /** The XML tag name for this section */
+    tag: string;
+    /** The content inside the tag */
+    content: string;
+    /** Optional attributes to add to the tag (e.g., { format: "plain text" }) */
+    attributes?: Record<string, string>;
+}
+/**
+ * Configuration for building a prompt section.
+ * Can be a full PromptSection object, just a string (content only), or undefined to use default.
+ */
+type SectionOverride = string | PromptSection | undefined;
+/**
+ * A template defining the default sections for a prompt.
+ * Keys are section identifiers, values are the default PromptSection definitions.
+ */
+type PromptTemplate<TSections extends string> = Record<TSections, PromptSection>;
+/**
+ * User-provided overrides for prompt sections.
+ * Each key can override the corresponding section's content or full definition.
+ */
+type PromptOverrides<TSections extends string> = Partial<Record<TSections, SectionOverride>>;
+/**
+ * Configuration for the prompt builder.
+ */
+interface PromptBuilderConfig<TSections extends string> {
+    /** Default sections that make up the prompt template */
+    template: PromptTemplate<TSections>;
+    /** Order in which sections should appear in the final prompt */
+    sectionOrder: TSections[];
+}
+/**
+ * A configured prompt builder instance with methods to build prompts.
+ */
+interface PromptBuilder<TSections extends string> {
+    /** The default template sections */
+    template: PromptTemplate<TSections>;
+    /** Build a prompt string, optionally overriding specific sections */
+    build: (overrides?: PromptOverrides<TSections>) => string;
+    /** Build a prompt with additional dynamic sections appended */
+    buildWithContext: (overrides?: PromptOverrides<TSections>, additionalSections?: PromptSection[]) => string;
+    /** Get a single section's content (useful for partial rendering) */
+    getSection: (section: TSections, override?: SectionOverride) => string;
+}
+/**
+ * Renders a PromptSection as an XML-like string.
+ */
+declare function renderSection(section: PromptSection): string;
+/**
+ * Creates a type-safe prompt builder from a template configuration.
+ *
+ * @example
+ * ```typescript
+ * const builder = createPromptBuilder({
+ *   template: {
+ *     task: { tag: 'task', content: 'Analyze the image...' },
+ *     tone: { tag: 'tone', content: 'Be professional.' },
+ *   },
+ *   sectionOrder: ['task', 'tone'],
+ * });
+ *
+ * // Use defaults
+ * const prompt1 = builder.build();
+ *
+ * // Override specific sections
+ * const prompt2 = builder.build({
+ *   tone: 'Be casual and friendly.',
+ * });
+ * ```
+ */
+declare function createPromptBuilder<TSections extends string>(config: PromptBuilderConfig<TSections>): PromptBuilder<TSections>;
+/**
+ * Creates a transcript section for inclusion in prompts.
+ */
+declare function createTranscriptSection(transcriptText: string, format?: "plain text" | "WebVTT"): PromptSection;
+/**
+ * Creates a tone section for inclusion in prompts.
+ */
+declare function createToneSection(instruction: string): PromptSection;
+/**
+ * Creates a language section for inclusion in prompts.
+ * Instructs the model to produce all output in the specified language.
+ */
+declare function createLanguageSection(languageName: string): PromptSection;
+
+/**
+ * Compact, provider-independent scene context shared by prompt consumers.
+ *
+ * Timestamps are absolute offsets from the beginning of the asset. The
+ * context intentionally excludes source windows, cues, images, shot details,
+ * and scored concepts so callers can pass it between workflows without
+ * coupling them to scene-generation internals.
+ */
+interface SceneContextItemV1 {
+    /** Stable zero-based position in the ordered scene sequence. */
+    scene_index: number;
+    /** Absolute scene start time in milliseconds. */
+    start_ms: number;
+    /** Absolute scene end time in milliseconds. */
+    end_ms: number;
+    /** Short human-readable scene title. */
+    title: string;
+    /** Compact summary of the scene's spoken content, when available. */
+    audible_narrative?: string;
+    /** Compact summary of the scene's visual content, when available. */
+    visual_narrative?: string;
+    /** Combined audible and visual narrative, when both signals are available. */
+    blended_narrative?: string;
+    /** Important spoken concepts represented as compact phrases. */
+    notable_audible_concepts?: string[];
+    /** Important visual concepts represented as compact phrases. */
+    notable_visual_concepts?: string[];
+    /** Number of shots or visual beats that make up the scene. */
+    shot_count?: number;
+}
+
+export { type LeakReason, type PromptBuilder, type PromptBuilderConfig, type PromptOverrides, type PromptSection, type PromptTemplate, type SafetyReport, type SafetyReporter, type SceneContextItemV1, type ScrubResult, type ScrubbedFieldReport, type SectionOverride, createLanguageSection, createPromptBuilder, createSafetyReporter, createToneSection, createTranscriptSection, detectLeakReason, detectSystemPromptLeak, detectUnexpectedKeys, detectUnexpectedKeysFromRawText, normalizeUntrustedUnicode, renderSection, scrubFreeTextField };