hilos-agent 0.9.1 → 0.9.3

package/README.md

@@ -4,7 +4,8 @@ Run **your own** coding agent — Claude Code, Codex, Cursor, opencode, Hermes,
 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 (including thread replies), runs your coding agent in a
+git-linked channel (including thread replies) and for **every message in a DM
+with your agent — no tag needed there**, runs your coding agent in a
 **local** checkout, and — by default — **opens a PR for review**. Your code and
 your git/`gh` credentials never leave your machine — hilos only relays messages.
 
@@ -31,7 +32,7 @@ needed:
 
 ```sh
 cd ~/code/your-repo
-npx hilos-agent --join <blob>        # token + endpoint from the link; repo auto-detected from cwd
+npx hilos-agent@latest --join <blob> # token + endpoint from the link; repo auto-detected from cwd
 ```
 
 Running from elsewhere, or want to map several repos explicitly? Use a config:
@@ -43,7 +44,7 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
   "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "opencode run", "agy -p", any command
-  "codingModel": "",  // model preset tier ("opus" | "sonnet" | "haiku") resolved at run time against the CLI's own model list (Cursor only today); "" = the tool's default
+  "codingModel": "",  // Codex tier ("most-capable" | "balanced" | "fastest"), resolved against this account's own model list; "" = the tool's default
   "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
   "defaultBranch": "main",
   "gate": false,               // default: open a PR directly. true = approve-before-push
@@ -73,7 +74,14 @@ 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.
+- **Trigger** — an `@mention` of your agent in a channel that's linked to a repo,
+  or any message in a DM with your agent (a DM is the address — no tag needed;
+  there, and only there, the agent may also answer with an emoji reaction or
+  stay quiet when a message truly needs nothing).
+  Mentions are picked up by polling; on servers that expose `get_wake_channel`,
+  a realtime doorbell (a content-free broadcast on every new message) wakes the
+  poll instantly, so pickup takes about a second instead of a poll interval
+  (needs Node >= 22 for the built-in WebSocket; otherwise it just keeps polling).
 - **Chat or code?** — the agent reads the conversation and decides with the model
   (via `chatCmd`), not a keyword list: a question/greeting/"let's just discuss" →
   a chat reply; anything asking for a change — including "just code it", "finish
@@ -189,13 +197,15 @@ backward compatible — omit them and the CLI behaves exactly as before.
 
 ## Model & permissions
 
-You don't have to hand-write `codingCmd`: the agent's **Connect via MCP** panel in
-hilos has **Model** (Vendor default / Opus / Sonnet / Haiku) and **Permissions**
-(Ask before edits / Auto-approve edits / Skip all prompts) pickers that bake your
-choice into the generated `--coding-cmd`. Change it later by editing `codingCmd` in
-`hilos-agent.json` — the daemon re-reads the file between polls and applies it
-without a restart (your `url`/`token` are never affected). The next section
-explains what each permission level means.
+You don't have to hand-write `codingCmd`: the agent's connection panel emits
+the selected provider's real executable and verified flags. Claude Code uses
+its stable `opus` / `sonnet` / `haiku` aliases. Codex carries a neutral
+`most-capable` / `balanced` / `fastest` tier that resolves against that
+account's own live catalog. Cursor, opencode, Antigravity, and Hermes keep their
+own model setting because no universal tier maps honestly onto their catalogs.
+Unsupported permission choices are omitted from the UI. Change the command
+later in `hilos-agent.json`; the daemon re-reads it between polls without
+touching the token.
 
 ## Permissions / autonomy
 
@@ -246,32 +256,43 @@ becomes the next turn in the same local session and checkout.
 
 ```sh
 # Inside the repo you want to stream:
-npx hilos-agent hooks install
+npx hilos-agent@latest hooks install
 
 # Install only one provider, if you prefer:
-npx hilos-agent hooks install --codex
-npx hilos-agent hooks install --claude
-npx hilos-agent hooks install --cursor
+npx hilos-agent@latest hooks install --codex
+npx hilos-agent@latest hooks install --claude
+npx hilos-agent@latest hooks install --cursor
 
 # Or opt in every repo on this machine:
-npx hilos-agent hooks install --global
+npx hilos-agent@latest hooks install --global
 ```
 
-This writes lifecycle entries into `.codex/hooks.json`, `.claude/settings.json`,
-and `.cursor/hooks.json` (or their home-directory equivalents with `--global`),
-preserving any hooks you already have. Codex asks you to review new project
-hooks once; open `/hooks` and trust the hilos entries. Preview all three blocks
-without writing anything:
+Claude Code and Cursor write lifecycle entries into this repo. Codex needs one
+entry in `~/.codex/hooks.json` because `codex exec` does not run repository
+hooks. hilos keeps that entry project-scoped with a 0600 allowlist at
+`~/.hilos/codex-hook-scope.json`, so other repos stay untouched unless you use
+`--global`. Launching Codex below the opted-in repository root still works, but
+a nested repository needs its own opt-in. If the allowlist is lost or malformed,
+new installs fail closed instead of reporting from every repo.
+
+Any hooks you already have are preserved. A pre-existing project-level hilos
+Codex entry is moved out, with a `.bak` beside the changed file. Codex asks you
+to review the home-level hilos hook once; open `/hooks` and trust the entry.
+The installer copies the dependency-free hook code into a private, versioned
+`~/.hilos/hook-runtime` and records its absolute entrypoint. A one-off npx run
+therefore remains usable offline; no global install or PATH change is required.
+Preview all three blocks without writing anything:
 
 ```sh
-npx hilos-agent hooks print
+npx hilos-agent@latest hooks print
 ```
 
 **Requirements:**
-- `npm i -g hilos-agent` so the `hilos-agent hook` command resolves at hook time.
-- A `~/.hilos/agent.json` with `url` and the owned agent's `token`; `channelId`
-  is needed only for the fallback live card. Generate these in the agent's
-  **Connect via MCP** panel in hilos (same panel as `--join`).
+- For live progress from every tool event, a `~/.hilos/agent.json` with `url`
+  and the owned agent's `token`; `channelId` is needed only for the fallback
+  live card. The normal one-line `--join` flow does not need that file for
+  replies: its token stays in daemon memory, and Hilos signs each session
+  binding so the daemon can verify it before resuming local code.
 - Keep `hilos-agent` running to pick replies up. Hooks alone still stream live
   steps, but MCP has no server-push channel that can wake an idle local client.
 
@@ -281,7 +302,14 @@ npx hilos-agent hooks print
 - A successful hilos post binds its returned message to this provider session.
   A person's later reply to that exact thread resumes the same session while
   `hilos-agent` is running. Ambient messages, older thread history, and agent
-  replies do not wake it.
+  replies do not wake it. Current workspace roles are checked at pickup: guests,
+  removed people, and unknown authors remain advisory and cannot start code.
+- The resumed turn receives bounded thread, room, and member context. Codex also
+  gets a random loopback-only Hilos MCP URL for that turn, so it can search any
+  room its linked owner can access when that owner minted the current key,
+  without receiving the bearer token. Regenerate an older key from Connect to
+  enable that inheritance. Admin-issued keys and other people's private rooms
+  stay outside the context.
 - The room's normal execution gate still applies; a chat-only guest room cannot
   resume local code.
 - Steps are coalesced into ~2s batches to keep traffic light.
@@ -290,10 +318,12 @@ npx hilos-agent hooks print
 - Up to 20 unique files touched are surfaced so reviewers can glance at the scope
   before the report card arrives.
 
-**Privacy:** project-level by default (only repos you opt into stream). Hook
-state stays in `~/.hilos/hook-state` and contains session ids, checkout paths,
-hilos message ids, progress steps, and any completed result waiting for a
-delivery retry — never the coding transcript. Kill
+**Privacy:** project-level by default (only repos you opt into stream, including
+Codex through its local allowlist). Hook state stays in
+`~/.hilos/hook-state` and contains session ids, checkout paths,
+hilos message ids, an opaque server-signed binding proof, a one-way credential
+scope after verification, progress steps, and any completed result waiting for
+a delivery retry — never the bearer token or coding transcript. Kill
 switches: `HILOS_HOOKS=off` pauses streaming and new bindings;
 `HILOS_REPLY_BRIDGE=off` pauses inbound replies. The hook always exits 0 — it
 will never interrupt or break your CLI session.

package/bin/hilos-agent.mjs

@@ -50,6 +50,8 @@ function parseArgs(argv) {
     else if (a === "--codex") flags.hookClient = "codex";
     else if (a === "--cursor") flags.hookClient = "cursor";
     else if (a === "--vendor") flags.vendor = argv[++i];
+    else if (a === "--scope-managed") flags.scopeManaged = true;
+    else if (a === "--managed-runtime") flags.managedRuntime = true;
     else if (a === "-h" || a === "--help") flags.help = true;
     else if (a === "-v" || a === "--version") flags.version = true;
     else positional.push(a);
@@ -73,12 +75,14 @@ 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 — claude -p, codex exec,
-                     cursor-agent -p --trust, opencode run, agy -p, hermes,
+                     cursor-agent -p --trust, opencode run, agy -p, hermes -z,
                      or any command
-                     that takes a prompt as its last arg (default: "claude -p")
-  --coding-model <tier>  model preset tier (opus | sonnet | haiku) resolved at
+                     that takes a prompt as its last arg (default:
+                     "claude -p --permission-mode acceptEdits")
+  --coding-model <tier>  model tier (default | most-capable | balanced | fastest)
+                     resolved at
                      run time against the CLI's own model list — never a baked
-                     id (Cursor only today; default: the tool's own model)
+                     id (Codex only today; default: the tool's own model)
   --chat-cmd <cmd>   fast command for chat replies + the plan-ack (default:
                      derived from the coding command, so a Codex or Cursor
                      daemon chats with its own tool)
@@ -106,7 +110,7 @@ async function main() {
   // fast, silent, and always exit 0, so it short-circuits before any daemon
   // machinery.
   if (cmd === "hook") {
-    await hookMain({ vendor: flags.vendor || "unknown" });
+    await hookMain({ vendor: flags.vendor || "unknown", scopeManaged: Boolean(flags.scopeManaged) });
     return;
   }
   if (cmd === "hooks") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
   "type": "module",
   "bin": {

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/config.mjs

@@ -103,9 +103,10 @@ const DEFAULTS = {
   codingEnv: "inherit",
   codingEnvAllow: [],
   // Model preset TIER for the coding run ("" / "default" = the tool's own
-  // default). "opus" | "sonnet" | "haiku" resolve at RUN time against the
-  // CLI's own model list — never a baked id that could 404 on another account
-  // (0504; cursor only today, see model-resolve.mjs).
+  // default). "most-capable" | "balanced" | "fastest" resolve at RUN time
+  // against Codex's own model list — never a baked id that could 404 on
+  // another account. The original opus/sonnet/haiku and Cursor values remain
+  // accepted as backward-compatible read aliases (0864).
   codingModel: "",
   // Chat replies + the code-task plan-ack use a FAST one-shot command so a casual
   // reply (or "I see it, here's my plan") comes back in seconds, not minutes.

package/src/handler.mjs

@@ -992,6 +992,58 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
 // code. Unusual on purpose so it can't be confused with a real chat reply.
 const CODE_SIGNAL = "__CODE__";
 
+// 0860 — the quiet option, offered ONLY on untagged DM wakes (message.implicit
+// === "dm"). In a DM every message reaches the agent without a tag, so some of
+// what arrives genuinely needs nothing: a closing "thanks", an "ok", an aside.
+// The model may answer those with this token instead of words — optionally
+// followed by one emoji to react with. An explicit @-mention NEVER gets this
+// option: a summons deserves a reply, and silence there is the exact
+// "agent ignores me" failure this ticket exists to end.
+export const NO_REPLY_SIGNAL = "__NO_REPLY__";
+
+/**
+ * Read the quiet-option sentinel off a chat model's output. Counts only when
+ * the FIRST non-empty line is the token alone or the token plus one emoji-ish
+ * word (no letters or digits — "__NO_REPLY__ ok" is a malformed reply, not a
+ * reaction, and posts as text so nothing a person needs gets eaten silently).
+ * @param {string} text
+ * @returns {{ noReply: boolean, emoji: string | null }}
+ */
+export function parseNoReply(text) {
+  const firstLine = String(text || "")
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  if (!firstLine || !firstLine.startsWith(NO_REPLY_SIGNAL)) {
+    return { noReply: false, emoji: null };
+  }
+  const rest = firstLine.slice(NO_REPLY_SIGNAL.length).trim();
+  if (!rest) return { noReply: true, emoji: null };
+  const tokens = rest.split(/\s+/);
+  const [emoji] = tokens;
+  if (tokens.length === 1 && emoji.length <= 16 && !/[A-Za-z0-9]/.test(emoji)) {
+    return { noReply: true, emoji };
+  }
+  return { noReply: false, emoji: null };
+}
+
+/**
+ * The prompt paragraph that grants the quiet option. Empty unless this wake is
+ * an untagged DM message — the ONLY context where not answering is ever right.
+ */
+export function dmJudgmentBlock(implicitDm) {
+  if (!implicitDm) return "";
+  return (
+    `\n\nThis is a direct-message conversation with you: the latest message reached you ` +
+    `because every DM message does — nobody typed your @-handle. Almost every message still ` +
+    `deserves your reply, and when in doubt, reply. But if the latest message truly needs ` +
+    `nothing from you — a closing "thanks" or "ok", a nicety, or something clearly said to ` +
+    `another person in this conversation — output ONLY the token ${NO_REPLY_SIGNAL}, ` +
+    `optionally followed by a single emoji to react with instead (e.g. ${NO_REPLY_SIGNAL} 👍). ` +
+    `Never use ${NO_REPLY_SIGNAL} on a question, a request, or anything that expects an answer.`
+  );
+}
+
 /**
  * Decide — with the LLM, not a word list — whether the latest message wants a
  * code change or a conversational reply, and produce the payload in the SAME
@@ -1012,7 +1064,7 @@ const CODE_SIGNAL = "__CODE__";
  * `error` is set when the model produced nothing (so the caller can be honest
  * about a timeout vs a missing binary instead of inventing a reply).
  */
-async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false, runCliFn }) {
+async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false, runCliFn, implicitDm = false }) {
   const doRun = runCliFn || runCli; // folder mode injects deps.runCli; repo flow uses the import
   const cmd = chatCmdFor(cfg);
   const parts = cmd.split(" ").filter(Boolean);
@@ -1046,7 +1098,8 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     `action language.` +
     `${followupBlock}\n\n` +
     `You are only routing here — output ONLY your text response. Do NOT use any tools, do NOT ` +
-    `edit files, do NOT run commands; a separate step does the actual coding.\n\n` +
+    `edit files, do NOT run commands; a separate step does the actual coding.` +
+    `${dmJudgmentBlock(implicitDm)}\n\n` +
     `${memoryPreamble(workspaceMemory)}Conversation so far:\n${transcript}`;
   const run = await doRun({
     cmd: parts[0],
@@ -1075,6 +1128,12 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     const nl = after.indexOf("\n");
     return { code: true, task: (nl >= 0 ? after.slice(nl + 1) : after).trim(), followupSignal };
   }
+  // The quiet option (0860) — only ever offered (and only ever honored) on an
+  // untagged DM wake, so a tagged summons can never be answered with silence.
+  if (implicitDm) {
+    const quiet = parseNoReply(out);
+    if (quiet.noReply) return { code: false, noReply: true, emoji: quiet.emoji, followupSignal };
+  }
   return { code: false, reply: out, followupSignal };
 }
 
@@ -1237,9 +1296,19 @@ async function proposePlanAck({ task, transcript, repoFullName, cfg, signal }) {
   return text.length > 400 ? text.slice(0, 399) + "…" : text;
 }
 
+/**
+ * React to the wake's message instead of replying (0860). Best-effort and
+ * capability-gated: on an older server (no add_reaction) or any failure the
+ * agent simply stays quiet, which is what the model chose anyway.
+ */
+async function reactQuietly({ tool, caps, message, emoji }) {
+  if (!emoji || !caps?.react || !message?.id) return;
+  await tool("add_reaction", { messageId: message.id, emoji }).catch(() => {});
+}
+
 /** Run the FAST chat CLI to produce a reply, using recent channel context. */
 async function respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps = {} }) {
-  void message;
+  const implicitDm = message?.implicit === "dm";
   const { transcript } = context || (await fetchContext({ channelId, tool, parentId }));
   const name = me?.agentName || "an assistant";
   // Tell the agent what the room is connected to so it doesn't ask "which repo?".
@@ -1255,7 +1324,8 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   const prompt =
     `You are ${name}, a teammate in a team chat (hilos). Reply to the latest message ` +
     `concisely and directly as a single chat message — no preamble, no headings. ` +
-    `${repoLine}\n\n` +
+    `${repoLine}` +
+    `${dmJudgmentBlock(implicitDm)}\n\n` +
     `${memoryPreamble(workspaceMemory)}` +
     `Conversation so far:\n${transcript}`;
 
@@ -1320,6 +1390,21 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   }
   const reply = (run.stdout || "").trim();
   if (run.error) console.log(`  ! ${parts[0]}: ${run.error.message}`);
+  // The quiet option (0860), honored only on an untagged DM wake. If a slow
+  // decision already posted a "Still thinking…" ping, silence would strand it
+  // — settle the ping with the reaction emoji (or a plain nod) instead.
+  if (implicitDm) {
+    const quiet = parseNoReply(reply);
+    if (quiet.noReply) {
+      console.log(`  chat → quiet${quiet.emoji ? ` (reacting ${quiet.emoji})` : " (no reply needed)"}`);
+      if (thinkingId) {
+        await deliver(quiet.emoji || "👍");
+      } else {
+        await reactQuietly({ tool, caps, message, emoji: quiet.emoji });
+      }
+      return;
+    }
+  }
   console.log(`  chat → ${reply ? `replied (${reply.length} chars)` : "no output"}; posting`);
   // Honest fallback: a timeout is NOT a missing binary. Only a real spawn failure
   // (ENOENT) means the command isn't on PATH.
@@ -2407,6 +2492,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   const onStopRequested = opts.onStopRequested;
   // When the mention was a thread reply, keep the whole exchange in that thread.
   const parentId = message.parentId ?? null;
+  // 0860 — an untagged DM wake: addressed by the room, not by an @-handle. The
+  // one context where the router/chat prompts offer the quiet option.
+  const implicitDm = message.implicit === "dm";
 
   const { links = [] } = await tool("get_links", { channelId }).catch(() => ({ links: [] }));
   // A folder link (0324) carries the folder PATH in repo_full_name for display —
@@ -2598,12 +2686,17 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
                 cfg,
                 signal,
                 runCliFn: deps.runCli,
+                implicitDm,
               });
       }
       if (routed.aborted || signal?.aborted) {
         await tool("post_message", { channelId, parentId, body: "Stopped." });
         return { status: "chat" };
       }
+      if (routed.noReply) {
+        await reactQuietly({ tool, caps, message, emoji: routed.emoji });
+        return { status: "quiet" };
+      }
       if (routed.code) {
         return await handleFolderTask({
           message,
@@ -2676,12 +2769,17 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           cfg,
           signal,
           hasActiveRun: activeRunOpen,
+          implicitDm,
         });
   if (routed.aborted || signal?.aborted) {
     await tool("post_message", { channelId, parentId, body: "Stopped." });
     return { status: "chat" };
   }
   if (!routed.code) {
+    if (routed.noReply) {
+      await reactQuietly({ tool, caps, message, emoji: routed.emoji });
+      return { status: "quiet" };
+    }
     let body = routed.reply;
     if (!body) {
       body =