@strav/brain 0.2.4 → 0.2.8

package/README.md

@@ -38,6 +38,29 @@ const result = await brain.generate('List 3 colors', {
 const vectors = await brain.embed('Hello world')
 ```
 
+## Tools
+
+Define tools that AI agents can use:
+
+```ts
+import { defineTool } from '@strav/brain'
+import { z } from 'zod'
+
+const searchTool = defineTool({
+  name: 'search',
+  description: 'Search the database',
+  parameters: z.object({ query: z.string() }),
+  execute: async ({ query }, context) => {
+    const userId = context?.userId
+    return await db.search(query, { userId })
+  },
+})
+```
+
+The `execute` function receives two parameters:
+- `args` - The parsed and validated tool arguments
+- `context` - Optional context object passed from the agent runner
+
 ## Agents
 
 ```ts
@@ -50,7 +73,10 @@ class ResearchAgent extends Agent {
   tools = [searchTool, summarizeTool]
 }
 
-const result = await brain.agent(ResearchAgent).input('Find info on Bun').run()
+// Run agent with context
+const runner = brain.agent(ResearchAgent)
+runner.context({ userId: '123' }) // Pass context to tools
+const result = await runner.input('Find info on Bun').run()
 ```
 
 ## Threads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "type": "module",
   "description": "AI module for the Strav framework",
   "license": "MIT",
@@ -15,8 +15,8 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@strav/kernel": "0.1.4",
-    "@strav/workflow": "0.1.4"
+    "@strav/kernel": "0.2.6",
+    "@strav/workflow": "0.2.6"
   },
   "dependencies": {
     "zod": "^3.25 || ^4.0"

package/src/helpers.ts

@@ -27,7 +27,8 @@ import type {
 /** Execute a single tool call, returning the result and the tool message. */
 async function executeTool(
   tools: ToolDefinition[] | undefined,
-  toolCall: ToolCall
+  toolCall: ToolCall,
+  context?: Record<string, unknown>
 ): Promise<{ result: unknown; message: Message }> {
   const toolDef = tools?.find(t => t.name === toolCall.name)
   let result: unknown
@@ -36,7 +37,7 @@ async function executeTool(
     result = `Error: Tool "${toolCall.name}" not found`
   } else {
     try {
-      result = await toolDef.execute(toolCall.arguments)
+      result = await toolDef.execute(toolCall.arguments, context)
     } catch (err) {
       result = `Error: ${err instanceof Error ? err.message : String(err)}`
     }
@@ -556,7 +557,7 @@ export class AgentRunner<T extends Agent = Agent> {
       await agent.onToolCall?.(toolCall)
 
       const start = performance.now()
-      const { result, message } = await executeTool(agent.tools, toolCall)
+      const { result, message } = await executeTool(agent.tools, toolCall, this._context)
       const duration = performance.now() - start
 
       const record: ToolCallRecord = {

package/src/tool.ts

@@ -12,22 +12,23 @@ import type { ToolDefinition, JsonSchema } from './types.ts'
  *   name: 'search',
  *   description: 'Search the database',
  *   parameters: z.object({ query: z.string() }),
- *   execute: async ({ query }) => {
- *     return await db.search(query)
+ *   execute: async ({ query }, context) => {
+ *     const userId = context?.userId
+ *     return await db.search(query, { userId })
  *   },
  * })
  */
-export function defineTool(config: {
+export function defineTool<TArgs = any, TContext = Record<string, unknown>>(config: {
   name: string
   description: string
   parameters: any
-  execute: (args: any) => unknown | Promise<unknown>
+  execute: (args: TArgs, context?: TContext) => unknown | Promise<unknown>
 }): ToolDefinition {
   return {
     name: config.name,
     description: config.description,
     parameters: zodToJsonSchema(config.parameters) as JsonSchema,
-    execute: config.execute,
+    execute: config.execute as (args: Record<string, unknown>, context?: Record<string, unknown>) => unknown | Promise<unknown>,
   }
 }
 

package/src/types.ts

@@ -49,7 +49,7 @@ export interface ToolDefinition {
   name: string
   description: string
   parameters: JsonSchema
-  execute: (args: Record<string, unknown>) => unknown | Promise<unknown>
+  execute: (args: Record<string, unknown>, context?: Record<string, unknown>) => unknown | Promise<unknown>
 }
 
 // ── Completion Request / Response ────────────────────────────────────────────