jev-recipes 0.8.5 → 0.9.0

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) | [Contributing](https://github.com/agencyenterprise/jev-recipes/blob/main/CONTRIBUTING.md)
+[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)
 
 <!-- BEGIN GENERATED: summary -->
 
@@ -243,6 +243,26 @@ console.log(`${result.requestsMade} calls for ${result.requestCount} tickets`);
 
 Accuracy can drop as batches grow. Measure on your own labeled data and tune `batchSize`; the [eval harness](https://github.com/agencyenterprise/jev-recipes/blob/main/CONTRIBUTING.md#model-evaluation) reports calibration per threshold.
 
+## Use inside an agent framework
+
+`jev-recipes/ai-sdk` and `jev-recipes/langchain` plug the harness recipes into the loop you already run. With the Vercel AI SDK, `guardTools` reviews every tool call with `tool-call-gate`, `routeModelStep` picks the model per call with `model-route`, and `completionCheck` accepts a completion claim only when `completion-gate` sees evidence:
+
+```js
+import { generateText, stepCountIs } from 'ai';
+import { completionCheck, guardTools, routeModelStep } from 'jev-recipes/ai-sdk';
+
+const done = completionCheck();
+const result = await generateText({
+  model: careful,
+  prompt: 'Run the account tests and publish release 1.2.0.',
+  tools: { ...guardTools(tools, { policy: 'Ask before publishing.' }), ...done.tools },
+  prepareStep: routeModelStep({ candidates: [{ id: 'fast', text: 'Small edits.', model: fast }] }),
+  stopWhen: [stepCountIs(8), done.stopWhen],
+});
+```
+
+Any recipe becomes a tool with `recipeTools(['route', 'verify'])`. The LangChain adapter offers the same guard, completion, and recipe tools for `bindTools`, `ToolNode`, and `createAgent`. Install `ai` or `@langchain/core` yourself; both are optional peers. See the [framework adapter guide](https://github.com/agencyenterprise/jev-recipes/blob/main/docs/framework-adapters.md) and the offline [AI SDK](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/ai-sdk-agent/README.md) and [LangChain](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/langchain-tools/README.md) examples.
+
 ## Use a local or alternative decision model
 
 Recipes talk to any server that implements the TypeSafe `systemOne` wire format. Point the SDK client at it with `baseURL`, or set `TYPESAFE_BASE_URL` in the environment, and pass the client to any recipe:

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

@@ -0,0 +1,38 @@
+import type { 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';
+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;
+export declare function recipeTools(names: readonly RecipeName[], options?: RecipeToolOptions): Record<string, RecipeTool>;
+export type GuardToolsOptions = GuardOptions & {
+    request?: string;
+};
+export declare function guardTools<TOOLS extends ToolSet>(tools: TOOLS, options?: GuardToolsOptions): TOOLS;
+export type ModelCandidate = {
+    id: string;
+    text: string;
+    model: LanguageModel;
+};
+export type RouteModelStepOptions = RecipeOptions & {
+    candidates: readonly ModelCandidate[];
+    request?: string;
+    context?: string;
+    minConfidence?: number;
+    fallback?: LanguageModel;
+    onDecision?: (event: {
+        decision: ModelRouteResult;
+        model: LanguageModel | undefined;
+    }) => void;
+};
+export declare function routeModelStep(options: RouteModelStepOptions): PrepareStepFunction<any, any>;
+export type CompletionCheck = {
+    tools: Record<string, Tool<{
+        report: string;
+        evidence?: string;
+    }, CompletionToolOutput>>;
+    stopWhen: StopCondition<any, any>;
+};
+export declare function completionCheck(options?: CompletionOptions): CompletionCheck;

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

@@ -0,0 +1,88 @@
+import { jsonSchema, tool } from 'ai';
+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';
+export function recipeTool(name, options = {}) {
+    const definition = defineRecipeTool(name, options);
+    return tool({
+        description: definition.description,
+        inputSchema: jsonSchema(definition.inputSchema),
+        execute: async (input, executionOptions) => definition.execute(input, executionOptions.abortSignal),
+    });
+}
+export function recipeTools(names, options = {}) {
+    return Object.fromEntries(names.map((name) => [name, recipeTool(name, options)]));
+}
+export function guardTools(tools, options = {}) {
+    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];
+    });
+    return Object.fromEntries(guarded);
+}
+export function routeModelStep(options) {
+    const { candidates, request, context, minConfidence, fallback, onDecision, ...recipeOptions } = options;
+    if (!candidates.length)
+        throw new Error('Supply at least one model candidate.');
+    const decisions = new WeakMap();
+    return async ({ initialMessages }) => {
+        if (!decisions.has(initialMessages)) {
+            const decision = await modelRoute({
+                request: request ?? requireText(firstUserText(initialMessages), 'request'),
+                models: candidates.map(({ id, text }) => ({ id, text })),
+                ...(context === undefined ? {} : { context }),
+                ...(minConfidence === undefined ? {} : { minConfidence }),
+            }, recipeOptions);
+            const selected = decision.status === 'ready' && decision.selection !== null
+                ? candidates.find((candidate) => candidate.id === decision.selection)?.model
+                : fallback;
+            onDecision?.({ decision, model: selected });
+            decisions.set(initialMessages, selected);
+        }
+        const model = decisions.get(initialMessages);
+        return model === undefined ? {} : { model };
+    };
+}
+export function completionCheck(options = {}) {
+    const toolName = options.toolName ?? DEFAULT_COMPLETION_TOOL_NAME;
+    const report = tool({
+        description: COMPLETION_TOOL_DESCRIPTION,
+        inputSchema: jsonSchema(COMPLETION_TOOL_INPUT_SCHEMA),
+        execute: async (input, executionOptions) => reviewCompletion({
+            task: options.task ?? requireText(firstUserText(executionOptions.messages), 'task'),
+            report: input.report,
+            evidence: input.evidence,
+        }, options, executionOptions.abortSignal),
+    });
+    return {
+        tools: { [toolName]: report },
+        stopWhen: ({ steps }) => {
+            const last = steps.at(-1);
+            return (last?.toolResults.some((result) => result.toolName === toolName &&
+                typeof result.output === 'object' &&
+                result.output !== null &&
+                result.output.accepted === true) ?? false);
+        },
+    };
+}
+function lastUserText(messages) {
+    return messageText(messages, 'user', 'last');
+}
+function firstUserText(messages) {
+    return messageText(messages, 'user', 'first');
+}

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

@@ -0,0 +1,24 @@
+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 type { RecipeName } from '../../catalog/schema.js';
+import { COMPLETION_TOOL_INPUT_SCHEMA } from '../shared.js';
+import type { CompletionOptions, GuardOptions, RecipeToolOptions } from '../shared.js';
+export type { BlockedToolOutput, CompletionEvent, CompletionOptions, CompletionToolOutput, GuardEvent, GuardOptions, RecipeToolOptions, } from '../shared.js';
+type JsonSchema = Record<string, unknown>;
+export type RecipeTool = DynamicStructuredTool<JsonSchema>;
+export declare function recipeTool(name: RecipeName, options?: RecipeToolOptions): RecipeTool;
+export declare function recipeTools(names: readonly RecipeName[], options?: RecipeToolOptions): RecipeTool[];
+export type GuardRequest = string | ((input: unknown, config: unknown) => string);
+export type GuardToolsOptions = GuardOptions & {
+    request: GuardRequest;
+};
+export declare function guardTools(tools: readonly GuardableTool[], options: GuardToolsOptions): DynamicStructuredTool[];
+export declare function completionTool(options: CompletionOptions & {
+    task: string;
+}): DynamicStructuredTool<typeof COMPLETION_TOOL_INPUT_SCHEMA>;

package/dist/adapters/langchain/index.js

@@ -0,0 +1,42 @@
+import { tool } from '@langchain/core/tools';
+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);
+    return tool((input, config) => definition.execute(input, config?.signal), {
+        name: definition.name,
+        description: definition.description,
+        schema: definition.inputSchema,
+    });
+}
+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);
+        }, {
+            name: original.name,
+            description: original.description,
+            schema,
+            ...(original.returnDirect === undefined ? {} : { returnDirect: original.returnDirect }),
+        });
+    });
+}
+export function completionTool(options) {
+    return tool((input, config) => reviewCompletion({ task: requireText(options.task, 'task'), report: input.report, evidence: input.evidence }, options, config?.signal), {
+        name: options.toolName ?? DEFAULT_COMPLETION_TOOL_NAME,
+        description: COMPLETION_TOOL_DESCRIPTION,
+        schema: COMPLETION_TOOL_INPUT_SCHEMA,
+    });
+}

package/dist/adapters/shared.d.ts

@@ -0,0 +1,88 @@
+import type { RecipeName } from '../catalog/schema.js';
+import type { CompletionGateResult } from '../recipes/completion-gate/index.js';
+import type { ToolCallGateResult } from '../recipes/tool-call-gate/index.js';
+import type { RecipeOptions } from '../src/schema.js';
+export type RecipeToolOptions = RecipeOptions & {
+    description?: string;
+};
+export type RecipeToolDefinition = {
+    name: RecipeName;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (input: unknown, signal?: AbortSignal) => Promise<Record<string, unknown>>;
+};
+export type GuardOptions = RecipeOptions & {
+    policy?: string;
+    context?: string;
+    minConfidence?: number;
+    onDecision?: (event: GuardEvent) => void;
+};
+export type GuardEvent = {
+    toolName: string;
+    input: unknown;
+    decision: ToolCallGateResult;
+};
+export type BlockedToolOutput = {
+    blocked: true;
+    action: 'ask' | 'deny';
+    verdict: ToolCallGateResult['verdict'];
+    status: ToolCallGateResult['status'];
+    detected: ToolCallGateResult['detected'];
+    confidence: number;
+    message: string;
+};
+export type CompletionOptions = RecipeOptions & {
+    task?: string;
+    evidence?: string;
+    toolName?: string;
+    minConfidence?: number;
+    onDecision?: (event: CompletionEvent) => void;
+};
+export type CompletionEvent = {
+    report: string;
+    evidence: string | undefined;
+    decision: CompletionGateResult;
+};
+export type CompletionToolOutput = {
+    accepted: boolean;
+    verdict: CompletionGateResult['verdict'];
+    status: CompletionGateResult['status'];
+    detected: CompletionGateResult['detected'];
+    confidence: number;
+    message: string;
+};
+export declare const DEFAULT_COMPLETION_TOOL_NAME = "report_completion";
+export declare 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 declare const COMPLETION_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly report: {
+            readonly type: "string";
+            readonly description: "What was done and how the task was completed.";
+        };
+        readonly evidence: {
+            readonly type: "string";
+            readonly description: "Concrete evidence that demonstrates completion, such as test output.";
+        };
+    };
+    readonly required: readonly ["report"];
+    readonly additionalProperties: false;
+};
+export declare function defineRecipeTool(name: RecipeName, options?: RecipeToolOptions): RecipeToolDefinition;
+export declare function renderToolCall(toolName: string, input: unknown): string;
+export declare function reviewToolCall(call: {
+    toolName: string;
+    input: unknown;
+    request: string;
+}, options: GuardOptions, signal?: AbortSignal): Promise<ToolCallGateResult>;
+export declare function blockedOutput(toolName: string, decision: ToolCallGateResult): BlockedToolOutput;
+export declare function reviewCompletion(claim: {
+    task: string;
+    report: string;
+    evidence: string | undefined;
+}, options: CompletionOptions, signal?: AbortSignal): Promise<CompletionToolOutput>;
+export declare function messageText(messages: readonly {
+    role: string;
+    content: unknown;
+}[], role: 'user' | 'assistant', position: 'first' | 'last'): string | undefined;
+export declare function requireText(value: string | undefined, description: string): string;

package/dist/adapters/shared.js

@@ -0,0 +1,132 @@
+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 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 = {
+    type: 'object',
+    properties: {
+        report: { type: 'string', description: 'What was done and how the task was completed.' },
+        evidence: {
+            type: 'string',
+            description: 'Concrete evidence that demonstrates completion, such as test output.',
+        },
+    },
+    required: ['report'],
+    additionalProperties: false,
+};
+export function defineRecipeTool(name, options = {}) {
+    const { description, ...recipeOptions } = options;
+    const recipe = describeRecipe(name);
+    const summary = description ??
+        (recipe.useWhen ? `${recipe.description} Use when: ${recipe.useWhen}` : recipe.description);
+    return {
+        name: recipe.id,
+        description: summary,
+        inputSchema: recipe.inputSchema,
+        execute: async (input, signal) => {
+            const run = await loadRecipe(name);
+            const result = await run(input, withSignal(recipeOptions, signal));
+            return result;
+        },
+    };
+}
+export function renderToolCall(toolName, input) {
+    return input === undefined ? `${toolName}()` : `${toolName}(${JSON.stringify(input)})`;
+}
+export async function reviewToolCall(call, options, signal) {
+    const { policy, context, minConfidence, onDecision, ...recipeOptions } = options;
+    const decision = await toolCallGate({
+        request: call.request,
+        toolCall: renderToolCall(call.toolName, call.input),
+        ...(context === undefined ? {} : { context }),
+        ...(policy === undefined ? {} : { policy }),
+        ...(minConfidence === undefined ? {} : { minConfidence }),
+    }, withSignal(recipeOptions, signal));
+    onDecision?.({ toolName: call.toolName, input: call.input, decision });
+    return decision;
+}
+export function blockedOutput(toolName, decision) {
+    const action = decision.action === 'deny' ? 'deny' : 'ask';
+    const risks = decision.detected.length ? ` Detected risks: ${decision.detected.join(', ')}.` : '';
+    const message = action === 'deny'
+        ? `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 {
+        blocked: true,
+        action,
+        verdict: decision.verdict,
+        status: decision.status,
+        detected: decision.detected,
+        confidence: decision.confidence,
+        message,
+    };
+}
+export async function reviewCompletion(claim, options, signal) {
+    const { evidence: fixedEvidence, minConfidence, onDecision, ...rest } = options;
+    const { task: _task, toolName: _toolName, ...recipeOptions } = rest;
+    const evidence = [fixedEvidence, claim.evidence]
+        .filter((text) => Boolean(text?.trim()))
+        .join('\n\n');
+    const decision = await completionGate({
+        task: claim.task,
+        report: claim.report,
+        ...(evidence ? { evidence } : {}),
+        ...(minConfidence === undefined ? {} : { minConfidence }),
+    }, withSignal(recipeOptions, signal));
+    onDecision?.({ report: claim.report, evidence: evidence || undefined, decision });
+    const accepted = decision.status === 'ready' && decision.verdict === 'complete';
+    const signals = decision.detected.length ? ` Signals: ${decision.detected.join(', ')}.` : '';
+    const message = accepted
+        ? 'The completion report was accepted.'
+        : decision.status === 'review'
+            ? `The completion report could not be judged confidently (verdict: ${decision.verdict}).${signals} Supply clearer evidence or continue working.`
+            : `The completion report was not accepted (verdict: ${decision.verdict}).${signals} Finish the remaining work or supply evidence that demonstrates completion.`;
+    return {
+        accepted,
+        verdict: decision.verdict,
+        status: decision.status,
+        detected: decision.detected,
+        confidence: decision.confidence,
+        message,
+    };
+}
+export function messageText(messages, role, position) {
+    const ordered = position === 'first' ? messages : [...messages].reverse();
+    for (const message of ordered) {
+        if (message.role !== role)
+            continue;
+        const text = contentText(message.content);
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+function contentText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => typeof part === 'object' && part !== null && 'text' in part && typeof part.text === 'string'
+        ? part.text
+        : '')
+        .filter((text) => text.trim())
+        .join('\n')
+        .trim();
+}
+export function requireText(value, description) {
+    if (!value)
+        throw new Error(`Cannot derive ${description}; supply it explicitly.`);
+    return value;
+}
+function withSignal(options, signal) {
+    const { client, model } = options;
+    const chosen = options.signal ?? signal;
+    return {
+        ...(client === undefined ? {} : { client }),
+        ...(model === undefined ? {} : { model }),
+        ...(chosen === undefined ? {} : { signal: chosen }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-recipes",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "Small, composable Jev decisions for retrieval, conversations, and agent workflows.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,14 @@
       "types": "./dist/evaluation/index.d.ts",
       "import": "./dist/evaluation/index.js"
     },
+    "./ai-sdk": {
+      "types": "./dist/adapters/ai-sdk/index.d.ts",
+      "import": "./dist/adapters/ai-sdk/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/adapters/langchain/index.d.ts",
+      "import": "./dist/adapters/langchain/index.js"
+    },
     "./package.json": "./package.json",
     "./action-compare": {
       "types": "./dist/recipes/action-compare/index.d.ts",
@@ -1035,6 +1043,8 @@
     "dist/cli/*.js",
     "dist/evaluation/**/*.js",
     "dist/evaluation/**/*.d.ts",
+    "dist/adapters/**/*.js",
+    "dist/adapters/**/*.d.ts",
     "dist/cli/*.d.ts",
     "dist/recipes/*/demo.json",
     "README.md",
@@ -1067,15 +1077,29 @@
     "test:coverage": "vitest run --coverage",
     "eval:featured": "node --env-file-if-exists=.env evals/featured.mjs",
     "site:build": "npm run generate:check && npm run build && node site/build.mjs",
-    "site:preview": "node site/preview.mjs"
+    "site:preview": "node --env-file-if-exists=.env site/preview.mjs"
   },
   "dependencies": {
     "@typesafe-ai/sdk": "^0.6.0",
     "zod": "^4.6.5"
   },
+  "peerDependencies": {
+    "ai": ">=7.0.0",
+    "@langchain/core": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@langchain/core": "^1.2.13",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "4.1.11",
+    "ai": "^7.0.122",
     "prettier": "3.9.8",
     "rimraf": "6.1.3",
     "typescript": "~5.9.3",