@humwick/runner 0.0.0-stage → 0.130.1

package/plugins/claude/hooks/subagent-skill-policy.cjs

@@ -0,0 +1,160 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { isRecord, isPathWithinBase } = require('@humwick/sdk');
+
+function stat(file) {
+  try { return fs.statSync(file); }
+  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return; throw error; }
+}
+function json(file) {
+  if (!stat(file)) return {};
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!isRecord(value)) throw new Error(`Expected object in ${file}`);
+  return value;
+}
+function ancestors(directory) {
+  const dirs = [];
+  for (let dir = path.resolve(directory); ; dir = path.dirname(dir)) {
+    dirs.push(dir);
+    if (path.dirname(dir) === dir) return dirs;
+  }
+}
+
+// Cache the byte cursor beside the native transcript; resumed sessions retain discovery history.
+// Only complete JSONL rows advance the cursor. Concurrent readers may repeat work, never skip it.
+async function discoveredDirectories(payload) {
+  if (!payload.transcript_path || !stat(payload.transcript_path)) return [];
+  const transcript = payload.transcript_path, info = fs.statSync(transcript);
+  const cachePath = `${transcript}.relay-skill-dirs.json`;
+  let state = json(cachePath);
+  if (state.ino !== info.ino || state.offset > info.size) state.offset = 0;
+  const dirs = new Set(state.directories || []);
+  const start = state.offset || 0;
+  if (info.size - start > 64 * 1024 * 1024) throw new Error('skill discovery transcript exceeds incremental read budget');
+  let offset = start, pending = Buffer.alloc(0);
+  if (info.size > start) for await (const chunk of fs.createReadStream(transcript, { start, end: info.size - 1 })) {
+    pending = Buffer.concat([pending, chunk]);
+    let end;
+    while ((end = pending.indexOf(10)) >= 0) {
+      const line = pending.subarray(0, end).toString('utf8');
+      offset += end + 1; pending = pending.subarray(end + 1);
+      if (!line.trim()) continue;
+      const row = JSON.parse(line);
+      if (row.cwd) dirs.add(path.resolve(row.cwd));
+      for (const block of Array.isArray(row.message?.content) ? row.message.content : []) {
+        if (block.type !== 'tool_use' || !['Read', 'Edit', 'Write', 'NotebookEdit', 'Glob', 'Grep'].includes(block.name)) continue;
+        const input = block.input || {}, file = input.file_path || input.notebook_path || input.path;
+        if (typeof file === 'string') dirs.add(['Glob', 'Grep'].includes(block.name) ? path.resolve(row.cwd || payload.cwd, file) : path.dirname(path.resolve(row.cwd || payload.cwd, file)));
+      }
+      if (dirs.size > 4096) throw new Error('skill discovery directory budget exceeded');
+    }
+    if (pending.length > 8 * 1024 * 1024) throw new Error('skill discovery transcript row too large');
+  }
+  const temporary = `${cachePath}.${process.pid}`;
+  try { fs.writeFileSync(temporary, JSON.stringify({ ino: info.ino, offset, directories: [...dirs] })); fs.renameSync(temporary, cachePath); }
+  finally { fs.rmSync(temporary, { force: true }); }
+  return [...dirs];
+}
+
+exports.skillDenial = async function skillDenial(payload, name) {
+  if (typeof name !== 'string' || !name.trim()) return 'cannot resolve an unnamed skill';
+  const launch = skillSources();
+  const cwd = path.resolve(payload.cwd || process.cwd()), initialCwd = launch.cwd || cwd;
+  const sources = launch.sources || ['user', 'project', 'local'];
+  const home = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  const roots = new Set(), settings = [];
+  if (sources.includes('user')) { roots.add(home); settings.push(json(path.join(home, 'settings.json'))); }
+  const directories = [cwd, initialCwd, ...(launch.directories || []).map((dir) => path.resolve(initialCwd, dir)), ...await discoveredDirectories(payload)];
+  for (const directory of directories) for (const parent of ancestors(directory)) {
+    const root = path.join(parent, '.claude');
+    if (sources.includes('project') || sources.includes('local')) roots.add(root);
+  }
+  for (const root of [...roots].reverse()) {
+    if (sources.includes('project')) settings.push(json(path.join(root, 'settings.json')));
+    if (sources.includes('local')) settings.push(json(path.join(root, 'settings.local.json')));
+  }
+  settings.push(launch.settings || {});
+  const enabled = Object.assign({}, ...settings.map((setting) => setting.enabledPlugins || {}));
+  const overrides = Object.assign({}, ...settings.map((setting) => setting.skillOverrides || {}));
+  if (overrides[name] === 'off') return `skill ${name} is disabled`;
+  const plugins = new Set((launch.plugins || []).map((dir) => path.resolve(initialCwd, dir)));
+  const installed = json(path.join(home, 'plugins/installed_plugins.json')).plugins;
+  if (isRecord(installed)) for (const [id, entries] of Object.entries(installed)) {
+    if (enabled[id] !== true || !Array.isArray(entries)) continue;
+    for (const entry of entries) if (typeof entry.installPath === 'string' && (!entry.projectPath || isPathWithinBase(cwd, entry.projectPath))) plugins.add(path.resolve(home, entry.installPath));
+  }
+  const candidates = new Map(), visited = new Set();
+  let managed = false;
+  const header = Buffer.allocUnsafe(64 * 1024);
+  function inspectText(text, identity, fallbackName, prefix, overrideModel, size = text.length) {
+    let fields = {};
+    if (/^\uFEFF?---[^\S\r\n]*\r?\n/.test(text)) {
+      const match = /^\uFEFF?---[^\S\r\n]*\r?\n([\s\S]*?)\r?\n---(?:\s|$)/.exec(text);
+      if (!match) throw new Error(`Incomplete skill frontmatter in ${identity}`);
+      fields = Bun.YAML.parse(match[1]) || {};
+      if (!isRecord(fields)) throw new Error(`Invalid skill frontmatter in ${identity}`);
+    }
+    const resolvedName = typeof fields.name === 'string' ? fields.name : fallbackName;
+    const aliases = prefix.endsWith(':') ? [prefix + resolvedName, prefix + fallbackName] : [resolvedName, fallbackName, ...(prefix ? [prefix + ':' + resolvedName, prefix + ':' + fallbackName] : [])];
+    if (!aliases.includes(name)) return;
+    candidates.set(JSON.stringify([identity, overrideModel]), { ...fields, model: overrideModel ?? fields.model, digest: crypto.createHash('sha256').update(text).update(String(size)).digest('hex'), managed });
+  }
+  function inspect(file, commands, prefix = '', overrideName, overrideModel) {
+    const info = stat(file);
+    if (!info) return;
+    const canonical = fs.realpathSync(file), identity = JSON.stringify([canonical, commands, prefix, overrideName, overrideModel]);
+    if (visited.has(identity)) return;
+    visited.add(identity);
+    if (visited.size > 4096) throw new Error('skill resolution traversal budget exceeded');
+    if (info.isDirectory()) {
+      if (!commands && stat(path.join(file, 'SKILL.md'))) inspect(path.join(file, 'SKILL.md'), false, prefix);
+      else for (const entry of fs.readdirSync(file)) inspect(path.join(file, entry), commands, prefix);
+    } else if (info.isFile() && (commands ? file.endsWith('.md') : path.basename(file) === 'SKILL.md')) {
+      const fd = fs.openSync(file, 'r');
+      try { inspectText(header.subarray(0, fs.readSync(fd, header, 0, header.length, 0)).toString('utf8'), canonical, overrideName || (commands ? path.basename(file, '.md') : path.basename(path.dirname(file))), prefix, overrideModel, info.size); }
+      finally { fs.closeSync(fd); }
+    }
+  }
+  for (const root of roots) {
+    const prefix = root === home ? '' : path.relative(initialCwd, path.dirname(root)).split(path.sep).join('/');
+    managed = root === home;
+    inspect(path.join(root, 'skills'), false, prefix); inspect(path.join(root, 'commands'), true, prefix);
+    managed = false;
+  }
+  for (const plugin of plugins) {
+    const manifest = json(path.join(plugin, '.claude-plugin/plugin.json'));
+    if (typeof manifest.name !== 'string') throw new Error(`Cannot establish plugin namespace in ${plugin}`);
+    const prefix = `${manifest.name}:`;
+    inspect(path.join(plugin, 'skills'), false, prefix);
+    if (!stat(path.join(plugin, 'skills')) && manifest.skills === undefined) inspect(path.join(plugin, 'SKILL.md'), false, prefix);
+    if (manifest.commands === undefined) inspect(path.join(plugin, 'commands'), true, prefix);
+    for (const key of ['skills', 'commands']) {
+      const paths = manifest[key];
+      for (const file of typeof paths === 'string' ? [paths] : Array.isArray(paths) ? paths : []) {
+        if (typeof file !== 'string') throw new Error('Unsupported plugin skill path');
+        const absolute = path.resolve(plugin, file);
+        if (!isPathWithinBase(absolute, plugin)) throw new Error('Plugin skill path escapes its root');
+        inspect(absolute, key === 'commands', prefix);
+      }
+    }
+    if (isRecord(manifest.commands)) for (const [command, definition] of Object.entries(manifest.commands)) {
+      if (!isRecord(definition)) throw new Error('Unsupported plugin command');
+      if (typeof definition.source === 'string') inspect(path.resolve(plugin, definition.source), true, prefix, command, definition.model);
+      if (typeof definition.content === 'string') inspectText(definition.content, `${plugin}:${command}`, command, prefix, definition.model);
+    }
+  }
+  // #3706: the role-provisioned copy in the managed home and its identical repo source are one skill; differing same-name skills stay ambiguous.
+  const sourced = new Set([...candidates.values()].filter((entry) => !entry.managed).map((entry) => entry.digest));
+  for (const [key, entry] of candidates) if (entry.managed && sourced.has(entry.digest)) candidates.delete(key);
+  if (candidates.size !== 1) return `skill ${name} ${candidates.size ? 'resolves ambiguously' : 'cannot be resolved'}; refusing unverified execution`;
+  const skill = [...candidates.values()][0];
+  if (typeof skill.context === 'string' && skill.context.trim() === 'fork' && harnessSubagentsDisabled()) return 'Harness sub-agents are disabled. Start a Relay workflow or ask your coordinator';
+  if (typeof skill.context === 'string' && skill.context.trim() === 'fork' && (typeof skill.model !== 'string' || !skill.model.trim() || skill.model.trim() === 'inherit')) return `fork skill ${name} requires an explicit model under capped profiles`;
+};
+
+// #3470: standalone CJS config adapters; this file is shipped beside subagent-guard.cjs.
+function skillSources() { return JSON.parse(process.env.AGENT_RELAY_CLAUDE_SKILL_SOURCES || '{}'); }
+function harnessSubagentsDisabled() { return process.env.AGENT_RELAY_HARNESS_SUBAGENTS === '0'; }
+exports.harnessSubagentsDisabled = harnessSubagentsDisabled;

package/plugins/claude/hooks/subagent-start.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+# shellcheck source=/dev/null
+source "${PLUGIN_ROOT}/hooks/relay-status.sh"
+relay_install_hook_guard subagent-start
+
+payload="$(cat || true)"
+agent_id="$(relay_json_string_field agent_id "$payload")"
+agent_type="$(relay_json_string_field agent_type "$payload")"
+
+relay_post_status busy subagent "${agent_id:-subagent}" "$agent_type" "$agent_type"

package/plugins/claude/hooks/subagent-stop.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+# shellcheck source=/dev/null
+source "${PLUGIN_ROOT}/hooks/relay-status.sh"
+relay_install_hook_guard subagent-usage
+
+payload="$(cat || true)"
+agent_id="$(relay_json_string_field agent_id "$payload")"
+agent_type="$(relay_json_string_field agent_type "$payload")"
+
+if [ -n "${AGENT_RELAY_RUNNER_PORT:-}" ] && [ -n "$(relay_json_string_field agent_transcript_path "$payload")" ]; then
+  printf '%s' "$payload" | relay_post_json "$AGENT_RELAY_RUNNER_PORT" /subagent-usage 4 >/dev/null
+fi
+
+if [ "${AGENT_RELAY_CLAUDE_TRANSPORT:-}" != "stream-json" ]; then
+  relay_post_status idle subagent "${agent_id:-subagent}" "$agent_type" "$agent_type"
+fi

package/plugins/claude/hooks/user-prompt-submit.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard user-prompt-submit
+fired_at="$(relay_now_ms)"
+payload="$(cat || true)"
+# prompt_id (#1086): Claude's own native turn identifier for the prompt starting
+# now — the same UUID the Stop hook reports and the transcript stamps on every
+# entry of this turn. Passed as the busy report's `id` so the runner adopts it as
+# currentTurnId instead of minting a random UUID (runner-core.ts setProviderStatus).
+prompt_id="$(relay_json_string_field prompt_id "$payload")"
+relay_post_status busy "" "$prompt_id"
+# Mirror a terminal/TUI-typed prompt into the dashboard chat and start reasoning
+# tailing for this turn. No-op for prompts the runner injected (chat box / relay).
+relay_post_user_prompt "$payload" "$fired_at"
+# Re-surface the request-review reminder each turn while there is unmerged
+# committed work — so a long session can't "forget" to land it. Silent otherwise.
+relay_emit_additional_context UserPromptSubmit "$(relay_review_reminder_text || true)"

package/plugins/claude/hooks/wait-loop-guard.ts

@@ -0,0 +1,120 @@
+// #2993: a FOREGROUND wait (bare long `sleep`, or an until/while loop that only sleeps between checks) holds the
+// turn; the wait belongs in one detached relay_run. STRICT ALLOWLIST: the command must be exactly
+//   setup* ( sleep D | (until|while) CHECK; do (sleep D | echo|printf|date|true)+; done ) rest*
+// Anything else (loops doing work, `for`, nesting, `$(...)`, background `&`, unknown durations) is not matched,
+// so every parse doubt fails open to "allow".
+import { lexCommandLine, unwrapGroupCommand } from "@humwick/sdk/gate-run-classify";
+import { CONTROL_KEYWORDS, trustedFlatCommand } from "./shell-trust";
+
+const MIN_BARE_SLEEP_SECONDS = 30;
+// Loops re-check, so even short sleeps accumulate; below this it is a startup/readiness blip (`until nc -z …; sleep 1`).
+const MIN_LOOP_SLEEP_SECONDS = 5;
+const MAX_UNWRAP_DEPTH = 2;
+const SETUP = new Set(["cd", "pushd", "export", "echo", "printf", "date", "true", ":"]);
+const BODY_FILLER = new Set(["echo", "printf", "date", "true", ":"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const DURATION = /^(\d+(?:\.\d+)?)([smhd]?)$/;
+const UNIT_SECONDS: Record<string, number> = { "": 1, s: 1, m: 60, h: 3600, d: 86400 };
+// A lone `&` backgrounds the wait: it does not hold the turn. Also catches `&` inside quotes, which fails open too.
+// Not every wait-shaped text runs: `a || b` may skip b, and `<` feeds stdin (a reader loop, not a wait).
+const UNSURE_OPERATORS = /\|\||</;
+const SHELL_BINARIES = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+// Only these flag bundles are known to EXECUTE the -c script; `-n`, `--help`, `-o x` and anything unknown do not qualify.
+const EXECUTING_FLAGS = /^-[leuxi]+$/;
+const EXECUTING_C_FLAGS = /^-[leuxi]*c$/;
+const READERS = new Set(["read", "mapfile", "readarray"]);
+const BACKGROUND_AMP = /(?<![&>])&(?![&>])/;
+const LOOP_KEYWORDS = CONTROL_KEYWORDS.filter((word) => word !== "while" && word !== "until");
+const STRUCTURE_WORDS = new Set([...CONTROL_KEYWORDS, "do", "done", "{", "}", "(", ")", "[["]);
+
+/** Seconds of a plain `sleep D…` segment (`sleep 1m 30s` sums), or null when it is not one or any arg is not a literal. */
+function sleepSeconds(words: string[]): number | null {
+  if (words[0] !== "sleep" || words.length < 2) return null;
+  let total = 0;
+  for (const arg of words.slice(1)) {
+    const match = DURATION.exec(arg);
+    if (!match) return null;
+    total += Number(match[1]) * UNIT_SECONDS[match[2]!]!;
+  }
+  return total;
+}
+
+const isSetup = (words: string[]): boolean => SETUP.has(words[0]!) || words.every((word) => ASSIGNMENT.test(word));
+// The first word of a "rest" segment must not open/close structure we did not parse.
+const isPlainRest = (words: string[]): boolean => !STRUCTURE_WORDS.has(words[0]!);
+
+/** True when the segments are one allowlisted wait. */
+function isForegroundWait(segments: string[][]): boolean {
+  let i = 0;
+  while (i < segments.length && isSetup(segments[i]!)) i += 1;
+  const head = segments[i];
+  if (!head) return false;
+  let next: number;
+  if (head[0] === "sleep") {
+    const seconds = sleepSeconds(head);
+    if (seconds === null || seconds < MIN_BARE_SLEEP_SECONDS) return false;
+    next = i + 1;
+  } else if (head[0] === "until" || head[0] === "while") {
+    const checkStart = head.slice(1);
+    // `while [IFS= ]read …` consumes stdin; an empty check is malformed.
+    const checkCommand = checkStart.find((word) => !ASSIGNMENT.test(word));
+    if (!checkCommand || READERS.has(checkCommand)) return false;
+    let j = i + 1;
+    while (j < segments.length && segments[j]![0] !== "do") {
+      if (STRUCTURE_WORDS.has(segments[j]![0]!)) return false;
+      j += 1;
+    }
+    if (j >= segments.length) return false;
+    // `do` may carry the first body command (`do sleep 60`) or stand alone (multi-line form).
+    let sleeps = false;
+    let first = true;
+    for (; j < segments.length; j += 1) {
+      const words = first ? segments[j]!.slice(1) : segments[j]!;
+      first = false;
+      if (words.length === 1 && words[0] === "done") break;
+      if (words.length === 0) continue;
+      const seconds = sleepSeconds(words);
+      if (seconds !== null) {
+        if (seconds === 0) return false;
+        if (seconds >= MIN_LOOP_SLEEP_SECONDS) sleeps = true;
+      } else if (!BODY_FILLER.has(words[0]!)) {
+        return false;
+      }
+    }
+    if (j >= segments.length || !sleeps) return false;
+    next = j + 1;
+  } else {
+    return false;
+  }
+  return segments.slice(next).every(isPlainRest);
+}
+
+/** The script of `<shell> [-l|-e|-u|-x|-i…] -c '<script>'` — only an exact, known-executing wrapper; else undefined. */
+function executingShellScript(candidate: string): string | undefined {
+  const segments = lexCommandLine(candidate);
+  const words = segments[0] ?? [];
+  if (!SHELL_BINARIES.has((words[0] ?? "").split("/").pop()!.toLowerCase())) return undefined;
+  let i = 1;
+  while (i < words.length && EXECUTING_FLAGS.test(words[i]!)) i += 1;
+  if (words.length !== i + 2 || !EXECUTING_C_FLAGS.test(words[i]!)) return undefined;
+  return words[i + 1];
+}
+
+const TIMEOUT_PREFIX = /^\s*timeout\s+(?:-\S+\s+)*\S+\s+/;
+
+/** The deny reason for a foreground wait, or null (allow). `command` is the raw tool command text. */
+export function waitLoopDenial(command: string): string | null {
+  const flat = trustedFlatCommand(command, LOOP_KEYWORDS);
+  if (flat === null || BACKGROUND_AMP.test(flat) || UNSURE_OPERATORS.test(flat)) return null;
+  let candidate: string | undefined = flat;
+  for (let depth = 0; depth <= MAX_UNWRAP_DEPTH && candidate !== undefined; depth += 1) {
+    candidate = candidate.replace(TIMEOUT_PREFIX, ""); // `timeout 600 <cmd>` is transparent
+    if (isForegroundWait(lexCommandLine(candidate))) {
+      return "Do not hold the turn on a foreground wait. Run it with the relay_run MCP tool (detach: true, waitMs: 0) as ONE poll loop with a deadline "
+        + "(e.g. `end=$((SECONDS+1800)); until <check>; do [ $SECONDS -ge $end ] && exit 1; sleep 30; done`), then end your turn with no text; "
+        + `Relay wakes you once when it finishes. Command: ${command}`;
+    }
+    candidate = executingShellScript(candidate) ?? unwrapGroupCommand(candidate);
+  }
+  return null;
+}

package/plugins/claude/monitors/monitors.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "agent-relay-runner-monitor",
+    "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/monitors/relay-monitor.ts\"",
+    "description": "Agent Relay runner message delivery pipe"
+  }
+]