promptloom 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,611 @@
+/**
+ * promptloom — Core type definitions
+ *
+ * The type system for a prompt compiler:
+ * - Sections with conditional inclusion
+ * - Multi-zone cache scoping
+ * - Tools with deferred loading
+ * - Token budgeting
+ * - Multi-provider output
+ */
+/**
+ * Context passed to compile() for conditional section evaluation.
+ *
+ * In Claude Code, sections are gated on feature flags, model capabilities,
+ * and user type. CompileContext is the generic equivalent.
+ */
+interface CompileContext {
+    /** Current model name (e.g., 'claude-opus-4-6') */
+    model?: string;
+    /** API provider (e.g., 'anthropic', 'bedrock', 'vertex', 'openai') */
+    provider?: string;
+    /** Allow arbitrary user-defined context */
+    [key: string]: unknown;
+}
+/** A compute function that returns a section's content, or null to skip */
+type ComputeFn = () => string | null | Promise<string | null>;
+/** Predicate for conditional section inclusion */
+type WhenPredicate = (ctx: CompileContext) => boolean;
+/** Cache scope for prompt blocks, matching Anthropic API semantics */
+type CacheScope = 'global' | 'org' | null;
+/**
+ * Options for section creation.
+ */
+interface SectionOptions {
+    /**
+     * Conditional predicate. Section is only included when this returns true.
+     *
+     * In Claude Code, this maps to `feature('FLAG')` and `process.env.USER_TYPE` checks
+     * that gate sections like TOKEN_BUDGET, KAIROS, VERIFICATION_AGENT.
+     */
+    when?: WhenPredicate;
+}
+/**
+ * A prompt section — the atomic unit of prompt assembly.
+ *
+ * Sections can be:
+ * - Static: content is computed once and cached for the session
+ * - Dynamic (cacheBreak: true): recomputed every time compile() is called
+ * - Conditional: only included when `when(context)` returns true
+ */
+interface Section {
+    /** Unique identifier for this section */
+    name: string;
+    /** Function that computes the section content */
+    compute: ComputeFn;
+    /** If true, this section is recomputed every compile() call */
+    cacheBreak: boolean;
+    /** If provided, section is only included when predicate returns true */
+    when?: WhenPredicate;
+}
+/**
+ * A zone marker in the entry list.
+ *
+ * Zones create cache block boundaries. All sections between two zone markers
+ * are compiled into a single CacheBlock with the zone's scope.
+ *
+ * In Claude Code, this is implemented via `SYSTEM_PROMPT_DYNAMIC_BOUNDARY`
+ * (a single boundary producing 2 zones). promptloom generalizes to N zones.
+ */
+interface ZoneMarker {
+    readonly __type: 'zone';
+    scope: CacheScope;
+}
+/** An entry in the compiler's internal list */
+type Entry = Section | ZoneMarker;
+/**
+ * A compiled prompt block with cache scope annotation.
+ *
+ * When sent to the Anthropic API, blocks with a non-null cacheScope
+ * get a `cache_control` field, enabling prompt caching.
+ */
+interface CacheBlock {
+    /** The text content of this block */
+    text: string;
+    /** Cache scope: 'global' (cross-org), 'org' (org-level), or null (no cache) */
+    cacheScope: CacheScope;
+}
+/** JSON Schema for tool input parameters */
+type JsonSchema = Record<string, unknown>;
+/**
+ * A tool definition with an embedded prompt.
+ *
+ * In Claude Code, each tool carries its own "user manual" for the LLM.
+ * The prompt is injected into the tool's description field in the API request.
+ */
+interface ToolDef {
+    /** Tool name (e.g., 'bash', 'read_file') */
+    name: string;
+    /**
+     * Tool prompt — the LLM-facing description.
+     * Can be a static string or an async function for dynamic prompts.
+     */
+    prompt: string | (() => string | Promise<string>);
+    /** JSON Schema defining the tool's input parameters */
+    inputSchema: JsonSchema;
+    /** If true, safe to call concurrently with other tools */
+    concurrencySafe?: boolean;
+    /** If true, this tool only reads and never writes */
+    readOnly?: boolean;
+    /**
+     * If true, the tool schema is deferred (not loaded until model requests it).
+     *
+     * In Claude Code, deferred tools get `defer_loading: true` in their schema
+     * and are discovered via ToolSearchTool on demand. This reduces system prompt
+     * token cost when you have many tools.
+     */
+    deferred?: boolean;
+    /**
+     * Explicit ordering for cache stability.
+     * Lower numbers come first. Tools without order use insertion order.
+     *
+     * In Claude Code, tool order is kept stable to maximize prompt cache hits —
+     * reordering tools changes the serialized bytes, breaking the cache.
+     */
+    order?: number;
+}
+/**
+ * A compiled tool schema ready for the API.
+ */
+interface CompiledTool {
+    name: string;
+    description: string;
+    input_schema: JsonSchema;
+    cache_control?: {
+        type: 'ephemeral';
+        scope?: CacheScope;
+    };
+    /** When true, the model must explicitly request this tool via tool search */
+    defer_loading?: true;
+}
+interface TokenEstimate {
+    /** Total estimated tokens for system prompt */
+    systemPrompt: number;
+    /** Total estimated tokens for inline (non-deferred) tool schemas */
+    tools: number;
+    /** Total estimated tokens for deferred tool schemas */
+    deferredTools: number;
+    /** Combined total (systemPrompt + tools, deferred excluded) */
+    total: number;
+}
+interface TokenBudgetConfig {
+    /** Total token budget for the conversation turn */
+    budget: number;
+    /** Stop at this fraction of budget (default: 0.9) */
+    completionThreshold?: number;
+    /** Minimum delta to avoid diminishing returns detection (default: 500) */
+    diminishingThreshold?: number;
+}
+interface CompilerOptions {
+    /** Default cache scope for the initial zone (default: 'org') */
+    defaultCacheScope?: CacheScope;
+    /** Cache scope used by boundary() for the dynamic zone (default: null) */
+    dynamicCacheScope?: CacheScope;
+    /** Bytes per token for rough estimation (default: 4) */
+    bytesPerToken?: number;
+    /**
+     * When true, the initial zone scope is upgraded to 'global'.
+     * Only effective for 1P Anthropic API usage.
+     */
+    enableGlobalCache?: boolean;
+}
+interface CompileResult {
+    /** Prompt blocks with cache annotations, one per zone */
+    blocks: CacheBlock[];
+    /** Inline tool schemas (non-deferred) with resolved prompts */
+    tools: CompiledTool[];
+    /** Deferred tool schemas (loaded on demand) */
+    deferredTools: CompiledTool[];
+    /** Token estimates */
+    tokens: TokenEstimate;
+    /** The full system prompt as a single string (blocks joined) */
+    text: string;
+}
+type ProviderFormat = 'anthropic' | 'openai' | 'bedrock';
+
+/**
+ * promptloom — The Prompt Compiler
+ *
+ * Implements Claude Code's prompt assembly pattern, generalized:
+ *
+ *  1. Multi-zone cache scoping (N blocks, not just 2)
+ *  2. Conditional section inclusion (when predicates)
+ *  3. Static/dynamic section caching
+ *  4. Tool schemas with embedded prompts and deferred loading
+ *  5. Stable tool ordering for cache hits
+ *  6. Token estimation and budget tracking
+ *
+ * Usage:
+ *
+ *   const pc = new PromptCompiler()
+ *
+ *   // Zone 1: no-cache header
+ *   pc.zone(null)
+ *   pc.static('attribution', 'x-model: claude')
+ *
+ *   // Zone 2: globally cacheable
+ *   pc.zone('global')
+ *   pc.static('identity', 'You are a coding assistant.')
+ *   pc.static('rules', () => loadRules())
+ *
+ *   // Zone 3: session-specific
+ *   pc.zone(null)
+ *   pc.dynamic('git', async () => gitStatus())
+ *   pc.static('opus_only', 'Use extended thinking.', {
+ *     when: (ctx) => ctx.model?.includes('opus'),
+ *   })
+ *
+ *   // Tools
+ *   pc.tool({ name: 'bash', prompt: '...', inputSchema: {...} })
+ *   pc.tool({ name: 'rare_tool', prompt: '...', inputSchema: {...}, deferred: true })
+ *
+ *   const result = await pc.compile({ model: 'claude-opus-4-6' })
+ */
+
+declare class PromptCompiler {
+    private entries;
+    private tools;
+    private sectionCache;
+    private toolCache;
+    private options;
+    constructor(options?: CompilerOptions);
+    /**
+     * Start a new cache zone. All sections after this marker are compiled
+     * into a single CacheBlock with the specified scope.
+     *
+     * Generalizes Claude Code's `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` to support
+     * N zones instead of just 2.
+     *
+     * @example
+     * pc.zone(null)      // no-cache zone (attribution, headers)
+     * pc.zone('global')  // globally cacheable (identity, rules)
+     * pc.zone('org')     // org-level cacheable
+     * pc.zone(null)      // session-specific (dynamic context)
+     */
+    zone(scope: CacheScope): this;
+    /**
+     * Insert a cache boundary. Shorthand for starting a new zone with
+     * `dynamicCacheScope` (default: null).
+     *
+     * Equivalent to Claude Code's `SYSTEM_PROMPT_DYNAMIC_BOUNDARY`.
+     * Only effective when `enableGlobalCache` is true (otherwise a no-op
+     * since there's no scope difference to split on).
+     *
+     * For explicit multi-zone control, use `zone()` instead.
+     */
+    boundary(): this;
+    /**
+     * Add a static section. Computed once and cached for the session.
+     *
+     * Equivalent to Claude Code's `systemPromptSection()`.
+     *
+     * @param options.when - Conditional predicate. Section is skipped when false.
+     */
+    static(name: string, content: string | ComputeFn, options?: SectionOptions): this;
+    /**
+     * Add a dynamic section. Recomputed every compile() call.
+     *
+     * Equivalent to Claude Code's `DANGEROUS_uncachedSystemPromptSection()`.
+     *
+     * @param options.when - Conditional predicate. Section is skipped when false.
+     */
+    dynamic(name: string, compute: ComputeFn, options?: SectionOptions): this;
+    /**
+     * Register a tool with an embedded prompt.
+     *
+     * Tools with `deferred: true` are compiled separately and excluded
+     * from the main tool list. They can be discovered on demand.
+     *
+     * Tools with `order` fields are sorted for stable serialization
+     * (cache hit optimization).
+     */
+    tool(def: ToolDef): this;
+    /**
+     * Compile the prompt: resolve sections per zone, compile tools,
+     * separate deferred tools, and estimate tokens.
+     *
+     * @param context - Optional context for conditional section evaluation.
+     *                  Sections with `when` predicates are evaluated against this.
+     */
+    compile(context?: CompileContext): Promise<CompileResult>;
+    /** Clear all caches. Call on `/clear` or `/compact`. */
+    clearCache(): void;
+    /** Clear only section cache (tools stay cached) */
+    clearSectionCache(): void;
+    /** Clear only tool cache (forces prompt re-resolution) */
+    clearToolCache(): void;
+    /** Get the number of registered sections */
+    get sectionCount(): number;
+    /** Get the number of registered tools (inline + deferred) */
+    get toolCount(): number;
+    /** List registered section names with their types */
+    listSections(): Array<{
+        name: string;
+        type: 'static' | 'dynamic' | 'zone';
+    }>;
+    /** List registered tool names */
+    listTools(): string[];
+    /**
+     * Group entries into zones.
+     *
+     * Entries before any zone marker belong to the "initial zone" whose
+     * scope is determined by `enableGlobalCache` and `defaultCacheScope`.
+     */
+    private groupIntoZones;
+    private estimateToolTokens;
+}
+
+/**
+ * promptloom — Section management
+ *
+ * Implements the two-tier section system from Claude Code:
+ * - `section()`: cached within session, computed once
+ * - `dynamicSection()`: recomputed every compile() call (cacheBreak: true)
+ *
+ * Extended with conditional inclusion via `when` predicates,
+ * mirroring Claude Code's `feature()` and `process.env.USER_TYPE` gates.
+ */
+
+/**
+ * Create a static section. Content is computed once and cached.
+ *
+ * Use for: identity prompts, rules, style guides — anything that
+ * doesn't change between turns.
+ */
+declare function section(name: string, compute: ComputeFn, options?: SectionOptions): Section;
+/**
+ * Create a dynamic section. Content is recomputed every compile() call.
+ *
+ * Claude Code calls this `DANGEROUS_uncachedSystemPromptSection` —
+ * the naming reflects that dynamic sections break prompt cache stability.
+ *
+ * Use for: MCP server instructions, real-time status, anything that
+ * changes between turns.
+ */
+declare function dynamicSection(name: string, compute: ComputeFn, options?: SectionOptions): Section;
+/**
+ * In-memory section cache.
+ *
+ * Mirrors `STATE.systemPromptSectionCache` from Claude Code.
+ * Static sections are computed once per session and cached here.
+ * Dynamic sections (cacheBreak: true) bypass the cache entirely.
+ */
+declare class SectionCache {
+    private cache;
+    get(name: string): string | null | undefined;
+    has(name: string): boolean;
+    set(name: string, value: string | null): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Resolve an array of sections, using cache for static ones.
+ *
+ * Mirrors `resolveSystemPromptSections()` from Claude Code:
+ * - Sections with a `when` predicate are filtered by compile context
+ * - Static sections: check cache first, compute if missing
+ * - Dynamic sections: always recompute
+ * - All sections resolved in parallel via Promise.all
+ */
+declare function resolveSections(sections: Section[], cache: SectionCache, context?: CompileContext): Promise<(string | null)[]>;
+
+/**
+ * promptloom — Cache boundary splitting
+ *
+ * Implements Claude Code's cache boundary mechanism:
+ * - A sentinel string divides the prompt into static (cacheable) and dynamic zones
+ * - Content before the boundary gets `cacheScope: 'global'` (cross-org cache)
+ * - Content after gets `cacheScope: null` (session-specific)
+ *
+ * This directly maps to Claude API's `cache_control` field on text blocks.
+ */
+
+/** The sentinel string used to mark the cache boundary */
+declare const CACHE_BOUNDARY = "__PROMPTLOOM_CACHE_BOUNDARY__";
+interface SplitOptions {
+    /** Cache scope for content before the boundary (default: 'global') */
+    staticScope?: CacheScope;
+    /** Cache scope for content after the boundary (default: null) */
+    dynamicScope?: CacheScope;
+    /** Fallback scope when no boundary is found (default: 'org') */
+    fallbackScope?: CacheScope;
+}
+/**
+ * Split a prompt string at the cache boundary into annotated blocks.
+ *
+ * Mirrors Claude Code's `splitSysPromptPrefix()`:
+ *
+ * - If boundary found:
+ *   [static content → staticScope] + [dynamic content → dynamicScope]
+ *
+ * - If no boundary:
+ *   [entire content → fallbackScope]
+ */
+declare function splitAtBoundary(prompt: string, options?: SplitOptions): CacheBlock[];
+
+/**
+ * promptloom — Multi-provider output formatting
+ *
+ * Claude Code supports multiple API providers:
+ * - Anthropic (1P): cache_control with scope on text blocks
+ * - AWS Bedrock: cache_control without scope
+ * - Google Vertex: cache_control without scope
+ * - OpenAI: single string system prompt, no caching API
+ *
+ * This module formats CompileResult for each provider.
+ */
+
+interface AnthropicCacheControl {
+    type: 'ephemeral';
+    ttl?: '5m' | '1h';
+}
+interface AnthropicTextBlock {
+    type: 'text';
+    text: string;
+    cache_control?: AnthropicCacheControl;
+}
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    cache_control?: AnthropicCacheControl;
+    defer_loading?: true;
+}
+/**
+ * Format compile result for Anthropic Messages API.
+ *
+ * Mirrors Claude Code's `buildSystemPromptBlocks()`.
+ * Blocks with a non-null cacheScope get `cache_control: { type: 'ephemeral' }`.
+ */
+declare function toAnthropic(result: CompileResult): {
+    system: AnthropicTextBlock[];
+    tools: AnthropicTool[];
+};
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/**
+ * Format compile result for OpenAI Chat Completions API.
+ *
+ * OpenAI uses a single string for system prompt (no block-level caching).
+ * Tools are wrapped in the `{ type: 'function', function: {...} }` format.
+ */
+declare function toOpenAI(result: CompileResult): {
+    system: string;
+    tools: OpenAITool[];
+};
+type BedrockSystemBlock = {
+    text: string;
+} | {
+    cachePoint: {
+        type: 'default';
+    };
+};
+interface BedrockTool {
+    toolSpec: {
+        name: string;
+        description: string;
+        inputSchema: {
+            jsonSchema: Record<string, unknown>;
+        };
+    };
+}
+/**
+ * Format compile result for AWS Bedrock Converse API.
+ *
+ * Bedrock uses `cachePoint: { type: 'default' }` instead of Anthropic's
+ * `cache_control: { type: 'ephemeral' }`. Tools use `toolSpec` wrapper.
+ */
+declare function toBedrock(result: CompileResult): {
+    system: BedrockSystemBlock[];
+    toolConfig: {
+        tools: BedrockTool[];
+    };
+};
+/**
+ * Convert cache blocks to Anthropic API text block format.
+ *
+ * @deprecated Use `toAnthropic(result).system` instead for full formatting.
+ * Kept for backward compatibility.
+ */
+declare function toAnthropicBlocks(blocks: CacheBlock[], enableCaching?: boolean): AnthropicTextBlock[];
+
+/**
+ * promptloom — Tool prompt management
+ *
+ * In Claude Code, every tool has its own `prompt.ts` — a "user manual"
+ * written for the LLM. Tool prompts are:
+ * - Computed once per session and cached (avoids mid-session drift)
+ * - Injected into the tool's `description` field in the API request
+ * - Can be static strings or async functions
+ * - Optionally deferred (loaded on demand via ToolSearchTool)
+ *
+ * This module provides the tool registry and compilation logic.
+ */
+
+/**
+ * Cache for resolved tool prompts.
+ *
+ * Mirrors Claude Code's `getToolSchemaCache()`:
+ * "Prevents mid-session GrowthBook flips from churning serialized tools array.
+ *  One generation per session unless cache is cleared."
+ */
+declare class ToolCache {
+    private cache;
+    get(key: string): CompiledTool | undefined;
+    set(key: string, tool: CompiledTool): void;
+    has(key: string): boolean;
+    clear(): void;
+}
+/**
+ * Compile a single tool definition into API-ready format.
+ *
+ * Uses session-level cache: first call computes, subsequent calls return cached.
+ * Deferred tools get `defer_loading: true` in their schema.
+ */
+declare function compileTool(def: ToolDef, cache: ToolCache, cacheScope?: CacheScope): Promise<CompiledTool>;
+/**
+ * Compile all tool definitions, resolving prompts in parallel.
+ *
+ * Tools are sorted by explicit `order` field first, then by insertion order.
+ * This ensures stable serialization for prompt cache hits.
+ */
+declare function compileTools(defs: ToolDef[], cache: ToolCache, cacheScope?: CacheScope): Promise<CompiledTool[]>;
+/**
+ * Create a tool definition with safe defaults.
+ */
+declare function defineTool(def: ToolDef): ToolDef;
+
+/**
+ * promptloom — Token estimation and budget utilities
+ *
+ * Mirrors Claude Code's token counting strategy:
+ * - Rough estimation based on byte length (fast, no API call)
+ * - File-type-aware estimation (JSON is denser → 2 bytes/token)
+ * - Budget tracking with diminishing returns detection
+ * - Natural language budget parsing (+500k, spend 2M tokens)
+ */
+
+/**
+ * Estimate token count from a string using byte-length heuristic.
+ *
+ * Claude Code uses 4 bytes/token as default, 2 for dense formats like JSON.
+ * This is intentionally approximate — accurate counting requires an API call.
+ */
+declare function estimateTokens(content: string, bytesPerToken?: number): number;
+/**
+ * Estimate tokens with file-type awareness.
+ * JSON/XML are denser (more tokens per byte) than natural language.
+ */
+declare function estimateTokensForFileType(content: string, extension: string): number;
+interface BudgetTracker {
+    continuationCount: number;
+    lastDeltaTokens: number;
+    lastGlobalTurnTokens: number;
+    startedAt: number;
+}
+type BudgetDecision = {
+    action: 'continue';
+    nudgeMessage: string;
+    pct: number;
+} | {
+    action: 'stop';
+    reason: 'budget_reached' | 'diminishing_returns' | 'no_budget';
+    pct: number;
+};
+declare function createBudgetTracker(): BudgetTracker;
+/**
+ * Check token budget and decide whether to continue.
+ *
+ * Mirrors Claude Code's `checkTokenBudget()`:
+ * - Continue if below completion threshold (default 90%)
+ * - Detect diminishing returns (3+ continuations with tiny deltas)
+ * - Return nudge messages to keep the model working
+ */
+declare function checkBudget(tracker: BudgetTracker, currentTokens: number, config: TokenBudgetConfig): BudgetDecision;
+/**
+ * Parse a token budget from natural language.
+ *
+ * Mirrors Claude Code's `parseTokenBudget()` from `src/utils/tokenBudget.ts`.
+ *
+ * Supported syntaxes:
+ * - Shorthand at start: "+500k", "+2M", "+1.5b"
+ * - Shorthand at end:   "do this task. +500k."
+ * - Verbose:            "use 500k tokens", "spend 2M tokens"
+ *
+ * @returns The parsed budget in tokens, or null if no budget found.
+ *
+ * @example
+ * parseTokenBudget('+500k')           // 500_000
+ * parseTokenBudget('spend 2M tokens') // 2_000_000
+ * parseTokenBudget('+1.5b')           // 1_500_000_000
+ * parseTokenBudget('hello world')     // null
+ */
+declare function parseTokenBudget(text: string): number | null;
+
+export { type AnthropicCacheControl, type AnthropicTextBlock, type AnthropicTool, type BedrockSystemBlock, type BedrockTool, type BudgetDecision, type BudgetTracker, CACHE_BOUNDARY, type CacheBlock, type CacheScope, type CompileContext, type CompileResult, type CompiledTool, type CompilerOptions, type ComputeFn, type Entry, type JsonSchema, type OpenAITool, PromptCompiler, type ProviderFormat, type Section, SectionCache, type SectionOptions, type SplitOptions, type TokenBudgetConfig, type TokenEstimate, ToolCache, type ToolDef, type WhenPredicate, type ZoneMarker, checkBudget, compileTool, compileTools, createBudgetTracker, defineTool, dynamicSection, estimateTokens, estimateTokensForFileType, parseTokenBudget, resolveSections, section, splitAtBoundary, toAnthropic, toAnthropicBlocks, toBedrock, toOpenAI };