hilos-agent 0.9.0 → 0.9.2

package/src/argv.mjs

@@ -0,0 +1,61 @@
+// Small shell-word parser for configured CLI commands. hilos never runs these
+// strings through a shell; this preserves quoted paths/values while keeping the
+// spawn boundary injection-safe. It intentionally supports words, single and
+// double quotes, and backslash-escaped whitespace/quotes—not expansions, pipes,
+// or redirects. Other backslashes stay literal so Windows and UNC paths work.
+
+export function commandArgv(command) {
+  const input = String(command || "");
+  const out = [];
+  let word = "";
+  let quote = "";
+  let started = false;
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    if (char === "\\" && quote !== "'") {
+      const next = input[index + 1];
+      const escapesQuote = next === '"' || (!quote && next === "'");
+      const escapesWhitespace = !quote && typeof next === "string" && /\s/.test(next);
+      if (escapesQuote || escapesWhitespace) {
+        word += next;
+        index += 1;
+      } else {
+        word += "\\";
+      }
+      started = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = "";
+      else word += char;
+      started = true;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (started) {
+        out.push(word);
+        word = "";
+        started = false;
+      }
+      continue;
+    }
+    word += char;
+    started = true;
+  }
+  if (started) out.push(word);
+  return out;
+}
+
+/**
+ * Encode one literal argument for `commandArgv`'s small command grammar.
+ * Single-quoted spans preserve whitespace and backslashes verbatim; an
+ * embedded apostrophe is represented as an adjacent double-quoted span.
+ */
+export function quoteCommandArg(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}

package/src/attachments.mjs

@@ -0,0 +1,310 @@
+// Message attachments → files the coding CLI can actually look at (0779).
+//
+// A designer pastes a screenshot and writes "fix this spacing". Before this,
+// the daemon handed its CLI a plain `author: body` transcript and the image was
+// gone — so the agent answered as if nothing had been sent, which reads as the
+// agent being bad rather than the pipe being broken.
+//
+// 0780 put the attachments on the mention itself (`list_mentions` resolves them
+// the same way `read_channel` and `get_thread` do, with a ONE-HOUR signed url).
+// This module turns that into local files.
+//
+// Rules:
+//   - FETCH AT EXECUTION, not at enqueue. The url is signed for an hour, so a
+//     job that waits behind other work is usually still fine — and downloading
+//     at enqueue means a burst of image mentions holds every job's bytes on
+//     disk at once. One running job, one temp dir. The tradeoff is stated at
+//     fetchMentionImages.
+//   - NEVER fail the run. Every error path returns fewer files (or none) and
+//     the run proceeds on the transcript alone, which already names the file.
+//   - Images only. Neither CLI takes a PDF or a zip as a native input, and
+//     downloading one would just be a file nobody opens.
+//   - NEVER fetch an internal address. `metadata.attachments` is written by
+//     whoever sent the message, and this code runs on the USER'S OWN MACHINE —
+//     an unguarded fetch would let a workspace member read the daemon
+//     operator's localhost and hand the result to a model. See guardedFetch.
+//   - Node builtins only, dependency-free, `fetch` injectable — so this is
+//     unit-tested offline with a stubbed fetch, no network and no daemon.
+
+import { lookup } from "node:dns/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** At most this many images per run — see lib/attachment-context.ts for why. */
+export const MAX_IMAGES = 4;
+
+/** Per-image byte ceiling (10MB). Over it the image is skipped, not truncated. */
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+/** Whole-request deadline per image. A slow host must not eat the run. */
+export const FETCH_TIMEOUT_MS = 20_000;
+
+/** Redirect hops we follow ourselves, re-checking the host at every one. */
+const MAX_REDIRECTS = 3;
+
+/**
+ * Is a resolved IP internal/reserved? Loopback, RFC1918, CGNAT, link-local
+ * (which is where 169.254.169.254 cloud metadata lives), IPv6 loopback and
+ * unique-local, and IPv4-mapped IPv6. A deliberate twin of `isBlockedIp` in
+ * lib/ssrf.ts — the daemon ships as its own npm package and imports no app
+ * code; tests pin the two to the same answers.
+ */
+export function isBlockedIp(ip) {
+  let h = String(ip || "").toLowerCase().replace(/^\[|\]$/g, "").split("%")[0];
+  const mapped = h.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (mapped) h = mapped[1];
+  if (h === "::" || h === "::1") return true;
+  if (h.startsWith("fe80:") || h.startsWith("fc") || h.startsWith("fd")) return true;
+  const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (m) {
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    if (a === 0 || a === 10 || a === 127) return true;
+    if (a === 169 && b === 254) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 100 && b >= 64 && b <= 127) return true;
+  }
+  return false;
+}
+
+/** Obviously-internal hostname, by name or literal IP. No DNS. */
+export function isBlockedHost(hostname) {
+  const h = String(hostname || "").toLowerCase().replace(/^\[|\]$/g, "");
+  if (h === "localhost" || h.endsWith(".localhost") || h.endsWith(".local") || h.endsWith(".internal")) {
+    return true;
+  }
+  return isBlockedIp(h);
+}
+
+/**
+ * May the daemon fetch this url? http(s) only, and no host that is — or
+ * resolves to — an internal address. Fails CLOSED: an unparseable url or a
+ * failed DNS lookup is a no.
+ * @param {string} url
+ * @param {{ lookupImpl?: any }} [opts]
+ */
+export async function isFetchableUrl(url, opts = {}) {
+  let parsed;
+  try {
+    parsed = new URL(String(url));
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+  const host = parsed.hostname;
+  if (isBlockedHost(host)) return false;
+  // A literal IP already passed isBlockedIp above; resolving it again is noise.
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return true;
+  const lookupImpl = opts.lookupImpl || lookup;
+  try {
+    const addrs = await lookupImpl(host, { all: true });
+    if (!addrs || !addrs.length) return false;
+    return !addrs.some((a) => isBlockedIp(a.address));
+  } catch {
+    return false; // DNS rebinding protection is worth a false negative
+  }
+}
+
+/**
+ * Fetch with the guards on: host-checked at every redirect hop (hence
+ * `redirect: "manual"` — following automatically would let a public url bounce
+ * to 169.254.169.254 behind our back), a whole-request timeout, and a streamed
+ * body with a running byte count so the cap holds even when `content-length` is
+ * absent or lying. `arrayBuffer()` would have materialized the whole response
+ * before any check could run.
+ *
+ * Returns a Buffer, or null for every failure — the caller treats null as "no
+ * image", never as a failed run.
+ * @param {string} url
+ * @param {{ fetchImpl?: any, lookupImpl?: any, maxBytes?: number, timeoutMs?: number }} [opts]
+ */
+export async function guardedFetch(url, opts = {}) {
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== "function") return null;
+  const maxBytes = opts.maxBytes ?? MAX_IMAGE_BYTES;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? FETCH_TIMEOUT_MS);
+  try {
+    let current = String(url);
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+      if (!(await isFetchableUrl(current, opts))) return null;
+      const res = await fetchImpl(current, { signal: controller.signal, redirect: "manual" });
+      if (!res) return null;
+      const status = Number(res.status ?? 0);
+      if (status >= 300 && status < 400) {
+        const next = res.headers?.get?.("location");
+        if (!next) return null;
+        current = new URL(next, current).toString(); // re-checked at the top
+        continue;
+      }
+      if (!res.ok) return null;
+      const declared = Number(res.headers?.get?.("content-length") ?? "");
+      if (Number.isFinite(declared) && declared > maxBytes) return null;
+      if (!res.body || typeof res.body.getReader !== "function") return null;
+      const reader = res.body.getReader();
+      const chunks = [];
+      let total = 0;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!value) continue;
+        total += value.byteLength ?? value.length ?? 0;
+        if (total > maxBytes) {
+          await reader.cancel().catch(() => {});
+          return null;
+        }
+        chunks.push(Buffer.from(value));
+      }
+      return total ? Buffer.concat(chunks) : null;
+    }
+    return null; // too many redirects
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** True when an attachment is an image a coding CLI can look at. */
+export function isImageAttachment(a) {
+  return Boolean(a) && typeof a.type === "string" && a.type.toLowerCase().startsWith("image/");
+}
+
+/**
+ * The image attachments on a mention, in order, capped. Non-images are dropped
+ * deliberately (the transcript still names them).
+ * @param {any} message a list_mentions row
+ */
+export function pickImageAttachments(message) {
+  const list = message && Array.isArray(message.attachments) ? message.attachments : [];
+  return list.filter((a) => isImageAttachment(a) && typeof a.url === "string" && a.url).slice(0, MAX_IMAGES);
+}
+
+/** A safe on-disk basename (never a path, never empty). */
+export function safeImageFilename(name, index) {
+  const base = String(name ?? "").split(/[/\\]/).pop() || "";
+  const cleaned = base
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^[-.]+/, "")
+    .slice(0, 60);
+  return cleaned || `image-${index + 1}.png`;
+}
+
+/**
+ * Download a mention's images into a fresh temp dir. Returns the files (with
+ * absolute paths) plus the dir, which the caller removes with `cleanupImages`
+ * once the run is over.
+ *
+ * Called at EXECUTION time (run.mjs's safeHandle), not at enqueue, so at most
+ * one job's images sit on disk however long the queue gets. THE TRADEOFF: the
+ * url the server signed lives one hour, and the daemon cannot re-resolve one
+ * (no tool re-signs a single message's attachments), so a job that waits more
+ * than an hour behind other work loses its images and runs text-only. That is
+ * the right way to lose: the transcript still names the file, and the
+ * alternative was every queued job's bytes held on the user's disk at once.
+ *
+ * Returns `{ dir: null, files: [] }` when there is nothing to fetch or when
+ * everything failed — the caller treats that as "text-only", which is exactly
+ * the pre-0779 behavior.
+ *
+ * @param {any} message
+ * @param {{ fetchImpl?: any, lookupImpl?: any, log?: any }} [opts]
+ */
+export async function fetchMentionImages(message, opts = {}) {
+  const picked = pickImageAttachments(message);
+  if (!picked.length) return { dir: null, files: [] };
+  let dir = null;
+  try {
+    dir = await mkdtemp(join(tmpdir(), "hilos-attach-"));
+  } catch {
+    return { dir: null, files: [] };
+  }
+  const files = [];
+  for (const [i, a] of picked.entries()) {
+    try {
+      const bytes = await guardedFetch(a.url, opts);
+      if (!bytes) continue;
+      const path = join(dir, `${i + 1}-${safeImageFilename(a.name, i)}`);
+      await writeFile(path, bytes);
+      files.push({ path, name: a.name || "attachment", type: a.type || "" });
+    } catch (e) {
+      opts.log?.error?.(`couldn't fetch an attachment: ${e?.message || e}`);
+    }
+  }
+  if (!files.length) {
+    await cleanupImages(dir);
+    return { dir: null, files: [] };
+  }
+  return { dir, files };
+}
+
+/** Remove a fetched-image temp dir. Best-effort and never throws. */
+export async function cleanupImages(dir) {
+  if (!dir) return;
+  try {
+    await rm(dir, { recursive: true, force: true });
+  } catch {
+    /* a leftover temp dir is the OS's problem, never the run's */
+  }
+}
+
+const TOKEN_RE = /!\[([^\]]*)\]\(attachment:([^)\s]*)\)/g;
+
+/**
+ * Replace every `![name](attachment:<id>)` pill token with the plain name. The
+ * daemon's models saw those raw tokens too — `fetchContext` builds its
+ * transcript straight from `body`, so an unresolvable `attachment:<uuid>`
+ * reached every chat reply and every routing decision.
+ */
+export function stripAttachmentTokens(body) {
+  return String(body ?? "")
+    .replace(TOKEN_RE, (_m, alt) => (String(alt).trim() ? String(alt).trim() : "attachment"))
+    .replace(/[ \t]+\n/g, "\n")
+    .trim();
+}
+
+/**
+ * One transcript line's text: the body with pill tokens flattened, plus an
+ * honest `[attached: name (type)]` marker per attachment.
+ *
+ * TWIN of `renderAttachmentLine` in lib/attachment-context.ts. It takes the
+ * already-resolved `attachments` array that read_channel / get_thread /
+ * list_mentions return, where the server version takes raw `metadata`; the two
+ * are pinned to identical output by matching tests. Change one, change both.
+ */
+export function renderAttachmentLine(body, attachments) {
+  const clean = stripAttachmentTokens(body);
+  const list = Array.isArray(attachments) ? attachments : [];
+  const markers = list
+    .map((a) => {
+      const name = (a && typeof a.name === "string" && a.name.trim()) || "attachment";
+      const type = a && typeof a.type === "string" ? a.type.trim() : "";
+      return type ? `[attached: ${name} (${type})]` : `[attached: ${name}]`;
+    })
+    .join(" ");
+  if (!markers) return clean;
+  return clean ? `${clean} ${markers}` : markers;
+}
+
+/**
+ * The prompt block that connects an image to the request. Without it the file
+ * is a path the agent has no reason to open — and even a CLI that took the
+ * image natively can't tell which of them the person meant.
+ *
+ * `readable: true` for a vendor with no image flag (Claude Code): the file is
+ * on disk and the agent opens it with its own file-read tool.
+ */
+export function imagePromptNote(files, opts = {}) {
+  if (!files || !files.length) return "";
+  const lines = files.map((f) => `- ${f.path} (${f.name}${f.type ? `, ${f.type}` : ""})`);
+  const head =
+    files.length === 1
+      ? "The person attached this image to the request:"
+      : `The person attached these ${files.length} images to the request:`;
+  const tail = opts.readable
+    ? "Open each file to look at it before you start — it is part of the request, not decoration."
+    : "They are attached to this prompt — look at them before you start.";
+  return [head, ...lines, tail].join("\n");
+}