hilos-agent 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# hilos-agent
+
+Run **your own** coding agent — Claude Code, Codex, Cursor, or any command — as
+an autonomous teammate inside a [hilos](https://hilos.sh) channel.
+
+It connects to hilos over MCP, watches for `@mentions` of your agent in a
+git-linked channel, runs your coding agent in a **local** checkout, and posts the
+proposed diff as a report card. **Nothing is pushed until a human approves in
+hilos.** Your code and your git/`gh` credentials never leave your machine — hilos
+only relays messages.
+
+```
+hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
+  human: "@scout fix the navbar overflow"
+  agent: branches, runs your coding CLI, captures the diff
+  agent: posts a proposal card (NOT pushed)
+  human: Approve  ▶  agent: git push + gh pr create  ▶  posts the PR link
+         Reject   ▶  agent: discards the branch
+         Changes  ▶  agent: re-runs with your note, proposes again
+```
+
+## Quick start
+
+In hilos: open your agent's profile → **Connect** → copy the
+`hilos-agent --join …` command. Then on your machine:
+
+```sh
+npx hilos-agent --join <blob>        # connect (token + endpoint come from the link)
+hilos-agent init                     # or: write a starter config to edit
+```
+
+Map each repo the agent may touch to a local checkout, then run it:
+
+```jsonc
+// ~/.hilos/agent.json  (or ./hilos-agent.json)
+{
+  "url": "https://hilos.sh/api/mcp",
+  "token": "mgo_…",
+  "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
+  "codingCmd": "claude -p",   // or "codex exec", "cursor-agent", any shell command
+  "defaultBranch": "main",
+  "gate": true                 // false = propose only, never push
+}
+```
+
+```sh
+hilos-agent          # watch every channel the agent is in
+hilos-agent --channel <id>   # scope to one channel
+```
+
+## How it works
+
+- **Trigger** — an `@mention` of your agent in a channel that's linked to a repo.
+- **Repo resolution** — the channel's linked repo is mapped to a local path via
+  `repos`. No mapping → the agent says so and stops.
+- **Run** — it branches off `defaultBranch` (refuses a dirty tree), runs
+  `codingCmd` with the task, and stages the result.
+- **Propose** — the staged diff is posted as a report card. The agent then polls
+  for your decision.
+- **Approve / Reject / Request changes** — approve pushes with *your* `git`/`gh`
+  and opens a PR; reject discards the branch; request-changes re-runs with your
+  note (bounded rounds).
+
+## Security
+
+The daemon runs a coding agent that can execute code in your repo — exactly as if
+you ran it in your terminal. hilos can only send text; **push is gated on a human
+approval recorded in hilos**, and uses your local credentials. Keep your token in
+the config file or `HILOS_TOKEN`, never in shared shell history.
+
+## Flags
+
+`--join <blob>` · `--channel <id>` · `--config <path>` · `--coding-cmd <cmd>` ·
+`--once` · `--backfill` · `--no-gate` · `--help`
+
+Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`, `HILOS_ONCE=1`,
+`HILOS_BACKFILL=1`.

package/bin/hilos-agent.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// hilos-agent — run your coding agent as an autonomous teammate in a hilos
+// channel. Picks up @mentions, proposes a diff, pushes only after a human
+// approves in hilos. Your code + credentials never leave your machine.
+//
+// Usage:
+//   hilos-agent --join <blob>      connect with a copy-paste link from hilos
+//   hilos-agent init               write a starter config (~/.hilos/agent.json)
+//   hilos-agent                    run with the resolved config (default)
+//   hilos-agent run                same as above, explicit
+//
+// Config (./hilos-agent.json or ~/.hilos/agent.json), overlaid by env + flags:
+//   { "url", "token", "channelId", "repos": {"owner/name":"/abs/path"},
+//     "codingCmd": "claude -p", "defaultBranch": "main", "gate": true }
+
+import { resolveConfig, decodeJoin, writeStarterConfig, GLOBAL_CONFIG } from "../src/config.mjs";
+import { run } from "../src/run.mjs";
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--join") flags.join = argv[++i];
+    else if (a === "--config") flags.config = argv[++i];
+    else if (a === "--channel") flags.channelId = argv[++i];
+    else if (a === "--url") flags.url = argv[++i];
+    else if (a === "--token") flags.token = argv[++i];
+    else if (a === "--coding-cmd") flags.codingCmd = argv[++i];
+    else if (a === "--once") flags.once = true;
+    else if (a === "--backfill") flags.backfill = true;
+    else if (a === "--no-gate") flags.gate = false;
+    else if (a === "-h" || a === "--help") flags.help = true;
+    else positional.push(a);
+  }
+  return { cmd: positional[0] || "run", flags };
+}
+
+const HELP = `hilos-agent — your coding agent as a teammate in hilos
+
+  hilos-agent --join <blob>      connect using a link copied from hilos
+  hilos-agent init               write a starter config to ~/.hilos/agent.json
+  hilos-agent                    run the daemon (watch @mentions, propose diffs)
+
+Options:
+  --channel <id>     watch only one channel (per-channel override)
+  --config <path>    use a specific config file
+  --coding-cmd <cmd> the coding agent to run (default: "claude -p")
+  --once             one poll then exit (cron-friendly)
+  --backfill         also act on mentions that predate startup
+  --no-gate          propose only; don't wait for approval / push
+  -h, --help         this help
+
+Docs: https://hilos.sh  ·  https://www.npmjs.com/package/hilos-agent`;
+
+async function main() {
+  const { cmd, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help || cmd === "help") {
+    console.log(HELP);
+    return;
+  }
+
+  const joinPayload = flags.join ? decodeJoin(flags.join) : undefined;
+  if (flags.join && !joinPayload) {
+    console.error("That --join link is invalid. Re-copy it from hilos.");
+    process.exit(1);
+  }
+
+  if (cmd === "init") {
+    const path = writeStarterConfig(joinPayload ? GLOBAL_CONFIG : flags.config, joinPayload || {});
+    console.log(`Wrote ${path}.`);
+    console.log(joinPayload ? "Token + endpoint set from your link." : "Fill in token + repos, then run `hilos-agent`.");
+    console.log('Map your repos: "repos": { "owner/name": "/abs/path/to/checkout" }');
+    return;
+  }
+
+  // run (default) — when --join is passed without init, connect straight away.
+  const cliFlags = { ...flags };
+  delete cliFlags.join;
+  delete cliFlags.help;
+  const cfg = resolveConfig({ flags: cliFlags, join: joinPayload });
+  await run(cfg);
+}
+
+main().catch((e) => {
+  console.error(e?.message || e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "hilos-agent",
+  "version": "0.1.0",
+  "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions, proposes a diff, and pushes only after a human approves — your code and credentials never leave your machine.",
+  "type": "module",
+  "bin": {
+    "hilos-agent": "bin/hilos-agent.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "hilos",
+    "mcp",
+    "agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "coding-agent"
+  ],
+  "license": "MIT"
+}

package/src/config.mjs

@@ -0,0 +1,96 @@
+// Config resolution: a JSON file (./hilos-agent.json or ~/.hilos/agent.json),
+// overlaid by env vars and CLI flags / a --join blob. The join blob carries the
+// MCP url + token (+ optional channel) so a user can paste one command.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+export const GLOBAL_CONFIG = join(homedir(), ".hilos", "agent.json");
+export const LOCAL_CONFIG = "hilos-agent.json";
+
+/** Decode a base64url join blob → { url, token, channelId }, or null. */
+export function decodeJoin(blob) {
+  try {
+    const b64 = String(blob).trim().replace(/-/g, "+").replace(/_/g, "/");
+    const json = Buffer.from(b64, "base64").toString("utf8");
+    const o = JSON.parse(json);
+    if (!o.u || !o.t) return null;
+    return { url: o.u, token: o.t, channelId: o.c };
+  } catch {
+    return null;
+  }
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** First config file that exists: explicit path → ./hilos-agent.json → ~/.hilos/agent.json. */
+export function findConfigPath(explicit) {
+  if (explicit) return explicit;
+  if (existsSync(LOCAL_CONFIG)) return LOCAL_CONFIG;
+  if (existsSync(GLOBAL_CONFIG)) return GLOBAL_CONFIG;
+  return null;
+}
+
+const DEFAULTS = {
+  url: "https://hilos.sh/api/mcp",
+  token: "",
+  channelId: "", // when set, watch only this channel (the per-channel override)
+  repos: {},
+  codingCmd: "claude -p",
+  defaultBranch: "main",
+  gate: true,
+  maxRounds: 3,
+  pollMs: 5000,
+  runTimeoutMs: 600000,
+  decisionTimeoutMs: 1800000,
+  decisionPollMs: 5000,
+  backfill: false,
+  once: false,
+};
+
+/** Merge defaults ← file ← env ← join ← flags into one config object. */
+export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
+  const file = readJson(findConfigPath(flags.config)) || {};
+  const env = {
+    url: process.env.HILOS_URL,
+    token: process.env.HILOS_TOKEN,
+    channelId: process.env.HILOS_CHANNEL,
+    codingCmd: process.env.CODING_CMD,
+    backfill: process.env.HILOS_BACKFILL === "1" ? true : undefined,
+    once: process.env.HILOS_ONCE === "1" ? true : undefined,
+  };
+  const merged = { ...DEFAULTS, ...file };
+  for (const [k, v] of Object.entries(env)) if (v !== undefined && v !== "") merged[k] = v;
+  if (joinPayload) {
+    merged.url = joinPayload.url;
+    merged.token = joinPayload.token;
+    if (joinPayload.channelId) merged.channelId = joinPayload.channelId;
+  }
+  for (const [k, v] of Object.entries(flags)) if (v !== undefined) merged[k] = v;
+  merged.repos = { ...DEFAULTS.repos, ...(file.repos || {}) };
+  return merged;
+}
+
+/** Write a starter config file (used by `hilos-agent init`). */
+export function writeStarterConfig(path, partial = {}) {
+  const target = path || GLOBAL_CONFIG;
+  mkdirSync(dirname(target), { recursive: true });
+  const starter = {
+    url: partial.url || DEFAULTS.url,
+    token: partial.token || "",
+    channelId: partial.channelId || "",
+    repos: partial.repos || { "owner/name": "/absolute/path/to/checkout" },
+    codingCmd: partial.codingCmd || DEFAULTS.codingCmd,
+    defaultBranch: DEFAULTS.defaultBranch,
+    gate: true,
+  };
+  writeFileSync(target, JSON.stringify(starter, null, 2) + "\n");
+  return target;
+}

package/src/daemon.mjs

@@ -0,0 +1,87 @@
+// Pure daemon helpers — no I/O. (Mirror of the app's scripts/lib/daemon.mjs so
+// the package stands alone; keep them equivalent.)
+
+/** Branch name from a task: `hilos/<kebab-first-words>-<suffix>`. */
+export function branchSlug(text, suffix) {
+  const base =
+    String(text || "")
+      .toLowerCase()
+      .replace(/@[a-z0-9-]+/g, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .split("-")
+      .filter(Boolean)
+      .slice(0, 6)
+      .join("-") || "task";
+  return `hilos/${base}-${suffix}`;
+}
+
+/** Truncate a diff to a byte budget at a line boundary. */
+export function truncateDiff(diff, maxBytes = 12000) {
+  if (diff.length <= maxBytes) return { text: diff, truncated: false, omittedLines: 0 };
+  const slice = diff.slice(0, maxBytes);
+  const lastNl = slice.lastIndexOf("\n");
+  const kept = lastNl > 0 ? slice.slice(0, lastNl) : slice;
+  const omittedLines = diff.slice(kept.length).split("\n").length - 1;
+  return { text: kept, truncated: true, omittedLines };
+}
+
+/** Local checkout path for a repo from config, or null. */
+export function resolveRepoPath(config, repoFullName) {
+  return (config && config.repos && config.repos[repoFullName]) || null;
+}
+
+/** Parse `git diff --shortstat` output into counts. */
+export function parseShortstat(s) {
+  const files = /(\d+) files? changed/.exec(s || "");
+  const ins = /(\d+) insertions?\(\+\)/.exec(s || "");
+  const del = /(\d+) deletions?\(-\)/.exec(s || "");
+  return {
+    files: files ? Number(files[1]) : 0,
+    insertions: ins ? Number(ins[1]) : 0,
+    deletions: del ? Number(del[1]) : 0,
+  };
+}
+
+/** Read a decision kind off a report object, or null if undecided. */
+export function decisionKind(report) {
+  return report && report.decision && report.decision.kind ? report.decision.kind : null;
+}
+
+/** Commit message for an approved proposal. */
+export function commitMessage(task) {
+  const first = String(task || "").split("\n")[0].slice(0, 72) || "hilos change";
+  return `${first}\n\nProposed via hilos and approved by a human reviewer.`;
+}
+
+/** PR title + body for an approved proposal. */
+export function prTitleBody(task, branch) {
+  const title = String(task || "").split("\n")[0].slice(0, 72) || branch;
+  const body =
+    "Proposed by a hilos agent from a channel request, approved by a human reviewer.\n\n" +
+    `Task: ${String(task || "").trim()}`;
+  return { title, body };
+}
+
+/** Build the post_report payload that serves as the approval card. */
+export function buildProposalReport(o) {
+  const firstLine = String(o.task || "").split("\n")[0].slice(0, 72) || "task";
+  const statLine = `${o.stat.files} file(s), +${o.stat.insertions}/-${o.stat.deletions} on \`${o.branch}\` in ${o.repoFullName}`;
+  const diffBlock =
+    "```diff\n" +
+    o.diffText +
+    (o.truncated ? `\n… (+${o.omittedLines} more lines)` : "") +
+    "\n```";
+  const summary = `Proposed changes for: ${firstLine}\n\n${statLine}\n\n${diffBlock}`;
+  const caveats = ["Not pushed yet — approve to push + open a PR, or reject to discard."];
+  if (o.runFailed) caveats.push("The coding agent exited non-zero; review the diff carefully.");
+  return { title: `Proposal: ${firstLine}`, summary, caveats, todos: [] };
+}
+
+/** kebab handle from a display name (matches the server's mention handle). */
+export function mentionHandle(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}

package/src/handler.mjs

@@ -0,0 +1,236 @@
+// The default task handler: turn an @mention in a git-linked channel into a
+// branch + a coding-agent run + a proposed diff, gated on a human approval in
+// hilos. Nothing is pushed until approved. Your code + credentials stay local.
+
+import { spawnSync } from "node:child_process";
+import {
+  branchSlug,
+  truncateDiff,
+  resolveRepoPath,
+  parseShortstat,
+  buildProposalReport,
+  decisionKind,
+  commitMessage,
+  prTitleBody,
+} from "./daemon.mjs";
+
+function defaultDeps() {
+  return {
+    git: (cwd, args) =>
+      spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 50 * 1024 * 1024 }),
+    openPR: (cwd, { title, body, branch, base }) => {
+      const r = spawnSync(
+        "gh",
+        ["pr", "create", "--title", title, "--body", body, "--head", branch, "--base", base],
+        { cwd, encoding: "utf8" },
+      );
+      const url = (r.stdout || "").trim().split("\n").filter(Boolean).pop() || null;
+      return { ok: r.status === 0, url, stderr: r.stderr || "" };
+    },
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Date.now(),
+  };
+}
+
+async function awaitDecision({ tool, channelId, reportMessageId, cfg, deps }) {
+  if (!reportMessageId) return { kind: "timeout" };
+  const deadline = deps.now() + cfg.decisionTimeoutMs;
+  while (deps.now() < deadline) {
+    let report = null;
+    const gr = await tool("get_report", { messageId: reportMessageId }).catch(() => null);
+    if (gr && gr.found && gr.report) report = gr.report;
+    if (!report) {
+      const { messages = [] } = await tool("read_channel", { channelId, limit: 200 }).catch(
+        () => ({ messages: [] }),
+      );
+      const m = messages.find((x) => x.id === reportMessageId);
+      report = m && m.report ? m.report : null;
+    }
+    const kind = report ? decisionKind(report) : null;
+    if (kind) return { kind, note: report.decision?.note || null };
+    await deps.sleep(cfg.decisionPollMs);
+  }
+  return { kind: "timeout" };
+}
+
+async function applyDecision({ decision, repoPath, branch, task, cfg, tool, channelId, deps }) {
+  if (decision.kind === "approved") {
+    deps.git(repoPath, ["commit", "-m", commitMessage(task)]);
+    const push = deps.git(repoPath, ["push", "-u", "origin", branch]);
+    if (push.status !== 0) {
+      await tool("post_message", {
+        channelId,
+        body: `Approved, but the push failed: ${(push.stderr || "").trim().slice(0, 300)}`,
+      });
+      return { status: "push-failed", branch };
+    }
+    const { title, body } = prTitleBody(task, branch);
+    const pr = deps.openPR(repoPath, { title, body, branch, base: cfg.defaultBranch });
+    await tool("post_report", {
+      channelId,
+      title: `Shipped: ${title}`,
+      summary:
+        pr.ok && pr.url
+          ? `Pushed \`${branch}\` and opened a pull request.`
+          : `Pushed \`${branch}\`. Open a PR manually — \`gh\` failed.`,
+      prUrl: pr.ok && pr.url ? pr.url : undefined,
+      caveats: pr.ok ? [] : [`gh pr create failed: ${(pr.stderr || "").trim().slice(0, 200)}`],
+    });
+    return { status: "pushed", branch, prUrl: pr.ok ? pr.url : null };
+  }
+
+  if (decision.kind === "rejected") {
+    deps.git(repoPath, ["reset", "--hard", "HEAD"]);
+    deps.git(repoPath, ["clean", "-fd"]);
+    deps.git(repoPath, ["switch", "-"]);
+    deps.git(repoPath, ["branch", "-D", branch]);
+    await tool("post_message", { channelId, body: `Rejected — discarded \`${branch}\`.` });
+    return { status: "discarded", branch };
+  }
+
+  if (decision.kind === "changes") {
+    await tool("post_message", {
+      channelId,
+      body: `Got it${decision.note ? `: ${decision.note}` : ""}. Leaving \`${branch}\` for a follow-up.`,
+    });
+    return { status: "changes", branch, note: decision.note };
+  }
+
+  await tool("post_message", {
+    channelId,
+    body: `Still awaiting review on \`${branch}\`. Re-mention me once you've decided.`,
+  });
+  return { status: "timeout", branch };
+}
+
+/** Handle one task. cfg/deps injectable for tests. */
+export async function handleTask({ message, channelId, tool }, cfg, depsOverride) {
+  const deps = depsOverride || defaultDeps();
+  const git = deps.git;
+
+  const { links = [] } = await tool("get_links", { channelId }).catch(() => ({ links: [] }));
+  const repoLink = links.find((l) => l.repo_full_name);
+  if (!repoLink) {
+    await tool("post_message", {
+      channelId,
+      body: "No repo is linked to this channel — link one so I can work on it.",
+    });
+    return { status: "no-repo" };
+  }
+  const repoFullName = repoLink.repo_full_name;
+
+  const repoPath = resolveRepoPath(cfg, repoFullName);
+  if (!repoPath) {
+    await tool("post_message", {
+      channelId,
+      body: `No local path is configured for ${repoFullName}. Add it to your hilos-agent.json under "repos".`,
+    });
+    return { status: "no-path" };
+  }
+
+  const status = git(repoPath, ["status", "--porcelain"]);
+  if (status.status !== 0) {
+    await tool("post_message", { channelId, body: `Can't read git status in ${repoPath}.` });
+    return { status: "git-error" };
+  }
+  if (status.stdout.trim()) {
+    await tool("post_message", {
+      channelId,
+      body: `Working tree at ${repoPath} is dirty — commit or stash first.`,
+    });
+    return { status: "dirty" };
+  }
+
+  const branch = branchSlug(message.body, String(deps.now()).slice(-6));
+  git(repoPath, ["fetch", "origin", cfg.defaultBranch]);
+  const co = git(repoPath, ["switch", "-c", branch]);
+  if (co.status !== 0) {
+    await tool("post_message", {
+      channelId,
+      body: `Couldn't create branch \`${branch}\`: ${co.stderr.trim()}`,
+    });
+    return { status: "branch-error" };
+  }
+
+  await tool("post_message", {
+    channelId,
+    body: `On it — working in ${repoFullName} on \`${branch}\`.`,
+  });
+
+  const parts = cfg.codingCmd.split(" ").filter(Boolean);
+  const proposeRound = async (promptText) => {
+    const run = spawnSync(parts[0], [...parts.slice(1), promptText], {
+      cwd: repoPath,
+      encoding: "utf8",
+      timeout: cfg.runTimeoutMs,
+      maxBuffer: 50 * 1024 * 1024,
+    });
+    git(repoPath, ["add", "-A"]);
+    const diff = git(repoPath, ["diff", "--cached"]).stdout || "";
+    if (!diff.trim()) return { empty: true };
+    const stat = parseShortstat(git(repoPath, ["diff", "--cached", "--shortstat"]).stdout);
+    const { text: diffText, truncated, omittedLines } = truncateDiff(diff);
+    const report = buildProposalReport({
+      task: message.body,
+      repoFullName,
+      branch,
+      diffText,
+      truncated,
+      omittedLines,
+      stat,
+      runFailed: run.status !== 0,
+    });
+    const res = await tool("post_report", { channelId, ...report });
+    return { reportMessageId: res?.messageId ?? null, stat };
+  };
+
+  let proposal = await proposeRound(message.body);
+  if (proposal.empty) {
+    await tool("post_message", {
+      channelId,
+      body: `No changes were produced. Cleaning up \`${branch}\`.`,
+    });
+    git(repoPath, ["switch", "-"]);
+    git(repoPath, ["branch", "-D", branch]);
+    return { status: "no-changes" };
+  }
+
+  if (!cfg.gate) {
+    return { status: "proposed", branch, reportMessageId: proposal.reportMessageId, stat: proposal.stat };
+  }
+
+  let decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps });
+  const maxRounds = cfg.maxRounds || 3;
+  let round = 1;
+  while (decision.kind === "changes" && round < maxRounds) {
+    await tool("post_message", {
+      channelId,
+      body: `Revising with your feedback${decision.note ? `: ${decision.note}` : ""} (round ${round + 1}/${maxRounds}).`,
+    });
+    const refined = await proposeRound(
+      `${message.body}\n\nReviewer feedback to address: ${decision.note || "(see the channel)"}`,
+    );
+    if (refined.empty) {
+      await tool("post_message", {
+        channelId,
+        body: `That feedback produced no further changes — leaving \`${branch}\` as proposed.`,
+      });
+      break;
+    }
+    proposal = refined;
+    decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps });
+    round += 1;
+  }
+
+  const result = await applyDecision({
+    decision,
+    repoPath,
+    branch,
+    task: message.body,
+    cfg,
+    tool,
+    channelId,
+    deps,
+  });
+  return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round };
+}

package/src/mcp.mjs

@@ -0,0 +1,38 @@
+// Minimal MCP-over-HTTP client (JSON-RPC 2.0). Dependency-free: uses global
+// fetch (Node >= 18). One bearer token, one endpoint.
+
+export function makeClient({ url, token }) {
+  let id = 0;
+
+  async function rpc(method, params) {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params }),
+    });
+    const json = await res.json();
+    if (json.error) throw new Error(json.error.message || "rpc error");
+    return json.result;
+  }
+
+  // Call a tool and parse its first text block (hilos tools return JSON text).
+  async function tool(name, args = {}) {
+    const r = await rpc("tools/call", { name, arguments: args });
+    const text = r?.content?.[0]?.text;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  async function listToolNames() {
+    try {
+      return ((await rpc("tools/list"))?.tools ?? []).map((t) => t.name);
+    } catch {
+      return [];
+    }
+  }
+
+  return { rpc, tool, listToolNames };
+}

package/src/run.mjs

@@ -0,0 +1,83 @@
+// The poll loop: connect over MCP, watch for @mentions of this agent, and hand
+// each one to the task handler. Prefers the workspace-wide list_mentions tool
+// (one poll, cursor-based); falls back to per-channel scanning on older servers.
+
+import { makeClient } from "./mcp.mjs";
+import { mentionHandle } from "./daemon.mjs";
+import { handleTask } from "./handler.mjs";
+
+export async function run(cfg, { handler = handleTask, log = console } = {}) {
+  if (!cfg.token) {
+    log.error("No token. Run `hilos-agent init`, set HILOS_TOKEN, or use --join <blob>.");
+    process.exit(1);
+  }
+
+  const { tool, listToolNames } = makeClient({ url: cfg.url, token: cfg.token });
+
+  const who = await tool("whoami");
+  const me = { ...who, handle: mentionHandle(who.agentName) };
+  log.log(`hilos-agent: ${me.agentName} (@${me.handle}) — ${cfg.url}`);
+  if (cfg.channelId) log.log(`scope: channel ${cfg.channelId}`);
+  log.log(`repos: ${Object.keys(cfg.repos).join(", ") || "(none configured)"}`);
+
+  const since = cfg.backfill ? 0 : Date.now();
+  const toolNames = await listToolNames();
+  const useMentions = !cfg.channelId && toolNames.includes("list_mentions");
+
+  let channelIds = [];
+  if (!useMentions) {
+    if (cfg.channelId) channelIds = [cfg.channelId];
+    else channelIds = ((await tool("list_channels"))?.channels ?? []).map((c) => c.id);
+  }
+  log.log(useMentions ? "watching: @-mentions" : `watching: ${channelIds.length} channel(s)`);
+
+  const seen = new Set();
+  const cursor = { value: since ? new Date(since).toISOString() : null };
+
+  async function passViaMentions() {
+    const out = await tool("list_mentions", cursor.value ? { since: cursor.value } : {});
+    const mentions = (out?.mentions ?? []).slice().reverse();
+    for (const m of mentions) {
+      if (seen.has(m.id)) continue;
+      seen.add(m.id);
+      await safeHandle(m, m.channelId);
+      if (!cursor.value || m.created_at > cursor.value) cursor.value = m.created_at;
+    }
+  }
+
+  async function passViaScan() {
+    for (const channelId of channelIds) {
+      const out = await tool("read_channel", { channelId, limit: 30 });
+      for (const m of out?.messages ?? []) {
+        if (seen.has(m.id)) continue;
+        seen.add(m.id);
+        if (m.author === me.agentName) continue;
+        const isMention = new RegExp(`@${me.handle}\\b`, "i").test(m.body || "");
+        if (isMention && new Date(m.created_at).getTime() >= since) await safeHandle(m, channelId);
+      }
+    }
+  }
+
+  async function safeHandle(message, channelId) {
+    try {
+      log.log(`→ task in ${channelId}: "${(message.body || "").slice(0, 80)}"`);
+      await handler({ message, channelId, tool }, cfg);
+    } catch (e) {
+      log.error(`handler error: ${e.message}`);
+      await tool("post_message", {
+        channelId,
+        body: `Hit an error working on that: ${e.message}`,
+      }).catch(() => {});
+    }
+  }
+
+  do {
+    try {
+      if (useMentions) await passViaMentions();
+      else await passViaScan();
+    } catch (e) {
+      log.error(`poll error: ${e.message}`);
+    }
+    if (!cfg.once) await new Promise((r) => setTimeout(r, cfg.pollMs));
+  } while (!cfg.once);
+}