@humwick/runner 0.0.0-stage → 0.130.0

package/LICENSE

@@ -0,0 +1,167 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management
+System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations than an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+Required Notice: Copyright 2026 Exelerus AB
+Licensor Line of Business: provider-independent runtimes and coordination software for teams of AI agents

package/agent-bin/agent-relay-browser

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Humwick #3489: `humwick browser` from the release this agent's runner belongs to, never an older
+# install a login shell puts first on PATH. Checkout: <root>/runner/agent-bin -> <root>/src;
+# npm: node_modules/@humwick/runner/agent-bin -> node_modules/@humwick/server/src.
+here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P) || exit 1
+for cli in "$here/../../src/index.ts" "$here/../../server/src/index.ts"; do
+  if [ -f "$cli" ]; then exec "${AGENT_RELAY_BUN_BIN:-bun}" run --no-env-file "$cli" browser "$@"; fi
+done
+echo "agent-relay-browser: no Humwick CLI next to $here" >&2
+exit 127

package/agent-bin/humwick

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Humwick #3470: `humwick browser` from the release this agent's runner belongs to, never an older
+# install a login shell puts first on PATH. Checkout: <root>/runner/agent-bin -> <root>/src;
+# npm: node_modules/@humwick/runner/agent-bin -> node_modules/@humwick/server/src.
+here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P) || exit 1
+for cli in "$here/../../src/index.ts" "$here/../../server/src/index.ts"; do
+  if [ -f "$cli" ]; then exec "${AGENT_RELAY_BUN_BIN:-bun}" run --no-env-file "$cli" "$@"; fi
+done
+echo "humwick: no CLI next to $here" >&2
+exit 127

package/hooks/fff-search-redirect/fff-search-redirect.cjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+"use strict";
+
+const { accessSync, constants, realpathSync } = require("node:fs");
+const { spawnSync } = require("node:child_process");
+const { isAbsolute, relative, resolve } = require("node:path");
+
+// Intentionally conservative: uncertain shell syntax, option parsing, paths, or
+// repository detection always leaves Bash alone.
+function wordsOf(command) {
+  if (command.length > 8192 || /[\n`$]/.test(command)) return null;
+  const words = [];
+  let word = "";
+  let quote = "";
+  let active = false;
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i];
+    if (!quote && /[|;&<>(){}]/.test(ch)) return null;
+    if (ch === "\\") {
+      if (++i >= command.length) return null;
+      word += command[i];
+      active = true;
+    } else if (quote) {
+      if (ch === quote) quote = "";
+      else word += ch;
+    } else if (ch === "'" || ch === '"') {
+      quote = ch;
+      active = true;
+    } else if (/\s/.test(ch)) {
+      if (active) words.push(word);
+      word = "";
+      active = false;
+    } else {
+      word += ch;
+      active = true;
+    }
+  }
+  if (quote) return null;
+  if (active) words.push(word);
+  return words.length && words.length <= 100 ? words : null;
+}
+
+function repoPath(target, cwd, root) {
+  if (!target || /[?*\[\]{}]/.test(target) || target === "-") return false;
+  try {
+    const realRoot = realpathSync(root);
+    const realTarget = realpathSync(isAbsolute(target) ? target : resolve(cwd, target));
+    const rel = relative(realRoot, realTarget);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+  } catch {
+    return false;
+  }
+}
+
+function candidateWords(command) {
+  const words = wordsOf(command);
+  return words && ["grep", "rg", "find"].includes(words[0]) ? words : null;
+}
+
+function classifyStandaloneSearch(command, cwd, root, words = candidateWords(command)) {
+  if (!words) return null;
+  const [program, ...args] = words;
+  if (program === "find") {
+    const expressionAt = args.findIndex((arg) => arg.startsWith("-") || arg === "!" || arg === "(");
+    const paths = expressionAt < 0 ? args : args.slice(0, expressionAt);
+    const expression = expressionAt < 0 ? [] : args.slice(expressionAt);
+    if (!paths.length || !expression.some((arg) => ["-name", "-iname", "-path", "-ipath"].includes(arg))) return null;
+    if (expression.some((arg) => ["-exec", "-execdir", "-delete", "-ok", "-okdir", "-fprint", "-fprintf"].includes(arg))) return null;
+    return paths.every((path) => repoPath(path, cwd, root)) ? "mcp__fff__find_files" : null;
+  }
+  let recursive = program === "rg";
+  let files = false;
+  let patterns = 0;
+  const positionals = [];
+  const values = new Set(program === "grep" ? ["-e", "--regexp", "-A", "-B", "-C", "--include", "--exclude", "--exclude-dir"] : ["-e", "--regexp", "-g", "--glob", "-t", "--type", "-A", "-B", "-C"]);
+  const flags = program === "grep" ? /^[rRinHhIlLqsvwxoEcF]+$/ : /^[niHlLqsvwocF]+$/;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") { positionals.push(...args.slice(i + 1)); break; }
+    if (values.has(arg)) {
+      if (++i >= args.length) return null;
+      if (arg === "-e" || arg === "--regexp") patterns += 1;
+      continue;
+    }
+    if (arg === "--files" && program === "rg") { files = true; continue; }
+    if (arg.startsWith("--")) {
+      if (/^--(line-number|ignore-case|files-with-matches|no-heading|hidden|fixed-strings|recursive)$/.test(arg)) {
+        if (arg === "--recursive") recursive = true;
+        continue;
+      }
+      if (/^--(glob|type|regexp|include|exclude)=/.test(arg)) {
+        if (arg.startsWith("--regexp=")) patterns += 1;
+        continue;
+      }
+      return null;
+    }
+    if (arg.startsWith("-") && arg !== "-") {
+      if (!flags.test(arg.slice(1))) return null;
+      if (program === "grep" && /[rR]/.test(arg)) recursive = true;
+      continue;
+    }
+    positionals.push(arg);
+  }
+  if (!recursive) return null;
+  if (files) return (positionals.length ? positionals : ["."]).every((path) => repoPath(path, cwd, root)) ? "mcp__fff__find_files" : null;
+  if (!patterns && !positionals.length) return null;
+  const paths = patterns ? positionals : positionals.slice(1);
+  if (program === "grep" && !paths.length) return null;
+  if (!paths.every((path) => repoPath(path, cwd, root))) return null;
+  return patterns > 1 ? "mcp__fff__multi_grep" : "mcp__fff__grep";
+}
+
+function fffBinary(env) { return env.AGENT_RELAY_FFF_MCP_BINARY; }
+
+function decide(payload, env = process.env, runGit = spawnSync) {
+  try {
+  if (payload?.tool_name !== "Bash" || typeof payload?.tool_input?.command !== "string") return null;
+  const command = payload.tool_input.command;
+  const words = candidateWords(command);
+  if (!words) return null;
+  const binary = fffBinary(env);
+  if (!binary || !isAbsolute(binary)) return null;
+  try { accessSync(binary, constants.X_OK); } catch { return null; }
+  const cwd = payload.cwd;
+  if (typeof cwd !== "string") return null;
+  const git = runGit("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", timeout: 300, stdio: ["ignore", "pipe", "ignore"] });
+  if (git.status !== 0 || !git.stdout?.trim()) return null;
+  const tool = classifyStandaloneSearch(command, cwd, git.stdout.trim(), words);
+  if (!tool) return null;
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: `Use ${tool} for this repository search (load with ToolSearch select:mcp__fff__find_files,mcp__fff__grep,mcp__fff__multi_grep).`,
+    },
+  };
+  } catch {
+    return null;
+  }
+}
+
+if (require.main === module) {
+  // Finish before Claude's five-second hook deadline even if stdin stalls.
+  setTimeout(() => process.exit(0), 4500).unref();
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    input += chunk;
+    if (input.length > 131072) process.exit(0);
+  });
+  process.stdin.on("end", () => {
+    try {
+      const decision = decide(JSON.parse(input));
+      if (decision) process.stdout.write(JSON.stringify(decision) + "\n");
+    } catch {
+      // Never trap Bash on a malformed provider payload or hook failure.
+    }
+  });
+}
+
+module.exports = { classifyStandaloneSearch, decide };

package/hooks/fff-search-redirect/hooks.json

@@ -0,0 +1,13 @@
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${HOOK_DIR}/fff-search-redirect.cjs\"",
+        "timeout": 5,
+        "suppressOutput": true
+      }]
+    }]
+  }
+}

package/hooks/rg-r-guard/hooks.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${HOOK_DIR}/rg-r-guard.cjs\"",
+            "timeout": 5,
+            "statusMessage": "Checking ripgrep replace guard",
+            "suppressOutput": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/rg-r-guard/rg-r-guard.cjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+"use strict";
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  input += chunk;
+});
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(input || "{}");
+  } catch {
+    return;
+  }
+
+  const toolName = String(payload.tool_name || payload.toolName || "").toLowerCase();
+  const command = String(payload.tool_input?.command || payload.toolInput?.command || "");
+  if (toolName !== "bash" || !command || !containsRipgrepReplaceFootgun(command)) return;
+
+  const reason = "Blocked: `rg -r` is ripgrep replace, not recursive search. Use `rg PATTERN PATH` for search, or `rg --replace REPLACEMENT PATTERN` only when replacement output is intentional.";
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.stdout.write("\n");
+});
+
+function containsRipgrepReplaceFootgun(command) {
+  for (const segment of splitShellSegments(command)) {
+    const words = shellWords(segment);
+    for (let i = 0; i < words.length; i += 1) {
+      const word = basename(words[i] || "");
+      if (word !== "rg" && word !== "ripgrep") continue;
+      if (ripgrepArgsUseReplace(words.slice(i + 1))) return true;
+    }
+  }
+  return false;
+}
+
+function ripgrepArgsUseReplace(args) {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] || "";
+    if (arg === "--") return false;
+    if (arg === "--replace" || arg.startsWith("--replace=")) return true;
+    if (arg === "-r") return true;
+    if (/^-([A-Za-z]*r[A-Za-z]*|[A-Za-z]*r=.+)$/.test(arg)) return true;
+  }
+  return false;
+}
+
+function splitShellSegments(text) {
+  const segments = [];
+  let current = "";
+  let quote = "";
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      current += ch;
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === "'" || ch === "\"") {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+    // Command-substitution + grouping boundaries (`$(rg -r …)`, backtick `` `rg -r …` ``,
+    // subshells) split into their own segments so the inner command is scanned on its own
+    // (basename of `$(rg` ≠ rg otherwise) and its args never bleed into the outer command's
+    // scan. Only fires OUTSIDE quotes — a single/double-quoted literal is left intact, matching
+    // the tokenizer's existing quote handling. Known gap: substitution inside double quotes
+    // ("$(rg -r x)") is still treated as an opaque quoted word.
+    if (ch === "(" || ch === ")" || ch === "`") {
+      if (current.trim()) segments.push(current);
+      current = "";
+      continue;
+    }
+    if (ch === ";" || ch === "|" || ch === "&" || ch === "\n") {
+      if (current.trim()) segments.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) segments.push(current);
+  return segments;
+}
+
+function shellWords(text) {
+  const words = [];
+  let current = "";
+  let quote = "";
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = "";
+      else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === "\"") {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (current) {
+        words.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (current) words.push(current);
+  return words;
+}
+
+function basename(value) {
+  return value.split("/").pop() || value;
+}

package/hooks/web-tools-redirect/hooks.json

@@ -0,0 +1,13 @@
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "WebSearch|WebFetch",
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${HOOK_DIR}/web-tools-redirect.cjs\"",
+        "timeout": 5,
+        "suppressOutput": true
+      }]
+    }]
+  }
+}

package/hooks/web-tools-redirect/web-tools-redirect.cjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+"use strict";
+
+const { createHash } = require("node:crypto");
+const { readFileSync, writeFileSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+
+// Answers built-in WebSearch/WebFetch with a redirect to Relay search/the local-first page reader.
+// Only provisioned tools are redirected. Page reads may retry natively; search stays on Relay.
+const REDIRECTS = {
+  WebSearch: {
+    tool: "brave",
+    use: "Relay web_search on the agent-relay MCP server (Tavily first, budget-capped Brave fallback)",
+    load: ["web_search"],
+  },
+  WebFetch: {
+    tool: "jina",
+    use: "the self-hosted page reader mcp__callmux__fetch__fetch first (max_length and start_index for chunks). Only if it fails or returns unusable JS-heavy content, use keyless Jina mcp__callmux__jina__read_url with url only (no question or API key)",
+    load: ["mcp__callmux__fetch__fetch", "mcp__callmux__jina__read_url"],
+  },
+};
+const MAX_REMEMBERED = 100;
+
+function enabledTools(env) {
+  return new Set(String(env.AGENT_RELAY_WEB_TOOLS || "").split(",").map((part) => part.trim()).filter(Boolean));
+}
+
+function stateFile(env, sessionId) {
+  const safe = typeof sessionId !== "string" ? "" : sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 80);
+  return safe ? join(env.AGENT_RELAY_SCRATCH_DIR || tmpdir(), `web-tools-redirect-${safe}.json`) : null;
+}
+
+function decide(payload, env = process.env) {
+  try {
+    const redirect = REDIRECTS[payload?.tool_name];
+    if (!redirect || !enabledTools(env).has(redirect.tool)) return null;
+    if (payload.tool_name === "WebSearch") return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse", permissionDecision: "deny",
+        permissionDecisionReason: `Use ${redirect.use} instead (discover with ToolSearch web_search). Report a Relay search error if unavailable.`,
+      },
+    };
+    const file = stateFile(env, payload.session_id);
+    if (!file) return null;
+    const key = createHash("sha256").update(`${payload.tool_name}\0${JSON.stringify(payload.tool_input ?? null)}`).digest("hex").slice(0, 32);
+    let seen = [];
+    try { seen = JSON.parse(readFileSync(file, "utf8")); } catch {}
+    if (!Array.isArray(seen)) seen = [];
+    if (seen.includes(key)) return null;
+    // Unrecorded means the retry could never pass: allow rather than trap the agent.
+    writeFileSync(file, JSON.stringify([...seen, key].slice(-MAX_REMEMBERED)), { mode: 0o600 });
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: `Use ${redirect.use} instead (load with ToolSearch select:${redirect.load.join(",")}). If it fails or is unavailable, repeat this exact ${payload.tool_name} call and it will run.`,
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+if (require.main === module) {
+  // Finish before Claude's five-second hook deadline even if stdin stalls.
+  setTimeout(() => process.exit(0), 4500).unref();
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    input += chunk;
+    if (input.length > 131072) process.exit(0);
+  });
+  process.stdin.on("end", () => {
+    try {
+      const decision = decide(JSON.parse(input));
+      if (decision) process.stdout.write(JSON.stringify(decision) + "\n");
+    } catch {
+      // Never trap a web call on a malformed provider payload or hook failure.
+    }
+  });
+}
+
+module.exports = { decide, REDIRECTS };