@samrahimi/smol-js 0.7.0 → 0.7.1

package/dist/index.d.mts

@@ -1191,27 +1191,31 @@ declare class ExaResearchTool extends Tool {
 
 /**
  * ProxyTool - Bridges the smol-js agent runtime to an external standalone tool
- * executed in an isolated Bun process.
+ * executed in an isolated Bun process via the toolHarness adapter.
  *
- * The tool file is never imported into the main Node.js process. Instead, when
- * an agent invokes this proxy, it spawns `bun run <toolPath>` and communicates
- * via a lightweight stdin/stdout JSON protocol.
+ * The tool file is never imported into the main Node.js process. When an agent
+ * invokes this proxy, it spawns:
  *
- * Protocol (stdout of child):
- *   - Lines prefixed with `[TOOL_OUTPUT]` are streaming log lines from the tool.
+ *   bun run <toolHarness.ts> <toolPath> <argsJson>
+ *
+ * The harness is the ONLY place that speaks the stdout protocol. The tool
+ * itself simply exports { TOOL_METADATA, execute } and knows nothing about
+ * how it is being called.
+ *
+ * Protocol (stdout of harness/child):
  *   - A line prefixed with `[TOOL_RESULT]` contains the JSON-serialized return value.
  *   - A line prefixed with `[TOOL_ERROR]` means the tool threw; payload is the message.
- *   - Any other stdout line is treated as a streaming log line.
+ *   - Any other stdout line (e.g. console.log inside execute()) is streaming output.
  *
- * Extensibility note: The transport (child_process + stdio) is encapsulated here.
- * A future subclass or factory could swap this for HTTP, gRPC, or IPC with no change
- * to the ProxyTool interface visible to agents or YAML definitions.
+ * Extensibility: The spawn+stdio transport is fully encapsulated here. A future
+ * variant (HTTP, gRPC, IPC) only needs to replace execute() — the tool file and
+ * YAML definition stay identical.
  */
 
 interface ProxyToolConfig {
     /** Absolute path to the .ts or .js tool file */
     toolPath: string;
-    /** Tool name (must match the class name inside the file) */
+    /** Tool name (must match the file's base name) */
     name: string;
     /** Human-readable description exposed to agents */
     description: string;
@@ -1230,14 +1234,16 @@ declare class ProxyTool extends Tool {
     private readonly toolPath;
     private readonly timeout;
     private bunPath;
+    private harnessPath;
     constructor(config: ProxyToolConfig);
     /**
-     * Ensure Bun is available before first invocation.
+     * Ensure Bun is available and locate the harness before first invocation.
      */
     setup(): Promise<void>;
     /**
-     * Spawn the tool in a Bun child process, pass serialized args via CLI,
-     * stream stdout back as log lines, and parse the final result.
+     * Spawn the harness in a Bun child process. The harness imports the tool,
+     * calls execute(args), and writes the protocol lines. Any console.log from
+     * the tool flows through stdout as plain lines.
      */
     execute(args: Record<string, unknown>): Promise<unknown>;
     private processLine;

package/dist/index.d.ts

@@ -1191,27 +1191,31 @@ declare class ExaResearchTool extends Tool {
 
 /**
  * ProxyTool - Bridges the smol-js agent runtime to an external standalone tool
- * executed in an isolated Bun process.
+ * executed in an isolated Bun process via the toolHarness adapter.
  *
- * The tool file is never imported into the main Node.js process. Instead, when
- * an agent invokes this proxy, it spawns `bun run <toolPath>` and communicates
- * via a lightweight stdin/stdout JSON protocol.
+ * The tool file is never imported into the main Node.js process. When an agent
+ * invokes this proxy, it spawns:
  *
- * Protocol (stdout of child):
- *   - Lines prefixed with `[TOOL_OUTPUT]` are streaming log lines from the tool.
+ *   bun run <toolHarness.ts> <toolPath> <argsJson>
+ *
+ * The harness is the ONLY place that speaks the stdout protocol. The tool
+ * itself simply exports { TOOL_METADATA, execute } and knows nothing about
+ * how it is being called.
+ *
+ * Protocol (stdout of harness/child):
  *   - A line prefixed with `[TOOL_RESULT]` contains the JSON-serialized return value.
  *   - A line prefixed with `[TOOL_ERROR]` means the tool threw; payload is the message.
- *   - Any other stdout line is treated as a streaming log line.
+ *   - Any other stdout line (e.g. console.log inside execute()) is streaming output.
  *
- * Extensibility note: The transport (child_process + stdio) is encapsulated here.
- * A future subclass or factory could swap this for HTTP, gRPC, or IPC with no change
- * to the ProxyTool interface visible to agents or YAML definitions.
+ * Extensibility: The spawn+stdio transport is fully encapsulated here. A future
+ * variant (HTTP, gRPC, IPC) only needs to replace execute() — the tool file and
+ * YAML definition stay identical.
  */
 
 interface ProxyToolConfig {
     /** Absolute path to the .ts or .js tool file */
     toolPath: string;
-    /** Tool name (must match the class name inside the file) */
+    /** Tool name (must match the file's base name) */
     name: string;
     /** Human-readable description exposed to agents */
     description: string;
@@ -1230,14 +1234,16 @@ declare class ProxyTool extends Tool {
     private readonly toolPath;
     private readonly timeout;
     private bunPath;
+    private harnessPath;
     constructor(config: ProxyToolConfig);
     /**
-     * Ensure Bun is available before first invocation.
+     * Ensure Bun is available and locate the harness before first invocation.
      */
     setup(): Promise<void>;
     /**
-     * Spawn the tool in a Bun child process, pass serialized args via CLI,
-     * stream stdout back as log lines, and parse the final result.
+     * Spawn the harness in a Bun child process. The harness imports the tool,
+     * calls execute(args), and writes the protocol lines. Any console.log from
+     * the tool flows through stdout as plain lines.
      */
     execute(args: Record<string, unknown>): Promise<unknown>;
     private processLine;

package/dist/index.js

@@ -792,7 +792,7 @@ Total time: ${(duration / 1e3).toFixed(2)}s`);
   }
   /** Sleep for a specified duration */
   sleep(ms) {
-    return new Promise((resolve6) => setTimeout(resolve6, ms));
+    return new Promise((resolve7) => setTimeout(resolve7, ms));
   }
 };
 
@@ -1461,12 +1461,12 @@ var UserInputTool = class extends Tool {
       input: process.stdin,
       output: process.stdout
     });
-    return new Promise((resolve6) => {
+    return new Promise((resolve7) => {
       rl.question(`
 [Agent asks]: ${question}
 Your response: `, (answer) => {
         rl.close();
-        resolve6(answer);
+        resolve7(answer);
       });
     });
   }
@@ -2795,7 +2795,7 @@ var ExaResearchTool = class extends Tool {
     while (Date.now() - startTime < this.maxPollTime) {
       attempts++;
       if (attempts > 1) {
-        await new Promise((resolve6) => setTimeout(resolve6, this.pollInterval));
+        await new Promise((resolve7) => setTimeout(resolve7, this.pollInterval));
       }
       const statusResponse = await fetch(`https://api.exa.ai/research/v1/${researchId}`, {
         method: "GET",
@@ -2848,6 +2848,7 @@ var ExaResearchTool = class extends Tool {
 
 // src/tools/ProxyTool.ts
 var import_child_process2 = require("child_process");
+var path6 = __toESM(require("path"));
 
 // src/utils/bunInstaller.ts
 var import_child_process = require("child_process");
@@ -2906,10 +2907,12 @@ function whichBun() {
 }
 
 // src/tools/ProxyTool.ts
-var TOOL_OUTPUT_PREFIX = "[TOOL_OUTPUT]";
 var TOOL_RESULT_PREFIX = "[TOOL_RESULT]";
 var TOOL_ERROR_PREFIX = "[TOOL_ERROR]";
 var DEFAULT_TOOL_TIMEOUT_MS = 6e4;
+function resolveHarnessPath() {
+  return path6.resolve(__dirname, "..", "toolHarness.ts");
+}
 var ProxyTool = class extends Tool {
   name;
   description;
@@ -2918,6 +2921,7 @@ var ProxyTool = class extends Tool {
   toolPath;
   timeout;
   bunPath = null;
+  harnessPath = null;
   constructor(config) {
     super();
     this.name = config.name;
@@ -2928,23 +2932,25 @@ var ProxyTool = class extends Tool {
     this.timeout = config.timeout ?? DEFAULT_TOOL_TIMEOUT_MS;
   }
   /**
-   * Ensure Bun is available before first invocation.
+   * Ensure Bun is available and locate the harness before first invocation.
    */
   async setup() {
     this.bunPath = await ensureBunAvailable();
+    this.harnessPath = resolveHarnessPath();
     this.isSetup = true;
   }
   /**
-   * Spawn the tool in a Bun child process, pass serialized args via CLI,
-   * stream stdout back as log lines, and parse the final result.
+   * Spawn the harness in a Bun child process. The harness imports the tool,
+   * calls execute(args), and writes the protocol lines. Any console.log from
+   * the tool flows through stdout as plain lines.
    */
   async execute(args) {
-    if (!this.bunPath) {
+    if (!this.bunPath || !this.harnessPath) {
       await this.setup();
     }
     const serializedArgs = JSON.stringify(args);
-    return new Promise((resolve6, reject) => {
-      const child = (0, import_child_process2.spawn)(this.bunPath, ["run", this.toolPath, serializedArgs], {
+    return new Promise((resolve7, reject) => {
+      const child = (0, import_child_process2.spawn)(this.bunPath, ["run", this.harnessPath, this.toolPath, serializedArgs], {
         stdio: ["pipe", "pipe", "pipe"],
         env: { ...process.env }
       });
@@ -3009,12 +3015,12 @@ ${logBuffer.join("\n")}
 [Tool result]
 `;
             if (typeof result === "string") {
-              resolve6(logPrefix + result);
+              resolve7(logPrefix + result);
             } else {
-              resolve6({ logs: logBuffer.join("\n"), result });
+              resolve7({ logs: logBuffer.join("\n"), result });
             }
           } else {
-            resolve6(result);
+            resolve7(result);
           }
           return;
         }
@@ -3024,7 +3030,7 @@ ${logBuffer.join("\n")}
             `Custom tool "${this.name}" exited with code ${code}. Output: ${combined || "(none)"}`
           ));
         } else {
-          resolve6(combined || `Tool "${this.name}" produced no output.`);
+          resolve7(combined || `Tool "${this.name}" produced no output.`);
         }
       });
       child.on("error", (err) => {
@@ -3035,7 +3041,7 @@ ${logBuffer.join("\n")}
       });
     });
   }
-  // --- internal line parser ---
+  // --- line parser: protocol is spoken by harness, interpreted here ---
   processLine(line, handlers) {
     const trimmed = line.trimEnd();
     if (!trimmed) return;
@@ -3048,8 +3054,6 @@ ${logBuffer.join("\n")}
       }
     } else if (trimmed.startsWith(TOOL_ERROR_PREFIX)) {
       handlers.onError(trimmed.slice(TOOL_ERROR_PREFIX.length).trim());
-    } else if (trimmed.startsWith(TOOL_OUTPUT_PREFIX)) {
-      handlers.onOutput(trimmed.slice(TOOL_OUTPUT_PREFIX.length).trim());
     } else {
       handlers.onOutput(trimmed);
     }
@@ -3058,7 +3062,7 @@ ${logBuffer.join("\n")}
 
 // src/tools/CustomToolScanner.ts
 var fs6 = __toESM(require("fs"));
-var path6 = __toESM(require("path"));
+var path7 = __toESM(require("path"));
 var METADATA_REGEX = /export\s+const\s+TOOL_METADATA\s*=\s*(\{[\s\S]*?\});\s*$/m;
 function scanCustomTools(folderPath) {
   if (!fs6.existsSync(folderPath)) {
@@ -3070,10 +3074,10 @@ function scanCustomTools(folderPath) {
   const discovered = [];
   for (const entry of entries) {
     if (entry.isDirectory()) continue;
-    const ext = path6.extname(entry.name).toLowerCase();
+    const ext = path7.extname(entry.name).toLowerCase();
     if (ext !== ".ts" && ext !== ".js") continue;
-    const filePath = path6.resolve(folderPath, entry.name);
-    const baseName = path6.basename(entry.name, ext);
+    const filePath = path7.resolve(folderPath, entry.name);
+    const baseName = path7.basename(entry.name, ext);
     let metadata;
     try {
       metadata = extractMetadata(filePath);
@@ -3141,7 +3145,7 @@ function loadCustomTools(folderPath) {
 
 // src/orchestrator/YAMLLoader.ts
 var fs7 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
+var path8 = __toESM(require("path"));
 var import_yaml = __toESM(require("yaml"));
 var TOOL_REGISTRY = {
   read_file: ReadFileTool,
@@ -3173,7 +3177,7 @@ var YAMLLoader = class {
    * Load a workflow from a YAML file path.
    */
   loadFromFile(filePath) {
-    const absolutePath = path7.isAbsolute(filePath) ? filePath : path7.resolve(process.cwd(), filePath);
+    const absolutePath = path8.isAbsolute(filePath) ? filePath : path8.resolve(process.cwd(), filePath);
     if (!fs7.existsSync(absolutePath)) {
       throw new Error(`Workflow file not found: ${absolutePath}`);
     }