feat(llm tools): Add patternTool helper to support pattern LLM tools (#1962)

* feat: Add extraParams support to LLM tool definitions

Adds the ability to pass extra parameters to pattern-based tools in LLM
dialog tool invocations. This allows tool definitions to specify additional
static parameters that get merged with the LLM-provided input when invoking
the underlying pattern.

Changes:
- Add extraParams field to LLMToolSchema for pattern-based tools
- Merge extraParams with tool call input when invoking patterns
- Update calculator pattern to accept optional base parameter
- Add example usage in default-app with base: 10 for calculator tool

This enables use cases like configuring tool behavior (e.g., number base
for calculator) without requiring the LLM to provide those values.

* feat: Allow patterns as LLM tool actions via OpaqueRef

Extends LLM tool system to support passing pattern recipes as actions,
not just handler streams. This enables using recipes with extraParams
directly as tool definitions.

Changes:
- Modified invokeToolCall to accept pattern and extraParams via charmMeta
- Updated tool resolution in startRequest to detect and extract patterns
  from OpaqueRef cells
- Added grep pattern example in note.tsx demonstrating the new capability

This allows more flexible tool definitions where patterns can be
composed with additional parameters and used as LLM actions.

* feat: Add patternTool helper for LLM tool definitions with pre-filled params

Add a new `patternTool` helper function that simplifies creating LLM tool
definitions from recipes with optional pre-filled parameters. This eliminates
the need for manual type casting and provides automatic type inference.

The helper:
- Automatically creates a recipe with description "tool"
- Constructs the { pattern, extraParams } object structure
- Properly types the result as OpaqueRef<Omit<T, keyof E>> (excluding pre-filled params)
- No manual type casting needed

Example usage:
```typescript
grep: patternTool(
  ({ query, content }: { query: string; content: string }) => {
    return derive({ query, content }, ({ query, content }) => {
      return content.split("\n").filter((c) => c.includes(query));
    });
  },
  { content },
),
// Type is automatically inferred as OpaqueRef<{ query: string }>
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* compile api types

* feat: Allow patternTool to accept existing recipes

Extend patternTool to accept either a function or an already-created
RecipeFactory. This provides flexibility when you want to reuse an existing
recipe with pre-filled parameters.

The function now:
- Checks if the input is a recipe using isRecipe()
- Only creates a new recipe if a function is passed
- Reuses the existing recipe if a RecipeFactory is passed

Example usage with existing recipe:
```typescript
const myRecipe = recipe<{ query: string; content: string }>(
  "Grep",
  ({ query, content }) => { ... }
);

// Pass existing recipe with extra params
const tool = patternTool(myRecipe, { content });
// Type: OpaqueRef<{ query: string }>
```

Updated default-app.tsx to demonstrate this pattern with the calculator tool.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* sanitize base input

* patternTool's 2nd parameter is optional, adjust type accordingly

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: seefeldb

packages/api/index.ts

@@ -388,6 +388,14 @@ export type RecipeFunction = {
   ): RecipeFactory<T, R>;
 };
 
+export type PatternToolFunction = <
+  T,
+  E extends Partial<T> = Record<PropertyKey, never>,
+>(
+  fnOrRecipe: ((input: OpaqueRef<Required<T>>) => any) | RecipeFactory<T, any>,
+  extraParams?: Opaque<E>,
+) => OpaqueRef<Omit<T, keyof E>>;
+
 export type LiftFunction = {
   <T extends JSONSchema = JSONSchema, R extends JSONSchema = JSONSchema>(
     argumentSchema: T,
@@ -573,6 +581,7 @@ export type GetRecipeEnvironmentFunction = () => RecipeEnvironment;
 // Re-export all function types as values for destructuring imports
 // These will be implemented by the factory
 export declare const recipe: RecipeFunction;
+export declare const patternTool: PatternToolFunction;
 export declare const lift: LiftFunction;
 export declare const handler: HandlerFunction;
 export declare const derive: DeriveFunction;

packages/patterns/common-tools.tsx

@@ -18,17 +18,27 @@ import {
 type CalculatorRequest = {
   /** The mathematical expression to evaluate. */
   expression: string;
+  /** The base to use for the calculation. */
+  base?: number;
 };
 
 export const calculator = recipe<
   CalculatorRequest,
   string | { error: string }
->("Calculator", ({ expression }) => {
-  return derive(expression, (expr) => {
-    const sanitized = expr.replace(/[^0-9+\-*/().\s]/g, "");
+>("Calculator", ({ expression, base }) => {
+  return derive({ expression, base }, ({ expression, base }) => {
+    const sanitized = expression.replace(/[^0-9+\-*/().\s]/g, "");
+    let sanitizedBase = Number(base);
+    if (
+      Number.isNaN(sanitizedBase) || sanitizedBase < 2 || sanitizedBase > 36
+    ) {
+      sanitizedBase = 10;
+    }
     let result;
     try {
-      result = Function(`"use strict"; return (${sanitized})`)();
+      result = Function(
+        `"use strict"; return Number(${sanitized}).toString(${sanitizedBase})`,
+      )();
     } catch (error) {
       result = { error: (error as any)?.message || "<error>" };
     }

packages/patterns/default-app.tsx

@@ -9,6 +9,7 @@ import {
   lift,
   NAME,
   navigateTo,
+  patternTool,
   recipe,
   str,
   UI,
@@ -170,9 +171,8 @@ export default recipe<CharmsListInput, CharmsListOutput>(
         readWebpage: {
           pattern: readWebpage,
         },
-        calculator: {
-          pattern: calculator,
-        },
+        // Example of using patternTool with an existing recipe and extra params
+        calculator: patternTool(calculator, { base: 10 }),
       },
     });
 

packages/patterns/note.tsx

@@ -9,6 +9,7 @@ import {
   navigateTo,
   Opaque,
   OpaqueRef,
+  patternTool,
   recipe,
   UI,
   wish,
@@ -25,6 +26,7 @@ type Output = {
 
   /** The content of the note */
   content: Default<string, "">;
+  grep: OpaqueRef<{ query: string }>;
   editContent: OpaqueRef<{ detail: { value: string } }>;
 };
 
@@ -154,6 +156,14 @@ const Note = recipe<Input, Output>(
       content,
       mentioned,
       backlinks,
+      grep: patternTool(
+        ({ query, content }: { query: string; content: string }) => {
+          return derive({ query, content }, ({ query, content }) => {
+            return content.split("\n").filter((c) => c.includes(query));
+          });
+        },
+        { content },
+      ),
       editContent: handleEditContent({ content }),
     };
   },

packages/runner/src/builder/built-in.ts

@@ -1,11 +1,14 @@
 import { BuiltInLLMDialogState } from "@commontools/api";
 import { createNodeFactory, lift } from "./module.ts";
+import { recipe } from "./recipe.ts";
+import { isRecipe } from "./types.ts";
 import type {
   Cell,
   JSONSchema,
   NodeFactory,
   Opaque,
   OpaqueRef,
+  RecipeFactory,
   Schema,
 } from "./types.ts";
 import type {
@@ -152,3 +155,52 @@ declare function createCell<S extends JSONSchema = JSONSchema>(
 ): Cell<Schema<S>>;
 
 export type { createCell };
+
+/**
+ * Helper function for creating LLM tool definitions from recipes with optional pre-filled parameters.
+ * Creates a recipe with the given function and returns an object suitable for use as an LLM tool,
+ * with proper TypeScript typing that reflects only the non-pre-filled parameters.
+ *
+ * @param fnOrRecipe - Either a recipe function or an already-created RecipeFactory
+ * @param extraParams - Optional object containing parameter values to pre-fill
+ * @returns An object with `pattern` and `extraParams` properties, typed to show only remaining params
+ *
+ * @example
+ * ```ts
+ * import { patternTool } from "commontools";
+ *
+ * const content = cell("Hello world");
+ *
+ * // With a function - recipe will be created automatically
+ * const grepTool = patternTool(
+ *   ({ query, content }: { query: string; content: string }) => {
+ *     return derive({ query, content }, ({ query, content }) => {
+ *       return content.split("\n").filter((c) => c.includes(query));
+ *     });
+ *   },
+ *   { content }
+ * );
+ *
+ * // With an existing recipe
+ * const myRecipe = recipe<{ query: string; content: string }>(
+ *   "Grep",
+ *   ({ query, content }) => { ... }
+ * );
+ * const grepTool2 = patternTool(myRecipe, { content });
+ *
+ * // Both result in type: OpaqueRef<{ query: string }>
+ * ```
+ */
+export function patternTool<T, E extends Partial<T>>(
+  fnOrRecipe: ((input: OpaqueRef<Required<T>>) => any) | RecipeFactory<T, any>,
+  extraParams?: Opaque<E>,
+): OpaqueRef<Omit<T, keyof E>> {
+  const pattern = isRecipe(fnOrRecipe)
+    ? fnOrRecipe
+    : recipe<T>("tool", fnOrRecipe);
+
+  return {
+    pattern,
+    extraParams: extraParams ?? {},
+  } as any as OpaqueRef<Omit<T, keyof E>>;
+}

packages/runner/src/builder/factory.ts

@@ -29,6 +29,7 @@ import {
   llm,
   llmDialog,
   navigateTo,
+  patternTool,
   str,
   streamData,
   wish,
@@ -100,6 +101,7 @@ export const createBuilder = (
     commontools: {
       // Recipe creation
       recipe,
+      patternTool,
 
       // Module creation
       lift,

packages/runner/src/builder/types.ts

@@ -25,6 +25,7 @@ import type {
   Opaque,
   OpaqueRef,
   OpaqueRefMethods,
+  PatternToolFunction,
   Recipe,
   RecipeFunction,
   RenderFunction,
@@ -275,6 +276,7 @@ export type Frame = {
 export interface BuilderFunctionsAndConstants {
   // Recipe creation
   recipe: RecipeFunction;
+  patternTool: PatternToolFunction;
 
   // Module creation
   lift: LiftFunction;

packages/runner/src/builtins/llm-dialog.ts

@@ -209,6 +209,7 @@ const LLMToolSchema = {
       required: ["argumentSchema", "resultSchema", "nodes"],
       asCell: true,
     },
+    extraParams: { type: "object" },
     charm: {
       // Accept whole charm - its own schema defines its handlers
       asCell: true,
@@ -425,11 +426,21 @@ async function invokeToolCall(
   space: MemorySpace,
   toolDef: Cell<Schema<typeof LLMToolSchema>> | undefined,
   toolCall: LLMToolCall,
-  charmMeta?: { handler?: any; cell?: Cell<any>; charm: Cell<any> },
+  charmMeta?: {
+    handler?: any;
+    cell?: Cell<any>;
+    charm: Cell<any>;
+    extraParams?: Record<string, unknown>;
+    pattern?: Readonly<Recipe>;
+  },
 ) {
-  const pattern = toolDef?.key("pattern").getRaw() as unknown as
-    | Readonly<Recipe>
-    | undefined;
+  const pattern = charmMeta?.pattern ??
+    toolDef?.key("pattern").getRaw() as unknown as
+      | Readonly<Recipe>
+      | undefined;
+  const extraParams = charmMeta?.extraParams ??
+    toolDef?.key("extraParams").get() ??
+    {};
   const handler = charmMeta?.handler ?? toolDef?.key("handler");
   // FIXME(bf): in practice, toolCall has toolCall.toolCallId not .id
   const result = runtime.getCell<any>(space, toolCall.id);
@@ -455,7 +466,7 @@ async function invokeToolCall(
 
   runtime.editWithRetry((tx) => {
     if (pattern) {
-      runtime.run(tx, pattern, toolCall.input, result);
+      runtime.run(tx, pattern, { ...toolCall.input, ...extraParams }, result);
     } else if (handler) {
       handler.withTx(tx).send({
         ...toolCall.input,
@@ -893,15 +904,30 @@ async function startRequest(
                     ],
                   };
                   const ref: Cell<any> = runtime.getCellFromLink(link);
-                  if (!isStream(ref)) {
+                  if (isStream(ref)) {
+                    charmMeta = {
+                      handler: ref as any,
+                      charm: agg.charm,
+                    } as any;
+                  } else {
+                    const pattern = (ref as Cell<any>).key("pattern")
+                      .getRaw() as unknown as
+                        | Readonly<Recipe>
+                        | undefined;
+                    if (pattern) {
+                      charmMeta = {
+                        pattern: pattern,
+                        extraParams:
+                          (ref as Cell<any>).key("extraParams").get() ?? {},
+                        charm: agg.charm,
+                      } as any;
+                    }
+                  }
+                  if (!charmMeta) {
                     throw new Error(
                       "path does not resolve to a handler stream",
                     );
                   }
-                  charmMeta = {
-                    handler: ref as any,
-                    charm: agg.charm,
-                  } as any;
                   // For run tools, pass only handler args. Accept both shapes:
                   // either nested under `args`, or top-level fields alongside path.
                   toolDef = undefined;

packages/static/assets/types/commontools.d.ts

@@ -244,6 +244,7 @@ export type RecipeFunction = {
     <T, R>(argumentSchema: string | JSONSchema, fn: (input: OpaqueRef<Required<T>>) => Opaque<R>): RecipeFactory<T, R>;
     <T, R>(argumentSchema: string | JSONSchema, resultSchema: JSONSchema, fn: (input: OpaqueRef<Required<T>>) => Opaque<R>): RecipeFactory<T, R>;
 };
+export type PatternToolFunction = <T, E extends Partial<T> = Record<PropertyKey, never>>(fnOrRecipe: ((input: OpaqueRef<Required<T>>) => any) | RecipeFactory<T, any>, extraParams?: Opaque<E>) => OpaqueRef<Omit<T, keyof E>>;
 export type LiftFunction = {
     <T extends JSONSchema = JSONSchema, R extends JSONSchema = JSONSchema>(argumentSchema: T, resultSchema: R, implementation: (input: Schema<T>) => Schema<R>): ModuleFactory<SchemaWithoutCell<T>, SchemaWithoutCell<R>>;
     <T, R>(implementation: (input: T) => R): ModuleFactory<T, R>;
@@ -319,6 +320,7 @@ export interface RecipeEnvironment {
 }
 export type GetRecipeEnvironmentFunction = () => RecipeEnvironment;
 export declare const recipe: RecipeFunction;
+export declare const patternTool: PatternToolFunction;
 export declare const lift: LiftFunction;
 export declare const handler: HandlerFunction;
 export declare const derive: DeriveFunction;