ENHANCEMENT: When runtime context failed an allow_regex, deny_regex or the built-in validators you can optionally use the return_message argument for the input to send a message in addition to raising an exception (current behavior, and default)

Author: PredictabilityAtScale

README.md

@@ -64,7 +64,8 @@ sampling:
 context:
   inputs:
     - name: user_message
-      non_empty: true
+      non_empty:
+        return_message: "Please enter a message before continuing."
       reject_secrets: true
     - name: app_context
       max_size: 2000
@@ -100,6 +101,10 @@ const result = await kit.renderPrompt({
   },
 });
 
+if (result.returnMessage) {
+  return result.returnMessage;
+}
+
 // result.request.body is ready for fetch()
 const response = await fetch('https://api.openai.com/v1/chat/completions', {
   method: 'POST',
@@ -133,6 +138,7 @@ Supported values for `warnings.contextSize` are `auto`, `off`, `result-only`, `c
 - **4 provider adapters** — OpenAI, Anthropic, Gemini, OpenRouter — body-only output
 - **Validation** — Zod schema validation, Levenshtein-based "did you mean?" for typos, variable usage checks
 - **Context hardening** — structured regexes with flags, `/pattern/i` convenience syntax, and built-in `non_empty` / `reject_secrets` validators
+- **Optional short-circuit messages** — validators can return a structured `returnMessage` instead of throwing when configured
 - **Context size guardrails** — optional per-input `max_size` metadata with non-blocking render-time warnings
 - **Warning controls** — top-level config can suppress or emit context size warnings differently in dev and prod
 - **Caching** — LRU cache with mtime-based invalidation
@@ -147,35 +153,40 @@ Each adapter produces a `{ body, provider, model }` object shaped for the target
 // OpenAI
 import { createPromptOpsKit } from 'promptopskit';
 const kit = createPromptOpsKit();
-const { request } = await kit.renderPrompt({
+let result = await kit.renderPrompt({
   path: 'hello',
   provider: 'openai',
   variables: { name: 'World', app_context: 'Welcome screen' },
 });
+if (!result.request) throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+const { request } = result;
 // request.body → { model, messages, temperature, reasoning_effort, ... }
 
 // Anthropic — system is a top-level field, max_tokens defaults to 4096
-const { request } = await kit.renderPrompt({
+result = await kit.renderPrompt({
   path: 'hello',
   provider: 'anthropic',
   variables: { name: 'World', app_context: 'Welcome screen' },
 });
+if (!result.request) throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
 // request.body → { model, messages, system, max_tokens, ... }
 
 // Gemini — contents/systemInstruction/generationConfig structure
-const { request } = await kit.renderPrompt({
+result = await kit.renderPrompt({
   path: 'hello',
   provider: 'gemini',
   variables: { name: 'World', app_context: 'Welcome screen' },
 });
+if (!result.request) throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
 // request.body → { contents, systemInstruction, generationConfig, ... }
 
 // OpenRouter — same shape as OpenAI, different provider label
-const { request } = await kit.renderPrompt({
+result = await kit.renderPrompt({
   path: 'hello',
   provider: 'openrouter',
   variables: { name: 'World', app_context: 'Welcome screen' },
 });
+if (!result.request) throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
 ```
 
 Provider adapters are also available as direct imports:
@@ -217,7 +228,7 @@ On the server, adapters also provide async prompt-aware helpers so you can use t
 ```typescript
 import { openaiAdapter } from 'promptopskit/openai';
 
-const request = await openaiAdapter.renderPrompt(
+const result = await openaiAdapter.renderPrompt(
   {
     path: 'summarizePullRequest',
   },
@@ -229,6 +240,12 @@ const request = await openaiAdapter.renderPrompt(
     strict: true,
   },
 );
+
+if (!('body' in result)) {
+  throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+}
+
+const request = result;
 ```
 
 If you need a different layout, keep passing `sourceDir` and `compiledDir` explicitly.
@@ -246,7 +263,7 @@ import { createUsageTapClient, runOpenAIWithUsageTap } from 'promptopskit/usaget
 const kit = createPromptOpsKit({ sourceDir: './prompts' });
 const usageTap = createUsageTapClient({ apiKey: process.env.USAGETAP_API_KEY! });
 
-const { request } = await kit.renderPrompt({
+const result = await kit.renderPrompt({
   path: 'support/reply',
   provider: 'openai',
   variables: {
@@ -255,6 +272,12 @@ const { request } = await kit.renderPrompt({
   },
 });
 
+if (!result.request) {
+  throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+}
+
+const { request } = result;
+
 const tracked = await runOpenAIWithUsageTap(usageTap, {
   begin: {
     customerId: 'user_123',
@@ -472,7 +495,7 @@ Creates a `PromptOpsKit` instance.
 
 ### `kit.renderPrompt(options)`
 
-Renders a prompt for a specific provider. Returns `{ resolved, request, warnings }`.
+Renders a prompt for a specific provider. Returns `{ resolved, request?, returnMessage?, warnings }`.
 
 | Option | Type | Description |
 |--------|------|-------------|

SKILL.md

@@ -104,6 +104,7 @@ Rules:
 - Use `allow_regex` for allowlist checks and `deny_regex` for blocklist checks on risky inputs
 - Prefer structured regexes like `{ pattern, flags }`; `/pattern/i` strings are also accepted and normalized internally
 - Use `non_empty: true` for required user text and `reject_secrets: true` for common secret redaction checks
+- When the caller should receive a structured fallback message instead of an exception, use object form with `return_message` on `allow_regex`, `deny_regex`, `non_empty`, or `reject_secrets`
 - Escape literal braces with `\{{` and `\}}`
 - In strict mode, missing variables throw an error
 - In permissive mode, unresolved placeholders are left intact
@@ -121,6 +122,8 @@ context:
 If a rendered value exceeds `max_size`, `renderPrompt()` emits a non-blocking `POK030` warning.
 At render time, callers can also pass `onContextOverflow` to transform oversized values before warnings/rendering.
 
+If a validator declares `return_message`, `renderPrompt()` returns that message in a structured result and omits the provider request instead of throwing for that validation failure. Invalid regex definitions still fail during `validate` and `compile` as `POK013` prompt-authoring errors.
+
 Malformed `allow_regex` and `deny_regex` values fail during `validate` and `compile`, not just at render time. When regex compilation fails, the error includes the prompt id, variable name, field name, and raw configured value.
 
 Example: this is the minimal valid shape for a prompt that references
@@ -271,7 +274,7 @@ const kit = createPromptOpsKit({
   },
 });
 
-const { request } = await kit.renderPrompt({
+const result = await kit.renderPrompt({
   path: 'support/reply',
   provider: 'openai',
   environment: 'production',
@@ -280,6 +283,16 @@ const { request } = await kit.renderPrompt({
     app_context: 'Account settings',
   },
 });
+
+if (result.returnMessage) {
+  return result.returnMessage;
+}
+
+if (!result.request) {
+  throw new Error('Prompt rendering did not produce a provider request.');
+}
+
+const { request } = result;
 ```
 
 ### Use `adapter.renderPrompt()` when:
@@ -292,7 +305,7 @@ const { request } = await kit.renderPrompt({
 import path from 'node:path';
 import { openaiAdapter } from 'promptopskit/openai';
 
-const request = await openaiAdapter.renderPrompt(
+const result = await openaiAdapter.renderPrompt(
   {
     path: 'support/reply',
     sourceDir: path.join(process.cwd(), 'prompts'),
@@ -307,6 +320,16 @@ const request = await openaiAdapter.renderPrompt(
     strict: true,
   },
 );
+
+if (result.returnMessage) {
+  return result.returnMessage;
+}
+
+if (!('body' in result)) {
+  throw new Error('Prompt rendering did not produce a provider request.');
+}
+
+const request = result;
 ```
 
 ### Use `adapter.render()` when:
@@ -438,7 +461,7 @@ Hello {{ name }}
 | Command | Description |
 |---------|-------------|
 | `promptopskit init [dir]` | Scaffold a prompts directory with starter files (including `defaults.md`) |
-| `promptopskit validate <dir>` | Validate all prompt files in a directory |
+| `promptopskit validate [sourceDir] [options]` | Validate all prompt files in a directory, defaulting to `./prompts` |
 | `promptopskit compile [src] [out]` | Compile `.md` prompts to JSON or ESM artifacts |
 | `promptopskit render <file>` | Render a prompt preview |
 | `promptopskit inspect <file>` | Print the normalized prompt asset |

docs/api-reference.md

@@ -42,7 +42,7 @@ const kit = createPromptOpsKit({
 
 ## `kit.renderPrompt(options)`
 
-Renders a prompt for a specific provider. Returns `{ resolved, request, warnings }`.
+Renders a prompt for a specific provider. Returns `{ resolved, request?, returnMessage?, warnings }`.
 
 ```typescript
 const result = await kit.renderPrompt({
@@ -79,13 +79,16 @@ Either `path` or `source` must be provided.
 ```typescript
 interface RenderResult {
   resolved: ResolvedPromptAsset;  // Fully resolved asset
-  request: ProviderRequest;       // { body, provider, model }
+  request?: ProviderRequest;      // { body, provider, model } when rendering continues
+  returnMessage?: string;         // Short-circuit message from context validation when configured
   warnings: string[];             // Non-fatal provider and render-time warnings
 }
 ```
 
 `warnings` may include provider adapter warnings and render-time `POK030` context size warnings when configured to be included in results.
 
+If a context validator fails and that validator declares `return_message`, `renderPrompt()` returns `returnMessage` and omits `request` instead of throwing.
+
 ## `kit.loadPrompt(path)`
 
 Load a prompt asset from compiled or source (based on mode). Returns a `PromptAsset`.

docs/getting-started.md

@@ -79,6 +79,10 @@ const result = await kit.renderPrompt({
   },
 });
 
+if (!result.request) {
+  return result.returnMessage;
+}
+
 // result.request.body is ready for fetch()
 const response = await fetch('https://api.openai.com/v1/chat/completions', {
   method: 'POST',

docs/inline-source.md

@@ -25,6 +25,10 @@ Hello {{ name }}!`,
   provider: 'openai',
   variables: { name: 'World' },
 });
+
+if (!result.request) {
+  throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+}
 ```
 
 ## With overrides
@@ -51,6 +55,10 @@ Hello {{ name }}!`,
   variables: { name: 'World' },
 });
 
+if (!result.request) {
+  throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+}
+
 // result.request.body.model === 'gpt-5.4-mini'
 ```
 
@@ -73,6 +81,10 @@ schema_version: 1
   provider: 'openai',
   variables: { question: 'What is 2+2?' },
 });
+
+if (!result.request) {
+  throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+}
 ```
 
 ## Limitations

docs/prompt-format.md

@@ -169,10 +169,10 @@ Each entry can be either a string variable name or an object with:
 - `name` — the template variable name
 - `max_size` — optional UTF-8 byte limit for the injected value
 - `trim` — optional trim-to-budget (`true`/`end` keeps first bytes, `start` keeps trailing bytes) applied when `max_size` is set
-- `allow_regex` — optional allowlist regex; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags }` and throws `POK031` on mismatch
-- `deny_regex` — optional blocklist regex; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags }` and throws `POK032` on match
-- `non_empty` — optional boolean validator; throws `POK033` when the final value is blank or whitespace-only
-- `reject_secrets` — optional boolean validator; throws `POK034` when the value matches the built-in secret detector
+- `allow_regex` — optional allowlist regex; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags, return_message? }` and throws `POK031` on mismatch unless `return_message` is configured
+- `deny_regex` — optional blocklist regex; accepts `"pattern"`, `/pattern/i`, or `{ pattern, flags, return_message? }` and throws `POK032` on match unless `return_message` is configured
+- `non_empty` — optional boolean or object validator; use `true` to throw `POK033`, or `{ return_message }` to short-circuit rendering with a structured message
+- `reject_secrets` — optional boolean or object validator; use `true` to throw `POK034`, or `{ return_message }` to short-circuit rendering with a structured message
 
 The validator warns about:
 - Variables used in templates but not declared in `context.inputs`
@@ -193,8 +193,10 @@ context:
       allow_regex:
         pattern: "^user_[a-z0-9]+$"
         flags: "i"
+        return_message: "User IDs must use the user_123 format."
     - name: pull_request_body
-      non_empty: true
+      non_empty:
+        return_message: "Pull request content is required."
       reject_secrets: true
       deny_regex: "/(ignore previous instructions|system:)/i"
 ```