promptopskit 0.3.8 → 0.4.0

package/dist/index.cjs

@@ -51,6 +51,7 @@ __export(src_exports, {
   interpolate: () => interpolate,
   loadPromptFile: () => loadPromptFile,
   openaiAdapter: () => openaiAdapter,
+  openaiResponsesAdapter: () => openaiResponsesAdapter,
   openrouterAdapter: () => openrouterAdapter,
   parsePrompt: () => parsePrompt,
   renderPrompt: () => renderPrompt,
@@ -144,8 +145,53 @@ function mergeOverride(base, override) {
   if (override.response !== void 0) {
     result.response = { ...result.response, ...override.response };
   }
+  if (override.cache !== void 0) {
+    result.cache = {
+      ...result.cache,
+      ...override.cache,
+      openai: mergeRecordBlock(result.cache?.openai, override.cache.openai),
+      anthropic: mergeRecordBlock(result.cache?.anthropic, override.cache.anthropic),
+      gemini: mergeRecordBlock(result.cache?.gemini, override.cache.gemini),
+      google: mergeRecordBlock(result.cache?.google, override.cache.google)
+    };
+  }
+  if (override.raw !== void 0) {
+    result.raw = {
+      ...result.raw,
+      ...override.raw,
+      openai: mergeRecordBlock(result.raw?.openai, override.raw.openai),
+      "openai-responses": mergeRecordBlock(result.raw?.["openai-responses"], override.raw["openai-responses"]),
+      openai_responses: mergeRecordBlock(result.raw?.openai_responses, override.raw.openai_responses),
+      anthropic: mergeRecordBlock(result.raw?.anthropic, override.raw.anthropic),
+      gemini: mergeRecordBlock(result.raw?.gemini, override.raw.gemini),
+      google: mergeRecordBlock(result.raw?.google, override.raw.google),
+      openrouter: mergeRecordBlock(result.raw?.openrouter, override.raw.openrouter)
+    };
+  }
+  if (override.provider_options !== void 0) {
+    result.provider_options = {
+      ...result.provider_options,
+      ...override.provider_options,
+      anthropic: {
+        ...result.provider_options?.anthropic,
+        ...override.provider_options.anthropic
+      },
+      gemini: {
+        ...result.provider_options?.gemini,
+        ...override.provider_options.gemini
+      },
+      openrouter: {
+        ...result.provider_options?.openrouter,
+        ...override.provider_options.openrouter
+      }
+    };
+  }
   return result;
 }
+function mergeRecordBlock(base, override) {
+  if (override === void 0) return base;
+  return { ...base, ...override };
+}
 
 // src/providers/resolve-asset.ts
 function resolveAssetForProvider(asset, runtime = {}) {
@@ -246,7 +292,66 @@ var SamplingSchema = import_zod.z.object({
 });
 var ResponseSchema = import_zod.z.object({
   format: import_zod.z.enum(["text", "json", "markdown"]).optional(),
-  stream: import_zod.z.boolean().optional()
+  stream: import_zod.z.boolean().optional(),
+  schema: import_zod.z.record(import_zod.z.unknown()).optional(),
+  schema_name: import_zod.z.string().optional(),
+  schema_description: import_zod.z.string().optional(),
+  schema_strict: import_zod.z.boolean().optional()
+});
+var AnthropicProviderOptionsSchema = import_zod.z.object({
+  top_k: import_zod.z.number().int().min(0).optional(),
+  tool_choice: import_zod.z.record(import_zod.z.unknown()).optional(),
+  output_config: import_zod.z.record(import_zod.z.unknown()).optional()
+});
+var GeminiProviderOptionsSchema = import_zod.z.object({
+  candidate_count: import_zod.z.number().int().positive().optional(),
+  top_k: import_zod.z.number().int().min(0).optional(),
+  seed: import_zod.z.number().int().optional(),
+  response_schema: import_zod.z.record(import_zod.z.unknown()).optional(),
+  response_json_schema: import_zod.z.record(import_zod.z.unknown()).optional(),
+  response_modalities: import_zod.z.array(import_zod.z.string()).optional(),
+  thinking_budget_tokens: import_zod.z.number().int().positive().optional()
+});
+var OpenRouterProviderOptionsSchema = import_zod.z.object({
+  provider: import_zod.z.record(import_zod.z.unknown()).optional(),
+  transforms: import_zod.z.array(import_zod.z.string()).optional(),
+  plugins: import_zod.z.array(import_zod.z.record(import_zod.z.unknown())).optional(),
+  models: import_zod.z.array(import_zod.z.string()).optional()
+});
+var ProviderOptionsSchema = import_zod.z.object({
+  anthropic: AnthropicProviderOptionsSchema.optional(),
+  gemini: GeminiProviderOptionsSchema.optional(),
+  openrouter: OpenRouterProviderOptionsSchema.optional()
+});
+var RawProviderBodySchema = import_zod.z.object({
+  openai: import_zod.z.record(import_zod.z.unknown()).optional(),
+  "openai-responses": import_zod.z.record(import_zod.z.unknown()).optional(),
+  openai_responses: import_zod.z.record(import_zod.z.unknown()).optional(),
+  anthropic: import_zod.z.record(import_zod.z.unknown()).optional(),
+  gemini: import_zod.z.record(import_zod.z.unknown()).optional(),
+  google: import_zod.z.record(import_zod.z.unknown()).optional(),
+  openrouter: import_zod.z.record(import_zod.z.unknown()).optional()
+});
+var OpenAICacheSchema = import_zod.z.object({
+  prompt_cache_key: import_zod.z.string().min(1).optional(),
+  retention: import_zod.z.enum(["in_memory", "24h"]).optional()
+});
+var AnthropicCacheSchema = import_zod.z.object({
+  mode: import_zod.z.enum(["automatic", "explicit"]).optional(),
+  type: import_zod.z.literal("ephemeral").optional(),
+  ttl: import_zod.z.enum(["5m", "1h"]).optional(),
+  cache_system_instructions: import_zod.z.boolean().optional(),
+  cache_tools: import_zod.z.boolean().optional(),
+  cache_prompt_template: import_zod.z.boolean().optional()
+});
+var GeminiCacheSchema = import_zod.z.object({
+  cached_content: import_zod.z.string().min(1).optional()
+});
+var CacheSchema = import_zod.z.object({
+  openai: OpenAICacheSchema.optional(),
+  anthropic: AnthropicCacheSchema.optional(),
+  gemini: GeminiCacheSchema.optional(),
+  google: GeminiCacheSchema.optional()
 });
 var HistorySchema = import_zod.z.object({
   max_items: import_zod.z.number().int().positive().optional()
@@ -297,7 +402,10 @@ var PromptAssetOverridesSchema = import_zod.z.object({
   reasoning: ReasoningSchema.optional(),
   sampling: SamplingSchema.optional(),
   response: ResponseSchema.optional(),
-  tools: import_zod.z.array(ToolRefSchema).optional()
+  cache: CacheSchema.optional(),
+  raw: RawProviderBodySchema.optional(),
+  tools: import_zod.z.array(ToolRefSchema).optional(),
+  provider_options: ProviderOptionsSchema.optional()
 });
 var SourceSchema = import_zod.z.object({
   file_path: import_zod.z.string().optional(),
@@ -309,8 +417,9 @@ var SectionsSchema = import_zod.z.object({
   notes: import_zod.z.string().optional()
 });
 var PromptDefaultsSchema = import_zod.z.object({
-  provider: import_zod.z.enum(["openai", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
+  provider: import_zod.z.enum(["openai", "openai-responses", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
   model: import_zod.z.string().optional(),
+  cache: CacheSchema.optional(),
   metadata: MetadataSchema.optional(),
   sections: import_zod.z.object({
     system_instructions: import_zod.z.string().optional()
@@ -320,13 +429,16 @@ var PromptAssetSchema = import_zod.z.object({
   id: import_zod.z.string(),
   schema_version: import_zod.z.number().int().positive().default(1),
   description: import_zod.z.string().optional(),
-  provider: import_zod.z.enum(["openai", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
+  provider: import_zod.z.enum(["openai", "openai-responses", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
   model: import_zod.z.string().optional(),
   fallback_models: import_zod.z.array(import_zod.z.string()).optional(),
   reasoning: ReasoningSchema.optional(),
   sampling: SamplingSchema.optional(),
   response: ResponseSchema.optional(),
+  cache: CacheSchema.optional(),
+  raw: RawProviderBodySchema.optional(),
   tools: import_zod.z.array(ToolRefSchema).optional(),
+  provider_options: ProviderOptionsSchema.optional(),
   mcp: MCPSchema.optional(),
   context: ContextSchema.optional(),
   includes: import_zod.z.array(import_zod.z.string()).optional(),
@@ -338,6 +450,123 @@ var PromptAssetSchema = import_zod.z.object({
   source: SourceSchema.optional()
 });
 
+// src/parser/frontmatter-guard.ts
+var FRONT_MATTER_DELIMITER = /^---[ \t]*$/;
+var REGEX_FIELD = /^(?<indent>\s*)(?<field>allow_regex|deny_regex)\s*:\s*(?<value>.*)$/;
+var PATTERN_FIELD = /^(?<indent>\s*)pattern\s*:\s*(?<value>.*)$/;
+var INLINE_PATTERN_FIELD = /(?:^|[{,]\s*)pattern\s*:\s*(?<value>"(?:\\.|[^"\\])*")/;
+function assertRegexFrontMatterQuoting(content, filePath) {
+  const frontMatter = extractFrontMatter(content);
+  if (!frontMatter) {
+    return;
+  }
+  let pendingRegex;
+  for (const [index, line] of frontMatter.lines.entries()) {
+    const lineNumber = frontMatter.startLine + index;
+    const regexMatch = line.match(REGEX_FIELD);
+    if (regexMatch?.groups) {
+      const field = regexMatch.groups.field;
+      const indent2 = regexMatch.groups.indent.length;
+      const value = regexMatch.groups.value.trim();
+      pendingRegex = value === "" ? { field, indent: indent2 } : void 0;
+      assertNoUnescapedBackslashInDoubleQuotedRegex(value, field, filePath, lineNumber);
+      assertNoUnescapedBackslashInInlinePattern(value, field, filePath, lineNumber);
+      continue;
+    }
+    if (!pendingRegex) {
+      continue;
+    }
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      continue;
+    }
+    const indent = line.match(/^\s*/)?.[0].length ?? 0;
+    if (indent <= pendingRegex.indent) {
+      pendingRegex = void 0;
+      continue;
+    }
+    const patternMatch = line.match(PATTERN_FIELD);
+    if (!patternMatch?.groups) {
+      continue;
+    }
+    assertNoUnescapedBackslashInDoubleQuotedRegex(
+      patternMatch.groups.value.trim(),
+      `${pendingRegex.field}.pattern`,
+      filePath,
+      lineNumber
+    );
+  }
+}
+function assertNoUnescapedBackslashInInlinePattern(value, field, filePath, lineNumber) {
+  const match = value.match(INLINE_PATTERN_FIELD);
+  const pattern = match?.groups?.value;
+  if (!pattern) {
+    return;
+  }
+  assertNoUnescapedBackslashInDoubleQuotedRegex(pattern, `${field}.pattern`, filePath, lineNumber);
+}
+function extractFrontMatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (!FRONT_MATTER_DELIMITER.test(lines[0] ?? "")) {
+    return void 0;
+  }
+  for (let index = 1; index < lines.length; index += 1) {
+    if (FRONT_MATTER_DELIMITER.test(lines[index] ?? "")) {
+      return {
+        lines: lines.slice(1, index),
+        startLine: 2
+      };
+    }
+  }
+  return void 0;
+}
+function assertNoUnescapedBackslashInDoubleQuotedRegex(value, field, filePath, lineNumber) {
+  if (!value.startsWith('"')) {
+    return;
+  }
+  const quoted = readDoubleQuotedScalar(value);
+  if (!quoted) {
+    return;
+  }
+  if (!hasUnescapedBackslash(quoted)) {
+    return;
+  }
+  const location = filePath ? `${filePath}:${lineNumber}` : `line ${lineNumber}`;
+  throw new Error(
+    `POK013: Invalid context regex YAML at ${location}, field "${field}": double-quoted regex strings treat backslashes as YAML escapes. Use unquoted /pattern/i literal form, single quotes, or double each backslash.`
+  );
+}
+function readDoubleQuotedScalar(value) {
+  let result = "";
+  for (let index = 1; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === '"') {
+      return result;
+    }
+    result += char;
+    if (char === "\\" && index + 1 < value.length) {
+      index += 1;
+      result += value[index];
+    }
+  }
+  return void 0;
+}
+function hasUnescapedBackslash(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    if (value[index] !== "\\") {
+      continue;
+    }
+    let count = 1;
+    while (value[index + count] === "\\") {
+      count += 1;
+    }
+    if (count % 2 === 1) {
+      return true;
+    }
+    index += count - 1;
+  }
+  return false;
+}
+
 // src/parser/sections.ts
 var SECTION_MAP = {
   "system instructions": "system_instructions",
@@ -378,6 +607,7 @@ function extractSections(body) {
 
 // src/parser/parser.ts
 function parsePrompt(content, filePath) {
+  assertRegexFrontMatterQuoting(content, filePath);
   const { data: frontMatter, content: body } = (0, import_gray_matter.default)(content);
   const sections = extractSections(body);
   const raw = {
@@ -958,6 +1188,21 @@ function withPromptInputSupport(adapter) {
   };
 }
 
+// src/providers/raw.ts
+function applyRawProviderBody(body, asset, provider) {
+  const raw = getRawProviderBody(asset, provider);
+  return raw ? { ...body, ...raw } : body;
+}
+function getRawProviderBody(asset, provider) {
+  if (provider === "openai-responses") {
+    return asset.raw?.["openai-responses"] ?? asset.raw?.openai_responses;
+  }
+  if (provider === "gemini") {
+    return asset.raw?.gemini ?? asset.raw?.google;
+  }
+  return asset.raw?.[provider];
+}
+
 // src/providers/openai.ts
 var openaiAdapter = withPromptInputSupport({
   name: "openai",
@@ -971,6 +1216,9 @@ var openaiAdapter = withPromptInputSupport({
     if (resolvedAsset.reasoning?.budget_tokens !== void 0) {
       warnings.push("OpenAI uses reasoning_effort, not budget_tokens. budget_tokens will be ignored.");
     }
+    if (resolvedAsset.response?.schema !== void 0 && resolvedAsset.response?.format !== "json") {
+      warnings.push("OpenAI response.schema requires response.format: json. schema will still be applied as JSON schema output.");
+    }
     return { valid: errors.length === 0, errors, warnings };
   },
   render(asset, runtime) {
@@ -995,6 +1243,7 @@ var openaiAdapter = withPromptInputSupport({
       model: resolvedAsset.model,
       messages
     };
+    const openaiCacheConfig = resolvedAsset.cache?.openai;
     if (resolvedAsset.sampling?.temperature !== void 0) body.temperature = resolvedAsset.sampling.temperature;
     if (resolvedAsset.sampling?.top_p !== void 0) body.top_p = resolvedAsset.sampling.top_p;
     if (resolvedAsset.sampling?.frequency_penalty !== void 0) body.frequency_penalty = resolvedAsset.sampling.frequency_penalty;
@@ -1004,12 +1253,28 @@ var openaiAdapter = withPromptInputSupport({
     if (resolvedAsset.reasoning?.effort) {
       body.reasoning_effort = resolvedAsset.reasoning.effort;
     }
-    if (resolvedAsset.response?.format === "json") {
+    if (resolvedAsset.response?.schema) {
+      body.response_format = {
+        type: "json_schema",
+        json_schema: {
+          name: resolvedAsset.response.schema_name ?? `${resolvedAsset.id}_response`,
+          ...resolvedAsset.response.schema_description ? { description: resolvedAsset.response.schema_description } : {},
+          schema: resolvedAsset.response.schema,
+          strict: resolvedAsset.response.schema_strict ?? true
+        }
+      };
+    } else if (resolvedAsset.response?.format === "json") {
       body.response_format = { type: "json_object" };
     }
     if (resolvedAsset.response?.stream !== void 0) {
       body.stream = resolvedAsset.response.stream;
     }
+    if (openaiCacheConfig?.prompt_cache_key) {
+      body.prompt_cache_key = openaiCacheConfig.prompt_cache_key;
+    }
+    if (openaiCacheConfig?.retention) {
+      body.prompt_cache_retention = openaiCacheConfig.retention;
+    }
     if (resolvedAsset.tools && resolvedAsset.tools.length > 0) {
       body.tools = resolvedAsset.tools.map((tool) => {
         if (typeof tool === "string") {
@@ -1028,13 +1293,115 @@ var openaiAdapter = withPromptInputSupport({
       });
     }
     return {
-      body,
+      body: applyRawProviderBody(body, resolvedAsset, "openai"),
       provider: "openai",
       model: resolvedAsset.model ?? "unknown"
     };
   }
 });
 
+// src/providers/openai-responses.ts
+var openaiResponsesAdapter = withPromptInputSupport({
+  name: "openai-responses",
+  validate(asset, runtime) {
+    const resolvedAsset = resolveAssetForProvider(asset, runtime);
+    const errors = [];
+    const warnings = [];
+    if (!resolvedAsset.model) {
+      errors.push("OpenAI Responses adapter requires a model to be specified.");
+    }
+    if (resolvedAsset.reasoning?.budget_tokens !== void 0) {
+      warnings.push("OpenAI Responses uses reasoning.effort, not budget_tokens. budget_tokens will be ignored.");
+    }
+    if (resolvedAsset.response?.schema !== void 0 && resolvedAsset.response?.format !== "json") {
+      warnings.push("OpenAI Responses response.schema requires response.format: json. schema will still be applied as JSON schema output.");
+    }
+    if (runtime?.openaiResponses?.conversation !== void 0 && runtime?.openaiResponses?.previous_response_id !== void 0) {
+      errors.push('OpenAI Responses options "conversation" and "previous_response_id" cannot both be set.');
+    }
+    return { valid: errors.length === 0, errors, warnings };
+  },
+  render(asset, runtime) {
+    const resolvedAsset = resolveAssetForProvider(asset, runtime);
+    const sections = renderSections(resolvedAsset, {
+      variables: runtime.variables,
+      strict: runtime.strict
+    });
+    const responseOptions = runtime.openaiResponses;
+    const input = [];
+    if (runtime.history) {
+      for (const msg of runtime.history) {
+        input.push({ role: msg.role, content: msg.content });
+      }
+    }
+    if (sections.prompt_template) {
+      input.push({ role: "user", content: sections.prompt_template });
+    }
+    const body = {
+      model: resolvedAsset.model,
+      input
+    };
+    if (responseOptions?.instructions !== void 0) {
+      body.instructions = responseOptions.instructions;
+    } else if (sections.system_instructions) {
+      body.instructions = sections.system_instructions;
+    }
+    if (resolvedAsset.sampling?.temperature !== void 0) body.temperature = resolvedAsset.sampling.temperature;
+    if (resolvedAsset.sampling?.top_p !== void 0) body.top_p = resolvedAsset.sampling.top_p;
+    if (resolvedAsset.sampling?.frequency_penalty !== void 0) body.frequency_penalty = resolvedAsset.sampling.frequency_penalty;
+    if (resolvedAsset.sampling?.presence_penalty !== void 0) body.presence_penalty = resolvedAsset.sampling.presence_penalty;
+    if (resolvedAsset.sampling?.stop !== void 0) body.stop = resolvedAsset.sampling.stop;
+    if (resolvedAsset.sampling?.max_output_tokens !== void 0) body.max_output_tokens = resolvedAsset.sampling.max_output_tokens;
+    if (resolvedAsset.reasoning?.effort) {
+      body.reasoning = { effort: resolvedAsset.reasoning.effort };
+    }
+    if (resolvedAsset.response?.schema) {
+      body.text = {
+        format: {
+          type: "json_schema",
+          name: resolvedAsset.response.schema_name ?? `${resolvedAsset.id}_response`,
+          ...resolvedAsset.response.schema_description ? { description: resolvedAsset.response.schema_description } : {},
+          schema: resolvedAsset.response.schema,
+          strict: resolvedAsset.response.schema_strict ?? true
+        }
+      };
+    } else if (resolvedAsset.response?.format === "json") {
+      body.text = { format: { type: "json_object" } };
+    }
+    if (resolvedAsset.response?.stream !== void 0) {
+      body.stream = resolvedAsset.response.stream;
+    }
+    if (resolvedAsset.tools && resolvedAsset.tools.length > 0) {
+      body.tools = resolvedAsset.tools.map((tool) => {
+        if (typeof tool === "string") {
+          const def = runtime.toolRegistry?.[tool];
+          if (def) return def;
+          return { type: "function", name: tool };
+        }
+        return {
+          type: "function",
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.input_schema
+        };
+      });
+    }
+    if (responseOptions?.previous_response_id !== void 0) body.previous_response_id = responseOptions.previous_response_id;
+    if (responseOptions?.conversation !== void 0) body.conversation = responseOptions.conversation;
+    if (responseOptions?.parallel_tool_calls !== void 0) body.parallel_tool_calls = responseOptions.parallel_tool_calls;
+    if (responseOptions?.max_tool_calls !== void 0) body.max_tool_calls = responseOptions.max_tool_calls;
+    if (responseOptions?.store !== void 0) body.store = responseOptions.store;
+    if (responseOptions?.metadata !== void 0) body.metadata = responseOptions.metadata;
+    if (responseOptions?.include !== void 0) body.include = responseOptions.include;
+    if (responseOptions?.background !== void 0) body.background = responseOptions.background;
+    return {
+      body: applyRawProviderBody(body, resolvedAsset, "openai-responses"),
+      provider: "openai-responses",
+      model: resolvedAsset.model ?? "unknown"
+    };
+  }
+});
+
 // src/providers/anthropic.ts
 var anthropicAdapter = withPromptInputSupport({
   name: "anthropic",
@@ -1054,6 +1421,12 @@ var anthropicAdapter = withPromptInputSupport({
     if (resolvedAsset.reasoning?.effort !== void 0) {
       warnings.push("Anthropic uses budget_tokens for thinking, not effort. effort will be mapped approximately.");
     }
+    if (resolvedAsset.response?.schema !== void 0 && resolvedAsset.response?.format !== "json") {
+      warnings.push("Anthropic response.schema is mapped to output_config.format and should usually be paired with response.format: json.");
+    }
+    if (resolvedAsset.provider_options?.anthropic?.top_k !== void 0 && resolvedAsset.provider_options.anthropic.top_k < 0) {
+      errors.push("Anthropic provider_options.top_k must be >= 0.");
+    }
     return { valid: errors.length === 0, errors, warnings };
   },
   render(asset, runtime) {
@@ -1063,20 +1436,38 @@ var anthropicAdapter = withPromptInputSupport({
       strict: runtime.strict
     });
     const messages = [];
+    const anthropicCacheConfig = resolvedAsset.cache?.anthropic;
+    const cacheType = anthropicCacheConfig?.type ?? "ephemeral";
+    const cacheControl = anthropicCacheConfig ? {
+      type: cacheType,
+      ...anthropicCacheConfig.ttl ? { ttl: anthropicCacheConfig.ttl } : {}
+    } : void 0;
+    const cacheMode = anthropicCacheConfig?.mode ?? "automatic";
     if (runtime.history) {
       for (const msg of runtime.history) {
         messages.push({ role: msg.role, content: msg.content });
       }
     }
     if (sections.prompt_template) {
-      messages.push({ role: "user", content: sections.prompt_template });
+      if (cacheControl && cacheMode === "explicit" && anthropicCacheConfig?.cache_prompt_template) {
+        messages.push({
+          role: "user",
+          content: [{ type: "text", text: sections.prompt_template, cache_control: cacheControl }]
+        });
+      } else {
+        messages.push({ role: "user", content: sections.prompt_template });
+      }
     }
     const body = {
       model: resolvedAsset.model,
       messages
     };
     if (sections.system_instructions) {
-      body.system = sections.system_instructions;
+      if (cacheControl && cacheMode === "explicit" && anthropicCacheConfig?.cache_system_instructions !== false) {
+        body.system = [{ type: "text", text: sections.system_instructions, cache_control: cacheControl }];
+      } else {
+        body.system = sections.system_instructions;
+      }
     }
     if (resolvedAsset.sampling?.temperature !== void 0) body.temperature = resolvedAsset.sampling.temperature;
     if (resolvedAsset.sampling?.top_p !== void 0) body.top_p = resolvedAsset.sampling.top_p;
@@ -1092,25 +1483,53 @@ var anthropicAdapter = withPromptInputSupport({
         budget_tokens: resolvedAsset.reasoning.budget_tokens
       };
     }
+    if (resolvedAsset.provider_options?.anthropic?.top_k !== void 0) {
+      body.top_k = resolvedAsset.provider_options.anthropic.top_k;
+    }
+    if (resolvedAsset.provider_options?.anthropic?.output_config !== void 0) {
+      body.output_config = resolvedAsset.provider_options.anthropic.output_config;
+    } else if (resolvedAsset.response?.schema !== void 0) {
+      body.output_config = {
+        format: {
+          type: "json_schema",
+          schema: resolvedAsset.response.schema
+        }
+      };
+    }
     if (resolvedAsset.response?.stream !== void 0) {
       body.stream = resolvedAsset.response.stream;
     }
+    if (cacheControl && cacheMode === "automatic") {
+      body.cache_control = cacheControl;
+    }
     if (resolvedAsset.tools && resolvedAsset.tools.length > 0) {
       body.tools = resolvedAsset.tools.map((tool) => {
         if (typeof tool === "string") {
           const def = runtime.toolRegistry?.[tool];
-          if (def) return def;
-          return { name: tool };
+          if (def) {
+            if (cacheControl && cacheMode === "explicit" && anthropicCacheConfig?.cache_tools) {
+              return { ...def, cache_control: cacheControl };
+            }
+            return def;
+          }
+          return {
+            name: tool,
+            ...cacheControl && cacheMode === "explicit" && anthropicCacheConfig?.cache_tools ? { cache_control: cacheControl } : {}
+          };
         }
         return {
           name: tool.name,
           description: tool.description,
-          input_schema: tool.input_schema ?? { type: "object", properties: {} }
+          input_schema: tool.input_schema ?? { type: "object", properties: {} },
+          ...cacheControl && cacheMode === "explicit" && anthropicCacheConfig?.cache_tools ? { cache_control: cacheControl } : {}
         };
       });
     }
+    if (resolvedAsset.provider_options?.anthropic?.tool_choice !== void 0) {
+      body.tool_choice = resolvedAsset.provider_options.anthropic.tool_choice;
+    }
     return {
-      body,
+      body: applyRawProviderBody(body, resolvedAsset, "anthropic"),
       provider: "anthropic",
       model: resolvedAsset.model ?? "unknown"
     };
@@ -1124,6 +1543,8 @@ var geminiAdapter = withPromptInputSupport({
     const resolvedAsset = resolveAssetForProvider(asset, runtime);
     const errors = [];
     const warnings = [];
+    const geminiCache = resolvedAsset.cache?.gemini?.cached_content;
+    const googleCache = resolvedAsset.cache?.google?.cached_content;
     if (!resolvedAsset.model) {
       errors.push("Gemini adapter requires a model to be specified.");
     }
@@ -1133,6 +1554,12 @@ var geminiAdapter = withPromptInputSupport({
     if (resolvedAsset.sampling?.presence_penalty !== void 0) {
       warnings.push("Gemini does not support presence_penalty. It will be ignored.");
     }
+    if (geminiCache && googleCache && geminiCache !== googleCache) {
+      warnings.push("Both cache.gemini.cached_content and cache.google.cached_content are set. Gemini uses cache.gemini.cached_content.");
+    }
+    if (resolvedAsset.response?.stream !== void 0) {
+      warnings.push("Gemini streaming is endpoint-based (streamGenerateContent), not body-based. response.stream will be ignored.");
+    }
     return { valid: errors.length === 0, errors, warnings };
   },
   render(asset, runtime) {
@@ -1159,20 +1586,33 @@ var geminiAdapter = withPromptInputSupport({
     const body = {
       contents
     };
+    const geminiCacheConfig = resolvedAsset.cache?.gemini ?? resolvedAsset.cache?.google;
     if (sections.system_instructions) {
       body.systemInstruction = {
         parts: [{ text: sections.system_instructions }]
       };
     }
     const generationConfig = {};
+    const geminiOptions = resolvedAsset.provider_options?.gemini;
     if (resolvedAsset.sampling?.temperature !== void 0) generationConfig.temperature = resolvedAsset.sampling.temperature;
     if (resolvedAsset.sampling?.top_p !== void 0) generationConfig.topP = resolvedAsset.sampling.top_p;
     if (resolvedAsset.sampling?.max_output_tokens !== void 0) generationConfig.maxOutputTokens = resolvedAsset.sampling.max_output_tokens;
     if (resolvedAsset.sampling?.stop !== void 0) generationConfig.stopSequences = resolvedAsset.sampling.stop;
+    if (geminiOptions?.candidate_count !== void 0) generationConfig.candidateCount = geminiOptions.candidate_count;
+    if (geminiOptions?.top_k !== void 0) generationConfig.topK = geminiOptions.top_k;
+    if (geminiOptions?.seed !== void 0) generationConfig.seed = geminiOptions.seed;
+    if (geminiOptions?.response_modalities !== void 0) generationConfig.responseModalities = geminiOptions.response_modalities;
+    if (resolvedAsset.response?.schema !== void 0) generationConfig.responseJsonSchema = resolvedAsset.response.schema;
+    if (geminiOptions?.response_schema !== void 0) generationConfig.responseSchema = geminiOptions.response_schema;
+    if (geminiOptions?.response_json_schema !== void 0) generationConfig.responseJsonSchema = geminiOptions.response_json_schema;
     if (resolvedAsset.response?.format === "json") {
       generationConfig.responseMimeType = "application/json";
     }
-    if (resolvedAsset.reasoning?.effort) {
+    if (geminiOptions?.thinking_budget_tokens !== void 0) {
+      body.thinkingConfig = {
+        thinkingBudget: geminiOptions.thinking_budget_tokens
+      };
+    } else if (resolvedAsset.reasoning?.effort) {
       body.thinkingConfig = {
         thinkingBudget: resolvedAsset.reasoning.effort === "high" ? 8192 : resolvedAsset.reasoning.effort === "medium" ? 4096 : 1024
       };
@@ -1180,6 +1620,9 @@ var geminiAdapter = withPromptInputSupport({
     if (Object.keys(generationConfig).length > 0) {
       body.generationConfig = generationConfig;
     }
+    if (geminiCacheConfig?.cached_content) {
+      body.cachedContent = geminiCacheConfig.cached_content;
+    }
     if (resolvedAsset.tools && resolvedAsset.tools.length > 0) {
       const functionDeclarations = resolvedAsset.tools.map((tool) => {
         if (typeof tool === "string") {
@@ -1196,7 +1639,7 @@ var geminiAdapter = withPromptInputSupport({
       body.tools = [{ functionDeclarations }];
     }
     return {
-      body,
+      body: applyRawProviderBody(body, resolvedAsset, "gemini"),
       provider: "gemini",
       model: resolvedAsset.model ?? "unknown"
     };
@@ -1207,13 +1650,45 @@ var geminiAdapter = withPromptInputSupport({
 var openrouterAdapter = withPromptInputSupport({
   name: "openrouter",
   validate(asset, runtime) {
-    return openaiAdapter.validate(asset, runtime);
+    const resolvedAsset = resolveAssetForProvider(asset, runtime);
+    const validation = openaiAdapter.validate(asset, runtime);
+    const hasOpenRouterModels = (resolvedAsset.provider_options?.openrouter?.models?.length ?? 0) > 0;
+    if (!hasOpenRouterModels) {
+      return validation;
+    }
+    const modelRequiredError = "OpenAI adapter requires a model to be specified.";
+    const errors = validation.errors.filter((error) => error !== modelRequiredError);
+    const warnings = validation.warnings.filter((warning) => warning !== modelRequiredError);
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
   },
   render(asset, runtime) {
-    const result = openaiAdapter.render(asset, runtime);
+    const resolvedAsset = resolveAssetForProvider(asset, runtime);
+    const result = openaiAdapter.render(
+      { ...resolvedAsset, raw: void 0 },
+      {
+        variables: runtime.variables,
+        history: runtime.history,
+        toolRegistry: runtime.toolRegistry,
+        strict: runtime.strict
+      }
+    );
+    const openrouterOptions = resolvedAsset.provider_options?.openrouter;
+    let body = { ...result.body };
+    if (openrouterOptions?.provider !== void 0) body.provider = openrouterOptions.provider;
+    if (openrouterOptions?.transforms !== void 0) body.transforms = openrouterOptions.transforms;
+    if (openrouterOptions?.plugins !== void 0) body.plugins = openrouterOptions.plugins;
+    if (openrouterOptions?.models !== void 0) body.models = openrouterOptions.models;
+    if (body.model === void 0) delete body.model;
+    body = applyRawProviderBody(body, resolvedAsset, "openrouter");
     return {
       ...result,
-      provider: "openrouter"
+      body,
+      provider: "openrouter",
+      model: resolvedAsset.model ?? openrouterOptions?.models?.[0] ?? "unknown"
     };
   }
 });
@@ -1221,6 +1696,7 @@ var openrouterAdapter = withPromptInputSupport({
 // src/providers/index.ts
 var adapters = {
   openai: openaiAdapter,
+  "openai-responses": openaiResponsesAdapter,
   anthropic: anthropicAdapter,
   google: geminiAdapter,
   gemini: geminiAdapter,
@@ -1275,8 +1751,22 @@ var KNOWN_FRONT_MATTER_KEYS = /* @__PURE__ */ new Set([
   "includes",
   "environments",
   "tiers",
-  "metadata"
+  "metadata",
+  "cache",
+  "provider_options",
+  "raw"
 ]);
+var RISKY_UNBOUNDED_INPUT_NAMES = [
+  "message",
+  "prompt",
+  "history",
+  "transcript",
+  "document",
+  "content",
+  "input",
+  "body",
+  "context"
+];
 function validateAsset(asset, frontMatterKeys, filePath) {
   const errors = [];
   const warnings = [];
@@ -1347,7 +1837,32 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       });
     }
   }
+  if (usedVars.size > 0 && (!asset.context?.inputs || asset.context.inputs.length === 0)) {
+    warnings.push({
+      code: "POK046",
+      message: `Template uses ${usedVars.size === 1 ? "a variable" : "variables"} but context.inputs is not declared.`,
+      filePath,
+      suggestion: "Declare context.inputs to enable input policy validation."
+    });
+  }
   for (const input of getContextInputs(asset)) {
+    const lowerName = input.name.toLowerCase();
+    if (input.max_size === void 0 && RISKY_UNBOUNDED_INPUT_NAMES.some((needle) => lowerName.includes(needle))) {
+      warnings.push({
+        code: "POK040",
+        message: `Context input "${input.name}" has no max_size and appears unbounded.`,
+        filePath,
+        suggestion: "Add max_size to constrain prompt payload growth."
+      });
+    }
+    if (input.allow_regex === void 0 && input.deny_regex === void 0 && input.non_empty === void 0 && input.reject_secrets === void 0) {
+      warnings.push({
+        code: "POK041",
+        message: `Context input "${input.name}" has no input hardening validators.`,
+        filePath,
+        suggestion: "Consider non_empty/reject_secrets and allow/deny regex validators."
+      });
+    }
     if (input.trim !== void 0 && input.trim !== false && input.max_size === void 0) {
       warnings.push({
         code: "POK014",
@@ -1375,6 +1890,91 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       }
     }
   }
+  if (asset.provider) {
+    let providerCache;
+    let cacheSuggestionField;
+    switch (asset.provider) {
+      case "openai":
+        providerCache = asset.cache?.openai;
+        cacheSuggestionField = "cache.openai";
+        break;
+      case "anthropic":
+        providerCache = asset.cache?.anthropic;
+        cacheSuggestionField = "cache.anthropic";
+        break;
+      case "gemini":
+      case "google":
+        providerCache = asset.cache?.gemini ?? asset.cache?.google;
+        cacheSuggestionField = "cache.gemini";
+        break;
+      default:
+        break;
+    }
+    if (cacheSuggestionField && providerCache === void 0) {
+      warnings.push({
+        code: "POK042",
+        message: `Provider "${asset.provider}" has no provider-specific cache settings.`,
+        filePath,
+        suggestion: `Consider configuring ${cacheSuggestionField} for better cache-hit behavior.`
+      });
+    }
+    if (!asset.model) {
+      warnings.push({
+        code: "POK044",
+        message: `Provider "${asset.provider}" is configured without a model.`,
+        filePath,
+        suggestion: "Set model in prompt or defaults to avoid adapter-time errors."
+      });
+    }
+  }
+  if (asset.cache?.gemini?.cached_content && asset.cache.google?.cached_content && asset.cache.gemini.cached_content !== asset.cache.google.cached_content) {
+    warnings.push({
+      code: "POK043",
+      message: "cache.gemini.cached_content and cache.google.cached_content are both set to different values.",
+      filePath,
+      suggestion: "Use one canonical value; Gemini prefers cache.gemini.cached_content."
+    });
+  }
+  for (const [envName, overrides] of Object.entries(asset.environments ?? {})) {
+    if (asset.cache && (!isRecord(overrides) || !overrides.cache)) {
+      warnings.push({
+        code: "POK045",
+        message: `Environment "${envName}" does not override cache while prompt-level cache is defined.`,
+        filePath,
+        suggestion: "Confirm cache strategy is intentionally shared across environments."
+      });
+    }
+  }
+  for (const [tierName, overrides] of Object.entries(asset.tiers ?? {})) {
+    if (asset.cache && (!isRecord(overrides) || !overrides.cache)) {
+      warnings.push({
+        code: "POK045",
+        message: `Tier "${tierName}" does not override cache while prompt-level cache is defined.`,
+        filePath,
+        suggestion: "Confirm cache strategy is intentionally shared across tiers."
+      });
+    }
+  }
+  for (const tool of asset.tools ?? []) {
+    if (isRecord(tool)) {
+      if (!tool.description) {
+        warnings.push({
+          code: "POK047",
+          message: `Inline tool "${tool.name}" is missing a description.`,
+          filePath,
+          suggestion: "Add description to improve model tool-selection quality."
+        });
+      }
+      if (!tool.input_schema) {
+        warnings.push({
+          code: "POK047",
+          message: `Inline tool "${tool.name}" is missing input_schema.`,
+          filePath,
+          suggestion: "Add input_schema so tool inputs are strongly typed."
+        });
+      }
+    }
+  }
   return {
     valid: errors.length === 0,
     errors,
@@ -1411,6 +2011,9 @@ function findClosestMatch(input, candidates) {
   }
   return best;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 // src/usagetap/client.ts
 var DEFAULT_BASE_URL = "https://api.usagetap.com";
@@ -1849,7 +2452,9 @@ var PromptOpsKit = class {
       throw new Error('Either "path" or "source" must be provided to renderPrompt()');
     }
     const adapter = getAdapter(options.provider);
-    const validation = adapter.validate(resolved);
+    const validation = adapter.validate(resolved, {
+      openaiResponses: options.openaiResponses
+    });
     if (!validation.valid) {
       throw new Error(
         `Provider validation failed for "${options.provider}":
@@ -1879,7 +2484,8 @@ var PromptOpsKit = class {
       variables: sanitization.variables,
       history: options.history,
       toolRegistry: options.toolRegistry,
-      strict: options.strict
+      strict: options.strict,
+      openaiResponses: options.openaiResponses
     });
     return {
       resolved,
@@ -1891,9 +2497,21 @@ var PromptOpsKit = class {
    * Validate a prompt file.
    */
   async validatePrompt(promptPath) {
-    const asset = await this.loadPrompt(promptPath);
     const sourceFile = (0, import_node_path4.resolve)(this.config.sourceDir, promptPath + ".md");
-    return validateAssetWithIncludes(asset, sourceFile);
+    try {
+      const asset = await this.loadPrompt(promptPath);
+      return validateAssetWithIncludes(asset, sourceFile);
+    } catch (error) {
+      const validationError = toPromptValidationError(error, sourceFile);
+      if (validationError) {
+        return {
+          valid: false,
+          errors: [validationError],
+          warnings: []
+        };
+      }
+      throw error;
+    }
   }
   /**
    * Clear the internal cache.
@@ -1905,6 +2523,20 @@ var PromptOpsKit = class {
 function createPromptOpsKit(config = {}) {
   return new PromptOpsKit(config);
 }
+function toPromptValidationError(error, filePath) {
+  if (!(error instanceof Error)) {
+    return void 0;
+  }
+  const match = error.message.match(/^(POK\d+):\s*(.*)$/);
+  if (!match) {
+    return void 0;
+  }
+  return {
+    code: match[1],
+    message: match[2],
+    filePath
+  };
+}
 async function renderPrompt(options) {
   const kit = createPromptOpsKit({
     sourceDir: options.sourceDir ?? DEFAULT_PROMPTS_DIR,
@@ -1936,6 +2568,7 @@ async function renderPrompt(options) {
   interpolate,
   loadPromptFile,
   openaiAdapter,
+  openaiResponsesAdapter,
   openrouterAdapter,
   parsePrompt,
   renderPrompt,