tnega 0.1.1 → 0.3.0

package/dist/tools.js

@@ -1,3 +1,5 @@
+import { createRequire as __tnegaCreateRequire } from 'node:module'; const require = __tnegaCreateRequire(import.meta.url);
+
 // packages/core/src/utils.ts
 var DisposableList = class {
   sn = 0;
@@ -308,6 +310,16 @@ var EventsService = class {
     args.push(next);
     return next();
   }
+  async waterfallAsync(...args) {
+    const [thisArg, callbacks] = this._resolve("waterfallAsync", args);
+    const inner = args.pop();
+    const next = async () => {
+      const callback = callbacks.shift();
+      return callback ? await Reflect.apply(callback, thisArg, args) : inner(...args);
+    };
+    args.push(next);
+    return next();
+  }
   register(label, hooks, callback, options) {
     const method = options.prepend ? "unshift" : "push";
     return this.ctx.fiber.effect(() => {
@@ -837,7 +849,16 @@ var ReflectService = class {
     this.mixin("reflect", ["get", "set", "provide", "accessor", "mixin"]);
     this.mixin("fiber", ["runtime", "effect"]);
     this.mixin("registry", ["inject", "plugin"]);
-    this.mixin("events", ["on", "once", "parallel", "emit", "serial", "bail", "waterfall"]);
+    this.mixin("events", [
+      "on",
+      "once",
+      "parallel",
+      "emit",
+      "serial",
+      "bail",
+      "waterfall",
+      "waterfallAsync"
+    ]);
   }
   ctx;
   static handler = {
@@ -1255,7 +1276,6 @@ var Service = class _Service {
 };
 
 // packages/tools/src/builtins.ts
-import { spawn } from "node:child_process";
 import {
   appendFile,
   mkdir,
@@ -1498,6 +1518,116 @@ function evaluateExpression(source) {
   return value;
 }
 
+// packages/tools/src/execution.ts
+import { spawn } from "node:child_process";
+function errorMessage(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+async function killProcessTree(child) {
+  if (child.pid === void 0) return;
+  if (process.platform === "win32") {
+    await new Promise((resolve2) => {
+      const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+        stdio: "ignore",
+        windowsHide: true
+      });
+      killer.on("error", () => resolve2());
+      killer.on("exit", () => resolve2());
+    });
+  } else {
+    try {
+      process.kill(-child.pid, "SIGKILL");
+    } catch {
+    }
+    child.kill("SIGKILL");
+  }
+}
+function runLocalShell(request) {
+  const timeoutMs = request.timeoutMs ?? 15e3;
+  const maxBuffer = request.maxBuffer ?? 1024 * 1024;
+  return new Promise((resolve2, reject) => {
+    const child = spawn(request.command, {
+      cwd: request.cwd,
+      shell: true,
+      windowsHide: true,
+      ...process.platform === "win32" ? {} : { detached: true }
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timer;
+    let onAbort = () => {
+    };
+    const append = (target, chunk, limit) => {
+      if (target.length >= limit) return target;
+      return target + chunk.toString("utf8").slice(0, limit - target.length);
+    };
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      request.signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (action) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      action();
+    };
+    const fail2 = (message2) => {
+      finish(() => {
+        void killProcessTree(child).finally(() => reject(new Error(message2)));
+      });
+    };
+    onAbort = () => fail2("shell command cancelled");
+    if (request.signal) {
+      if (request.signal.aborted) onAbort();
+      else request.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => fail2(`shell command timed out after ${timeoutMs}ms`), timeoutMs);
+    }
+    child.stdout.on("data", (chunk) => {
+      stdout = append(stdout, chunk, maxBuffer);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr = append(stderr, chunk, maxBuffer);
+    });
+    child.on("error", (error) => {
+      finish(() => resolve2({ exitCode: 1, stdout, stderr: errorMessage(error) }));
+    });
+    child.on("close", (code, closeSignal) => {
+      finish(() => resolve2({
+        exitCode: code ?? 1,
+        stdout,
+        stderr: closeSignal ? `killed by ${closeSignal}` : stderr
+      }));
+    });
+  });
+}
+var localExecutionProvider = {
+  runShell: runLocalShell,
+  async fetchHttp(request) {
+    const init = {};
+    if (request.headers) init.headers = request.headers;
+    if (request.signal) init.signal = request.signal;
+    const response = await fetch(request.url, init);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const maxBytes = request.maxBytes ?? 256 * 1024;
+    const truncated = buffer.byteLength > maxBytes;
+    const headers = {};
+    response.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    return {
+      status: response.status,
+      ok: response.ok,
+      headers,
+      body: buffer.subarray(0, maxBytes).toString("utf8"),
+      truncated
+    };
+  }
+};
+
 // packages/tools/src/path.ts
 import { realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
@@ -1570,7 +1700,8 @@ function normalizeConfig(config = {}) {
     maxWriteBytes: config.maxWriteBytes ?? 1024 * 1024,
     maxSearchBytes: config.maxSearchBytes ?? 1024 * 1024,
     maxResults: config.maxResults ?? 200,
-    timeoutMs: config.timeoutMs ?? 15e3
+    timeoutMs: config.timeoutMs ?? 15e3,
+    execution: config.execution ?? localExecutionProvider
   };
 }
 function definition(name2, description, execute, parameters) {
@@ -2038,22 +2169,12 @@ function httpGetTool(config) {
       }
       const headers = optionalRecord(args.headers, "headers") ?? {};
       const maxBytes = optionalNumber(args.maxBytes, "maxBytes") ?? config.maxReadBytes;
-      const init = { headers };
-      if (options.signal) init.signal = options.signal;
-      const response = await fetch(url, init);
-      const buffer = Buffer.from(await response.arrayBuffer());
-      const truncated = buffer.byteLength > maxBytes;
-      const headerMap = {};
-      response.headers.forEach((value, key) => {
-        headerMap[key] = value;
+      return config.execution.fetchHttp({
+        url: url.href,
+        ...Object.keys(headers).length ? { headers } : {},
+        ...maxBytes !== config.maxReadBytes ? { maxBytes } : {},
+        ...options.signal ? { signal: options.signal } : {}
       });
-      return {
-        status: response.status,
-        ok: response.ok,
-        headers: headerMap,
-        body: buffer.subarray(0, maxBytes).toString("utf8"),
-        truncated
-      };
     },
     {
       type: "object",
@@ -2078,13 +2199,13 @@ function shellTool(config) {
       const command = stringField(args.command, "command");
       const cwd = await resolveInside(config.cwd, optionalString(args.cwd, "cwd") ?? ".");
       const timeoutMs = optionalNumber(args.timeoutMs, "timeoutMs") ?? config.timeoutMs;
-      const result = await runShellCommand(
+      const result = await config.execution.runShell({
         command,
         cwd,
         timeoutMs,
-        config.maxWriteBytes,
-        options.signal
-      );
+        maxBuffer: config.maxWriteBytes,
+        ...options.signal ? { signal: options.signal } : {}
+      });
       return {
         exitCode: result.exitCode,
         stdout: result.stdout,
@@ -2102,84 +2223,6 @@ function shellTool(config) {
     }
   );
 }
-async function killProcessTree(child) {
-  if (child.pid === void 0) return;
-  if (process.platform === "win32") {
-    await new Promise((resolve2) => {
-      const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
-        stdio: "ignore",
-        windowsHide: true
-      });
-      killer.on("error", () => resolve2());
-      killer.on("exit", () => resolve2());
-    });
-  } else {
-    try {
-      process.kill(-child.pid, "SIGKILL");
-    } catch {
-    }
-    child.kill("SIGKILL");
-  }
-}
-function runShellCommand(command, cwd, timeoutMs, maxBuffer, signal) {
-  return new Promise((resolve2, reject) => {
-    const child = spawn(command, {
-      cwd,
-      shell: true,
-      windowsHide: true,
-      ...process.platform === "win32" ? {} : { detached: true }
-    });
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-    let timer;
-    let onAbort = () => {
-    };
-    const append = (target, chunk, limit) => {
-      if (target.length >= limit) return target;
-      return target + chunk.toString("utf8").slice(0, limit - target.length);
-    };
-    const cleanup = () => {
-      if (timer) clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-    };
-    const finish = (action) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      action();
-    };
-    const fail2 = (message2) => {
-      finish(() => {
-        void killProcessTree(child).finally(() => reject(new Error(message2)));
-      });
-    };
-    onAbort = () => fail2("shell command cancelled");
-    if (signal) {
-      if (signal.aborted) onAbort();
-      else signal.addEventListener("abort", onAbort, { once: true });
-    }
-    if (timeoutMs > 0) {
-      timer = setTimeout(() => fail2(`shell command timed out after ${timeoutMs}ms`), timeoutMs);
-    }
-    child.stdout.on("data", (chunk) => {
-      stdout = append(stdout, chunk, maxBuffer);
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr = append(stderr, chunk, maxBuffer);
-    });
-    child.on("error", (error) => {
-      finish(() => resolve2({ exitCode: 1, stdout, stderr: message(error) }));
-    });
-    child.on("close", (code, closeSignal) => {
-      finish(() => resolve2({
-        exitCode: code ?? 1,
-        stdout,
-        stderr: closeSignal ? `killed by ${closeSignal}` : stderr
-      }));
-    });
-  });
-}
 function createBuiltinToolDefinitions(config = {}) {
   const normalized = normalizeConfig(config);
   const disabled = new Set(normalized.disabled);
@@ -2320,6 +2363,7 @@ function toToolError(error) {
 var ToolsService = class extends Service {
   static provide = "tools";
   _tools = /* @__PURE__ */ new Map();
+  _guards = /* @__PURE__ */ new Set();
   _policy;
   constructor(ctx, config = {}) {
     super(ctx, "tools");
@@ -2337,13 +2381,27 @@ var ToolsService = class extends Service {
         throw new ToolAlreadyRegisteredError(name2);
       }
       this._tools.set(name2, definition2);
+      this.ctx.emit("tools/change");
       return () => {
         this._tools.delete(name2);
+        this.ctx.emit("tools/change");
       };
     }, `ctx.tools.register(${JSON.stringify(name2)})`);
   }
   unregister(name2) {
-    return this._tools.delete(name2);
+    const removed = this._tools.delete(name2);
+    if (removed) this.ctx.emit("tools/change");
+    return removed;
+  }
+  /** Register a monotonic guard evaluated after pre-execute policy. */
+  guard(guard) {
+    if (typeof guard !== "function") throw new TypeError("tool guard must be a function");
+    return this.ctx.fiber.effect(() => {
+      this._guards.add(guard);
+      return () => {
+        this._guards.delete(guard);
+      };
+    }, "ctx.tools.guard()");
   }
   has(name2) {
     return this._tools.has(name2);
@@ -2357,58 +2415,99 @@ var ToolsService = class extends Service {
   async execute(name2, input, options = {}) {
     const tool = this._tools.get(name2);
     if (!tool) throw new ToolNotFoundError(name2);
-    const request = {
+    let request = {
       tool,
       name: name2,
       input,
       options,
       startedAt: Date.now()
     };
-    await this.ctx.parallel("tools/pre-execute", request);
-    const policy = request.tool.policy;
-    const authorizer = policy?.authorizer ?? this._policy.authorizer;
-    if (authorizer) {
-      const allowed = await authorizer(request);
-      if (!allowed) {
-        return this._finish(
-          request,
-          this._failure(
-            request,
-            new ToolAuthorizationError(`tool authorization denied: ${name2}`)
-          )
-        );
-      }
-    }
-    const validator = policy?.validator ?? this._policy.validator;
+    let preError;
     try {
-      await validator(request.input, request.tool);
+      const resolved = await this.ctx.waterfallAsync(
+        "tools/pre-execute",
+        request,
+        async (payload) => {
+          await this._applyPolicy(payload);
+          return payload;
+        }
+      );
+      if (!resolved) {
+        throw new ToolAuthorizationError(`tool rejected by tools/pre-execute: ${name2}`);
+      }
+      request = resolved;
+      const denial = await this._checkGuards(request);
+      if (denial) throw new ToolAuthorizationError(denial);
     } catch (error) {
-      return this._finish(request, this._failure(request, error));
+      preError = error;
     }
-    let output;
-    let caught;
+    let result;
     try {
-      await this.ctx.parallel("tools/execute", request);
-      output = await tool.execute(request.input, request.options);
+      if (!preError) {
+        result = await this.ctx.waterfallAsync(
+          "tools/execute",
+          request,
+          async (payload) => {
+            const output = await payload.tool.execute(payload.input, payload.options);
+            return this._success(payload, output);
+          }
+        );
+      }
     } catch (error) {
-      caught = error;
+      result = this._failure(request, error);
     }
-    const result = caught === void 0 ? this._success(request, output) : this._failure(request, caught);
-    const truncator = policy?.truncator ?? this._policy.truncator;
-    if (truncator) {
-      try {
-        return this._finish(request, await truncator(result, request));
-      } catch (error) {
-        return this._finish(request, this._failure(request, error));
-      }
+    if (preError) result = this._failure(request, preError);
+    if (!result) {
+      result = this._failure(
+        request,
+        new Error("tools/execute did not return a tool result")
+      );
     }
-    return this._finish(request, result);
+    try {
+      const normalized = await this.ctx.waterfallAsync(
+        "tools/post-execute",
+        { request, result },
+        async (payload) => {
+          const policy = payload.request.tool.policy;
+          const truncator = policy?.truncator ?? this._policy.truncator;
+          return truncator ? await truncator(payload.result, payload.request) : payload.result;
+        }
+      );
+      if (normalized && typeof normalized.ok === "boolean") result = normalized;
+    } catch (error) {
+      result = this._failure(request, error);
+    }
+    return this._finish(
+      request,
+      result ?? this._failure(
+        request,
+        new Error("tools/execute did not return a tool result")
+      )
+    );
   }
   async _finish(request, result) {
-    await this.ctx.parallel("tools/post-execute", { request, result });
     await this.ctx.parallel("tools/result", { request, result });
     return result;
   }
+  async _applyPolicy(request) {
+    const policy = request.tool.policy;
+    const authorizer = policy?.authorizer ?? this._policy.authorizer;
+    if (authorizer) {
+      const allowed = await authorizer(request);
+      if (!allowed) {
+        throw new ToolAuthorizationError(`tool authorization denied: ${request.name}`);
+      }
+    }
+    const validator = policy?.validator ?? this._policy.validator;
+    if (validator) await validator(request.input, request.tool);
+  }
+  async _checkGuards(request) {
+    for (const guard of this._guards) {
+      const denial = await guard(request);
+      if (denial) return denial;
+    }
+    return void 0;
+  }
   _validate(definition2) {
     if (!definition2 || typeof definition2.schema?.name !== "string" || !definition2.schema.name) {
       throw new TypeError("tool definition requires a non-empty schema.name");
@@ -2427,6 +2526,7 @@ var ToolsService = class extends Service {
       durationMs: Date.now() - request.startedAt
     };
     if (request.options.callId) result.callId = request.options.callId;
+    this._applyConcludesTurn(request, result);
     return result;
   }
   _failure(request, error) {
@@ -2441,6 +2541,12 @@ var ToolsService = class extends Service {
     if (request.options.callId) result.callId = request.options.callId;
     return result;
   }
+  _applyConcludesTurn(request, result) {
+    const staticDeclares = request.tool.metadata?.concludesTurn;
+    if (staticDeclares === true || request.options.concludesTurn === true) {
+      result.concludesTurn = true;
+    }
+  }
 };
 var tools = {
   name: "tools",
@@ -2461,6 +2567,7 @@ export {
   builtinTools,
   createBuiltinToolDefinitions,
   evaluateExpression,
+  localExecutionProvider,
   name,
   resolveInside,
   tools,