@getenki/ai-darwin-arm64 0.5.40 → 0.5.61

package/README.md

@@ -19,6 +19,7 @@ The package ships prebuilt native binaries for:
 The current package surface is:
 
 - `NativeEnkiAgent`
+- `NativeToolRegistry`
 - `NativeMultiAgentRuntime`
 - `NativeWorkflowRuntime`
 - `JsAgentStatus`
@@ -29,13 +30,27 @@ The current package surface is:
 - `JsAgentRunResult`
 - `JsExecutionStep`
 
-`NativeEnkiAgent` is the main entrypoint. It can be created in four modes:
+`NativeEnkiAgent` is the main entrypoint. It can be created in five modes:
 
 - `new(...)` for a plain agent
 - `NativeEnkiAgent.withTools(...)`
+- `NativeEnkiAgent.withToolRegistry(...)`
 - `NativeEnkiAgent.withMemory(...)`
 - `NativeEnkiAgent.withToolsAndMemory(...)`
 
+`NativeToolRegistry` supports:
+
+- `new(...)`
+- `registerTools(...)`
+- `clear()`
+- `toolNames()`
+- `size`
+
+It also supports two loop customization levels:
+
+- `agenticLoop` constructor arguments for prompt-level loop customization
+- `setAgentLoopHandler(...)` for a JavaScript-defined loop override
+
 `NativeMultiAgentRuntime` supports:
 
 - `new(...)`
@@ -101,9 +116,70 @@ Constructor arguments:
 - `model?: string`
 - `maxIterations?: number`
 - `workspaceHome?: string`
+- `agenticLoop?: string`
 
 If omitted, the runtime falls back to built-in defaults for name, prompt, and max iterations.
 
+## Custom Agentic Loops
+
+Use the optional `agenticLoop` argument when you want to replace the default loop instructions seen by the model but still keep the normal Rust runtime loop:
+
+```js
+const { NativeEnkiAgent } = require('@getenki/ai')
+
+const agent = new NativeEnkiAgent(
+  'Assistant',
+  'Answer clearly and keep responses short.',
+  'ollama::qwen3.5:latest',
+  20,
+  process.cwd(),
+  [
+    '1. Understand the request.',
+    '2. Decide whether a tool is needed.',
+    '3. Summarize observations.',
+    '4. Return the final answer.',
+  ].join('\n'),
+)
+```
+
+Use `setAgentLoopHandler(...)` when you want JavaScript to own the loop itself:
+
+```js
+const { NativeEnkiAgent } = require('@getenki/ai')
+
+const agent = new NativeEnkiAgent(
+  'Assistant',
+  'Answer clearly and keep responses short.',
+  'ollama::qwen3.5:latest',
+  8,
+  process.cwd(),
+)
+
+agent.setAgentLoopHandler((requestJson) => {
+  const request = JSON.parse(requestJson)
+  return JSON.stringify({
+    content: `Handled in JavaScript for: ${request.user_message}`,
+    steps: [
+      {
+        index: 1,
+        phase: 'Custom',
+        kind: 'final',
+        detail: 'Returned a final answer from JavaScript',
+      },
+    ],
+  })
+})
+```
+
+The handler receives a JSON request containing the current transcript, system prompt, tool catalog, model, iteration limit, and workspace paths.
+
+Use `clearAgentLoopHandler()` to restore the default runtime loop.
+
+Repository examples:
+
+- [`example/basic-js/custom-agent-loop.js`](/I:/projects/enki/core-next/example/basic-js/custom-agent-loop.js)
+- [`example/basic-js/react-custom-agent-loop.js`](/I:/projects/enki/core-next/example/basic-js/react-custom-agent-loop.js)
+
 ## Tools
 
 Tools can be attached with `NativeEnkiAgent.withTools(...)`. Each tool object must provide:
@@ -224,6 +300,79 @@ Instead of putting `execute` on every tool, you can pass a shared `toolHandler`
 - `workspaceDir`
 - `sessionsDir`
 
+### Reusable Tool Registries
+
+If you want to manage a shared pool of tools and attach it to multiple agents later, create a `NativeToolRegistry` and connect it dynamically:
+
+```js
+const { NativeEnkiAgent, NativeToolRegistry } = require('@getenki/ai')
+
+const registry = new NativeToolRegistry()
+registry.registerTools(
+  [
+    {
+      name: 'lookup_release',
+      description: 'Return a canned release note.',
+      parametersJson: JSON.stringify({
+        type: 'object',
+        properties: {
+          version: { type: 'string' },
+        },
+        required: ['version'],
+      }),
+    },
+  ],
+  (toolName, inputJson) => JSON.stringify({ toolName, inputJson }),
+)
+
+const agent = new NativeEnkiAgent(
+  'Registry Agent',
+  'Use connected tools when they help.',
+  'ollama::qwen3.5:latest',
+  20,
+  process.cwd(),
+)
+
+agent.connectToolRegistry(registry)
+```
+
+You can also construct the agent directly from a registry with `NativeEnkiAgent.withToolRegistry(...)`.
+
+This is the cleanest path when multiple agents should share the same tool catalog or when tools need to be connected after agent construction.
+
+TypeScript uses the same API:
+
+```ts
+import { NativeEnkiAgent, NativeToolRegistry } from '@getenki/ai'
+
+const registry = new NativeToolRegistry()
+registry.registerTools(
+  [
+    {
+      name: 'lookup_release',
+      description: 'Return a canned release note.',
+      parameters: {
+        type: 'object',
+        properties: {
+          version: { type: 'string' },
+        },
+        required: ['version'],
+      },
+    },
+  ],
+  (toolName: string, inputJson: string) => JSON.stringify({ toolName, inputJson }),
+)
+
+const agent = NativeEnkiAgent.withToolRegistry(
+  'Registry Agent',
+  'Use connected tools when they help.',
+  'ollama::qwen3.5:latest',
+  20,
+  process.cwd(),
+  registry,
+)
+```
+
 ## Memory
 
 Memory modules are plain objects:
@@ -542,6 +691,9 @@ JavaScript example:
 cd example/basic-js
 npm install
 npm start
+npm run start:tool-registry
+npm run start:custom-agent-loop
+npm run start:react-custom-agent-loop
 npm run start:multi-agent-tools-memory
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getenki/ai-darwin-arm64",
-  "version": "0.5.40",
+  "version": "0.5.61",
   "cpu": [
     "arm64"
   ],