jev-recipes 0.9.2 → 0.9.6

package/README.md

@@ -7,7 +7,7 @@
 [![Node.js version](https://img.shields.io/node/v/jev-recipes)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/agencyenterprise/jev-recipes/blob/main/LICENSE)
 
-[Quickstart](#use-a-recipe) | [Live music app](https://jev-ai-music.com/) | [Coding assistants](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/coding-assistants.md) | [Recipe catalog](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md) | [API vs. SDK vs. recipes](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/api-sdk-recipes.md) | [Agent frameworks](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/framework-adapters.md) | [Contributing](https://github.com/agencyenterprise/jev-recipes/blob/main/CONTRIBUTING.md)
+[Recipe guides at jev-recipes.com](https://jev-recipes.com/) | [Quickstart](#use-a-recipe) | [Live music app](https://jev-ai-music.com/) | [Coding assistants](https://jev-recipes.com/docs/coding-assistants/) | [Recipe catalog](https://jev-recipes.com/recipes/) | [API vs. SDK vs. recipes](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/api-sdk-recipes.md) | [Agent frameworks](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/framework-adapters.md) | [Contributing](https://github.com/agencyenterprise/jev-recipes/blob/main/CONTRIBUTING.md)
 
 <!-- BEGIN GENERATED: summary -->
 
@@ -15,21 +15,35 @@
 
 <!-- END GENERATED: summary -->
 
+## Documentation versions
+
+Run `npm ls jev-recipes` in your project to check the version you installed, then choose its `v<version>` tag from [all release tags](https://github.com/agencyenterprise/jev-recipes/tags) to browse matching documentation.
+
+The hosted catalog and links to `main` can include unreleased changes. See [release notes](https://github.com/agencyenterprise/jev-recipes/releases) for compatibility and migration changes.
+
+## Help and contributions
+
+[Ask a usage question](https://github.com/agencyenterprise/jev-recipes/issues/new?template=usage-question.yml), [report a software bug](https://github.com/agencyenterprise/jev-recipes/issues/new?template=bug-report.yml), [share an unexpected model decision](https://github.com/agencyenterprise/jev-recipes/issues/new?template=model-decision.yml), or [request a recipe](https://github.com/agencyenterprise/jev-recipes/issues/new?template=recipe-request.yml).
+
+For a reproducible software problem, start with the [standalone reproduction example](https://github.com/agencyenterprise/jev-recipes/tree/main/examples/reproduction). Share sanitized inputs and logs, never credentials or private data. To help improve the project, see [your first contribution](https://github.com/agencyenterprise/jev-recipes/blob/main/CONTRIBUTING.md#your-first-contribution).
+
+## How it works
+
 Each recipe accepts your data, calls [Jev through TypeSafe's System One API](https://docs.typesafe.ai/introduction) or an injected compatible client, and returns a structured decision. Use it in a Node.js backend, a script, or a research evaluation. Your application decides what happens next.
 
 ## Start with one decision
 
-| Your task                         | Try without a key                     | Build the workflow                                                                                                                |
-| --------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Route work to the right team      | `npx jev-recipes demo route`          | [Route work](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/getting-started/README.md#route-work)             |
-| Select useful evidence            | `npx jev-recipes demo rerank`         | [Select evidence](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/getting-started/README.md#select-evidence)   |
-| Review an agent's proposed action | `npx jev-recipes demo tool-call-gate` | [Review an action](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/getting-started/README.md#review-an-action) |
+| Your task                         | Recipe guide                                                        | Try without a key                     | Build the workflow                                                                                                                |
+| --------------------------------- | ------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Route work to the right team      | [`route`](https://jev-recipes.com/recipes/route/)                   | `npx jev-recipes demo route`          | [Route work](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/getting-started/README.md#route-work)             |
+| Select useful evidence            | [`rerank`](https://jev-recipes.com/recipes/rerank/)                 | `npx jev-recipes demo rerank`         | [Select evidence](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/getting-started/README.md#select-evidence)   |
+| Review an agent's proposed action | [`tool-call-gate`](https://jev-recipes.com/recipes/tool-call-gate/) | `npx jev-recipes demo tool-call-gate` | [Review an action](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/getting-started/README.md#review-an-action) |
 
 These demos use saved responses. The [runnable workflow examples](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/getting-started/README.md) show ready decisions, uncertainty, and provider failures. Use [TypeSafe directly or Vercel Gateway](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/integrations.md) for live calls.
 
 For example, give `route` a support message and descriptions of your teams. It returns a team such as `billing`, or a review outcome when the choice is uncertain.
 
-Evaluate your own cases with the [installed evaluator](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/evaluation.md), retain model responses, and replay confidence policies offline. The [agent workflow](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/agent-loop/README.md) and [customer queue](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/customer-queue/README.md) show how decisions fit into application code. [Direct and Gateway integrations](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/integrations.md) use the same recipe interface.
+Evaluate your own cases with the [installed evaluator](https://jev-recipes.com/docs/evaluation/), retain model responses, and replay confidence policies offline. The [agent workflow](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/agent-loop/README.md) and [customer queue](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/customer-queue/README.md) show how decisions fit into application code. [Direct and Gateway integrations](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/integrations.md) use the same recipe interface.
 
 ## Watch Jev play checkers against Jev using the checkers-move recipe
 

package/dist/adapters/ai-sdk/index.d.ts

@@ -1,8 +1,8 @@
-import type { LanguageModel, PrepareStepFunction, StopCondition, Tool, ToolSet } from 'ai';
+import type { FlexibleSchema, LanguageModel, PrepareStepFunction, StopCondition, Tool, ToolSet } from 'ai';
 import type { RecipeName } from '../../catalog/schema.js';
 import type { ModelRouteResult } from '../../recipes/model-route/index.js';
 import type { RecipeOptions } from '../../src/schema.js';
-import type { CompletionOptions, CompletionToolOutput, GuardOptions, RecipeToolOptions } from '../shared.js';
+import type { BlockedToolOutput, CompletionOptions, CompletionToolOutput, GuardOptions, RecipeToolOptions } from '../shared.js';
 export type { BlockedToolOutput, CompletionEvent, CompletionOptions, CompletionToolOutput, GuardEvent, GuardOptions, RecipeToolOptions, } from '../shared.js';
 export type RecipeTool = Tool<Record<string, unknown>, Record<string, unknown>>;
 export declare function recipeTool(name: RecipeName, options?: RecipeToolOptions): RecipeTool;
@@ -10,7 +10,20 @@ export declare function recipeTools(names: readonly RecipeName[], options?: Reci
 export type GuardToolsOptions = GuardOptions & {
     request?: string;
 };
-export declare function guardTools<TOOLS extends ToolSet>(tools: TOOLS, options?: GuardToolsOptions): TOOLS;
+type ToolExecution<DEFINITION extends ToolSet[string]> = NonNullable<DEFINITION['execute']>;
+type ToolOutput<RESULT> = RESULT extends AsyncIterable<infer OUTPUT> ? OUTPUT : Awaited<RESULT>;
+type GuardedOutput<DEFINITION extends ToolSet[string]> = ToolOutput<ReturnType<ToolExecution<DEFINITION>>> | BlockedToolOutput;
+type GuardedExecution<DEFINITION extends ToolSet[string]> = {
+    [KEY in keyof Pick<DEFINITION, 'execute'>]: (...args: Parameters<ToolExecution<DEFINITION>>) => AsyncGenerator<GuardedOutput<DEFINITION>>;
+};
+type GuardedTool<DEFINITION extends ToolSet[string]> = DEFINITION extends unknown ? Omit<DEFINITION, 'execute' | 'toModelOutput' | 'outputSchema'> & GuardedExecution<DEFINITION> & {
+    outputSchema?: FlexibleSchema<GuardedOutput<DEFINITION>>;
+    toModelOutput?: NonNullable<Tool<Parameters<ToolExecution<DEFINITION>>[0], GuardedOutput<DEFINITION>>['toModelOutput']>;
+} : never;
+export type GuardedTools<TOOLS extends ToolSet> = {
+    [NAME in keyof TOOLS]: 'execute' extends keyof TOOLS[NAME] ? ToolExecution<TOOLS[NAME]> extends never ? TOOLS[NAME] : GuardedTool<TOOLS[NAME]> : TOOLS[NAME];
+};
+export declare function guardTools<TOOLS extends ToolSet>(tools: TOOLS, options?: GuardToolsOptions): GuardedTools<TOOLS>;
 export type ModelCandidate = {
     id: string;
     text: string;

package/dist/adapters/ai-sdk/index.js

@@ -1,6 +1,8 @@
-import { jsonSchema, tool } from 'ai';
+import { asSchema, jsonSchema, tool } from 'ai';
+import { z } from 'zod';
 import { modelRoute } from '../../recipes/model-route/index.js';
-import { COMPLETION_TOOL_DESCRIPTION, COMPLETION_TOOL_INPUT_SCHEMA, DEFAULT_COMPLETION_TOOL_NAME, blockedOutput, defineRecipeTool, messageText, requireText, reviewCompletion, reviewToolCall, } from '../shared.js';
+import { toolCallGateResultSchema } from '../../recipes/tool-call-gate/index.js';
+import { BLOCKED_TOOL_OUTPUT_KIND, COMPLETION_TOOL_DESCRIPTION, COMPLETION_TOOL_INPUT_SCHEMA, DEFAULT_COMPLETION_TOOL_NAME, blockedOutput, defineRecipeTool, messageText, requireText, reviewCompletion, reviewToolCall, } from '../shared.js';
 export function recipeTool(name, options = {}) {
     const definition = defineRecipeTool(name, options);
     return tool({
@@ -13,27 +15,75 @@ export function recipeTools(names, options = {}) {
     return Object.fromEntries(names.map((name) => [name, recipeTool(name, options)]));
 }
 export function guardTools(tools, options = {}) {
+    return Object.fromEntries(Object.entries(tools).map(([name, definition]) => [name, guardTool(name, definition, options)]));
+}
+function guardTool(toolName, definition, options) {
+    const execute = definition.execute;
+    if (typeof execute !== 'function')
+        return definition;
     const { request, ...guardOptions } = options;
-    const guarded = Object.entries(tools).map(([toolName, definition]) => {
-        if (!('execute' in definition) || typeof definition.execute !== 'function')
-            return [toolName, definition];
-        const execute = definition.execute;
-        const wrapped = {
-            ...definition,
-            execute: async (input, executionOptions) => {
-                const decision = await reviewToolCall({
-                    toolName,
-                    input,
-                    request: request ?? requireText(lastUserText(executionOptions.messages), 'request'),
-                }, guardOptions, executionOptions.abortSignal);
-                if (decision.action !== 'allow')
-                    return blockedOutput(toolName, decision);
-                return execute(input, executionOptions);
-            },
-        };
-        return [toolName, wrapped];
+    const toModelOutput = definition.toModelOutput;
+    return {
+        ...definition,
+        execute: async function* (input, executionOptions) {
+            guardOptions.signal?.throwIfAborted();
+            executionOptions.abortSignal?.throwIfAborted();
+            const decision = await reviewToolCall({
+                toolName,
+                input,
+                request: request ?? requireText(lastUserText(executionOptions.messages), 'request'),
+            }, guardOptions, executionOptions.abortSignal);
+            guardOptions.signal?.throwIfAborted();
+            executionOptions.abortSignal?.throwIfAborted();
+            if (decision.action !== 'allow') {
+                yield blockedOutput(toolName, decision);
+                return;
+            }
+            const output = execute(input, executionOptions);
+            if (isAsyncIterable(output))
+                yield* output;
+            else
+                yield await output;
+        },
+        ...(toModelOutput === undefined
+            ? {}
+            : {
+                toModelOutput: (result) => blockedToolOutputSchema.safeParse(result.output).success
+                    ? { type: 'json', value: result.output }
+                    : toModelOutput(result),
+            }),
+        ...(definition.outputSchema === undefined
+            ? {}
+            : { outputSchema: includeBlockedOutput(definition.outputSchema) }),
+    };
+}
+function isAsyncIterable(value) {
+    return (typeof value?.[Symbol.asyncIterator] ===
+        'function');
+}
+const blockedToolOutputSchema = toolCallGateResultSchema
+    .pick({ verdict: true, status: true, detected: true, confidence: true })
+    .extend({
+    kind: z.literal(BLOCKED_TOOL_OUTPUT_KIND),
+    blocked: z.literal(true),
+    action: z.enum(['ask', 'deny']),
+    message: z.string(),
+});
+function includeBlockedOutput(outputSchema) {
+    const original = asSchema(outputSchema);
+    return jsonSchema(async () => ({
+        anyOf: [
+            { $id: 'urn:jev-recipes:tool-output', ...(await original.jsonSchema) },
+            z.toJSONSchema(blockedToolOutputSchema),
+        ],
+    }), {
+        validate: async (value) => {
+            const blocked = blockedToolOutputSchema.safeParse(value);
+            if (blocked.success)
+                return { success: true, value: blocked.data };
+            return original.validate ? original.validate(value) : { success: true, value };
+        },
     });
-    return Object.fromEntries(guarded);
 }
 export function routeModelStep(options) {
     const { candidates, request, context, minConfidence, fallback, onDecision, ...recipeOptions } = options;

package/dist/adapters/langchain/index.d.ts

@@ -1,11 +1,4 @@
-import type { DynamicStructuredTool } from '@langchain/core/tools';
-export type GuardableTool = {
-    name: string;
-    description: string;
-    schema: unknown;
-    returnDirect?: boolean;
-    invoke(input: any, config?: any): Promise<unknown>;
-};
+import { DynamicStructuredTool } from '@langchain/core/tools';
 import type { RecipeName } from '../../catalog/schema.js';
 import { COMPLETION_TOOL_INPUT_SCHEMA } from '../shared.js';
 import type { CompletionOptions, GuardOptions, RecipeToolOptions } from '../shared.js';
@@ -18,6 +11,13 @@ export type GuardRequest = string | ((input: unknown, config: unknown) => string
 export type GuardToolsOptions = GuardOptions & {
     request: GuardRequest;
 };
+export type GuardableTool = {
+    name: string;
+    description: string;
+    schema: unknown;
+    returnDirect?: boolean;
+    invoke(input: any, config?: any): Promise<unknown>;
+};
 export declare function guardTools(tools: readonly GuardableTool[], options: GuardToolsOptions): DynamicStructuredTool[];
 export declare function completionTool(options: CompletionOptions & {
     task: string;

package/dist/adapters/langchain/index.js

@@ -1,4 +1,5 @@
-import { tool } from '@langchain/core/tools';
+import { DynamicStructuredTool, tool } from '@langchain/core/tools';
+import { ToolMessage } from '@langchain/core/messages';
 import { COMPLETION_TOOL_DESCRIPTION, COMPLETION_TOOL_INPUT_SCHEMA, DEFAULT_COMPLETION_TOOL_NAME, blockedOutput, defineRecipeTool, requireText, reviewCompletion, reviewToolCall, } from '../shared.js';
 export function recipeTool(name, options = {}) {
     const definition = defineRecipeTool(name, options);
@@ -12,26 +13,53 @@ export function recipeTools(names, options = {}) {
     return names.map((name) => recipeTool(name, options));
 }
 export function guardTools(tools, options) {
-    const { request, ...guardOptions } = options;
-    return tools.map((original) => {
-        const schema = original.schema;
-        return tool(async (input, config) => {
-            const decision = await reviewToolCall({
-                toolName: original.name,
-                input,
-                request: typeof request === 'function' ? request(input, config) : request,
-            }, guardOptions, config?.signal);
-            if (decision.action !== 'allow')
-                return blockedOutput(original.name, decision);
-            const { toolCall: _toolCall, ...delegatedConfig } = config ?? {};
-            return original.invoke(input, delegatedConfig);
-        }, {
+    return tools.map((original) => new GuardedTool(original, options));
+}
+class GuardedTool extends DynamicStructuredTool {
+    original;
+    guardOptions;
+    constructor(original, guardOptions) {
+        super({
             name: original.name,
             description: original.description,
-            schema,
-            ...(original.returnDirect === undefined ? {} : { returnDirect: original.returnDirect }),
+            schema: original.schema,
+            returnDirect: original.returnDirect ?? false,
+            func: (input, _runManager, config) => this.invoke(input, config),
         });
-    });
+        this.original = original;
+        this.guardOptions = guardOptions;
+    }
+    async invoke(input, config) {
+        const { request, ...options } = this.guardOptions;
+        const args = isToolCall(input) ? input.args : input;
+        const requestConfig = isToolCall(input) ? { ...config, toolCall: input } : config;
+        options.signal?.throwIfAborted();
+        config?.signal?.throwIfAborted();
+        const decision = await reviewToolCall({
+            toolName: this.name,
+            input: args,
+            request: typeof request === 'function' ? request(args, requestConfig) : request,
+        }, options, config?.signal);
+        options.signal?.throwIfAborted();
+        config?.signal?.throwIfAborted();
+        if (decision.action === 'allow')
+            return this.original.invoke(input, config);
+        const output = blockedOutput(this.name, decision);
+        const toolCallId = requestConfig?.toolCall?.id;
+        return toolCallId === undefined
+            ? output
+            : new ToolMessage({
+                name: this.name,
+                tool_call_id: toolCallId,
+                content: JSON.stringify(output),
+            });
+    }
+    call(input, config, tags) {
+        return this.invoke(input, tags === undefined ? config : { ...config, tags: config?.tags ?? tags });
+    }
+}
+function isToolCall(input) {
+    return (typeof input === 'object' && input !== null && 'type' in input && input.type === 'tool_call');
 }
 export function completionTool(options) {
     return tool((input, config) => reviewCompletion({ task: requireText(options.task, 'task'), report: input.report, evidence: input.evidence }, options, config?.signal), {

package/dist/adapters/shared.d.ts

@@ -22,7 +22,9 @@ export type GuardEvent = {
     input: unknown;
     decision: ToolCallGateResult;
 };
+export declare const BLOCKED_TOOL_OUTPUT_KIND = "jev-recipes/blocked-tool-output";
 export type BlockedToolOutput = {
+    kind: typeof BLOCKED_TOOL_OUTPUT_KIND;
     blocked: true;
     action: 'ask' | 'deny';
     verdict: ToolCallGateResult['verdict'];

package/dist/adapters/shared.js

@@ -2,6 +2,7 @@ import { describeRecipe } from '../catalog/index.js';
 import { loadRecipe } from '../catalog/runner.js';
 import { completionGate } from '../recipes/completion-gate/index.js';
 import { toolCallGate } from '../recipes/tool-call-gate/index.js';
+export const BLOCKED_TOOL_OUTPUT_KIND = 'jev-recipes/blocked-tool-output';
 export const DEFAULT_COMPLETION_TOOL_NAME = 'report_completion';
 export const COMPLETION_TOOL_DESCRIPTION = 'Report that the task is complete. State what was done in report, and put the evidence that demonstrates it, such as test output, command results, or observed behavior, in evidence. A claim without evidence is not accepted.';
 export const COMPLETION_TOOL_INPUT_SCHEMA = {
@@ -54,6 +55,7 @@ export function blockedOutput(toolName, decision) {
         ? `The call to ${toolName} was refused by policy and did not run.${risks} Do not retry it. Explain what you intended and continue with permitted work.`
         : `The call to ${toolName} did not run because a person must confirm it first.${risks} Do not retry it unattended. Explain what you intended and continue with other permitted work.`;
     return {
+        kind: BLOCKED_TOOL_OUTPUT_KIND,
         blocked: true,
         action,
         verdict: decision.verdict,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-recipes",
-  "version": "0.9.2",
+  "version": "0.9.6",
   "description": "248 small Jev decisions for JavaScript and TypeScript: route, rerank, gate, grade, compare, and label text for agents, RAG, support, code review, and music. Each returns a typed result with explicit uncertainty. Plug into Vercel AI SDK or LangChain agents, import one recipe, or run the CLI with JSON from any language.",
   "type": "module",
   "license": "MIT",
@@ -1068,6 +1068,8 @@
     "jev-recipes": "node --env-file-if-exists=.env dist/cli/index.js",
     "ci": "node scripts/ci.mjs",
     "pack:check": "node scripts/pack-check.mjs",
+    "check:consumer": "node scripts/check-consumer.mjs",
+    "check:reproduction": "node scripts/check-reproduction.mjs",
     "prepack": "npm run generate:check && npm run build",
     "prepublishOnly": "npm run ci",
     "test": "npm run test:recipes && npm run test:tooling",
@@ -1084,8 +1086,8 @@
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "ai": ">=7.0.0",
-    "@langchain/core": ">=1.0.0"
+    "@langchain/core": ">=1.0.0",
+    "ai": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "ai": {
@@ -1100,6 +1102,7 @@
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "4.1.11",
     "ai": "^7.0.122",
+    "marked": "^18.0.14",
     "prettier": "3.9.8",
     "rimraf": "6.1.3",
     "typescript": "~5.9.3",