ftown 0.25.0 → 0.25.1

package/hooks/ftown-antigravity-hook.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# ftown hook for the Google Antigravity CLI (agy); installed to
+# ~/.ftown/antigravity-hook.sh and registered in ~/.gemini/config/hooks.json.
+# Translates agy's camelCase hook payload (stdin) to the bridge /hook wire format and POSTs it.
+# On a turn-end Stop it drains this session's ftown inbox FIRST: with mail it
+# prints {"decision":"continue","reason":"<mail>"} and posts nothing (the agent
+# keeps working); without mail it posts Stop. On terminationReason
+# MAX_FORCED_INVOCATIONS / USER_CANCELED / ERROR it never drains, only posts Stop.
+#
+# Always exits 0, also on HUP/INT/TERM/PIPE (a non-zero or signalled PreToolUse
+# hook makes agy BLOCK the tool), and writes nothing to stdout except that one
+# Stop mail line (agy parses stdout as JSON). Inert unless FTOWN_SESSION_ID is
+# set and curl + jq are available.
+#
+# Worst-case runtime: ~6s inside agy's 10s hook timeout. The POST tries at most
+# 2 endpoint candidates x curl --max-time 2 (4s); on Stop the inbox read through
+# `ftown security proxy` uses a 2s request timeout and happens before the POST,
+# and when it delivers mail no POST follows.
+#
+# bash 3.2 compatible (macOS /bin/bash). No set -e on purpose; no temp files.
+# The hook's working directory is agy's hooks.json folder, so pwd is never used.
+
+BG_PID=""
+# shellcheck disable=SC2329  # invoked through the trap below
+on_signal() {
+  [ -n "$BG_PID" ] && kill "$BG_PID" 2>/dev/null
+  exit 0
+}
+trap 'exit 0' EXIT
+trap on_signal HUP INT TERM PIPE
+
+INPUT=$(cat)
+
+[ -n "${FTOWN_SESSION_ID:-}" ] || exit 0
+command -v curl >/dev/null 2>&1 || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Parse once; invalid JSON or a missing hookEventName ends the hook silently.
+FIELDS=$(printf '%s' "$INPUT" | jq -c '
+  if type == "object" and ((.hookEventName // "") | type) == "string" and (.hookEventName // "") != "" then
+    {event: .hookEventName,
+     first: (.invocationNum == 0),
+     term: (.terminationReason | if type == "string" then . else "" end),
+     conv: ((.conversationId // "") | if type == "string" then . else tostring end),
+     cwd: ((.cwd // "") | if type == "string" then . else tostring end),
+     tool: (if (.toolCall | type) == "object" then
+              ({} + (if .toolCall.name != null then {tool_name: .toolCall.name} else {} end)
+                  + (if (.toolCall.args | type) == "object" then {tool_input: .toolCall.args} else {} end)
+                  + (if (.toolCall.id | type) == "string" then {tool_use_id: .toolCall.id} else {} end))
+            else {} end)}
+  else empty end' 2>/dev/null) || exit 0
+INPUT=""
+[ -n "$FIELDS" ] || exit 0
+
+EVENT=$(printf '%s' "$FIELDS" | jq -r '.event' 2>/dev/null) || exit 0
+case "$EVENT" in
+  SessionStart|PreToolUse|PostToolUse|Stop) HOOK_EVENT="$EVENT" ;;
+  PreInvocation)
+    FIRST=$(printf '%s' "$FIELDS" | jq -r '.first' 2>/dev/null) || exit 0
+    [ "$FIRST" = "true" ] || exit 0
+    HOOK_EVENT="UserPromptSubmit"
+    ;;
+  *) exit 0 ;;
+esac
+
+# Endpoint candidates, mirroring the muse helper: explicit env first, then the
+# bridge pointer the current bridge rewrites on every startup.
+CANDIDATES=""
+add_candidate() {
+  case "$1" in ''|*[!0-9]*) return 0 ;; esac
+  [ "$1" -gt 0 ] 2>/dev/null || return 0
+  CANDIDATES="${CANDIDATES}$1 $2
+"
+}
+ENV_PORT="${FTOWN_HOOK_PORT:-}"
+ENV_TOKEN="${FTOWN_HOOK_TOKEN:-}"
+add_candidate "$ENV_PORT" "$ENV_TOKEN"
+BRIDGE_JSON="${FTOWN_BRIDGE_POINTER:-${HOME:-}/.ftown/bridge.json}"
+if [ -n "${HOME:-}" ] && [ -f "$BRIDGE_JSON" ]; then
+  BPORT=$(jq -r '.port // empty' "$BRIDGE_JSON" 2>/dev/null)
+  BTOKEN=$(jq -r '.token // empty' "$BRIDGE_JSON" 2>/dev/null)
+  if [ -n "$BPORT" ] && { [ "$BPORT" != "$ENV_PORT" ] || [ "$BTOKEN" != "$ENV_TOKEN" ]; }; then
+    add_candidate "$BPORT" "$BTOKEN"
+  fi
+fi
+
+# One POST attempt, run in the background so a trapped signal interrupts the
+# `wait` at once instead of after curl's timeout. Its stdout/stderr go to
+# /dev/null so a curl left behind by a signal (it ends within its own 2s
+# bound) never holds agy's hook pipes open. The body goes on curl's
+# stdin (no ARG_MAX limit); the attempt succeeds only on a 2xx status.
+post_once() {
+  if [ -n "$3" ]; then
+    printf '%s' "$1" | curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:$2/hook" \
+      -H 'Content-Type: application/json' -H "Authorization: Bearer $3" \
+      --connect-timeout 1 --max-time 2 --data-binary @- 2>/dev/null
+  else
+    printf '%s' "$1" | curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:$2/hook" \
+      -H 'Content-Type: application/json' \
+      --connect-timeout 1 --max-time 2 --data-binary @- 2>/dev/null
+  fi | { IFS= read -r _code; case "${_code:-}" in 2*) exit 0 ;; esac; exit 1; }
+}
+
+# POST the hook payload; first 2xx wins. Fire-and-forget: failures are silent.
+post_hook() {
+  _body="$1"
+  while IFS=' ' read -r _port _token _rest; do
+    [ -n "${_port:-}" ] || continue
+    post_once "$_body" "$_port" "${_token:-}" >/dev/null 2>&1 &
+    BG_PID=$!
+    wait "$BG_PID"
+    _rc=$?
+    BG_PID=""
+    [ "$_rc" -eq 0 ] && return 0
+  done <<CANDIDATES_EOF
+$CANDIDATES
+CANDIDATES_EOF
+  return 1
+}
+
+PAYLOAD=$(printf '%s' "$FIELDS" | jq -c \
+  --arg sid "$FTOWN_SESSION_ID" \
+  --arg ev "$HOOK_EVENT" \
+  --arg envconv "${ANTIGRAVITY_CONVERSATION_ID:-}" \
+  '{ftown_session_id: $sid, ftown_session_source: "env", hook_event_name: $ev,
+    session_id: (if .conv != "" then .conv else $envconv end), cwd: .cwd}
+   + (if $ev == "PreToolUse" or $ev == "PostToolUse" then .tool else {} end)' \
+  2>/dev/null) || exit 0
+[ -n "$PAYLOAD" ] || exit 0
+
+if [ "$HOOK_EVENT" != "Stop" ]; then
+  post_hook "$PAYLOAD"
+  exit 0
+fi
+
+# Stop: drain the inbox first (unless agy will not continue), exactly like the
+# muse helper: a single wait=0 drain through the authenticated
+# `ftown security proxy`, which marks the mail delivered.
+drain_mail() {
+  _term=$(printf '%s' "$FIELDS" | jq -r '.term' 2>/dev/null)
+  case "$_term" in
+    MAX_FORCED_INVOCATIONS|USER_CANCELED|ERROR) return 1 ;;
+  esac
+  _enc=$(jq -n -r --arg s "$FTOWN_SESSION_ID" '$s | @uri' 2>/dev/null)
+  [ -n "$_enc" ] || return 1
+  _cli=$(command -v ftown 2>/dev/null || true)
+  [ -n "$_cli" ] || _cli="${HOME:-}/.ftown/bin/ftown"
+  [ -x "$_cli" ] || return 1
+  _req=$(jq -n -c --arg path "/api/sessions/${_enc}/inbox?wait=0" '{method:"GET",path:$path,timeoutMs:2000}' 2>/dev/null)
+  [ -n "$_req" ] || return 1
+  _inbox=$(printf '%s' "$_req" | "$_cli" security proxy 2>/dev/null | jq -c 'select(.status >= 200 and .status < 300) | .body' 2>/dev/null)
+  [ -n "$_inbox" ] || return 1
+  _count=$(printf '%s' "$_inbox" | jq -r '(.messages // []) | length' 2>/dev/null)
+  [ -n "$_count" ] && [ "$_count" -gt 0 ] 2>/dev/null || return 1
+  MAIL_OUT=$(printf '%s' "$_inbox" | jq -c \
+    '{decision: "continue", reason: ("[ftown mail]\n" + ([(.messages // [])[] | "[\(.ts // "")] \(.fromName // .from // "external") (\(.type // "message")): \(.body // "")"] | join("\n")))}' \
+    2>/dev/null)
+  [ -n "$MAIL_OUT" ]
+}
+
+MAIL_OUT=""
+if drain_mail; then
+  # Mail delivered: the agent continues, so the session stays busy (no POST).
+  # stderr is silenced so a reader that closed the pipe cannot see "Broken pipe".
+  printf '%s\n' "$MAIL_OUT" 2>/dev/null
+  exit 0
+fi
+post_hook "$PAYLOAD"
+exit 0

package/hooks/ftown-grok-hook.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+# ftown hook for the Grok CLI, installed to ~/.ftown/grok-hook.sh and
+# registered for every grok hook event in ~/.grok/hooks/ftown.json.
+# What it does:
+#   1. Reads grok's hook payload (JSON on stdin) and POSTs it to the bridge
+#      /hook route in ftown's snake_case wire format.
+#   2. On Stop with reason "end_turn" it drains this session's ftown inbox
+#      FIRST: when mail was delivered it prints
+#      {"decision":"block","reason":"<mail>"} so grok continues the turn with
+#      the mail (capped at 9,500 characters plus a re-read pointer, since grok
+#      clips the reason at 10,000) and posts NOTHING, keeping the session busy;
+#      with no mail it posts Stop. Stop "shutdown"/"channel_closed" (session
+#      end) is ignored entirely; any other Stop reason just posts Stop.
+#
+# Inert (exit 0, no output) unless spawned by ftown (FTOWN_SESSION_ID set) and
+# curl + jq are available. Always exits 0; stdout is written only for mail.
+#
+# Worst-case runtime (grok hook timeout is 10s): on Stop end_turn one inbox
+# read through `ftown security proxy` with timeoutMs 2000 (2s plus CLI
+# startup), then, only when no mail came back, the POST tries at most two
+# endpoints (env port, bridge pointer), each curl bounded by --max-time 2
+# (4s): about 6s plus CLI startup.
+# Bridge reachability, auth, inbox read and mail text mirror
+# bridge/muse-plugin/lib/ftown-hook.sh.
+
+# Consume the whole payload first so grok never sees a broken pipe even when
+# the hook turns out to be inert.
+INPUT=$(cat 2>/dev/null)
+
+# Inert unless spawned by ftown.
+[ -n "${FTOWN_SESSION_ID:-}" ] || exit 0
+command -v curl >/dev/null 2>&1 || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Valid JSON object with a non-empty string hook_event_name, else silent exit.
+printf '%s' "$INPUT" | jq -e \
+  'type == "object" and (.hook_event_name | type == "string" and length > 0)' \
+  >/dev/null 2>&1 || exit 0
+
+HOOK_EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name' 2>/dev/null) || exit 0
+STOP_REASON=$(printf '%s' "$INPUT" | jq -r '.reason // empty | tostring' 2>/dev/null)
+[ -n "$HOOK_EVENT" ] || exit 0
+
+# Grok's two session-end reasons (every process exit fires an extra Stop with
+# one of them) are not turn ends: no POST, no inbox read, no output.
+if [ "$HOOK_EVENT" = "Stop" ]; then
+  case "$STOP_REASON" in
+    shutdown|channel_closed) exit 0 ;;
+  esac
+fi
+
+# Endpoint candidates, mirroring the muse helper: explicit env first, then the
+# bridge pointer the current bridge rewrites on every startup (a resurrected
+# session may hold a stale env port).
+CANDIDATES=""
+add_candidate() {
+  case "$1" in ''|*[!0-9]*) return 0 ;; esac
+  [ "$1" -gt 0 ] 2>/dev/null || return 0
+  CANDIDATES="${CANDIDATES}$1 $2
+"
+}
+ENV_PORT="${FTOWN_HOOK_PORT:-}"
+ENV_TOKEN="${FTOWN_HOOK_TOKEN:-}"
+add_candidate "$ENV_PORT" "$ENV_TOKEN"
+BRIDGE_JSON="${FTOWN_BRIDGE_POINTER:-${HOME:-}/.ftown/bridge.json}"
+if [ -n "${HOME:-}" ] && [ -f "$BRIDGE_JSON" ]; then
+  BPORT=$(jq -r '.port // empty' "$BRIDGE_JSON" 2>/dev/null)
+  BTOKEN=$(jq -r '.token // empty' "$BRIDGE_JSON" 2>/dev/null)
+  if [ -n "$BPORT" ] && { [ "$BPORT" != "$ENV_PORT" ] || [ "$BTOKEN" != "$ENV_TOKEN" ]; }; then
+    add_candidate "$BPORT" "$BTOKEN"
+  fi
+fi
+[ -n "$CANDIDATES" ] || exit 0
+
+# POST the hook payload; first 2xx wins. Fire-and-forget: failures are silent.
+# The body goes on curl's stdin (printf is a builtin), never argv, so a large
+# tool_input cannot exceed ARG_MAX.
+post_hook() {
+  _body="$1"
+  while IFS=' ' read -r _port _token _rest; do
+    [ -n "${_port:-}" ] || continue
+    if [ -n "${_token:-}" ]; then
+      _code=$(printf '%s' "$_body" | curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:${_port}/hook" \
+        -H 'Content-Type: application/json' -H "Authorization: Bearer ${_token}" \
+        --connect-timeout 1 --max-time 2 --data-binary @- 2>/dev/null)
+    else
+      _code=$(printf '%s' "$_body" | curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:${_port}/hook" \
+        -H 'Content-Type: application/json' \
+        --connect-timeout 1 --max-time 2 --data-binary @- 2>/dev/null)
+    fi
+    case "${_code:-}" in
+      2*) return 0 ;;
+    esac
+  done <<CANDIDATES_EOF
+$CANDIDATES
+CANDIDATES_EOF
+  return 1
+}
+
+# Build the wire body with jq straight from the payload. tool_* keys are kept
+# only when present (tool_input stays a JSON value); session_id falls back to
+# $GROK_SESSION_ID when the payload has none.
+PAYLOAD=$(printf '%s' "$INPUT" | jq -c \
+  --arg sid "$FTOWN_SESSION_ID" \
+  --arg gsid "${GROK_SESSION_ID:-}" \
+  '{
+     ftown_session_id: $sid,
+     ftown_session_source: "env",
+     hook_event_name: .hook_event_name,
+     session_id: (if (.session_id | type) == "string" and .session_id != "" then .session_id else $gsid end),
+     cwd: (if (.cwd | type) == "string" then .cwd else "" end)
+   }
+   + (if .tool_name != null then {tool_name: .tool_name} else {} end)
+   + (if .tool_input != null then {tool_input: .tool_input} else {} end)
+   + (if .tool_use_id != null then {tool_use_id: .tool_use_id} else {} end)' \
+  2>/dev/null) || exit 0
+[ -n "$PAYLOAD" ] || exit 0
+
+# Drain this session's inbox: single wait=0 read through `ftown security proxy`
+# (marks delivered). On success sets MAIL_DECISION to the Stop "block" line
+# and returns 0; returns 1 when no mail was delivered for any reason (empty
+# inbox, CLI missing, proxy failure).
+MAIL_DECISION=""
+drain_mail() {
+  _sid_enc=$(jq -n -r --arg s "$FTOWN_SESSION_ID" '$s | @uri' 2>/dev/null)
+  [ -n "$_sid_enc" ] || return 1
+  _cli=$(command -v ftown 2>/dev/null || true)
+  [ -n "$_cli" ] || _cli="${HOME:-}/.ftown/bin/ftown"
+  [ -x "$_cli" ] || return 1
+  _request=$(jq -n -c --arg path "/api/sessions/${_sid_enc}/inbox?wait=0" '{method:"GET",path:$path,timeoutMs:2000}' 2>/dev/null) || return 1
+  _inbox=$(printf '%s' "$_request" | "$_cli" security proxy 2>/dev/null | jq -c 'select(.status >= 200 and .status < 300) | .body' 2>/dev/null)
+  [ -n "$_inbox" ] || return 1
+  _count=$(printf '%s' "$_inbox" | jq -r '(.messages // []) | length' 2>/dev/null)
+  [ -n "$_count" ] && [ "$_count" -gt 0 ] 2>/dev/null || return 1
+  # Grok clips a block reason at 10,000 characters, and the drain has already
+  # marked the mail delivered: cap the text at 9,500 characters (jq counts
+  # codepoints, not bytes) and, when cut, end with a re-read pointer.
+  MAIL_DECISION=$(printf '%s' "$_inbox" | jq -c \
+    --arg pointer '[ftown mail truncated: run `ftown sessions inbox --all --peek` to read the full messages]' \
+    '("[ftown mail]\n" + ([(.messages // [])[] | "[\(.ts // "")] \(.fromName // .from // "external") (\(.type // "message")): \(.body // "")"] | join("\n")))
+     | (if length > 9500 then .[0:9500] + "\n" + $pointer else . end)
+     | {decision: "block", reason: .}' \
+    2>/dev/null) || return 1
+  [ -n "$MAIL_DECISION" ]
+}
+
+# Turn-end ordering (contract A2.1): on a real turn end drain FIRST. When mail
+# was delivered grok keeps working, so print the decision and post nothing
+# (posting Stop would mark a busy session idle). Otherwise post Stop.
+if [ "$HOOK_EVENT" = "Stop" ] && [ "$STOP_REASON" = "end_turn" ]; then
+  if drain_mail; then
+    printf '%s\n' "$MAIL_DECISION"
+    exit 0
+  fi
+fi
+post_hook "$PAYLOAD"
+exit 0

package/hooks/notify.sh

@@ -1,5 +1,13 @@
 #!/bin/bash
 INPUT=$(cat)
+# Grok runs Claude-compatible hooks too; ~/.ftown/grok-hook.sh is its channel. Stand down only
+# when GROK_HOOK_EVENT is set and is not "notification" (the Grok script does not forward that
+# event) AND the payload has a string hookEventName (Grok always sends it; Claude, Codex and
+# Cursor do not, so an inherited variable does not silence them).
+if [ -n "${GROK_HOOK_EVENT:-}" ] && [ "${GROK_HOOK_EVENT}" != "notification" ] \
+  && printf '%s' "$INPUT" | jq -e '(.hookEventName | type) == "string" and (.hookEventName | length) > 0' >/dev/null 2>&1; then
+  exit 0
+fi
 
 PORT="${FTOWN_HOOK_PORT:-}"
 SESSION_ID="${FTOWN_SESSION_ID:-}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftown",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
@@ -72,5 +72,5 @@
   "overrides": {
     "qs": "6.16.1"
   },
-  "gitHead": "e4010193f960ffff69015be86c5e06aa18dc060c"
+  "gitHead": "d7098c8cbdbce5b92542cf883a6c2b5900be2276"
 }

package/skills/ftown/references/sessions.md

@@ -46,7 +46,7 @@ ftown sessions remove <session-id>
 ftown sessions archive
 
 # Recreate a removed session from its tombstone (resumes the agent
-# conversation when a claude/cursor/codex/Pi session id was recorded; Kimi Code
+# conversation when a claude/cursor/codex/Pi/grok/antigravity session id was recorded; Kimi Code
 # continues by working directory; the revived session gets a NEW id)
 ftown sessions revive <session-id>
 ```
@@ -205,6 +205,14 @@ follow-up turn when mail arrives, including while Pi is idle. opencode's
 installed plugin delivers pending mail as a new prompt when a turn goes idle.
 Muse's installed `ftown` plugin reports the native session id on SessionStart
 and pumps pending mail as context on Stop.
+Grok's ftown hooks (`~/.grok/hooks/ftown.json`) report the native session id
+and deliver mail that arrives mid-turn when the turn ends; the typed nudge
+remains the fallback for an idle Grok agent.
+Antigravity's ftown Stop hook (`~/.gemini/config/hooks.json`, entry `ftown`)
+reports the conversation id and delivers mail at turn end.
+Grok and Antigravity hooks do not run in the interactive TUI until the folder
+has been trusted in that CLI's own trust prompt; the owner answers it once per
+folder, and ftown does not bypass it.
 Cursor and shell sessions rely on an idle one-line nudge to run `ftown harness
 mail read` instead.
 
@@ -235,8 +243,8 @@ Fan-out targets are messaged sequentially, one JSON result line per target.
 
 | Flag | Description |
 |------|-------------|
-| `--shell` | Explicit harness override: `claude`, `cursor`, `codex`, `grok`, `muse`, `pi`, `kimi-code`, `opencode`, `shell`, or Claude Code provider flavors `zai`, `kimi`, `deepseek`, `fireworks`. When omitted inside a session, inherits that session's harness; outside a session, defaults to `claude`. |
-| `--prompt` | Initial task — passed as a CLI launch argument to `claude`/Claude provider flavors/`cursor`/`codex`/`grok`/`muse`/`pi` (typed after boot for other shells) |
+| `--shell` | Explicit harness override: `claude`, `cursor`, `codex`, `grok`, `muse`, `antigravity`, `pi`, `kimi-code`, `opencode`, `shell`, or Claude Code provider flavors `zai`, `kimi`, `deepseek`, `fireworks`. When omitted inside a session, inherits that session's harness; outside a session, defaults to `claude`. |
+| `--prompt` | Initial task — passed as a CLI launch argument to `claude`/Claude provider flavors/`cursor`/`codex`/`grok`/`muse`/`antigravity`/`pi` (typed after boot for other shells) |
 | `--workdir` | Working directory |
 | `--name` | Dashboard label |
 | `--command` | Full command override (skips `--shell` builder) |