wtagent 0.1.0-alpha.0

package/src/tools/registry.js

@@ -0,0 +1,129 @@
+import { ToolValidationError } from "../shared/errors.js";
+
+export class ToolRegistry {
+  #definitions = new Map();
+
+  register(definition) {
+    if (!definition?.name || typeof definition.execute !== "function") {
+      throw new Error("Tool definition requires name and execute.");
+    }
+    if (this.#definitions.has(definition.name)) {
+      throw new Error(`Duplicate tool: ${definition.name}`);
+    }
+    this.#definitions.set(definition.name, definition);
+    return this;
+  }
+
+  list() {
+    return [...this.#definitions.values()].map((definition) => ({
+      name: definition.name,
+      description: definition.description,
+      inputDescription: definition.inputDescription,
+      risk: definition.risk ?? "execute",
+    }));
+  }
+
+  validate(toolCall) {
+    const definition = this.#definitions.get(toolCall.name);
+    if (!definition) {
+      throw new ToolValidationError(`Unknown tool: ${toolCall.name}`);
+    }
+
+    const result = definition.inputSchema.safeParse(toolCall.args ?? {});
+    if (!result.success) {
+      throw new ToolValidationError(
+        `Invalid arguments for ${toolCall.name}: ${result.error.message}`,
+        { details: result.error.issues },
+      );
+    }
+
+    return {
+      ...toolCall,
+      args: result.data,
+      definition,
+    };
+  }
+
+  async execute(preparedCall, context) {
+    const execution = Promise.resolve().then(
+      () => preparedCall.definition.execute(preparedCall.args, context),
+    );
+    const timeoutMs = preparedCall.definition.managesTimeout
+      ? null
+      : Number(context.toolTimeoutMs);
+    let timer = null;
+
+    try {
+      let outcome;
+      if (Number.isSafeInteger(timeoutMs) && timeoutMs > 0) {
+        outcome = await Promise.race([
+          execution.then(
+            (result) => ({ type: "result", result }),
+            (error) => ({ type: "error", error }),
+          ),
+          new Promise((resolve) => {
+            timer = setTimeout(
+              () => resolve({ type: "timeout" }),
+              timeoutMs,
+            );
+            timer.unref?.();
+          }),
+        ]);
+      } else {
+        outcome = await execution.then(
+          (result) => ({ type: "result", result }),
+          (error) => ({ type: "error", error }),
+        );
+      }
+
+      if (outcome.type === "timeout") {
+        execution.catch(() => undefined);
+        const completionUnknown = preparedCall.definition.risk !== "read";
+        return {
+          callId: preparedCall.id,
+          name: preparedCall.name,
+          ok: false,
+          message: completionUnknown
+            ? (
+              `Tool exceeded the ${timeoutMs}ms runtime guard. `
+              + "The operation may still complete because it does not support "
+              + "hard cancellation; completion is unknown."
+            )
+            : `Tool exceeded the ${timeoutMs}ms runtime guard.`,
+          meta: {
+            timedOut: true,
+            completionUnknown,
+            recoverable: true,
+          },
+        };
+      }
+
+      if (outcome.type === "error") {
+        throw outcome.error;
+      }
+
+      const result = outcome.result;
+      return {
+        callId: preparedCall.id,
+        name: preparedCall.name,
+        ok: Boolean(result.ok),
+        message: result.message ?? "",
+        data: result.data,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        meta: result.meta,
+      };
+    } catch (error) {
+      return {
+        callId: preparedCall.id,
+        name: preparedCall.name,
+        ok: false,
+        message: error.message,
+        stderr: error.stack,
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+

package/src/tools/safe-env.js

@@ -0,0 +1,67 @@
+const SAFE_ENV_NAMES = new Set([
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TMP",
+  "TEMP",
+  "TMPDIR",
+  "SYSTEMROOT",
+  "COMSPEC",
+  "PATHEXT",
+  "WINDIR",
+  "TERM",
+  "COLORTERM",
+  "CI",
+  "NODE_ENV",
+  "NO_COLOR",
+  "FORCE_COLOR",
+  // Windows-specific locations that common tools (npm, git, node, ...)
+  // need to locate config, caches, and the user profile.
+  "APPDATA",
+  "LOCALAPPDATA",
+  "USERPROFILE",
+  "PROGRAMDATA",
+  "PROGRAMFILES",
+  "PROGRAMFILES(X86)",
+  "PROGRAMW6432",
+  "PUBLIC",
+  "HOMEDRIVE",
+  "HOMEPATH",
+  "NUMBER_OF_PROCESSORS",
+  "OS",
+  "PROCESSOR_ARCHITECTURE",
+]);
+
+const SENSITIVE_NAME = /(TOKEN|SECRET|PASSWORD|PASSWD|API[_-]?KEY|PRIVATE[_-]?KEY|COOKIE|CREDENTIAL|AUTH)/i;
+
+export function buildToolEnvironment({ inheritSensitive = false } = {}) {
+  if (inheritSensitive) {
+    return { ...process.env };
+  }
+
+  const environment = {};
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value == null || SENSITIVE_NAME.test(name)) {
+      continue;
+    }
+    // Environment variable names are case-insensitive on Windows; normalize
+    // to upper case for the allow-list lookup while preserving the original
+    // key in the returned object.
+    const upper = name.toUpperCase();
+    if (
+      SAFE_ENV_NAMES.has(upper)
+      || name.startsWith("npm_")
+      || name.startsWith("NPM_")
+      || name.startsWith("XDG_")
+    ) {
+      environment[name] = value;
+    }
+  }
+  return environment;
+}
+

package/src/tools/terminal-exec.js

@@ -0,0 +1,118 @@
+import { spawn } from "node:child_process";
+import { buildToolEnvironment } from "./safe-env.js";
+import { killProcessTree } from "./process-utils.js";
+
+function appendLimited(current, chunk, maxBytes) {
+  const next = current + chunk.toString("utf8");
+  if (Buffer.byteLength(next, "utf8") <= maxBytes) {
+    return { text: next, truncated: false };
+  }
+  return {
+    text: next.slice(0, maxBytes),
+    truncated: true,
+  };
+}
+
+export async function runProgram({
+  program,
+  argv = [],
+  cwd,
+  timeoutMs,
+  maxOutputBytes,
+  inheritSensitiveEnv = false,
+  onOutput,
+}) {
+  return await new Promise((resolve) => {
+    const startedAt = Date.now();
+    let stdout = "";
+    let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let timedOut = false;
+    let settled = false;
+    let terminationGuard = null;
+    let outputQueue = Promise.resolve();
+
+    const child = spawn(program, argv, {
+      cwd,
+      env: buildToolEnvironment({ inheritSensitive: inheritSensitiveEnv }),
+      shell: false,
+      detached: process.platform !== "win32",
+      windowsHide: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    const finish = async (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(terminationGuard);
+      await outputQueue;
+      resolve({
+        ...result,
+        stdout,
+        stderr,
+        timedOut,
+        truncated: stdoutTruncated || stderrTruncated,
+        durationMs: Date.now() - startedAt,
+      });
+    };
+
+    const enqueueOutput = (output) => {
+      outputQueue = outputQueue
+        .then(() => onOutput?.(output))
+        .catch(() => undefined);
+    };
+
+    child.stdout.on("data", (chunk) => {
+      const appended = appendLimited(stdout, chunk, maxOutputBytes);
+      stdout = appended.text;
+      stdoutTruncated ||= appended.truncated;
+      enqueueOutput({ stream: "stdout", chunk: chunk.toString("utf8") });
+    });
+    child.stderr.on("data", (chunk) => {
+      const appended = appendLimited(stderr, chunk, maxOutputBytes);
+      stderr = appended.text;
+      stderrTruncated ||= appended.truncated;
+      enqueueOutput({ stream: "stderr", chunk: chunk.toString("utf8") });
+    });
+
+    child.once("error", (error) => {
+      void finish({
+        ok: false,
+        exitCode: null,
+        signal: null,
+        error,
+      });
+    });
+    child.once("close", (exitCode, signal) => {
+      void finish({
+        ok: !timedOut && exitCode === 0,
+        exitCode,
+        signal,
+      });
+    });
+
+    const timer = setTimeout(async () => {
+      timedOut = true;
+      await killProcessTree(child.pid);
+
+      if (settled) {
+        return;
+      }
+
+      terminationGuard = setTimeout(() => {
+        void finish({
+          ok: false,
+          exitCode: null,
+          signal: null,
+          completionUnknown: true,
+        });
+      }, 1_000);
+      terminationGuard.unref?.();
+    }, timeoutMs);
+    timer.unref?.();
+  });
+}