hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tools/effects.py

@@ -0,0 +1,724 @@
+"""
+Effect identity for the tool standard wave 2 (S3 idempotency, S5 per-resource
+budgets).
+
+Three things live here, all pure functions (no I/O except reading files that
+are about to be written, to hash them):
+
+1. The **effect key** (S3). The runtime derives it; the model never supplies
+   one:
+
+       key = sha256(effect, canonical_target, canonical_payload)
+
+   `canonical_target` comes from the registry's `target_on` fields: the
+   resolved absolute path for files (family "file", so write_file, edit_file
+   and a bash redirect to the same path share it), the recipients for an
+   email, the channel for Slack, title + start for a calendar event, and so
+   on. `canonical_payload` comes from the remaining `idempotent_on` fields.
+   For a whole-file write the payload is the sha256 of the file content (one
+   trailing newline run ignored, so `echo x > f` and write_file("x") agree).
+   The key is the same digest the agent-mode broker calls `payloadDigest`.
+
+2. **Bash file writes** (Q-T2). `bash_file_writes(command)` parses the simple
+   shell forms models use to write files: `>`/`>>` redirects (with echo,
+   printf, cat <<EOF), `tee [-a]`, `cp`/`mv` onto a path and `sed -i`. Each
+   becomes a FileWrite on the same "file:<abs path>" target as write_file.
+   Limits (documented in docs/TOOL-STANDARD.md): anything with variable or
+   command expansion in the target, `dd of=`, `install`, `rsync`, writes made
+   by scripts or programs the command runs (python -c, node -e, git ...),
+   `cd` changing the base directory, and subshell/eval tricks are not seen.
+
+3. **Resource identity** (S5). `resources(tool, args)` lists the things a
+   call touches: paths, URLs, message/event/plan/memory ids, and for bash the
+   path-like words of the command plus its text. `touches(r, missing)`
+   decides whether a call is still going after a resource that was just
+   reported not_found: the same path; the same basename anywhere under a home
+   directory (so an invented `/Users/<someone>/...` copy counts); a directory
+   that contains it below home (listing the folder to look for it); or, for
+   bash, the basename in the command text.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass
+from typing import Any, Iterable, List, Optional, Sequence, Tuple
+from urllib.parse import urlsplit, urlunsplit
+
+# Arguments whose value is a local path (resolved to an absolute path).
+PATH_FIELDS = ("path", "image_path", "file", "save_path", "attachments")
+# Arguments that identify a resource for the per-resource budget.
+RESOURCE_PATH_FIELDS = ("path", "image_path", "file", "attachments")
+RESOURCE_ID_FIELDS = ("message_id", "event_id", "plan_id", "memory_id")
+# Tools whose target is a whole file's content.
+FILE_CONTENT_TOOLS = {"write_file": "content"}
+# Tools that create the path they name; a not_found on that path earlier in
+# the turn does not block them (creating it is not searching for it). Their
+# other resources (a download URL) are still checked.
+CREATE_TOOLS = frozenset({"write_file", "download", "qr_code", "image_generate"})
+_RECIPIENT_FIELDS = ("to", "cc", "bcc", "recipient")
+MAX_HASH_BYTES = 50 * 1024 * 1024
+
+
+# ───────────────────────── canonical forms ─────────────────────────
+
+def home() -> str:
+    return os.path.realpath(os.path.expanduser("~"))
+
+
+def resolve_path(p: Any, base: Optional[str] = None) -> Optional[str]:
+    """Absolute, normalised, symlink-resolved path; None if not a usable path."""
+    if not isinstance(p, str) or not p.strip():
+        return None
+    p = p.strip()
+    for var in ("${HOME}", "$HOME"):
+        if p == var or p.startswith(var + "/"):
+            p = "~" + p[len(var):]
+    if "$" in p or "`" in p:
+        return None
+    p = os.path.expanduser(p)
+    if not os.path.isabs(p):
+        p = os.path.join(base or home(), p)
+    return os.path.realpath(os.path.normpath(p))
+
+
+def normalize_url(u: Any) -> Optional[str]:
+    if not isinstance(u, str) or not u.strip():
+        return None
+    try:
+        s = urlsplit(u.strip())
+    except ValueError:
+        return u.strip()
+    path = s.path.rstrip("/") or ""
+    return urlunsplit((s.scheme.lower(), s.netloc.lower(), path, s.query, ""))
+
+
+def _canon_value(field: str, v: Any) -> Any:
+    if field in _RECIPIENT_FIELDS:
+        items = v if isinstance(v, (list, tuple)) else re.split(r"[,;]", str(v or ""))
+        return sorted({str(x).strip().lower() for x in items if str(x).strip()})
+    if field in PATH_FIELDS:
+        if isinstance(v, (list, tuple)):
+            return sorted(filter(None, (resolve_path(x) for x in v)))
+        return resolve_path(v) or v
+    if field == "url":
+        return normalize_url(v)
+    if field == "method" and isinstance(v, str):
+        return v.strip().upper()
+    if isinstance(v, str):
+        return v.strip()
+    return v
+
+
+def _present(v: Any) -> bool:
+    return v not in (None, "", [], {}, ())
+
+
+def _dumps(obj: Any) -> str:
+    return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":"), default=str)
+
+
+def sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8", "surrogateescape")).hexdigest()
+
+
+def content_hash(content: str) -> str:
+    """Hash of file content as written: one trailing run of newlines ignored."""
+    data = content.encode("utf-8", "surrogateescape") if isinstance(content, str) else content
+    return hashlib.sha256(data.rstrip(b"\n")).hexdigest()
+
+
+def file_hash(path: Optional[str]) -> Optional[str]:
+    """content_hash of the file on disk now; None if missing/unreadable/huge."""
+    if not path:
+        return None
+    try:
+        if not os.path.isfile(path) or os.path.getsize(path) > MAX_HASH_BYTES:
+            return None
+        with open(path, "rb") as fh:
+            return hashlib.sha256(fh.read().rstrip(b"\n")).hexdigest()
+    except OSError:
+        return None
+
+
+def read_text(path: Optional[str]) -> Optional[str]:
+    try:
+        if path and os.path.isfile(path) and os.path.getsize(path) <= MAX_HASH_BYTES:
+            with open(path, "rb") as fh:
+                return fh.read().decode("utf-8", "surrogateescape")
+    except OSError:
+        pass
+    return None
+
+
+def file_target(path: str) -> str:
+    return f"file:{path}"
+
+
+def make_key(effect: str, target: str, payload: str) -> str:
+    return sha256(f"{effect}\x1f{target}\x1f{payload}")
+
+
+# ───────────────────────── effective effect ─────────────────────────
+
+_SQL_READ = re.compile(r"^\s*(select|with|pragma|explain|show|describe)\b", re.I)
+_GITHUB_READ = {"repos", "issues", "prs", "search_code", "user_info"}
+
+
+def effective_effect(spec, args: dict) -> str:
+    """The registry effect, narrowed by payload for the few tools whose
+    effect depends on it (a GET is a read, not a send)."""
+    name, effect = spec.name, spec.effect
+    if name == "http_request" and str(args.get("method") or "GET").upper() in ("GET", "HEAD",
+                                                                                "OPTIONS"):
+        return "read"
+    if name == "sql_query" and _SQL_READ.match(str(args.get("query") or "")):
+        return "read"
+    if name == "github" and str(args.get("action") or "") in _GITHUB_READ:
+        return "read"
+    return effect
+
+
+# ───────────────────────── effect identity for a tool call ─────────────────────────
+
+@dataclass(frozen=True)
+class Effect:
+    tool: str
+    effect: str            # write / send / spend / delete / system
+    target: str            # canonical target
+    payload: str           # canonical payload (string form)
+    key: Optional[str]     # None: not idempotent (recorded for the activity log only)
+    file_path: Optional[str] = None          # set for file-family targets
+    expected_post_hash: Optional[str] = None  # file content hash after a whole-file write
+
+    @property
+    def payload_hash(self) -> str:
+        return sha256(self.payload)
+
+
+def call_effect(spec, args: dict) -> Optional[Effect]:
+    """Effect identity for one non-read tool call; None for reads."""
+    effect = effective_effect(spec, args)
+    if effect == "read":
+        return None
+    idem = tuple(getattr(spec, "idempotent_on", ()) or ())
+    target_on = tuple(getattr(spec, "target_on", ()) or ())
+    name = spec.name
+
+    file_path = None
+    if target_on and all(f in PATH_FIELDS for f in target_on) and len(target_on) == 1:
+        file_path = resolve_path(args.get(target_on[0]))
+    if file_path:
+        target = file_target(file_path)
+    elif target_on:
+        parts = {f: _canon_value(f, args.get(f)) for f in target_on if _present(args.get(f))}
+        target = f"{name}:{_dumps(parts)}" if parts else name
+    else:
+        target = name
+
+    if name in FILE_CONTENT_TOOLS and file_path:
+        content = args.get(FILE_CONTENT_TOOLS[name])
+        content = content if isinstance(content, str) else str(content or "")
+        h = content_hash(content)
+        payload = f"content:{h}"
+        return Effect(name, effect, target, payload, make_key("write", target, payload),
+                      file_path=file_path, expected_post_hash=h)
+
+    payload_fields = [f for f in idem if f not in target_on]
+    payload_obj = {f: _canon_value(f, args.get(f)) for f in payload_fields if _present(args.get(f))}
+    payload = _dumps(payload_obj)
+    key = make_key(effect, target, payload) if idem else None
+    return Effect(name, effect, target, payload, key, file_path=file_path)
+
+
+def summarize_args(args: Any, limit: int = 400) -> str:
+    try:
+        s = _dumps(args)
+    except Exception:
+        s = repr(args)
+    return s if len(s) <= limit else s[:limit] + "..."
+
+
+# ───────────────────────── bash: tokenizer ─────────────────────────
+
+@dataclass
+class Tok:
+    kind: str           # "word" | "op"
+    value: str
+    expansion: bool = False   # contains unresolved $var / `cmd` / glob
+    quoted: bool = False
+
+
+_OPS = ("&&", "||", ";;", ">>", "&>>", "&>", ">|", ">&", "<<-", "<<", "<&", "|&",
+        ";", "|", "&", "<", ">", "(", ")", "\n")
+_SEPARATORS = {"&&", "||", ";", ";;", "&", "\n", "(", ")", "|", "|&"}
+
+
+def tokenize(cmd: str) -> List[Tok]:
+    """A small POSIX-ish shell tokenizer: quotes, escapes, operators, fd
+    redirects (2>, 1>>) and here-documents (body attached to the `<<` op)."""
+    toks: List[Tok] = []
+    i, n = 0, len(cmd)
+    word: List[str] = []
+    in_word = False
+    expansion = quoted = False
+    pending_heredocs: List[Tuple[Tok, str, bool]] = []
+    h = home()
+
+    def end_word():
+        nonlocal word, in_word, expansion, quoted
+        if in_word:
+            toks.append(Tok("word", "".join(word), expansion, quoted))
+        word, in_word, expansion, quoted = [], False, False, False
+
+    def dollar(j: int) -> Tuple[Optional[str], int]:
+        for var in ("${HOME}", "$HOME"):
+            if cmd.startswith(var, j):
+                k = j + len(var)
+                if var == "$HOME" and k < n and (cmd[k].isalnum() or cmd[k] == "_"):
+                    break
+                return h, k
+        return None, j
+
+    while i < n:
+        c = cmd[i]
+        if c == "\\" and i + 1 < n:
+            if cmd[i + 1] == "\n":
+                i += 2
+                continue
+            word.append(cmd[i + 1]); in_word = True; i += 2
+            continue
+        if c == "'":
+            j = cmd.find("'", i + 1)
+            j = n if j < 0 else j
+            word.append(cmd[i + 1:j]); in_word = True; quoted = True; i = j + 1
+            continue
+        if c == '"':
+            in_word = True; quoted = True; i += 1
+            while i < n and cmd[i] != '"':
+                if cmd[i] == "\\" and i + 1 < n and cmd[i + 1] in '"\\$`\n':
+                    word.append(cmd[i + 1]); i += 2
+                    continue
+                if cmd[i] == "$":
+                    val, k = dollar(i)
+                    if val is not None:
+                        word.append(val); i = k
+                        continue
+                    expansion = True
+                if cmd[i] == "`":
+                    expansion = True
+                word.append(cmd[i]); i += 1
+            i += 1
+            continue
+        if c == "$":
+            val, k = dollar(i)
+            if val is not None:
+                word.append(val); in_word = True; i = k
+                continue
+            expansion = True; word.append(c); in_word = True; i += 1
+            continue
+        if c in "`*?[":
+            expansion = True; word.append(c); in_word = True; i += 1
+            continue
+        if c == "~" and not in_word:
+            word.append(c); in_word = True; i += 1
+            continue
+        if c == "#" and not in_word:
+            j = cmd.find("\n", i)
+            i = n if j < 0 else j
+            continue
+        if c in " \t":
+            end_word(); i += 1
+            continue
+        op = next((o for o in _OPS if cmd.startswith(o, i)), None)
+        if op:
+            # "2>" / "1>>": a digit-only word glued to a redirect is an fd.
+            if op[0] in "<>" and in_word and not quoted and "".join(word).isdigit():
+                fd = "".join(word)
+                word, in_word = [], False
+                toks.append(Tok("op", fd + op))
+            else:
+                end_word()
+                toks.append(Tok("op", op))
+            i += len(op)
+            if op in ("<<", "<<-"):
+                # Read the delimiter word now; the body follows the next newline.
+                while i < n and cmd[i] in " \t":
+                    i += 1
+                j = i
+                while j < n and cmd[j] not in " \t\n;|&<>()":
+                    j += 1
+                raw = cmd[i:j]
+                delim = raw.strip("'\"").replace("\\", "")
+                pending_heredocs.append((toks[-1], delim, raw != delim))
+                i = j
+            if op == "\n" and pending_heredocs:
+                for htok, delim, lit in pending_heredocs:
+                    body_lines = []
+                    while i < n:
+                        j = cmd.find("\n", i)
+                        line = cmd[i:] if j < 0 else cmd[i:j]
+                        i = n if j < 0 else j + 1
+                        if (line.lstrip("\t") if htok.value == "<<-" else line) == delim:
+                            break
+                        body_lines.append(line)
+                    body = "".join(l + "\n" for l in body_lines)
+                    htok.value = htok.value + "\x00" + body
+                    htok.expansion = (not lit) and ("$" in body or "`" in body)
+                pending_heredocs = []
+            continue
+        word.append(c); in_word = True; i += 1
+    end_word()
+    return toks
+
+
+# ───────────────────────── bash: file writes ─────────────────────────
+
+@dataclass
+class FileWrite:
+    path: str                 # resolved absolute path
+    mode: str                 # "w" (replace) or "a" (append)
+    content: Optional[str]    # known content written (None: unknown)
+    via: str                  # ">", ">>", "tee", "cp", "mv", "sed -i", ...
+
+
+@dataclass
+class _Seg:
+    words: List[Tok]
+    redirects: List[Tuple[str, Tok]]
+    heredoc: Optional[Tok]
+    piped_from_prev: bool
+
+
+def _segments(toks: Sequence[Tok]) -> List[_Seg]:
+    segs: List[_Seg] = []
+    cur = _Seg([], [], None, False)
+    i = 0
+    while i < len(toks):
+        t = toks[i]
+        if t.kind == "op" and t.value in _SEPARATORS:
+            segs.append(cur)
+            cur = _Seg([], [], None, t.value in ("|", "|&"))
+            i += 1
+            continue
+        if t.kind == "op" and t.value.split("\x00")[0] in ("<<", "<<-"):
+            cur.heredoc = t
+            i += 1
+            continue
+        if t.kind == "op" and t.value.lstrip("0123456789") in (">", ">>", ">|", "&>", "&>>",
+                                                               "<", ">&", "<&"):
+            nxt = toks[i + 1] if i + 1 < len(toks) and toks[i + 1].kind == "word" else None
+            cur.redirects.append((t.value, nxt))
+            i += 2 if nxt else 1
+            continue
+        if t.kind == "word":
+            cur.words.append(t)
+        i += 1
+    segs.append(cur)
+    return [s for s in segs if s.words or s.redirects]
+
+
+_PRINTF_ESC = {"n": "\n", "t": "\t", "\\": "\\", "r": "\r", "'": "'", '"': '"'}
+
+
+def _printf_unescape(s: str) -> Optional[str]:
+    out, i = [], 0
+    while i < len(s):
+        c = s[i]
+        if c == "\\" and i + 1 < len(s):
+            e = _PRINTF_ESC.get(s[i + 1])
+            if e is None:
+                return None
+            out.append(e); i += 2
+            continue
+        out.append(c); i += 1
+    return "".join(out)
+
+
+def _printf(args: List[str]) -> Optional[str]:
+    if not args:
+        return None
+    fmt = _printf_unescape(args[0])
+    if fmt is None:
+        return None
+    pieces = re.split(r"(%%|%s|%[^%s]?)", fmt)
+    spec_count = sum(1 for p in pieces if p == "%s")
+    if any(p.startswith("%") and p not in ("%%", "%s") for p in pieces if p):
+        return None
+    rest = args[1:]
+    if spec_count == 0:
+        return fmt.replace("%%", "%")
+    out = []
+    groups = max(1, -(-len(rest) // spec_count))
+    for g in range(groups):
+        vals = rest[g * spec_count:(g + 1) * spec_count]
+        k = 0
+        for p in pieces:
+            if p == "%s":
+                out.append(vals[k] if k < len(vals) else ""); k += 1
+            elif p == "%%":
+                out.append("%")
+            else:
+                out.append(p)
+    return "".join(out)
+
+
+def _echo(args: List[str]) -> Optional[str]:
+    newline, escapes = True, False
+    while args and re.fullmatch(r"-[neE]+", args[0]):
+        newline = newline and "n" not in args[0]
+        escapes = escapes or "e" in args[0]
+        args = args[1:]
+    text = " ".join(args)
+    if escapes and "\\" in text:
+        text = _printf_unescape(text)
+        if text is None:
+            return None
+    return text + ("\n" if newline else "")
+
+
+def _stdout(seg: _Seg, stdin: Optional[str], base: str) -> Optional[str]:
+    """Known stdout of a simple command, or None."""
+    if not seg.words or any(w.expansion for w in seg.words):
+        return None
+    cmd, args = seg.words[0].value, [w.value for w in seg.words[1:]]
+    if cmd == "echo":
+        return _echo(args)
+    if cmd == "printf":
+        return _printf(args)
+    if cmd == "cat":
+        files = [a for a in args if not a.startswith("-") or a == "-"]
+        if not files:
+            if seg.heredoc is not None:
+                if seg.heredoc.expansion:
+                    return None
+                return seg.heredoc.value.split("\x00", 1)[1] if "\x00" in seg.heredoc.value else None
+            return stdin
+        texts = [read_text(resolve_path(f, base)) for f in files]
+        return None if any(t is None for t in texts) else "".join(texts)
+    return None
+
+
+def bash_file_writes(command: str, base: Optional[str] = None) -> List[FileWrite]:
+    """File writes a bash command will make, as far as simple parsing can tell."""
+    if not isinstance(command, str) or not command.strip():
+        return []
+    base = base or home()
+    try:
+        segs = _segments(tokenize(command))
+    except Exception:  # never let a parser bug block a command
+        return []
+    writes: List[FileWrite] = []
+    prev_out: Optional[str] = None
+    for seg in segs:
+        stdin = prev_out if seg.piped_from_prev else None
+        out = _stdout(seg, stdin, base)
+        for op, target in seg.redirects:
+            if target is None or target.expansion:
+                continue
+            core = op.lstrip("0123456789")
+            fd = op[: len(op) - len(core)] or "1"
+            if core in ("<", "<&", ">&"):
+                continue
+            path = resolve_path(target.value, base)
+            if not path or path.startswith("/dev/"):
+                continue
+            mode = "a" if core in (">>", "&>>") else "w"
+            known = out if (fd == "1" and core in (">", ">>", ">|")) else None
+            if fd == "2":
+                known = None
+            writes.append(FileWrite(path, mode, known, op))
+        words = [w for w in seg.words]
+        if words and not any(w.expansion for w in words):
+            cmd = words[0].value
+            args = [w.value for w in words[1:]]
+            if cmd == "tee":
+                append = any(a in ("-a", "--append") for a in args)
+                for a in args:
+                    if a.startswith("-"):
+                        continue
+                    p = resolve_path(a, base)
+                    if p and not p.startswith("/dev/"):
+                        writes.append(FileWrite(p, "a" if append else "w", stdin, "tee"))
+            elif cmd in ("cp", "mv"):
+                operands = [a for a in args if not a.startswith("-")]
+                if "-t" in args or "--target-directory" in args or len(operands) < 2:
+                    pass
+                else:
+                    dest = resolve_path(operands[-1], base)
+                    srcs = [resolve_path(s, base) for s in operands[:-1]]
+                    if dest and all(srcs):
+                        into_dir = len(srcs) > 1 or os.path.isdir(dest)
+                        for s in srcs:
+                            d = os.path.join(dest, os.path.basename(s)) if into_dir else dest
+                            writes.append(FileWrite(d, "w", read_text(s), cmd))
+            elif cmd == "sed":
+                inplace, i, script_seen = False, 0, False
+                targets = []
+                while i < len(args):
+                    a = args[i]
+                    if a == "-i" or a.startswith("-i") or a.startswith("--in-place"):
+                        inplace = True
+                        # BSD sed: `-i ''` / `-i .bak` takes a suffix argument.
+                        if a == "-i" and i + 1 < len(args) and (args[i + 1] == ""
+                                                               or args[i + 1].startswith(".")) \
+                                and i + 2 < len(args):
+                            i += 1
+                    elif a in ("-e", "-f", "--expression", "--file"):
+                        script_seen = True
+                        i += 1
+                    elif a.startswith("-"):
+                        pass
+                    elif not script_seen:
+                        script_seen = True
+                    else:
+                        targets.append(a)
+                    i += 1
+                if inplace:
+                    for a in targets:
+                        p = resolve_path(a, base)
+                        if p:
+                            writes.append(FileWrite(p, "w", None, "sed -i"))
+        prev_out = out
+    return writes
+
+
+def planned_file_effects(writes: Iterable[FileWrite]) -> List[Tuple[str, Optional[Effect]]]:
+    """Per path: the effect we can key BEFORE running (None if unknown).
+
+    A path written once with known content in replace mode keys on the final
+    content (same key as write_file). A path only appended to with known
+    content keys on the appended text. Anything else is unknown until it ran.
+    """
+    by_path: dict = {}
+    for w in writes:
+        by_path.setdefault(w.path, []).append(w)
+    out = []
+    for path, ws in by_path.items():
+        target = file_target(path)
+        eff = None
+        if len(ws) == 1 and ws[0].mode == "w" and ws[0].content is not None:
+            h = content_hash(ws[0].content)
+            payload = f"content:{h}"
+            eff = Effect("bash", "write", target, payload, make_key("write", target, payload),
+                         file_path=path, expected_post_hash=h)
+        elif all(w.mode == "a" and w.content is not None for w in ws):
+            appended = "".join(w.content for w in ws)
+            payload = f"append:{content_hash(appended)}"
+            eff = Effect("bash", "write", target, payload, make_key("write", target, payload),
+                         file_path=path)
+        out.append((path, eff))
+    return out
+
+
+def recorded_file_effect(path: str, writes: Sequence[FileWrite]) -> Optional[Effect]:
+    """Per path, AFTER running: the effect to record, keyed on what is on disk
+    (appends with known text keep the append key)."""
+    target = file_target(path)
+    ws = [w for w in writes if w.path == path]
+    if ws and all(w.mode == "a" and w.content is not None for w in ws):
+        payload = f"append:{content_hash(''.join(w.content for w in ws))}"
+        return Effect("bash", "write", target, payload, make_key("write", target, payload),
+                      file_path=path)
+    h = file_hash(path)
+    if h is None:
+        return None
+    payload = f"content:{h}"
+    return Effect("bash", "write", target, payload, make_key("write", target, payload),
+                  file_path=path, expected_post_hash=h)
+
+
+# ───────────────────────── resources (S5) ─────────────────────────
+
+@dataclass(frozen=True)
+class Resource:
+    kind: str     # "path" | "url" | "<field>" (ids) | "text" (bash command)
+    value: str
+
+    def __str__(self) -> str:
+        return f"{self.kind}:{self.value}"
+
+
+_HOME_ROOT = re.compile(r"^/(?:Users|home)/[^/]+(?=/|$)|^/root(?=/|$)")
+_PATHISH = re.compile(r"^(?:~|\.{1,2}/|/)|/|\.[A-Za-z0-9]{1,8}$")
+
+
+def home_tail(path: str) -> Optional[str]:
+    """Path relative to a home directory (the real one or any /Users/<x>,
+    /home/<x>, /root); None when it is not under a home."""
+    h = home()
+    if path == h or path.startswith(h + "/"):
+        return path[len(h):].lstrip("/")
+    m = _HOME_ROOT.match(path)
+    if m:
+        return path[m.end():].lstrip("/")
+    # macOS realpath of /tmp etc. is not a home; a sandboxed HOME may live
+    # under /private/var/... and is covered by the first branch.
+    return None
+
+
+def resources(spec_name: str, args: dict, base: Optional[str] = None) -> List[Resource]:
+    out: List[Resource] = []
+    if not isinstance(args, dict):
+        return out
+    if spec_name == "bash":
+        cmd = args.get("command")
+        if isinstance(cmd, str) and cmd.strip():
+            out.append(Resource("text", cmd))
+            try:
+                toks = tokenize(cmd)
+            except Exception:
+                toks = []
+            for t in toks:
+                if t.kind == "word" and not t.expansion and _PATHISH.search(t.value) \
+                        and not t.value.startswith("-") and "://" not in t.value:
+                    p = resolve_path(t.value, base)
+                    if p:
+                        out.append(Resource("path", p))
+        return out
+    for f in RESOURCE_PATH_FIELDS:
+        v = args.get(f)
+        for item in (v if isinstance(v, (list, tuple)) else [v]):
+            p = resolve_path(item, base) if isinstance(item, str) else None
+            if p:
+                out.append(Resource("path", p))
+    u = normalize_url(args.get("url"))
+    if u:
+        out.append(Resource("url", u))
+    for f in RESOURCE_ID_FIELDS:
+        v = args.get(f)
+        if _present(v):
+            out.append(Resource(f, str(v).strip()))
+    return out
+
+
+def _stem(name: str) -> str:
+    return os.path.splitext(name)[0]
+
+
+def touches(r: Resource, missing: Resource) -> bool:
+    """Is call resource `r` still about the not-found resource `missing`?"""
+    if missing.kind == "path":
+        m = missing.value
+        mbase = os.path.basename(m)
+        if r.kind == "text":
+            stem = _stem(mbase)
+            return bool(mbase) and (mbase in r.value or (len(stem) >= 6 and stem in r.value))
+        if r.kind != "path":
+            return False
+        p = r.value
+        if p == m:
+            return True
+        if mbase and os.path.basename(p) == mbase and home_tail(p) is not None:
+            return True  # same file name anywhere under a home (invented paths)
+        # A directory above it below a home (also an invented home), or its
+        # direct parent anywhere: listing the folder to look for it.
+        pt, mt = home_tail(p), home_tail(m)
+        if pt and mt and mt.startswith(pt.rstrip("/") + "/"):
+            return True
+        if p == os.path.dirname(m) and p != "/":
+            return True
+        return False
+    return r.kind == missing.kind and r.value == missing.value