@open1s/ezbos 1.0.0

package/examples/02-hooks.ts

@@ -0,0 +1,82 @@
+import { BrainOS, defineHook, hook, mergeHooks, createHookRegistry, HookEvent, version } from '../src/index.js';
+
+const beforeHook = defineHook(HookEvent.BeforeToolCall, (ctx: any) => {
+  console.log(`  [BeforeToolCall] ${ctx.data?.tool_name}`);
+  return 'continue';
+});
+
+const afterHook = defineHook(HookEvent.AfterToolCall, (ctx: any) => {
+  console.log(`  [AfterToolCall] completed`);
+  return 'continue';
+});
+
+const beforeLlmHook = defineHook(HookEvent.BeforeLlmCall, (ctx: any) => {
+  console.log(`  [BeforeLlmCall]`);
+  return 'continue';
+});
+
+const afterLlmHook = defineHook(HookEvent.AfterLlmCall, (ctx: any) => {
+  console.log(`  [AfterLlmCall]`);
+  return 'continue';
+});
+
+const onMessageHook = defineHook(HookEvent.OnMessage, (ctx: any) => {
+  console.log(`  [OnMessage] ${ctx.data?.message?.substring(0, 50)}`);
+  return 'continue';
+});
+
+const onCompleteHook = defineHook(HookEvent.OnComplete, (ctx: any) => {
+  console.log(`  [OnComplete]`);
+  return 'continue';
+});
+
+const onErrorHook = defineHook(HookEvent.OnError, (ctx: any) => {
+  console.log(`  [OnError] ${ctx.data?.error}`);
+  return 'continue';
+});
+
+async function main() {
+  console.log(`\n=== 02-hooks.ts - Hook API Demo (v${version()}) ===\n`);
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  const addTool = { name: 'Add', description: 'Add', schema: { properties: { a: {}, b: {} } }, callback: () => '42' };
+
+  console.log('--- All HookEvent values ---');
+  console.log('HookEvent.BeforeToolCall:', HookEvent.BeforeToolCall);
+  console.log('HookEvent.AfterToolCall:', HookEvent.AfterToolCall);
+  console.log('HookEvent.BeforeLlmCall:', HookEvent.BeforeLlmCall);
+  console.log('HookEvent.AfterLlmCall:', HookEvent.AfterLlmCall);
+  console.log('HookEvent.OnMessage:', HookEvent.OnMessage);
+  console.log('HookEvent.OnComplete:', HookEvent.OnComplete);
+  console.log('HookEvent.OnError:', HookEvent.OnError);
+
+  console.log('\n--- mergeHooks ---');
+  const allHooks = mergeHooks(
+    beforeHook, afterHook, beforeLlmHook, afterLlmHook,
+    onMessageHook, onCompleteHook, onErrorHook
+  );
+  console.log(`Merged ${allHooks.length} hooks`);
+
+  console.log('\n--- defineHook returns ---');
+  console.log('beforeHook:', beforeHook);
+  console.log('afterHook:', afterHook);
+
+  const agent = brain.agent('hooks-demo')
+    .with_tools(addTool)
+    .with_hooks(beforeHook, afterHook, beforeLlmHook, afterLlmHook);
+
+  const started = await agent.start();
+
+  console.log('\n--- Running agent with hooks ---');
+  const result = await started.ask('What is 10 + 20? Use the Add tool.');
+  console.log(`Result: ${result}`);
+
+  await started.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/examples/03-plugins.ts

@@ -0,0 +1,91 @@
+import { BrainOS, definePlugin, plugin, on_llm_request, on_llm_response, on_tool_call, on_tool_result, mergePlugins, getPluginHandlers, version } from '../src/index.js';
+
+const plainPlugin = definePlugin({
+  name: 'plain-plugin',
+  on_llm_request(req: any) { console.log('  [Plain Plugin] LLM request:', req.model); return req; },
+  on_llm_response(resp: any) { console.log('  [Plain Plugin] LLM response'); return resp; },
+  on_tool_call(call: any) { console.log('  [Plain Plugin] Tool call:', call.name); return call; },
+  on_tool_result(result: any) { console.log('  [Plain Plugin] Tool result:', String(result).slice(0, 30)); return result; },
+});
+
+const pluginA = definePlugin({
+  name: 'plugin-a',
+  on_llm_request(req: any) { console.log('  [Plugin A] LLM request'); return req; },
+});
+
+const pluginB = definePlugin({
+  name: 'plugin-b',
+  on_tool_result(result: any) { console.log('  [Plugin B] Tool result:', String(result).slice(0, 30)); return result; },
+});
+
+class DecoratedPlugin {
+  __pluginName = 'decorated-plugin';
+
+  on_llm_request(req: any) {
+    console.log('  [Decorated] LLM request');
+    return req;
+  }
+
+  on_llm_response(resp: any) {
+    console.log('  [Decorated] LLM response');
+    return resp;
+  }
+
+  on_tool_call(call: any) {
+    console.log('  [Decorated] Tool call:', call.name);
+    return call;
+  }
+
+  on_tool_result(result: any) {
+    console.log('  [Decorated] Tool result');
+    return result;
+  }
+}
+
+async function main() {
+  console.log(`\n=== 03-plugins.ts - Plugin API Demo (v${version()}) ===\n`);
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  const addTool = { name: 'Add', description: 'Add', schema: { properties: { a: {}, b: {} } }, callback: () => '42' };
+
+  console.log('--- definePlugin ---');
+  console.log('plainPlugin name:', plainPlugin.name);
+  console.log('pluginA name:', pluginA.name);
+  console.log('pluginB name:', pluginB.name);
+
+  console.log('\n--- mergePlugins ---');
+  const merged = mergePlugins(pluginA, pluginB, plainPlugin);
+  console.log(`Merged ${merged.length} plugins:`, merged.map(p => p.name));
+
+  console.log('\n--- getPluginHandlers from class instance ---');
+  const decorated = new DecoratedPlugin();
+  const handlers = getPluginHandlers(decorated);
+  console.log('DecoratedPlugin handlers extracted:', handlers);
+
+  console.log('\n--- Agent with merged plugins ---');
+  const agent = brain.agent('plugins-demo')
+    .with_tools(addTool)
+    .with_plugins(plainPlugin);
+
+  const started = await agent.start();
+  console.log('Running agent with plainPlugin...');
+  await started.ask('Use the Add tool to calculate 5 + 3.');
+
+  console.log('\n--- Agent with decorated class plugin ---');
+  const agent2 = brain.agent('plugins-demo-2')
+    .with_tools(addTool)
+    .with_plugins(decorated);
+
+  const started2 = await agent2.start();
+  await started2.ask('Use the Add tool to calculate 7 + 3.');
+
+  await started.close();
+  await started2.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/examples/04-mcp.ts

@@ -0,0 +1,74 @@
+import { BrainOS, defineMcpProcess, defineMcpHttp, McpBuilder, version } from '../src/index.js';
+
+const HTTP_MCP_URL = 'http://127.0.0.1:8000/mcp';
+
+async function main() {
+  console.log(`\n=== 04-mcp.ts - MCP Server Demo (v${version()}) ===\n`);
+
+  console.log('--- defineMcpProcess / defineMcpHttp ---');
+  const processConfig = defineMcpProcess('files', 'npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']);
+  const httpConfig = defineMcpHttp('hello-mcp', HTTP_MCP_URL);
+  console.log('processConfig:', processConfig);
+  console.log('httpConfig:', httpConfig);
+
+  console.log('\n--- McpBuilder ---');
+  const mcpBuilder = new McpBuilder()
+    .process('files', 'npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+    .http('hello-mcp', HTTP_MCP_URL);
+  const builtConfigs = mcpBuilder.build();
+  console.log('Built MCP configs:', builtConfigs);
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  console.log('\n--- Agent with MCP process (filesystem server) ---');
+  const agent = brain.agent('mcp-demo')
+    .with_mcp_process('files', 'npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']);
+
+  const started = await agent.start();
+
+  console.log('--- listMcpTools() ---');
+  try {
+    const mcpTools = await started.listMcpTools();
+    console.log(`MCP tools available: ${mcpTools.length}`);
+    mcpTools.slice(0, 3).forEach((t: any) => console.log(`  - ${t.name}: ${t.description?.substring(0, 80)}...`));
+    if (mcpTools.length > 3) console.log(`  ... and ${mcpTools.length - 3} more`);
+  } catch (e) {
+    console.log('MCP tools listing result:', (e as Error).message);
+  }
+
+  console.log('\n--- LLM call using MCP process tool ---');
+  try {
+    const result = await started.ask('List the files in /tmp directory using the MCP filesystem tool');
+    console.log('Result:', result.substring(0, 200));
+  } catch (e) {
+    console.log('LLM call error:', (e as Error).message);
+  }
+
+  console.log('\n--- Agent with MCP HTTP server ---');
+  const httpAgent = brain.agent('mcp-http-demo')
+    .with_mcp_http('hello-mcp', HTTP_MCP_URL);
+
+  try {
+    const httpStarted = await httpAgent.start();
+    const httpTools = await httpStarted.listMcpTools();
+    console.log(`HTTP MCP tools available: ${httpTools.length}`);
+    httpTools.forEach((t: any) => console.log(`  - ${t.name}: ${t.description}`));
+
+    if (httpTools.length > 0) {
+      console.log('\n--- LLM call using HTTP MCP tool ---');
+      const httpResult = await httpStarted.ask('Use the greet tool to say hello to World');
+      console.log('HTTP MCP Result:', httpResult);
+    }
+    await httpStarted.close();
+  } catch (e) {
+    console.log('HTTP MCP failed:', (e as Error).message);
+  }
+
+  await started.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/examples/05-skills.ts

@@ -0,0 +1,45 @@
+import { BrainOS, defineSkill, SkillsBuilder, version } from '../src/index.js';
+import { initTracing } from '@open1s/jsbos';
+
+initTracing();
+
+
+async function main() {
+  console.log(`\n=== 05-skills.ts - Skills API Demo (v${version()}) ===\n`);
+
+  console.log('--- defineSkill ---');
+  const skill = defineSkill('math-expert', 'You are a math expert. Always show your work step by step.');
+  console.log('Skill:', skill);
+
+  console.log('\n--- SkillsBuilder ---');
+  const builder = 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.');
+
+  const built = builder.build();
+  console.log('Built skills:', built);
+  console.log('  dirs:', built.dirs);
+  console.log('  inline:', built.inline.map(s => s.name));
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  console.log('\n--- Agent with skills from directory ---');
+  const agent = brain.agent('skills-demo')
+    .with_skills_dir('./skills');
+
+  const started = await agent.start();
+  console.log('Agent started with skills configured');
+
+  console.log('\n--- LLM call with skills ---');
+  const result = await started.ask('Review this code for potential bugs: function greet(name) { return "Hello, " + name; }');
+  console.log('Result:', result);
+
+  await started.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/examples/06-session.ts

@@ -0,0 +1,72 @@
+import { initTracing } from '@open1s/jsbos';
+import { BrainOS, defineTool, version } from '../src/index.js';
+
+initTracing();
+
+async function main() {
+  console.log(`\n=== 06-session.ts - Session API Demo (v${version()}) ===\n`);
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  const greetingTool = defineTool('Greet', 'Greet someone')
+    .required('name', 'string', 'Name of the person to greet')
+    .handle((args: any) => `Hello, ${args.name}!`);
+
+  const agent = brain.agent('session-demo')
+    .with_tools(greetingTool)
+    .with_systemPrompt('You are a friendly assistant.');
+
+  const started = await agent.start();
+
+  console.log('--- Multi-turn conversation ---');
+
+  await started.ask('My name is Alice');
+  console.log('After Q1, session chars:', started.exportSession().length);
+
+  await started.ask('What is 2 + 2?');
+  console.log('After Q2, session chars:', started.exportSession().length);
+
+  await started.ask('What is my name?');
+  console.log('After Q3, session chars:', started.exportSession().length);
+
+  console.log('\n--- Session compact (LLM summary) ---');
+  const sessionBefore = started.exportSession().length;
+  console.log('Session before compact:', sessionBefore, 'chars');
+
+  await started.compactSession();
+  const afterCompact = started.exportSession().length;
+  console.log('After compactSession:', afterCompact, 'chars');
+
+  console.log('\n--- Verify compact worked ---');
+  const verifyResult = await started.ask('What is my name?');
+  console.log('Verify:', verifyResult.trim());
+
+  console.log('\n--- Session export / import ---');
+  const json = started.exportSession();
+  console.log('Export (first 150 chars):', json.substring(0, 150), '...');
+
+  console.log('\n--- SessionManager fluent API ---');
+  const agent2 = brain.agent('session-demo-2')
+    .with_tools(greetingTool)
+    .with_systemPrompt('You are a friendly assistant.');
+  const started2 = await agent2.start();
+
+  await started2.ask('Say hello to Bob');
+  const sessionJson = started2.exportSession();
+  console.log('Session before import length:', sessionJson.length);
+
+  started2.clearSession();
+  console.log('After clear, length:', started2.exportSession().length);
+
+  started2.importSession(sessionJson);
+  console.log('After import, length:', started2.exportSession().length);
+
+  await started.close();
+  await started2.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/examples/07-agent-advanced.ts

@@ -0,0 +1,86 @@
+import { BrainOS, tool, version } from '../src/index.js';
+
+async function main() {
+  console.log(`\n=== 07-agent-advanced.ts - Agent Advanced Demo (v${version()}) ===\n`);
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  const addTool = tool('Add', 'Add two numbers', (args: any) => String(args.a + args.b));
+
+  console.log('--- BrainOS.with() static factory ---');
+  const quickBuilder = brain.agent('quick');
+  const quickAgent = await quickBuilder
+    .with_systemPrompt('You are a calculator.')
+    .with_temperature(0.5)
+    .start();
+  console.log('Quick agent created via BrainOS.with()');
+  console.log('Quick agent tools:', quickAgent.tools);
+  console.log('Quick agent config:', quickAgent.config);
+
+  console.log('\n--- Agent stream() - Real-time chat ---');
+  const streamAgent = brain.agent('stream-demo')
+    .with_tools(addTool)
+    .with_systemPrompt('You are a helpful assistant.');
+
+  const started = await streamAgent.start();
+
+  console.log('Streaming response:');
+  let streamedText = '';
+  await started.stream('What is 5 + 3? And what is the capital of France?', (token) => {
+     if(token.type === 'Text') {
+        process.stdout.write(token.text);
+     }
+     if(token.type === 'ReasoningContent') {
+        process.stdout.write(token.text);
+     }
+  });
+  console.log('\n\nStreamed text length:', streamedText.length);
+
+  console.log('\n--- Agent streamCollect() ---');
+  const tokens = await started.streamCollect('What is 10 + 20?');
+  console.log('Collected', tokens.length, 'tokens');
+  const textTokens = tokens.filter(t => t.text);
+  console.log('Text tokens:', textTokens.length);
+  if (textTokens.length > 0) {
+    console.log('Collected text:', textTokens.map(t => t.text).join(''));
+  }
+
+  console.log('\n--- Agent metrics ---');
+  const metrics = started.metrics;
+  console.log('Metrics object keys:', Object.keys(metrics));
+  console.log('Metrics:', JSON.stringify(metrics, null, 2));
+
+  console.log('\n--- resetMetrics() ---');
+  started.resetMetrics();
+  console.log('Metrics after reset:', started.metrics);
+
+  console.log('\n--- Agent config ---');
+  console.log('Config:', started.config);
+  console.log('Config model:', started.config.model);
+  console.log('Config temperature:', started.config.temperature);
+
+  console.log('\n--- Agent tools list ---');
+  console.log('Tools:', started.tools);
+
+  console.log('\n--- Resilience options ---');
+  const resilientAgent = brain.agent('resilient')
+    .with_tools(addTool)
+    .with_resilience({
+      circuitBreakerMaxFailures: 3,
+      circuitBreakerCooldownSecs: 10,
+      rateLimitCapacity: 5,
+      rateLimitWindowSecs: 60,
+      rateLimitMaxRetries: 3,
+    });
+  const resilientStarted = await resilientAgent.start();
+  console.log('Resilient agent configured with circuit breaker + rate limiting');
+  console.log('Resilient agent config:', resilientStarted.config);
+
+  await resilientStarted.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/examples/08-brainos-messaging.ts

@@ -0,0 +1,83 @@
+import { BrainOS, version } from '../src/index.js';
+
+async function main() {
+  console.log(`\n=== 08-brainos-messaging.ts - Messaging Demo (v${version()}) ===\n`);
+
+  const brain = new BrainOS();
+  await brain.start();
+
+  console.log('--- Query/Queryable pattern ---');
+  const queryServer = await brain.queryable('math-query', (input: string) => {
+    console.log('[Queryable] Received:', input);
+    const n = parseInt(input);
+    if (isNaN(n)) return 'Error: invalid number';
+    return String(n * n);
+  });
+  await queryServer.start();
+
+  const queryClient = await brain.query('math-query');
+  const response = await queryClient.ask('42', 5000);
+  console.log('[QueryClient] Response for 42:', response);
+
+  console.log('\n--- Caller/Callable pattern ---');
+  const callableServer = await brain.callable('rpc-add', (input: string) => {
+    console.log('[Callable] Received:', input);
+    const parts = input.split(',');
+    if (parts.length !== 2) return 'Error: need two numbers separated by comma';
+    return String(parseInt(parts[0]) + parseInt(parts[1]));
+  });
+  await callableServer.start();
+
+  const callerClient = await brain.caller('rpc-add');
+  const callResult = await callerClient.call('10,20');
+  console.log('[CallerClient] Result for 10,20:', callResult);
+
+  console.log('\n--- Publisher/Subscriber pattern (recv) ---');
+  const sub1 = await brain.subscriber('test-topic');
+  console.log('Subscriber topic:', sub1.topic);
+
+  const pub = await brain.publisher('test-topic');
+  console.log('Publisher topic:', pub.topic);
+  await pub.text('Hello from PublisherWrapper!');
+  await pub.json({ msg: 'structured', value: 123 });
+  console.log('Published via PublisherWrapper.text() and .json()');
+
+  console.log('Waiting for messages...');
+  const msg1 = await sub1.recv(3000);
+  console.log('[Subscriber] Received 1:', msg1);
+  const msg2 = await sub1.recv(3000);
+  console.log('[Subscriber] Received 2:', msg2);
+  await sub1.stop();
+
+  console.log('\n--- Publisher/Subscriber pattern (run) ---');
+  const sub2 = await brain.subscriber('run-topic');
+  const pub2 = await brain.publisher('run-topic');
+
+  console.log('Starting subscriber with run()...');
+  const runPromise = sub2.run((msg) => {
+    console.log('[Subscriber.run] Received:', msg);
+  });
+
+  await pub2.text('Message 1 via run');
+  await pub2.text('Message 2 via run');
+  await pub2.json({ action: 'test', id: 42 });
+
+  await new Promise(r => setTimeout(r, 1000));
+  await sub2.stop();
+  await runPromise;
+
+  console.log('\n--- Agent with messaging integration ---');
+  const agent = brain.agent('messaging-demo')
+    .with_systemPrompt('You are a helpful assistant. When asked about messaging, explain the patterns.');
+
+  const started = await agent.start();
+  const messagingResult = await started.ask('Explain the difference between Query and Publisher messaging patterns.');
+  console.log('Agent response:', messagingResult);
+
+  await started.close();
+  await brain.stop();
+  console.log('\nDone.');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@open1s/ezbos",
+  "version": "1.0.0",
+  "description": "Simple BrainOS - Easy wrapper for @open1s/jsbos",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test",
+    "example:tools": "tsx examples/01-tools.ts",
+    "example:hooks": "tsx examples/02-hooks.ts",
+    "example:plugins": "tsx examples/03-plugins.ts",
+    "example:mcp": "tsx examples/04-mcp.ts",
+    "example:skills": "tsx examples/05-skills.ts",
+    "example:session": "tsx examples/06-session.ts",
+    "example:agent": "tsx examples/07-agent-advanced.ts",
+    "example:messaging": "tsx examples/08-brainos-messaging.ts"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "brainos",
+    "ezbos"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@open1s/jsbos": "^2.1.4"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/node": "^25.8.0",
+    "tsx": "^4.22.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
+  },
+  "packageManager": "yarn@4.13.0+sha512.5c20ba010c99815433e5c8453112165e673f1c7948d8d2b267f4b5e52097538658388ebc9f9580656d9b75c5cc996f990f611f99304a2197d4c56d21eea370e7"
+}

package/skills/code-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: code-review
+description: Expert code review for potential bugs, security, and performance
+category: development
+version: 1.0.0
+---
+
+# Code Review Skill
+
+You are an expert code reviewer. When reviewing code:
+
+1. Check for potential bugs and edge cases
+2. Identify security vulnerabilities
+3. Suggest performance improvements
+4. Review for readability and maintainability
+5. Provide concrete examples of improvements
+
+Always format your response with clear sections and code examples.