@open1s/ezbos 1.0.0

package/README.md

@@ -0,0 +1,468 @@
+# @open1s/ezbos
+
+Simple BrainOS - Easy wrapper for [@open1s/jsbos](https://www.npmjs.com/package/@open1s/jsbos). Build AI agents with tools, hooks, plugins, MCP, skills, and messaging.
+
+## Install
+
+```bash
+npm install @open1s/ezbos
+```
+
+## Quick Start
+
+```ts
+import { BrainOS, tool } from '@open1s/ezbos';
+
+const brain = new BrainOS();
+await brain.start();
+
+const addTool = tool('Add', 'Add two numbers', (args) => String(args.a + args.b));
+
+const agent = brain.agent('assistant')
+  .with_tools(addTool)
+  .with_systemPrompt('You are a helpful assistant.');
+
+const started = await agent.start();
+const result = await started.ask('What is 5 + 3?');
+console.log(result);
+
+await started.close();
+await brain.stop();
+```
+
+## Configuration
+
+Place a `brainos.json` in your project root:
+
+```json
+{
+  "global_model": {
+    "model": "nvidia/meta/llama-3.1-8b-instruct",
+    "base_url": "https://integrate.api.nvidia.com/v1",
+    "api_key": "your-key"
+  }
+}
+```
+
+BrainOS auto-discovers this config on `start()`. You can also pass options directly:
+
+```ts
+const brain = new BrainOS({
+  model: 'nvidia/meta/llama-3.1-8b-instruct',
+  baseUrl: 'https://integrate.api.nvidia.com/v1',
+  apiKey: 'nvapi-xxx',
+});
+await brain.start();
+```
+
+## Agent Builder
+
+Fluent builder for creating agents:
+
+```ts
+const agent = brain.agent('name')
+  .with_systemPrompt('You are helpful.')
+  .with_model('nvidia/meta/llama-3.1-8b-instruct')
+  .with_baseUrl('https://integrate.api.nvidia.com/v1')
+  .with_apiKey('your-key')
+  .with_temperature(0.7)
+  .with_timeout(120)
+  .with_maxTokens(4096)
+  .with_tools(tool1, tool2)
+  .with_hooks(hook1, hook2)
+  .with_plugins(plugin1)
+  .with_mcp_process('fs', 'npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+  .with_mcp_http('math', 'http://127.0.0.1:8000/mcp')
+  .with_skills_dir('./skills')
+  .with_skills({ name: 'Code Review', content: '...' })
+  .with_resilience({ circuitBreakerMaxFailures: 3, rateLimitCapacity: 5 });
+
+const started = await agent.start();
+```
+
+### Resilience
+
+Configure circuit breaker and rate limiting:
+
+```ts
+agent.with_resilience({
+  circuitBreakerMaxFailures: 3,    // trip after 3 failures
+  circuitBreakerCooldownSecs: 10,  // wait 10s before retry
+  rateLimitCapacity: 5,            // allow 5 requests
+  rateLimitWindowSecs: 60,         // per 60 seconds
+  rateLimitMaxRetries: 3,          // retry 3 times when limited
+});
+```
+
+## Tools
+
+Define tools the LLM can call.
+
+### Simple Tool
+
+```ts
+import { tool } from '@open1s/ezbos';
+
+const add = tool('Add', 'Add two numbers', (args) => String(args.a + args.b));
+```
+
+### Tool Builder
+
+For tools with schema and optional parameters:
+
+```ts
+import { defineTool, ok, err } from '@open1s/ezbos';
+
+const greet = defineTool('Greet', 'Greet someone')
+  .required('name', 'string', 'Name to greet')
+  .param('language', 'string', 'Language code', 'en')
+  .handle((args) => `Hello, ${args.name}!`);
+
+const divide = defineTool('Divide', 'Divide two numbers')
+  .required('n', 'number', 'Numerator')
+  .required('d', 'number', 'Denominator')
+  .handle((args) => {
+    if (args.d === 0) return err('Division by zero');
+    return ok(args.n / args.d);
+  });
+```
+
+### Result Helpers
+
+```ts
+const success = ok({ value: 42 }, { cached: true });
+const failure = err('Not found', { code: 404 });
+```
+
+**Note:** Tool callbacks must be synchronous. The underlying jsbos native layer does not support async tool callbacks.
+
+## Hooks
+
+Intercept agent lifecycle events.
+
+```ts
+import { HookEvent, defineHook } from '@open1s/ezbos';
+
+const logHook = defineHook(HookEvent.BeforeToolCall, (ctx) => {
+  console.log('About to call:', ctx.data?.tool_name);
+  return 'continue';  // or 'abort'
+});
+
+agent.with_hooks(logHook);
+```
+
+Available events:
+
+| Event | Description |
+|-------|-------------|
+| `BeforeToolCall` | Before a tool is invoked |
+| `AfterToolCall` | After a tool returns |
+| `BeforeLlmCall` | Before sending to LLM |
+| `AfterLlmCall` | After receiving from LLM |
+| `OnMessage` | On each message |
+| `OnComplete` | When task completes |
+| `OnError` | On error |
+
+### Merge Hooks
+
+```ts
+import { mergeHooks } from '@open1s/ezbos';
+
+const allHooks = mergeHooks(beforeHook, afterHook, beforeLlmHook);
+agent.with_hooks(allHooks);
+```
+
+## Plugins
+
+Register plugins for LLM/tool lifecycle events.
+
+### Plain Plugin
+
+```ts
+import { definePlugin } from '@open1s/ezbos';
+
+const loggerPlugin = definePlugin({
+  name: 'logger',
+  on_llm_request: (req) => { console.log('LLM request:', req.model); return req; },
+  on_llm_response: (resp) => { console.log('LLM response'); return resp; },
+  on_tool_call: (call) => { console.log('Tool call:', call.name); return call; },
+  on_tool_result: (result) => { console.log('Tool result'); return result; },
+});
+
+agent.with_plugins(loggerPlugin);
+```
+
+### Class-based Plugin
+
+```ts
+import { getPluginHandlers } from '@open1s/ezbos';
+
+class MyPlugin {
+  __pluginName = 'my-plugin';
+
+  on_llm_request(req: any) { return req; }
+  on_llm_response(resp: any) { return resp; }
+  on_tool_call(call: any) { return call; }
+  on_tool_result(result: any) { return result; }
+}
+
+const plugin = new MyPlugin();
+const handlers = getPluginHandlers(plugin);
+agent.with_plugins(plugin);
+```
+
+### Merge Plugins
+
+```ts
+import { mergePlugins } from '@open1s/ezbos';
+
+const merged = mergePlugins(pluginA, pluginB);
+agent.with_plugins(merged);
+```
+
+## MCP
+
+Connect to MCP (Model Context Protocol) servers.
+
+### Process-based
+
+```ts
+import { defineMcpProcess } from '@open1s/ezbos';
+
+const config = defineMcpProcess('files', 'npx', [
+  '-y', '@modelcontextprotocol/server-filesystem', '/tmp'
+]);
+
+agent.with_mcp_process('files', 'npx', [
+  '-y', '@modelcontextprotocol/server-filesystem', '/tmp'
+]);
+```
+
+### HTTP-based
+
+```ts
+import { defineMcpHttp } from '@open1s/ezbos';
+
+const config = defineMcpHttp('hello-mcp', 'http://127.0.0.1:8000/mcp');
+
+agent.with_mcp_http('hello-mcp', 'http://127.0.0.1:8000/mcp');
+```
+
+### MCP Builder
+
+```ts
+import { McpBuilder } from '@open1s/ezbos';
+
+const configs = new McpBuilder()
+  .process('files', 'npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+  .http('hello-mcp', 'http://127.0.0.1:8000/mcp')
+  .build();
+```
+
+### List MCP Tools
+
+```ts
+const mcpTools = await started.listMcpTools();
+console.log(`MCP tools available: ${mcpTools.length}`);
+```
+
+## Skills
+
+Add domain-specific instructions to the system prompt.
+
+### Define Skill
+
+```ts
+import { defineSkill } from '@open1s/ezbos';
+
+const skill = defineSkill('math-expert', 'You are a math expert. Always show your work step by step.');
+```
+
+### Directory-based
+
+Auto-discovers `SKILL.md` files in a directory:
+
+```ts
+agent.with_skills_dir('./skills');
+```
+
+Directory structure:
+```
+skills/
+  code-review/
+    SKILL.md
+```
+
+### Skills Builder
+
+```ts
+import { SkillsBuilder } from '@open1s/ezbos';
+
+const built = new SkillsBuilder()
+  .from_dir('./skills')
+  .add('code-review', 'You are a code reviewer. Be thorough.')
+  .add('api-design', 'You are an API designer. Follow REST best practices.')
+  .build();
+```
+
+## Agent (Started)
+
+The running agent instance.
+
+### LLM Calls
+
+```ts
+// ReAct loop (tools + reasoning)
+const result = await started.ask('What is 5 + 3?');
+
+// ReAct with explicit task
+const result2 = await started.react('Calculate the sum');
+
+// Simple LLM call (no tools)
+const result3 = await started.runSimple('Say hello');
+```
+
+### Streaming
+
+```ts
+// Stream tokens
+await started.stream('Task', (token) => {
+  if (token.type === 'Text') process.stdout.write(token.text);
+  if (token.type === 'ReasoningContent') process.stdout.write(token.text);
+});
+
+// Collect all tokens
+const tokens = await started.streamCollect('Task');
+const text = tokens.filter(t => t.text).map(t => t.text).join('');
+```
+
+### Session Management
+
+```ts
+// AI-powered compaction (replaces old messages with LLM summary)
+await started.compactSession();
+
+// Save/restore
+started.saveSession('./session.json');
+started.restoreSession('./session.json');
+
+// Clear
+started.clearSession();
+
+// Export/import as JSON
+const json = started.exportSession();
+started.importSession(json);
+```
+
+### Metrics
+
+```ts
+const metrics = started.metrics;
+console.log(metrics.llmCallCount);
+console.log(metrics.toolInvocationCount);
+console.log(metrics.totalWallTimeUs);
+
+started.resetMetrics();
+```
+
+### Info
+
+```ts
+console.log(started.tools);    // ['Add', 'Greet']
+console.log(started.config);   // { model, baseUrl, temperature, ... }
+```
+
+## Messaging
+
+Pub/sub, query, and RPC patterns via the message bus.
+
+### Publisher / Subscriber
+
+```ts
+// Publisher
+const pub = await brain.publisher('events');
+await pub.text('Hello');
+await pub.json({ event: 'click', x: 100 });
+
+// Subscriber - recv with timeout
+const sub = await brain.subscriber('events');
+const msg = await sub.recv(3000);
+
+// Subscriber - continuous processing
+const sub2 = await brain.subscriber('events');
+await sub2.run((msg) => console.log('Received:', msg));
+await sub2.stop();
+```
+
+### Query / Queryable (request-response)
+
+```ts
+// Server
+const server = await brain.queryable('math', (input) => {
+  const n = parseInt(input);
+  return String(n * n);
+});
+await server.start();
+
+// Client
+const client = await brain.query('math');
+const response = await client.ask('21', 5000);  // "441"
+```
+
+### Caller / Callable (RPC)
+
+```ts
+// Server
+const rpcServer = await brain.callable('add', (input) => {
+  const [a, b] = input.split(',').map(Number);
+  return String(a + b);
+});
+await rpcServer.start();
+
+// Client
+const rpcClient = await brain.caller('add');
+const result = await rpcClient.call('10,20');  // "30"
+```
+
+## Quick Agent
+
+One-liner to create and start an agent:
+
+```ts
+import { BrainOS } from '@open1s/ezbos';
+
+const agent = await BrainOS.with('assistant', {
+  model: 'nvidia/meta/llama-3.1-8b-instruct',
+  apiKey: 'nvapi-xxx',
+});
+const result = await agent.ask('Hello');
+await agent.close();
+```
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| `01-tools.ts` | Tool definitions (required/optional params), ok/err results, isErrorResult, error handling |
+| `02-hooks.ts` | All 7 hook events, defineHook, mergeHooks, hook registry |
+| `03-plugins.ts` | Plain plugins, class-based plugins, getPluginHandlers, mergePlugins |
+| `04-mcp.ts` | Process-based MCP, HTTP MCP, McpBuilder, listMcpTools |
+| `05-skills.ts` | defineSkill, SkillsBuilder, skill directories |
+| `06-session.ts` | Multi-turn conversation, compactSession, save/restore, export/import |
+| `07-agent-advanced.ts` | Streaming, streamCollect, metrics, resilience, config |
+| `08-brainos-messaging.ts` | Query/Queryable, Caller/Callable, Publisher/Subscriber (recv + run) |
+
+```bash
+npm run example:tools
+npm run example:hooks
+npm run example:plugins
+npm run example:mcp
+npm run example:skills
+npm run example:session
+npm run example:agent
+npm run example:messaging
+```
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,89 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "@open1s/ezbos",
+      "dependencies": {
+        "@open1s/jsbos": "^2.1.4",
+      },
+      "devDependencies": {
+        "tsx": "^4.22.0",
+        "typescript": "^6.0.3",
+      },
+    },
+  },
+  "packages": {
+    "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.28.0", "", { "os": "aix", "cpu": "ppc64" }, "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA=="],
+
+    "@esbuild/android-arm": ["@esbuild/android-arm@0.28.0", "", { "os": "android", "cpu": "arm" }, "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ=="],
+
+    "@esbuild/android-arm64": ["@esbuild/android-arm64@0.28.0", "", { "os": "android", "cpu": "arm64" }, "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw=="],
+
+    "@esbuild/android-x64": ["@esbuild/android-x64@0.28.0", "", { "os": "android", "cpu": "x64" }, "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA=="],
+
+    "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.28.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q=="],
+
+    "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.28.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ=="],
+
+    "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.28.0", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q=="],
+
+    "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.28.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw=="],
+
+    "@esbuild/linux-arm": ["@esbuild/linux-arm@0.28.0", "", { "os": "linux", "cpu": "arm" }, "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw=="],
+
+    "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.28.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A=="],
+
+    "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.28.0", "", { "os": "linux", "cpu": "ia32" }, "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ=="],
+
+    "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.28.0", "", { "os": "linux", "cpu": "none" }, "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg=="],
+
+    "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.28.0", "", { "os": "linux", "cpu": "none" }, "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w=="],
+
+    "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.28.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg=="],
+
+    "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.28.0", "", { "os": "linux", "cpu": "none" }, "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ=="],
+
+    "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.28.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q=="],
+
+    "@esbuild/linux-x64": ["@esbuild/linux-x64@0.28.0", "", { "os": "linux", "cpu": "x64" }, "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ=="],
+
+    "@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.28.0", "", { "os": "none", "cpu": "arm64" }, "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw=="],
+
+    "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.28.0", "", { "os": "none", "cpu": "x64" }, "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw=="],
+
+    "@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.28.0", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g=="],
+
+    "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.28.0", "", { "os": "openbsd", "cpu": "x64" }, "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA=="],
+
+    "@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.28.0", "", { "os": "none", "cpu": "arm64" }, "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w=="],
+
+    "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.28.0", "", { "os": "sunos", "cpu": "x64" }, "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw=="],
+
+    "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.28.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA=="],
+
+    "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.28.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA=="],
+
+    "@esbuild/win32-x64": ["@esbuild/win32-x64@0.28.0", "", { "os": "win32", "cpu": "x64" }, "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw=="],
+
+    "@open1s/jsbos": ["@open1s/jsbos@2.1.4", "", { "optionalDependencies": { "@open1s/jsbos-darwin-arm64": "2.1.4", "@open1s/jsbos-linux-arm64-gnu": "2.1.4", "@open1s/jsbos-linux-x64-gnu": "2.1.4", "@open1s/jsbos-win32-arm64-msvc": "2.1.4", "@open1s/jsbos-win32-x64-msvc": "2.1.4" } }, "sha512-G8FCJFJsELMWtBSyqiDyO1BqFMi45wxdS8RVKUc6+B+imjhht2ZBn7L2O46AErhlZOAKoU/yEeVOKu17Ni5RKQ=="],
+
+    "@open1s/jsbos-darwin-arm64": ["@open1s/jsbos-darwin-arm64@2.1.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-b6N2J37Rdg2i4+pFQLhmPpXSiPu842eYqY8ZfV/hWdwTIiehg9qG/1kcMETK9icmHc4Md9xQzXtN1Ytb3Q0l6g=="],
+
+    "@open1s/jsbos-linux-arm64-gnu": ["@open1s/jsbos-linux-arm64-gnu@2.1.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-3BrurLQGxHBkfL51T3EFOqmnFIml7cNFm5f5xX1nBqBLJ+u2TyRMMemeGNlPVI4vl0CQDKy3SIQaEsL1pRzvwQ=="],
+
+    "@open1s/jsbos-linux-x64-gnu": ["@open1s/jsbos-linux-x64-gnu@2.1.4", "", { "os": "linux", "cpu": "x64" }, "sha512-XfLzVZG4fHyyIbX1sV5uADHRIsXLtzNiEKMuJG1oz6ZWA3k4WOZKWhrFw/M3D4ZuyrovQdA4FdfmPI5za9Epcw=="],
+
+    "@open1s/jsbos-win32-arm64-msvc": ["@open1s/jsbos-win32-arm64-msvc@2.1.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-pelaitUjyLYCtaXkSFvD5N0v6GX7fOs+B8vZ60/WwraTcksrD4ZU9twEwdgRiep/qY1lydIQIv/72ReX5dCDSA=="],
+
+    "@open1s/jsbos-win32-x64-msvc": ["@open1s/jsbos-win32-x64-msvc@2.1.4", "", { "os": "win32", "cpu": "x64" }, "sha512-tCOtC0pjF9IWwF3WcmBIIdufQTA4pZlnB9OStDBT4jOR++ukTffXLg3i52H77rz5HayJSJBE2Onrmxy2ZXBj6Q=="],
+
+    "esbuild": ["esbuild@0.28.0", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.28.0", "@esbuild/android-arm": "0.28.0", "@esbuild/android-arm64": "0.28.0", "@esbuild/android-x64": "0.28.0", "@esbuild/darwin-arm64": "0.28.0", "@esbuild/darwin-x64": "0.28.0", "@esbuild/freebsd-arm64": "0.28.0", "@esbuild/freebsd-x64": "0.28.0", "@esbuild/linux-arm": "0.28.0", "@esbuild/linux-arm64": "0.28.0", "@esbuild/linux-ia32": "0.28.0", "@esbuild/linux-loong64": "0.28.0", "@esbuild/linux-mips64el": "0.28.0", "@esbuild/linux-ppc64": "0.28.0", "@esbuild/linux-riscv64": "0.28.0", "@esbuild/linux-s390x": "0.28.0", "@esbuild/linux-x64": "0.28.0", "@esbuild/netbsd-arm64": "0.28.0", "@esbuild/netbsd-x64": "0.28.0", "@esbuild/openbsd-arm64": "0.28.0", "@esbuild/openbsd-x64": "0.28.0", "@esbuild/openharmony-arm64": "0.28.0", "@esbuild/sunos-x64": "0.28.0", "@esbuild/win32-arm64": "0.28.0", "@esbuild/win32-ia32": "0.28.0", "@esbuild/win32-x64": "0.28.0" }, "bin": "bin/esbuild" }, "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw=="],
+
+    "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
+
+    "tsx": ["tsx@4.22.0", "", { "dependencies": { "esbuild": "~0.28.0" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "bin": "dist/cli.mjs" }, "sha512-8ccZMPD69s1AbKXx0C5ddTNZfNjwV04iIKgjZmKfKxMynEtSYcK0Lh7iQFh53fI5Yu4pb9usgAiqyPmEONaALg=="],
+
+    "typescript": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="],
+  }
+}

package/examples/00-pr.ts

@@ -0,0 +1 @@
+console.log('This is a placeholder file for the 00-pr.ts example. Please refer to the other example files for actual code demonstrations of BrainOS features.');

package/examples/01-tools.ts

@@ -0,0 +1,85 @@
+import { BrainOS, defineTool, tool, ok, err, isErrorResult, version } from '../src/index.js';
+
+import {initTracing} from "@open1s/jsbos";
+
+// initTracing();
+
+const addTool = defineTool('Add', 'Add two numbers')
+  .required('a', 'number', 'First number')
+  .required('b', 'number', 'Second number')
+  .handle((args: any) => { console.error('Adding numbers:', args.a, args.b); return args.a + args.b; });
+
+const multiplyTool = defineTool('Multiply', 'Multiply two numbers')
+  .required('x', 'number', 'First number')
+  .required('y', 'number', 'Second number')
+  .handle((args: any) => { console.error('Multiplying numbers:', args.x, args.y); return args.x * args.y; });
+
+const stringConcatTool = defineTool('Concat', 'Concatenate two strings')
+  .param('str1', 'string', 'First string')
+  .param('str2', 'string', 'Second string')
+  .param('separator', 'string', 'Separator', ', ')
+  .handle((args: any) => { console.error('Concatenating strings:', args.str1, args.str2, args.separator); return args.str1 + args.separator + args.str2; });
+
+const divideTool = defineTool('Divide', 'Divide two numbers')
+  .required('n', 'number', 'Numerator')
+  .required('d', 'number', 'Denominator')
+  .handle((args: any) => {
+    console.error('Dividing numbers:', args.n, args.d);
+    if (args.d === 0) return err('Division by zero');
+    return ok(args.n / args.d);
+  });
+
+const asyncWeatherTool = defineTool('Weather', 'Get weather for a city')
+  .required('city', 'string', 'City name')
+  .handle((args: any) => {
+    console.error('Fetching weather for city:', args.city);
+    return ok({ city: args.city, temp: 22, condition: 'sunny', unit: 'celsius' });
+  });
+
+const errorTool = tool('Fail', 'Always returns an error', () => {
+  throw new Error('Intentional failure from errorTool');
+});
+
+async function main() {
+  console.log(`\n=== 01-tools.ts - Tool API Demo (v${version()}) ===\n`);
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  const agent = brain.agent('tools-demo')
+    .with_tools(addTool, multiplyTool, stringConcatTool, divideTool, asyncWeatherTool, errorTool);
+
+  const started = await agent.start();
+
+  const tests = [
+    { q: 'What is 15 + 27?', expect: 42 },
+    { q: 'What is 8 times 6?', expect: 48 },
+    { q: 'Concatenate "Brain" and "OS" with separator "-"', expect: 'Brain-OS' },
+    { q: 'Divide 100 by 4', expect: 25 },
+    { q: 'Divide 10 by 0', expect: 'error' },
+    { q: 'What is the weather in Tokyo?', expect: 'ok' },
+  ];
+
+  for (const t of tests) {
+    console.log(`\nQ: ${t.q}`);
+    console.log(`   Expected: ${t.expect}`);
+    const result = await started.ask(t.q);
+    console.log(`   A: ${result}`);
+  }
+
+  console.log('\n--- Tool definitions ---');
+  console.log('addTool schema:', JSON.stringify((addTool as any).schema, null, 2));
+
+  console.log('\n--- isErrorResult demo ---');
+  const okResult = ok(42);
+  const errResult = err('bad');
+  console.log('ok(42):', okResult, 'isErrorResult:', isErrorResult(okResult));
+  console.log('err("bad"):', errResult, 'isErrorResult:', isErrorResult(errResult));
+
+  await started.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });