Tether

tether — steer a long-running session from your inbox

Beta. The transport (e2a) and the flow are real; polish (adaptive backoff, richer digests) is still open.

/tether keeps you connected to a working session over email. The agent emails you updates when it judges there's something worth reporting (not on a timer, not every turn), and checks your inbox on an interval so your replies — questions or new instructions — are picked up within a few minutes. Reply stop to end.

Transport primer. tether rides on e2a. The e2a operate-well manual — the dependency-provided e2a skill — carries the mental model this skill assumes: how threading really works (reply headers + stable subject, not conversation_id), when a shared agents.e2a.dev address is all you need vs. a custom domain, and how to handle send statuses. Read the e2a skill by name if you're new to e2a; tether does not re-explain those.

Architecture (why this shape)

Coding agents are turn-based; nothing native listens to an inbox mid-session. So the two directions use different mechanisms:

• Send = agent-driven. The agent calls tether.sh update "…" at meaningful moments (finished a slice, hit a blocker, needs a decision). Cadence is the model's judgment → no per-turn spam, nothing to throttle.
• Receive = real-time wait. The agent runs tether.sh listen — it blocks on the e2a CLI's WebSocket (e2a listen --once; no LLM tokens while waiting) for the duration set at start --for, so replies are picked up within seconds; if the WebSocket is unavailable it degrades automatically to interval polling. It wakes the agent only when a reply actually arrives (or the window ends). See Durability tiers for keeping it alive across idle/sleep.
• Questions = ask by email. When the agent needs a decision or clarification from you, it must not use a terminal prompt / AskUserQuestion — you're AFK and can't see it, which would stall the whole session. It calls tether.sh ask "<question>", which emails the question into the thread and blocks until you reply, then prints your answer. This is the hard rule: while tethered, every question goes over email, never the terminal.
• Blocked-alert = hook (optional). A Notification hook emails you when the agent is stuck on a permission prompt it can't proceed past. Note: an emailed reply cannot answer a CLI permission prompt (there's no native way to inject approval), so for unattended runs pre-authorize the tools the session needs (a permission allowlist / a less-prompting mode). The hook is the safety net, not the approval channel.

Setup (once)

Prerequisites: Node (the transport is the e2a CLI, currently the 2.x line pinned as TETHER_MIN_CLI in lib.sh — resolved from $E2A_CLI, then PATH, then fetched automatically via npx -y @e2a/cli@^MIN, so there is nothing to install by hand) and Python 3 (local state handling only).

The range is major-bounded on purpose. tether parses the CLI's TSV columns and branches on its exit codes, and a major bump is allowed to change both — 2.0.0 did. So a CLI newer than the pinned major is not adopted automatically (tether falls back to npx and says so); someone re-verifies tether against the new major and bumps TETHER_MIN_CLI. Failing inert beats failing silently in an unattended session.

Fast path (recommended): tether.sh setup

tether.sh, install.sh, and tether.env.example all sit in this skill's own directory, next to this SKILL.md. Substitute its absolute path for $TETHER_DIR in every command below; the scripts resolve their own resources, so any working directory works.

If the e2a CLI is logged in (e2a login in a browser, or a key persisted with e2a config set api_key <key> on a headless box), one command does the whole bootstrap:

"$TETHER_DIR/tether.sh" setup

It verifies the credential (e2a whoami), ensures a tether inbox (reusing an existing tether-… agent or creating one on the shared domain — it will not silently adopt a non-tether inbox), mints a least-privilege agent-scoped key (e2a_agt_…), and writes ~/.e2a-tether.env (previous file kept as .bak). Every step fails hard — it never stores the broad account key and never reports "ready" with a half-working config. Flags: --email you@yourdomain to use/create a specific inbox, --new to force a fresh one.

Manual setup (fallback)

1. Get an agent-scoped API key (e2a_agt_… — least privilege, so a leaked key can't touch the rest of the account): from the CLI with e2a keys create --agent <inbox>, or from https://e2a.dev/api-keys. No domain? Create the agent on the shared agents.e2a.dev domain (e2a agents create name@agents.e2a.dev — live immediately, no DNS).
2. Save the credentials:

   cp "$TETHER_DIR/tether.env.example" ~/.e2a-tether.env
   chmod 600 ~/.e2a-tether.env   # fill E2A_API_KEY (e2a_agt_…) + E2A_AGENT_EMAIL

3. (Optional) blocked-alert hook:

   "$TETHER_DIR/install.sh" --to <repo-root>

Credentials resolve in order: explicit env vars → ~/.e2a-tether.env → ~/.e2a/config.json. Note that e2a login saves an account-scoped key and does not set agent_email — so ~/.e2a/config.json alone is not enough for tether, which needs a specific inbox. Either set both explicitly:

e2a keys create --agent <inbox>          # least-privilege e2a_agt_… key
e2a config set agent_email <inbox>       # or export E2A_AGENT_EMAIL

or put the agent key + inbox in ~/.e2a-tether.env and leave the CLI config alone.

Two ways a send can be accepted but never delivered — both fail loudly. pending_review means the message was held for approval; a terminal failed means the server persisted a delivery failure. tether.sh detects both on every send: an affected intro makes start refuse to arm, and an affected update/ask exits non-zero — held is 2 for update, 4 for ask; terminal failure is 5 for both — so the session never mistakes either for a delivered message. A terminal failure is not retryable — the server already recorded an outcome for that message id, so re-sending risks a duplicate. Inspect it with e2a messages get <id>.

First run (new user) — set them up, then tether

Before tethering, confirm the harness can actually send. Run "$T" status (where T is defined below). If it reports config: MISSING, this is a first-time user — help them get to a working setup instead of just failing:

1. Is e2a connected at all? If they've never used e2a, hand them e2a login — or, when e2a isn't installed globally, the npx form: npx -y @e2a/cli login (same auto-fetch the harness itself uses). It opens the browser sign-up/sign-in and saves an account-scoped key to ~/.e2a/config.json. (Headless box: they mint an account key in the dashboard, persist it with e2a config set api_key <key>, then validate it with e2a whoami.) Interactive sign-in is theirs to complete: hand them the command, don't drive it.
2. Run the bootstrap: "$T" setup — it creates the inbox, mints the agent-scoped key, and writes ~/.e2a-tether.env. See Setup above for what it refuses to do.
3. Re-check. "$T" status should now print config: OK (agent …). Proceed to the runtime flow.

If status already prints config: OK, skip this — they're a returning user. Don't put a configured user through onboarding.

Runtime flow (what the agent does when /tether is invoked)

Let T="$TETHER_DIR/tether.sh".

0. Preflight. Run "$T" status. If config: MISSING, do First run (new user) above before continuing — don't call start and let it error out.
1. Ask the user's email address and how long to stay tethered (e.g. 30m, 2h, 8h/overnight, or until they say stop). They're present at this step, so a normal question is fine.
2. Start: "$T" start <email> --title "<work>" --for <duration> (or --until <ISO>; omit both for until-stop) — sends the intro, opens the thread, arms, records the window. --title is required (start refuses without it): a short description of the work being done (e.g. "migrate loft → @e2a/ui", "fix webhook retries") — it becomes the thread's subject line (Tether: <repo> — <title>), which is how the user tells this session apart from others in their inbox. The subject is fixed at start (threading needs it stable), so title the work, not the first step. --for takes a single unit (30m, 2h, 8h, 1d); a compound like 1h30m is rejected rather than silently treated as no-limit. If the intro comes back pending_review, start refuses to arm because the intro was not dispatched.
3. Work, and send updates as you see fit — prefer HTML, it renders far better in mail clients: write the HTML to a file and run "$T" update --html <file> — a plain-text fallback is auto-derived (or pass --text "<fallback>"). Plain "$T" update "<text>" is for quick one-liner acks only. To send a file (a rendered PDF, a screenshot, a small log), add --attach <file> — repeatable, on either form, capped at 15 MB total per send (exit 3 = file not found, exit 4 = over the cap; past the cap, upload the file somewhere and send a link instead). Good moments: finished a slice, made a decision that's worth surfacing, hit a blocker, or before a long unattended stretch. Skip trivial turns. If update reports pending_review (exit 2), the update did not reach the user — stop and fix the inbox configuration before continuing. Exit 5 means the send reached a terminal failed outcome: also undelivered, but do not re-send it (the server already recorded that message id) — inspect it with e2a messages get <id> first.
4. Need a decision from the user? Ask by email — never the terminal. Run "$T" ask "<question>" (in the background); it emails the question and blocks until the user replies, then prints the answer. --attach <file> works here too — attach the artifact the decision hinges on (a diff, a mockup) rather than describing it. Do not use AskUserQuestion or a bare terminal prompt while tethered — an AFK user can't answer it and the session stalls. ask coordinates with listen automatically (it holds a lock so a background listen pauses and can't swallow your answer). Handle its exit codes: exit 3 = timed out with no reply (default 30m) — re-ask, send a nudge update, or keep working and listening, but never fall back to a terminal prompt; exit 4 = the question was held for review and not dispatched (fix the inbox configuration); exit 5 = the question hit a terminal failed outcome — it never reached the user, so ask returns immediately instead of blocking for the full timeout; don't blindly re-ask.
5. Listen for the whole window: run "$T" listen in the background. It waits on the CLI's WebSocket (real-time, no tokens while waiting; degrades to polling if the WS is unavailable) and exits with either:
   • REPLY_RECEIVED: + the message → act on it (then update with the result), and relaunch listen for the remaining window; or
   • TETHER_EXPIRED → the window is up; run "$T" stop. Replies are deduped by message-id and survive e2a's async parse, so none are dropped or repeated. (poll is the same one-shot check if you want it manually.)
6. Stop when the user replies stop/done, the window expires, or the work is complete: "$T" stop.