hilos-agent 0.11.2 → 0.11.3

package/README.md

@@ -1,13 +1,16 @@
 # hilos-agent
 
-Run **your own** coding agent — Claude Code, Codex, Cursor, opencode, Hermes, or any command — as
+Run **your own** coding agent — Claude Code, Codex, Cursor, opencode,
+Antigravity, Hermes, 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 (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.
+**local** checkout, and — by default — **opens a PR for review**. The checkout
+and your coding-provider/git credentials stay on your machine. Changes go to the
+configured Git remote; hilos receives bounded plans, progress, reports, and—when
+the pre-push gate is enabled—the proposal diff.
 
 ```
 hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
@@ -19,13 +22,13 @@ hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
          Changes  ▶  agent re-works with your note
 ```
 
-Prefer **approve-before-push**? Set `"gate": true` — the agent then posts the
-proposed diff as a card and pushes only after you Approve (nothing leaves your
-machine until then).
+Prefer **approve-before-push**? Set `"gate": true` — the agent posts a bounded
+proposed diff to hilos as a card, then pushes the change to the Git remote only
+after you Approve.
 
 ## Quick start
 
-In hilos: open your agent's profile → **Connect** → **Run in channel**. Copy the
+In hilos: open your agent's profile → **Connect agent** → **Run in channel**. Copy the
 terminal command and run it from inside your repo's folder. It waits at a hidden
 prompt; copy the private join code from Hilos and paste it there. The daemon
 matches the repo by its git remote, so no config is needed, and the reusable
@@ -39,30 +42,42 @@ npx hilos-agent@latest --join-stdin  # then paste the private join code when ask
 Previously copied `--join <blob>` commands remain compatible. New commands use
 stdin because the blob contains the agent token and should not live in argv.
 
-Running from elsewhere, or want to map several repos explicitly? Use a config:
+Running from elsewhere, or want to map several repos explicitly? Save this as
+`~/.hilos/agent.json` (or `./hilos-agent.json`). The file is strict JSON, so it
+cannot contain comments:
 
-```jsonc
-// ~/.hilos/agent.json  (or ./hilos-agent.json)
+```json
 {
   "url": "https://hilos.sh/api/mcp",
   "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": "",  // 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
-  "webSearch": true,  // native public-web tools are on by default; false stops Hilos enablement/instructions
+  "codingCmd": "claude -p --permission-mode acceptEdits",
+  "codingModel": "",
+  "chatCmd": "",
+  "webSearch": true,
   "defaultBranch": "main",
-  "gate": false,               // default: open a PR directly. true = approve-before-push
-  "heartbeatMs": 180000,       // long runs post one "still working…" thread reply this often (0 = off, min 15s)
-  "chatTimeoutMs": 90000,      // cap a chat reply / plan-ack so a stalled model can't go silent
-  "longPollMs": 20000,         // ask the server to HOLD the mention poll and answer the moment work lands (0 = plain 5s polling; older servers fall back automatically)
-  "catchupMs": 86400000        // how far back a restart replays mentions from the persisted cursor (default 24h; 0 = restart at "now", the pre-0866 behavior)
+  "gate": false,
+  "heartbeatMs": 180000,
+  "chatTimeoutMs": 90000,
+  "longPollMs": 20000,
+  "catchupMs": 86400000
 }
 ```
 
+`codingCmd` above is the safe default; it can also be `codex exec`,
+`cursor-agent -p --output-format text --trust`, `opencode run`, `agy -p`, or a
+custom command. `codingModel` accepts the Codex tiers `most-capable`, `balanced`,
+or `fastest`; empty uses the tool's default. Empty `chatCmd` derives a fast chat
+command from `codingCmd`. `webSearch: false` disables hilos's web-search
+enablement, and `gate: true` switches to approve-before-push. `heartbeatMs: 0`
+disables the heartbeat (minimum nonzero value 15 seconds); `longPollMs: 0` uses
+plain five-second polling; `catchupMs: 0` restarts at now instead of replaying
+the default 24-hour window.
+
 **Staying responsive.** Every code task posts an **instant acknowledgement**
-(under a second), and — if your server exposes `edit_message` and a `chatCmd` is
-set — a quick **plan** ("On it — I'll do X, then open a PR") edits into it. On a
+(under a second), and — if your server exposes `edit_message` and a fast chat
+command can be resolved (explicit `chatCmd` or one derived from `codingCmd`) —
+a quick **plan** ("On it — I'll do X, then open a PR") edits into it. On a
 run longer than `heartbeatMs` (default 3 min; env `HILOS_HEARTBEAT_MS`, `0`
 disables, clamped to ≥15s) the agent posts **one progress reply** in the thread
 then edits it in place with elapsed time + the CLI's latest line — so the channel
@@ -98,7 +113,7 @@ The local daemon can give its coding and chat agents a narrow bridge to
 third-party WebMCP sites. It is off until you name exact origins and exact read
 tools in the machine's config:
 
-```jsonc
+```json
 {
   "webMcp": {
     "origins": {
@@ -152,8 +167,10 @@ access its operator granted. See the complete contract in
   it", "approved", or "go for it" after a request, in any language → a code run.
 - **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.
+- **Run** — it temporarily stashes a dirty checkout, branches off
+  `defaultBranch`, runs `codingCmd` with the task, stages the result, and attempts
+  to restore the person's pre-existing work on every exit path. If `stash pop`
+  conflicts, the stash stays intact and the room gets the recovery command.
 - **Continue the thread's PR** — when the mention lands in a thread hilos says is
   about a pull request, the daemon works on *that* PR instead of opening a second
   one: it fetches the PR's head branch, commits there, and the same PR updates.
@@ -192,8 +209,7 @@ to a plain **local folder** and the agent works in it **directly** — it edits
 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
+```json
 {
   "folders": { "<channelId>": "/Users/you/notes-site" }
 }
@@ -227,7 +243,7 @@ It's your own machine, so this is the same trust as running the CLI yourself.
 
 Add an optional per-channel deploy target next to `folders`:
 
-```jsonc
+```json
 {
   "folders": { "<channelId>": "/Users/you/notes-site" },
   "deploy": { "<channelId>": { "provider": "vercel", "prod": false } }
@@ -282,30 +298,29 @@ touching the token.
 
 ## Permissions / autonomy
 
-`codingCmd` decides how much the coding agent can do on its own. Three levels,
-safest first:
-
-- **`opencode run` (runtime-gated).** When the connected hilos server advertises
-  runtime permissions, the daemon runs OpenCode through an authenticated
-  loopback server and becomes its sole permission responder. A tool ask pauses
-  mechanically, posts a card in the run thread, and resumes only after a channel
-  member chooses **Allow once**, an exact harness-suggested **Always** rule, or
-  **Deny**. Missing transport, expiry, and cancellation all reject the tool
-  call. `opencode run --auto` deliberately bypasses these cards and keeps
-  OpenCode's dangerous auto-approve behavior.
-- **`--permission-mode acceptEdits` (default).** The agent edits files without
-  prompting, but in headless `claude -p` a step that needs bash — run the tests,
-  install a dep — has no interactive prompt to grant, so the task can **stall**.
-  Good when the work is edit-only; frustrating for anything that needs to run
-  commands.
-- **`--dangerously-skip-permissions` (recommended for independent agents).** Full
-  autonomy: the agent can run the tests, install deps, and finish hands-off.
-  Caution: it can run **any** command in the repo you point it at — only use it
-  on a repo and machine where that's acceptable. This is the option to pick if
-  you want the agent to actually work on its own.
-
-  ```jsonc
-  "codingCmd": "claude -p --dangerously-skip-permissions"
+There are two separate gates:
+
+- **Room runtime permissions.** When the workspace has granted runtime
+  permissions, current daemons put Claude Code, Codex, Cursor, and OpenCode
+  behind the same server-authorized card flow. A tool ask pauses mechanically
+  and resumes only after an eligible channel member chooses **Allow once**, an
+  exact harness-suggested **Always** rule, or **Deny**. Cursor and OpenCode use
+  ACP; Claude Code uses its permission-prompt tool; Codex uses `codex
+  mcp-server` because `codex exec` has no approval transport. Once a relay is
+  active, authority loss, expiry, cancellation, and transport failure all fail
+  closed. A positively unavailable old-CLI transport is the compatibility
+  exception: the daemon warns the room, then starts the ungated fallback.
+  Explicit vendor bypass modes such as `opencode run --auto` or Claude Code's
+  `--dangerously-skip-permissions` deliberately opt out of the cards.
+- **The CLI's own mode.** Without a workspace runtime grant, `codingCmd` remains
+  authoritative. The default Claude Code command uses
+  `--permission-mode acceptEdits`: it may edit without prompting, but a headless
+  command that needs additional approval can stall. For a fully independent
+  local agent, `--dangerously-skip-permissions` can run any command in the repo
+  you point it at, so use it only where that trust is acceptable.
+
+  ```json
+  { "codingCmd": "claude -p --dangerously-skip-permissions" }
   ```
 
 - **Approve-before-push (`gate:true`), most cautious.** Independent of the two
@@ -314,9 +329,9 @@ safest first:
 
 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. When the workspace grants runtime approvals,
-OpenCode, Cursor, Claude Code, and Codex all pause on the same durable hilos
-permission card. A refusal or broken decision path fails closed.
+before anything is pushed. Runtime cards and the push gate are independent: one
+governs tools during the run, the other governs when the resulting code leaves
+the machine.
 
 ## Hooks — keep a raw Codex, Claude Code, or Cursor session in the room
 
@@ -365,8 +380,9 @@ npx hilos-agent@latest hooks print
   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.
+- Keep `hilos-agent` running to pick replies up. Hooks only emit lifecycle
+  events; the daemon is the consumer that waits on the server's wake/long-poll
+  path and resumes the local session.
 
 **What you get:**
 - Team members see "Editing lib/x.ts" or "Running pnpm test" on the agent's live
@@ -422,8 +438,9 @@ An older server simply leaves it off.
 ### Run transcripts are opt-in
 
 The room gets what a teammate needs to see: a plan, live progress, a report, a
-PR. The coding tool's own stream is **not** part of that by default — the live
-card is an eight-step window and nothing keeps it after the run.
+PR. The coding tool's raw stream is **not** part of that by default. Current
+servers do keep a bounded, redacted set of structured activity facts through
+the runtime-neutral event protocol described above; that is not a transcript.
 
 Set `"uploadTranscripts": true` and the daemon, after posting its report, sends
 the tail of that run's stream to hilos, where it becomes the same transcript a
@@ -457,8 +474,14 @@ arguments can be visible to other processes on the machine, so use
 Likewise, prefer `--join-stdin` over the legacy `--join <blob>` form for a new
 connection.
 
-Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`, `HILOS_ONCE=1`,
-`HILOS_BACKFILL=1`, `HILOS_UPLOAD_TRANSCRIPTS=1|0`.
+See `hilos-agent --help` for the `init`, `webmcp`, `web doctor`, and `hooks`
+subcommands.
+
+Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`,
+`HILOS_CODING_MODEL`, `HILOS_CHAT_CMD`, `HILOS_WEB_SEARCH=1|0`,
+`HILOS_ACP=1|0`, `HILOS_HEARTBEAT_MS`, `HILOS_PROGRESS_MS`,
+`HILOS_CHAT_TIMEOUT_MS`, `HILOS_REPLY_BRIDGE=1|0`, `HILOS_ONCE=1`,
+`HILOS_BACKFILL=1`, and `HILOS_UPLOAD_TRANSCRIPTS=1|0`.
 
 ## Releasing
 

package/bin/hilos-agent.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // hilos-agent — run your coding agent as an autonomous teammate in a hilos
-// channel. Picks up @mentions and opens a PR by default; --gate adds a human
-// approval checkpoint before the push. Your code + credentials never leave
-// your machine.
+// channel. Picks up @mentions and opens a PR by default; an optional pre-push
+// gate waits for a person's approval. The checkout and credentials stay local;
+// changes go to the configured Git remote and bounded run state goes to hilos.
 //
 // Usage:
 //   hilos-agent --join <blob>      connect with a copy-paste link from hilos

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.2",
-  "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. It picks up mentions, makes the change locally, and opens a PR for human review.",
+  "version": "0.11.3",
+  "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. The checkout and credentials stay local; changes go to your configured Git remote as a PR for human review, and bounded progress and reports go to hilos.",
   "type": "module",
   "bin": {
     "hilos-agent": "bin/hilos-agent.mjs"

package/src/handler.mjs

@@ -5,7 +5,8 @@
 //
 // Turn an @mention in a git-linked channel into a branch + a coding-agent run.
 // By default it opens a PR for review; with gate:true it posts a proposed diff
-// and pushes only after approval. Your code + credentials stay local.
+// and pushes only after approval. The checkout and credentials stay local;
+// bounded progress/reports go to hilos and changes go to the Git remote.
 
 import { spawnSync } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";