promptopskit 0.3.9 → 0.4.2

package/dist/index.cjs

@@ -145,6 +145,29 @@ 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,
@@ -156,11 +179,19 @@ function mergeOverride(base, override) {
       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 = {}) {
@@ -264,23 +295,42 @@ var ResponseSchema = import_zod.z.object({
   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()
+  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()
+  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(),
@@ -353,6 +403,7 @@ var PromptAssetOverridesSchema = import_zod.z.object({
   sampling: SamplingSchema.optional(),
   response: ResponseSchema.optional(),
   cache: CacheSchema.optional(),
+  raw: RawProviderBodySchema.optional(),
   tools: import_zod.z.array(ToolRefSchema).optional(),
   provider_options: ProviderOptionsSchema.optional()
 });
@@ -385,6 +436,7 @@ var PromptAssetSchema = import_zod.z.object({
   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(),
@@ -398,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",
@@ -438,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 = {
@@ -515,6 +685,7 @@ function mergeDefaults(base, local) {
   return {
     provider: local.provider ?? base.provider,
     model: local.model ?? base.model,
+    cache: mergeCache(base.cache, local.cache),
     metadata: {
       ...base.metadata ?? {},
       ...local.metadata ?? {}
@@ -526,10 +697,12 @@ function mergeDefaults(base, local) {
   };
 }
 function applyDefaults(asset, defaults) {
+  const cache = mergeCache(defaults.cache, asset.cache);
   const hasDefaultMetadata = defaults.metadata && Object.keys(defaults.metadata).length > 0;
   const hasDefaultSystem = !!defaults.sections?.system_instructions;
   const hasDefaultScalars = defaults.provider !== void 0 || defaults.model !== void 0;
-  if (!hasDefaultMetadata && !hasDefaultSystem && !hasDefaultScalars) {
+  const hasDefaultCache = cache !== void 0;
+  if (!hasDefaultMetadata && !hasDefaultSystem && !hasDefaultScalars && !hasDefaultCache) {
     return asset;
   }
   const mergedMetadata = {
@@ -543,10 +716,38 @@ function applyDefaults(asset, defaults) {
     ...asset,
     provider: asset.provider ?? defaults.provider,
     model: asset.model ?? defaults.model,
+    cache,
     metadata,
     sections
   };
 }
+function mergeCache(base, local) {
+  const merged = {
+    ...base ?? {},
+    ...local ?? {},
+    openai: {
+      ...base?.openai ?? {},
+      ...local?.openai ?? {}
+    },
+    anthropic: {
+      ...base?.anthropic ?? {},
+      ...local?.anthropic ?? {}
+    },
+    gemini: {
+      ...base?.gemini ?? {},
+      ...local?.gemini ?? {}
+    },
+    google: {
+      ...base?.google ?? {},
+      ...local?.google ?? {}
+    }
+  };
+  if (merged.openai && Object.keys(merged.openai).length === 0) delete merged.openai;
+  if (merged.anthropic && Object.keys(merged.anthropic).length === 0) delete merged.anthropic;
+  if (merged.gemini && Object.keys(merged.gemini).length === 0) delete merged.gemini;
+  if (merged.google && Object.keys(merged.google).length === 0) delete merged.google;
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
 
 // src/composition/resolve-includes.ts
 async function resolveIncludes(asset, basePath, visited = /* @__PURE__ */ new Set()) {
@@ -1018,6 +1219,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",
@@ -1073,6 +1289,7 @@ var openaiAdapter = withPromptInputSupport({
         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
         }
@@ -1107,7 +1324,7 @@ var openaiAdapter = withPromptInputSupport({
       });
     }
     return {
-      body,
+      body: applyRawProviderBody(body, resolvedAsset, "openai"),
       provider: "openai",
       model: resolvedAsset.model ?? "unknown"
     };
@@ -1174,6 +1391,7 @@ var openaiResponsesAdapter = withPromptInputSupport({
         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
         }
@@ -1208,7 +1426,7 @@ var openaiResponsesAdapter = withPromptInputSupport({
     if (responseOptions?.include !== void 0) body.include = responseOptions.include;
     if (responseOptions?.background !== void 0) body.background = responseOptions.background;
     return {
-      body,
+      body: applyRawProviderBody(body, resolvedAsset, "openai-responses"),
       provider: "openai-responses",
       model: resolvedAsset.model ?? "unknown"
     };
@@ -1234,8 +1452,8 @@ 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) {
-      warnings.push("Anthropic does not support response.schema structured output in this adapter. It will be ignored.");
+    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.");
@@ -1299,6 +1517,16 @@ var anthropicAdapter = withPromptInputSupport({
     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;
     }
@@ -1332,7 +1560,7 @@ var anthropicAdapter = withPromptInputSupport({
       body.tool_choice = resolvedAsset.provider_options.anthropic.tool_choice;
     }
     return {
-      body,
+      body: applyRawProviderBody(body, resolvedAsset, "anthropic"),
       provider: "anthropic",
       model: resolvedAsset.model ?? "unknown"
     };
@@ -1404,9 +1632,10 @@ var geminiAdapter = withPromptInputSupport({
     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_schema !== void 0) generationConfig.responseSchema = geminiOptions.response_schema;
     if (geminiOptions?.response_modalities !== void 0) generationConfig.responseModalities = geminiOptions.response_modalities;
-    if (resolvedAsset.response?.schema !== void 0) generationConfig.responseSchema = resolvedAsset.response.schema;
+    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";
     }
@@ -1441,7 +1670,7 @@ var geminiAdapter = withPromptInputSupport({
       body.tools = [{ functionDeclarations }];
     }
     return {
-      body,
+      body: applyRawProviderBody(body, resolvedAsset, "gemini"),
       provider: "gemini",
       model: resolvedAsset.model ?? "unknown"
     };
@@ -1452,13 +1681,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"
     };
   }
 });
@@ -1522,8 +1783,21 @@ var KNOWN_FRONT_MATTER_KEYS = /* @__PURE__ */ new Set([
   "environments",
   "tiers",
   "metadata",
-  "cache"
+  "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 = [];
@@ -1594,7 +1868,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",
@@ -1622,6 +1921,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,
@@ -1658,6 +2042,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";
@@ -2141,9 +2528,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.
@@ -2155,6 +2554,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,