hilos-agent 0.1.16 → 0.4.0

package/README.md

@@ -87,6 +87,69 @@ hilos-agent --channel <id>   # scope to one channel
   card and polls for your decision; **Approve** pushes + opens the PR, **Reject**
   discards the branch, **Request changes** re-runs with your note (bounded rounds).
 
+## Local folders (no repo required)
+
+A channel doesn't need a linked GitHub repo to get coding work done. Map a channel
+to a plain **local folder** and the agent works in it **directly** — it edits the
+files in place (no branch, no commit, no PR), then posts a report of what changed.
+It's your own machine, so this is the same trust as running the CLI yourself.
+
+```jsonc
+// hilos-agent.json
+{
+  "folders": { "<channelId>": "/Users/you/notes-site" }
+}
+```
+
+- **Trigger** — an `@mention` in a channel with **no linked repo** but a `folders`
+  mapping. The same LLM router decides chat vs. code; a coding ask runs in the
+  folder.
+- **Git folders** — if the folder is a git repo, the agent snapshots `git status`
+  before/after and reports the exact files it created/changed/removed plus a
+  `git diff --stat`. It **never** touches your index, branches, pushes, or runs
+  `gh`. On the report card: **Approve** keeps the changes (they're already live),
+  **Request changes** re-runs in place with your note (bounded by `maxRounds`),
+  **Reject** reverts *only what this run changed* (`git checkout` the files it
+  modified, delete the files it created) — your pre-existing local edits are left
+  untouched.
+- **Non-git folders** — it still runs, but says up front it can't show a file-level
+  diff or auto-undo; a reject asks you to revert by hand.
+- A **linked repo always wins** — the folder map is only consulted when the channel
+  has no repo link.
+- **Folder link registration** — on startup the daemon registers each `folders`
+  mapping with hilos (over the `link_folder` MCP tool) so the channel shows a
+  folder chip — the folder's name, its full path, and which machine it lives on —
+  without any manual step. It's best-effort and capability-gated: older servers
+  that don't expose `link_folder` are skipped silently, and a failed registration
+  only logs a line, never blocking the daemon. Registration happens once at
+  startup, so a `folders` entry added while the daemon is running needs a restart
+  to appear.
+
+## Embedding the daemon
+
+`run(cfg, opts)` is the poll loop, and it's embeddable. Beyond `handler`/`log` it
+accepts:
+
+```js
+import { run } from "hilos-agent/src/run.mjs";
+
+const controller = new AbortController();
+await run(cfg, {
+  signal: controller.signal,   // abort → interrupts the poll sleep, cancels the
+                               //         active job, and returns cleanly
+  onEvent: (e) => {            // lifecycle events for a host UI (wrapped in
+    // e.type: "status" | "task-start" | "task-done" | "task-error"
+    console.log(e);            //   try/catch — a bad listener can't crash the loop)
+  },
+});
+// later: controller.abort();  // run() resolves once the active job tears down
+```
+
+Event shapes: `{ type: "status", text }`, `{ type: "task-start", channelId,
+messageId, text }`, `{ type: "task-done", channelId, status }`, and
+`{ type: "task-error", channelId, error }`. Both options are optional and fully
+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
@@ -125,6 +188,47 @@ The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
 you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
 before anything is pushed.
 
+## Hooks — stream a raw Claude Code session
+
+Don't want to run a persistent daemon? You can still make your Claude Code CLI
+sessions visible to your team in real time. **Claude Code hooks** (shipped in
+0448) let every tool call your session makes stream directly into your agent's
+live status card in hilos — no daemon, no extra process.
+
+```sh
+# Inside the repo you want to stream:
+npx hilos-agent hooks install
+
+# Or stream all your Claude Code sessions, everywhere:
+npx hilos-agent hooks install --global
+```
+
+This writes `PostToolUse`, `Stop`, and `SessionEnd` hook entries into
+`.claude/settings.json` (project) or `~/.claude/settings.json` (global),
+preserving any hooks you already have. Preview the block without writing anything:
+
+```sh
+npx hilos-agent hooks print
+```
+
+**Requirements:**
+- `npm i -g hilos-agent` so the `hilos-agent hook` command resolves at hook time.
+- A `~/.hilos/agent.json` with `url`, `token`, and `channelId`. Generate these in
+  the agent's **Connect via MCP** panel in hilos (same panel as `--join`).
+
+**What you get:**
+- Team members see "Editing lib/x.ts" or "Running pnpm test" on the agent's live
+  card as each tool fires — without you doing anything beyond the install.
+- Steps are coalesced into ~2s batches to keep traffic light.
+- When a turn ends (`Stop`), the card settles to done. The next turn revives the
+  same card — one card per session, not one per turn.
+- 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). Global
+kill switch: `HILOS_HOOKS=off`. The hook always exits 0 — it will never interrupt
+or break your CLI session.
+
 ## Security
 
 The daemon runs a coding agent that can execute code in your repo — exactly as if

package/bin/hilos-agent.mjs

@@ -18,6 +18,7 @@
 
 import { resolveConfig, decodeJoin, writeStarterConfig, GLOBAL_CONFIG } from "../src/config.mjs";
 import { run } from "../src/run.mjs";
+import { hookMain, hooksMain } from "../src/hook.mjs";
 
 function parseArgs(argv) {
   const flags = {};
@@ -34,10 +35,11 @@ function parseArgs(argv) {
     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 === "--global") flags.global = true;
     else if (a === "-h" || a === "--help") flags.help = true;
     else positional.push(a);
   }
-  return { cmd: positional[0] || "run", flags };
+  return { cmd: positional[0] || "run", flags, positional };
 }
 
 const HELP = `hilos-agent — your coding agent as a teammate in hilos
@@ -45,6 +47,10 @@ 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)
+  hilos-agent hooks install      stream this repo's Claude Code sessions to your
+                                 hilos channel (writes .claude/settings.json;
+                                 --global for every repo). "hooks print" shows
+                                 the snippet; HILOS_HOOKS=off pauses streaming.
 
 Options:
   --channel <id>     watch only one channel (per-channel override)
@@ -60,12 +66,24 @@ Options:
 Docs: https://hilos.sh  ·  https://www.npmjs.com/package/hilos-agent`;
 
 async function main() {
-  const { cmd, flags } = parseArgs(process.argv.slice(2));
+  const { cmd, flags, positional } = parseArgs(process.argv.slice(2));
   if (flags.help || cmd === "help") {
     console.log(HELP);
     return;
   }
 
+  // `hook` is invoked BY Claude Code on every tool call (0448) — it must be
+  // fast, silent, and always exit 0, so it short-circuits before any daemon
+  // machinery.
+  if (cmd === "hook") {
+    await hookMain();
+    return;
+  }
+  if (cmd === "hooks") {
+    hooksMain(positional[1], { global: Boolean(flags.global) });
+    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.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.1.16",
+  "version": "0.4.0",
   "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/config.mjs

@@ -43,6 +43,11 @@ const DEFAULTS = {
   token: "",
   channelId: "", // when set, watch only this channel (the per-channel override)
   repos: {},
+  // Local-folder mode (0322): map a channelId → an absolute folder path so a
+  // channel with NO linked GitHub repo can still get coding work done in a plain
+  // folder on this machine. Changes apply directly (no branch/PR). Live-reloadable
+  // like `repos`. Shape: { "<channelId>": "/abs/path" }.
+  folders: {},
   // acceptEdits lets the CLI make file edits without prompting (bias to action);
   // it still won't run arbitrary commands. Override in hilos-agent.json if you
   // want a stricter (or `--dangerously-skip-permissions`) command.
@@ -111,6 +116,8 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
   }
   for (const [k, v] of Object.entries(flags)) if (v !== undefined) merged[k] = v;
   merged.repos = { ...DEFAULTS.repos, ...(file.repos || {}) };
+  // Local-folder map, merged like `repos` (an object, not a scalar overlay).
+  merged.folders = { ...DEFAULTS.folders, ...(file.folders || {}) };
   // Remember where the file lives so reloadConfig can re-read it live.
   merged.configPath = findConfigPath(flags.config) || null;
   return merged;
@@ -135,6 +142,10 @@ const LIVE_FIELDS = [
   // NOT queueConcurrency: the queue is built once at startup, so it can't change
   // live. queueAcks IS live (intake() reads it per-mention from liveCfg).
   "queueAcks",
+  // folders is an object map; it's listed here for documentation, but the actual
+  // live merge (with DEFAULTS) happens in the special-cased block below, exactly
+  // like `repos`, so a partial edit doesn't drop the defaults.
+  "folders",
 ];
 
 /**
@@ -160,6 +171,9 @@ export function reloadConfig(prev) {
   if (next.heartbeatMs > 0) next.heartbeatMs = Math.max(15000, Number(next.heartbeatMs) || 0);
   next.progressMs = Math.max(750, Number(next.progressMs) || 2000);
   if (file.repos) next.repos = { ...DEFAULTS.repos, ...file.repos };
+  // Merge the folder map like repos (overriding the raw scalar-loop assignment
+  // above with a proper DEFAULTS-merged object).
+  if (file.folders) next.folders = { ...DEFAULTS.folders, ...file.folders };
   return next;
 }
 

package/src/daemon.mjs

@@ -31,6 +31,55 @@ export function resolveRepoPath(config, repoFullName) {
   return (config && config.repos && config.repos[repoFullName]) || null;
 }
 
+/** Local folder path for a channel from config (folder mode, 0322), or null.
+ *  Mirrors resolveRepoPath — a channel with no linked repo can still map to a
+ *  plain folder on this machine where the agent works directly. */
+export function resolveFolderPath(config, channelId) {
+  return (config && config.folders && config.folders[channelId]) || null;
+}
+
+/** Parse `git status --porcelain` (v1) into a Map(path → "XY" status code).
+ *  Handles renames ("old -> new" → keeps the new name) and quoted paths. */
+function parsePorcelain(text) {
+  const map = new Map();
+  for (const raw of String(text || "").split("\n")) {
+    if (!raw.trim()) continue;
+    const code = raw.slice(0, 2); // two status columns
+    let path = raw.slice(3); // skip the single separating space
+    const arrow = path.indexOf(" -> ");
+    if (arrow >= 0) path = path.slice(arrow + 4); // a rename reports old -> new
+    path = path.replace(/^"(.*)"$/, "$1"); // unquote paths with special chars
+    if (path) map.set(path, code);
+  }
+  return map;
+}
+
+/**
+ * What changed between two `git status --porcelain` snapshots taken before and
+ * after a run: files the run created (new/untracked/added), modified, or deleted.
+ * Pure + unit-testable. A path whose status is identical in both snapshots is a
+ * PRE-EXISTING local change (dirty before the run) and is excluded. Returns
+ * `{ modified, created, deleted }`, each a sorted string[].
+ */
+export function diffStatusSets(before, after) {
+  const b = parsePorcelain(before);
+  const a = parsePorcelain(after);
+  const created = [];
+  const modified = [];
+  const deleted = [];
+  for (const [path, code] of a) {
+    if (b.get(path) === code) continue; // unchanged since before the run
+    const c = code.trim();
+    if (code.includes("?") || c === "A" || c === "AM") created.push(path);
+    else if (c.startsWith("D")) deleted.push(path);
+    else modified.push(path);
+  }
+  created.sort();
+  modified.sort();
+  deleted.sort();
+  return { modified, created, deleted };
+}
+
 /** Parse `git diff --shortstat` output into counts. */
 export function parseShortstat(s) {
   const files = /(\d+) files? changed/.exec(s || "");