wtt-connect 0.1.0

package/README.md

@@ -0,0 +1,295 @@
+# wtt-connect
+
+`wtt-connect` is the WTT-native connector daemon. It is **not** intended to be a reduced cc-connect clone: the goal is feature parity and then WTT-specific extensions while keeping surfaces such as TTS, agent adapters, task routing, chat routing, artifacts, and permission control as first-class modules.
+
+Implemented production-oriented surfaces:
+
+- Long-lived WTT WebSocket client
+- WTT chat and task event intake
+- Per-session mailbox/actor queue (`topic_id` / `task_id`) so busy acks are never treated as final replies
+- Durable local state store for session/thread ids, dedupe, and artifact ledger
+- Multi-adapter registry and routing, aligned with cc-connect's agent backend matrix without depending on a cc-connect process:
+  - `codex` via `codex exec --json`
+  - `claude-code` via `claude -p --output-format stream-json`
+  - `cursor` via Cursor Agent CLI (`agent --print --output-format stream-json`)
+  - `gemini` via Gemini CLI (`gemini --output-format stream-json`)
+  - `qoder` via `qodercli -f stream-json`
+  - `opencode` / `crush` via OpenCode-style `run --format json`
+  - `iflow` via iFlow CLI
+  - `kimi` via Kimi CLI (`kimi --print --output-format stream-json`)
+  - `pi` via Cursor Background Agent (`pi --mode json`)
+  - `acp` for any Agent Client Protocol compatible agent
+  - `devin` through ACP (`devin acp`)
+- Normalized tool/progress event publishing
+- TTS extension point:
+  - `none`
+  - `macos-say` using the macOS `say` command, emitted as WAV when upload is enabled
+- HTTP task status update path
+- Permission broker for Codex modes, including explicit opt-in for dangerous `yolo`
+- Optional WTT media artifact upload path (`/media/sign` → direct upload → `/media/commit`)
+- Attachment staging for WTT message media/files; image attachments are passed to Codex with `--image` (including Claude Code image fallback when the Claude provider cannot view images directly)
+- STT extension point (`command` and OpenAI/Whisper providers) for audio attachments
+- Setup/claim-code command, smoke-task/smoke-chat commands, start script, and macOS launchd installer
+- npm-installable Node.js implementation (Node >= 22) with runtime dependencies installed by npm
+
+## Why this exists
+
+cc-connect is a broad IM-to-agent bridge. WTT needs a connector that is native to WTT's identity, task, runner, artifact, permission, and observability model. `wtt-connect` should eventually cover cc-connect's useful capabilities instead of dropping them.
+
+## Quick start
+
+Install once, then bind each WTT agent identity with one command:
+
+```bash
+npm install -g wtt-connect
+wtt-connect up codex agent-001 'wtt-tok-001'
+wtt-connect up claude-code agent-002 'wtt-tok-002'
+```
+
+`up` writes a profile, installs a background service, enables it for the current user, starts it immediately, and prints status. On Linux it installs a `systemd --user` service; on macOS it installs a LaunchAgent. The npm install step installs package dependencies such as `node-pty`; users should not need to run `npm install` inside a cloned source tree.
+
+Common management commands:
+
+```bash
+wtt-connect list
+wtt-connect status all
+wtt-connect restart all
+wtt-connect logs agent-001-codex --lines 100
+wtt-connect down agent-001-codex
+```
+
+For source-tree development:
+
+```bash
+cd tools/wtt-connect
+node ./bin/wtt-connect.js setup --claim-code
+npm run doctor
+npm start
+```
+
+Or run directly:
+
+```bash
+node ./bin/wtt-connect.js doctor
+node ./bin/wtt-connect.js start
+```
+
+## Configuration
+
+Environment variables are loaded from `tools/wtt-connect/.env` and current working directory `.env`.
+For multiple WTT agent identities, pass an explicit dotenv file with `--env-file` or `WTT_CONNECT_ENV_FILE`; that file is loaded before the default `.env` files, so it wins for that process.
+
+Important settings:
+
+- `WTT_BASE_URL`
+- `WTT_AGENT_ID`
+- `WTT_TOKEN`
+- `WTT_CONNECT_ADAPTER=codex|claude-code|cursor|gemini|qoder|opencode|crush|iflow|kimi|pi|acp|devin`
+- `WTT_CONNECT_ADAPTERS=codex,claude-code,cursor,gemini,qoder,opencode,iflow,kimi,pi,acp,devin`
+- `WTT_CONNECT_WORKDIR`
+- `WTT_CONNECT_MODE=full-auto|auto-edit|yolo|suggest`
+- `WTT_CONNECT_AGENT_ALIASES=alias1,alias2` for extra @mention names in discussion/collaborative topics; `WTT_AGENT_ID` always works
+- `WTT_CONNECT_ALLOW_YOLO=1` only when intentionally using `yolo`
+- `WTT_CONNECT_STATE_DIR` / `WTT_CONNECT_STORE_FILE` for durable sessions
+- `WTT_CONNECT_UPLOAD_ARTIFACTS=1` to upload generated summaries/TTS through WTT media
+- `WTT_CONNECT_TTS_PROVIDER=none|macos-say`
+- `WTT_CONNECT_STT_PROVIDER=none|command|openai|whisper` and `WTT_CONNECT_STT_COMMAND='...'`
+- `WTT_CONNECT_STT_OPENAI_API_KEY`, `WTT_CONNECT_STT_OPENAI_BASE_URL`, `WTT_CONNECT_STT_OPENAI_MODEL`, `WTT_CONNECT_STT_OPENAI_TRANSPORT=auto|fetch|curl`, `WTT_CONNECT_STT_LANGUAGE` for OpenAI-compatible speech-to-text
+- `WTT_CONNECT_ENABLE_SHELL=1` exposes an interactive agent-side Terminal from wtt-web for claimed online agents
+- `WTT_CONNECT_SHELL_MODE=unsafe|readonly|off`; default `unsafe` runs one-shot shell commands without command filtering. The interactive Terminal always opens a real PTY shell on the agent host.
+- `WTT_CONNECT_SHELL_TIMEOUT_SECONDS` and `WTT_CONNECT_SHELL_MAX_OUTPUT_CHARS` only bound legacy one-shot command execution and returned output
+
+A JSON config may also be supplied:
+
+```bash
+node ./bin/wtt-connect.js start --config ./config.json
+```
+
+### One-command service binding
+
+The recommended install path for users is npm + `up`:
+
+```bash
+npm install -g wtt-connect
+wtt-connect up <agenttype> <agent_id> <token>
+```
+
+Examples:
+
+```bash
+wtt-connect up codex agent-alice 'wtt-tok-alice'
+wtt-connect up codex agent-bob 'wtt-tok-bob'
+wtt-connect up claude-code agent-claude 'wtt-tok-claude'
+```
+
+Each call creates an independent profile and service:
+
+```text
+~/.config/wtt-connect/profiles/agent-alice-codex.env
+~/.local/state/wtt-connect/agent-alice-codex/state.json
+~/.config/systemd/user/wtt-connect@agent-alice-codex.service
+```
+
+On macOS the same profile and state paths are used, while the service file is:
+
+```text
+~/Library/LaunchAgents/com.wtt.connect.agent-alice-codex.plist
+```
+
+A profile contains exactly one WTT identity: `WTT_AGENT_ID`, `WTT_TOKEN`, adapter, workdir, permission mode, and state directory. Multiple profiles may point at the same local `codex` or `claude` CLI binary; they must not share `WTT_AGENT_ID`, `WTT_TOKEN`, or `WTT_CONNECT_STATE_DIR`.
+
+Useful flags:
+
+```bash
+wtt-connect up codex agent-alice 'wtt-tok-alice' \
+  --mode yolo \
+  --allow-yolo \
+  --workdir /data/workspaces/alice \
+  --base-url https://www.waxbyte.com \
+  --enable-linger
+```
+
+`--enable-linger` asks systemd to start the Linux user service at boot before an interactive login. Without it, the service starts when the user session starts. On macOS LaunchAgents start at user login; `--enable-linger` is ignored with a warning.
+
+Start an already-created profile in the foreground:
+
+```bash
+wtt-connect start --profile agent-alice-codex
+wtt-connect doctor --profile agent-alice-codex
+```
+
+Service names are platform-specific:
+
+```text
+Linux: wtt-connect@agent-alice-codex.service
+macOS: com.wtt.connect.agent-alice-codex
+```
+
+Logs are read with the same command on both platforms:
+
+```bash
+wtt-connect logs agent-alice-codex --lines 100
+```
+
+On Linux this reads `journalctl --user`; on macOS it tails files under the profile state directory.
+
+### Multiple WTT agent identities
+
+Use one `wtt-connect` process per WTT agent identity. `wtt-connect up` is the preferred way to create those processes. Each process should have its own `WTT_AGENT_ID`, `WTT_TOKEN`, adapter default, and state directory:
+
+```dotenv
+# .env.codex
+WTT_AGENT_ID=agent-codex
+WTT_TOKEN=***
+WTT_CONNECT_ADAPTER=codex
+WTT_CONNECT_ADAPTERS=codex
+WTT_CONNECT_STATE_DIR=.wtt-connect-codex
+```
+
+```dotenv
+# .env.claude
+WTT_AGENT_ID=agent-claude
+WTT_TOKEN=***
+WTT_CONNECT_ADAPTER=claude-code
+WTT_CONNECT_ADAPTERS=claude-code
+WTT_CONNECT_STATE_DIR=.wtt-connect-claude
+```
+
+Start them separately:
+
+```bash
+./start.sh --env-file .env.codex
+./start.sh --env-file .env.claude
+```
+
+Install them as separate macOS LaunchAgents:
+
+```bash
+./scripts/install-launchd.sh --name codex --env-file .env.codex
+./scripts/install-launchd.sh --name claude --env-file .env.claude
+```
+
+Install them as separate Linux `systemd --user` services from a source checkout if you are not using npm:
+
+```bash
+./scripts/install-agent.sh codex agent-codex '***'
+./scripts/install-agent.sh claude-code agent-claude '***'
+```
+
+The npm equivalent is preferred for end users:
+
+```bash
+wtt-connect up codex agent-codex '***'
+wtt-connect up claude-code agent-claude '***'
+```
+
+Use named options when you need a custom service name, permission mode, or boot-before-login behavior:
+
+```bash
+./scripts/install-systemd-user.sh \
+  --name alice-codex \
+  --agent-id agent-codex \
+  --token '***' \
+  --adapter codex \
+  --mode yolo \
+  --allow-yolo \
+  --publish-progress \
+  --enable-linger
+
+./scripts/install-systemd-user.sh \
+  --name alice-claude \
+  --agent-id agent-claude \
+  --token '***' \
+  --adapter claude-code \
+  --mode yolo \
+  --allow-yolo \
+  --publish-progress \
+  --enable-linger
+```
+
+Each invocation writes a separate `.env.<name>`, `.wtt-connect-<name>` state directory, and `wtt-connect-<name>.service`. Multiple WTT agent identities may share the same local `codex` or `claude` CLI binary; only the WTT identity and state directory need to be unique.
+
+Uninstall one identity with:
+
+```bash
+./scripts/uninstall-launchd.sh --name codex
+./scripts/uninstall-systemd-user.sh --name alice-codex
+```
+
+Discussion/collaborative topics are mention-gated: `wtt-connect` only replies when the message targets its `WTT_AGENT_ID`, one of `WTT_CONNECT_AGENT_ALIASES`, backend-resolved `runner_agent_id`, or a multi-mention `mention_target_agent_ids` entry. P2P and task topics still run normally.
+
+Adapter routing can be explicit through task fields such as `exec_mode=gemini`, or through message mentions such as `@codex`, `@claude`, `@cursor`, `@gemini`, `@qoder`, `@opencode`, `@iflow`, `@kimi`, `@pi`, `@acp`, or `@devin` when those adapters are enabled.
+
+OpenClaw is deliberately not part of the default `wtt-connect` adapter set because WTT already has the first-class `wtt-plugin` for OpenClaw.
+
+## Direction
+
+Near-term parity targets with cc-connect:
+
+1. Rich attachment rendering in WTT Web and task artifact schema persistence
+2. Fine-grained permission broker with per-task policy, not just env-level modes
+3. TTS/STT providers beyond macOS `say`
+4. Multiple concurrent local adapters under one claimed WTT agent
+5. Durable session store expanded across all native adapters
+6. Tool/progress event normalization for WTT Web observability
+7. Installer/claim flow integrated with wtt-web
+8. Artifact schema in task rows, not only topic messages
+
+## Production helpers
+
+```bash
+./start.sh
+./scripts/install-launchd.sh
+./scripts/uninstall-launchd.sh
+```
+
+## Smoke tests
+
+Run the connector in one terminal, then:
+
+```bash
+node ./bin/wtt-connect.js smoke-task --expected WTT_CONNECT_TASK_READY
+node ./bin/wtt-connect.js smoke-chat --expected WTT_CONNECT_CHAT_READY
+```
+
+`smoke-chat` requires a second sender agent via `WTT_SMOKE_SENDER_AGENT_ID` and `WTT_SMOKE_SENDER_TOKEN`.

package/bin/wtt-connect.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/main.js';
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err?.stack || err?.message || String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "wtt-connect",
+  "version": "0.1.0",
+  "private": false,
+  "description": "WTT-native connector daemon for Codex, Claude Code, Cursor, Gemini, ACP, and other coding agent surfaces.",
+  "type": "module",
+  "bin": {
+    "wtt-connect": "bin/wtt-connect.js"
+  },
+  "scripts": {
+    "check": "node --check bin/wtt-connect.js && node --check src/*.js && node --check src/adapters/*.js",
+    "doctor": "node ./bin/wtt-connect.js doctor",
+    "setup": "node ./bin/wtt-connect.js setup",
+    "smoke:task": "node ./bin/wtt-connect.js smoke-task",
+    "smoke:chat": "node ./bin/wtt-connect.js smoke-chat",
+    "start": "node ./bin/wtt-connect.js start"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "systemd",
+    "README.md",
+    "package.json"
+  ]
+}

package/scripts/install-agent.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+exec "$ROOT/scripts/install-systemd-user.sh" "$@"

package/scripts/install-launchd.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+NAME=""
+ENV_FILE=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name)
+      NAME="$2"; shift 2 ;;
+    --env-file)
+      ENV_FILE="$2"; shift 2 ;;
+    *)
+      echo "unknown argument: $1" >&2
+      echo "usage: $0 [--name codex] [--env-file .env.codex]" >&2
+      exit 2 ;;
+  esac
+done
+if [[ -z "$NAME" && -n "$ENV_FILE" ]]; then
+  base="$(basename "$ENV_FILE")"
+  NAME="${base#.env.}"
+  NAME="${NAME#.env}"
+fi
+LABEL="com.wtt.connect${NAME:+.$NAME}"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+mkdir -p "$HOME/Library/LaunchAgents" "$ROOT/logs"
+PROGRAM_ARGS="<string>$ROOT/start.sh</string>"
+if [[ -n "$ENV_FILE" ]]; then
+  PROGRAM_ARGS="$PROGRAM_ARGS<string>--env-file</string><string>$ENV_FILE</string>"
+fi
+NODE_BIN="$(command -v node || true)"
+NODE_DIR="$(dirname "${NODE_BIN:-/usr/bin/node}")"
+LAUNCH_PATH="$NODE_DIR:$PATH"
+cat > "$PLIST" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>$LABEL</string>
+  <key>ProgramArguments</key><array>$PROGRAM_ARGS</array>
+  <key>WorkingDirectory</key><string>$ROOT</string>
+  <key>EnvironmentVariables</key><dict>
+    <key>PATH</key><string>$LAUNCH_PATH</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>$ROOT/logs/${LABEL}.out.log</string>
+  <key>StandardErrorPath</key><string>$ROOT/logs/${LABEL}.err.log</string>
+</dict></plist>
+PLIST
+launchctl unload "$PLIST" >/dev/null 2>&1 || true
+launchctl load "$PLIST"
+echo "installed $PLIST"

package/scripts/install-systemd-user.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+usage() {
+  local code="${1:-2}"
+  cat >&2 <<'USAGE'
+Usage:
+  install-systemd-user.sh <agenttype> <agent_id> <token> [options]
+  install-systemd-user.sh --name <name> --agent-id <agent_id> --token <token> --adapter <adapter> [options]
+
+Minimal:
+  <agenttype>             codex or claude-code
+  <agent_id>              WTT agent id
+  <token>                 WTT agent token
+
+Named options:
+  --name <name>           Local service/env suffix, e.g. alice-codex.
+                          Defaults to <agent_id>-<adapter>.
+  --agent-id <agent_id>   WTT agent id
+  --token <token>         WTT agent token
+  --adapter <adapter>     codex, claude-code, cursor, gemini, qoder, opencode, iflow, kimi, pi, acp, devin.
+                          Defaults to codex.
+
+Options:
+  --base-url <url>        WTT base URL (default: https://www.waxbyte.com)
+  --workdir <dir>         Agent working directory (default: wtt-connect root)
+  --env-file <file>       Env file to write (default: .env.<name>)
+  --state-dir <dir>       State directory (default: .wtt-connect-<name>)
+  --mode <mode>           full-auto, auto-edit, suggest, yolo (default: full-auto)
+  --allow-yolo            Required when --mode yolo is used
+  --publish-progress      Publish agent progress/status messages
+  --timeout <seconds>     Per-run timeout (default: 3600)
+  --node-bin <path>       node binary (default: command -v node)
+  --codex-bin <path>      codex binary shared by any number of services
+  --claude-bin <path>     claude binary shared by any number of services
+  --enable-linger         Enable systemd user linger so services start at boot before login
+  --no-start              Enable service but do not start it now
+USAGE
+  exit "$code"
+}
+
+NAME=""
+AGENT_ID=""
+TOKEN=""
+ADAPTER=""
+BASE_URL="https://www.waxbyte.com"
+WORKDIR="$ROOT"
+ENV_FILE=""
+STATE_DIR=""
+MODE="${WTT_CONNECT_MODE:-full-auto}"
+ALLOW_YOLO=0
+PUBLISH_PROGRESS=0
+TIMEOUT_SECONDS=3600
+NODE_BIN="${WTT_NODE_BIN:-$(command -v node || true)}"
+CODEX_BIN="${WTT_CODEX_BIN:-$(command -v codex || true)}"
+CLAUDE_BIN="${WTT_CLAUDE_BIN:-$(command -v claude || true)}"
+ENABLE_LINGER=0
+START_NOW=1
+POSITIONAL=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name) NAME="$2"; shift 2 ;;
+    --agent-id) AGENT_ID="$2"; shift 2 ;;
+    --token) TOKEN="$2"; shift 2 ;;
+    --adapter) ADAPTER="$2"; shift 2 ;;
+    --base-url) BASE_URL="$2"; shift 2 ;;
+    --workdir) WORKDIR="$2"; shift 2 ;;
+    --env-file) ENV_FILE="$2"; shift 2 ;;
+    --state-dir) STATE_DIR="$2"; shift 2 ;;
+    --mode) MODE="$2"; shift 2 ;;
+    --allow-yolo) ALLOW_YOLO=1; shift ;;
+    --publish-progress) PUBLISH_PROGRESS=1; shift ;;
+    --timeout) TIMEOUT_SECONDS="$2"; shift 2 ;;
+    --node-bin) NODE_BIN="$2"; shift 2 ;;
+    --codex-bin) CODEX_BIN="$2"; shift 2 ;;
+    --claude-bin) CLAUDE_BIN="$2"; shift 2 ;;
+    --enable-linger) ENABLE_LINGER=1; shift ;;
+    --no-start) START_NOW=0; shift ;;
+    -h|--help) usage 0 ;;
+    --*) echo "unknown argument: $1" >&2; usage ;;
+    *)
+      POSITIONAL+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ "${#POSITIONAL[@]}" -gt 0 ]]; then
+  [[ -z "$AGENT_ID" && -z "$TOKEN" ]] || { echo "do not mix positional agent/token with --agent-id/--token" >&2; exit 2; }
+  [[ -z "$ADAPTER" ]] || { echo "do not mix positional agenttype with --adapter" >&2; exit 2; }
+  [[ "${#POSITIONAL[@]}" -eq 3 ]] || { echo "positional usage: $0 <agenttype> <agent_id> <token>" >&2; usage; }
+  ADAPTER="${POSITIONAL[0]}"
+  AGENT_ID="${POSITIONAL[1]}"
+  TOKEN="${POSITIONAL[2]}"
+fi
+
+ADAPTER="${ADAPTER:-codex}"
+if [[ -z "$NAME" && -n "$AGENT_ID" ]]; then
+  NAME="$AGENT_ID-$ADAPTER"
+fi
+
+[[ -n "$NAME" && -n "$AGENT_ID" && -n "$TOKEN" && -n "$ADAPTER" ]] || usage
+[[ -n "$NODE_BIN" && -x "$NODE_BIN" ]] || { echo "node binary not found; pass --node-bin" >&2; exit 1; }
+
+SAFE_NAME="$(printf '%s' "$NAME" | tr -cs 'A-Za-z0-9_.@-' '-' | sed 's/^-//; s/-$//')"
+[[ -n "$SAFE_NAME" ]] || { echo "invalid --name" >&2; exit 1; }
+
+case "$MODE" in
+  suggest|auto-edit|full-auto|yolo) ;;
+  *) echo "invalid --mode: $MODE" >&2; exit 1 ;;
+esac
+if [[ "$MODE" == "yolo" && "$ALLOW_YOLO" != "1" ]]; then
+  echo "--mode yolo requires --allow-yolo" >&2
+  exit 1
+fi
+
+ENV_FILE="${ENV_FILE:-$ROOT/.env.$SAFE_NAME}"
+STATE_DIR="${STATE_DIR:-$ROOT/.wtt-connect-$SAFE_NAME}"
+SERVICE_NAME="wtt-connect-$SAFE_NAME.service"
+SYSTEMD_USER_DIR="$HOME/.config/systemd/user"
+SERVICE_PATH="$SYSTEMD_USER_DIR/$SERVICE_NAME"
+
+NODE_MAJOR="$("$NODE_BIN" -p 'Number(process.versions.node.split(".")[0])')"
+NODE_WS_FLAG=()
+if [[ "$NODE_MAJOR" -lt 22 ]]; then
+  NODE_WS_FLAG=(--experimental-websocket)
+fi
+
+mkdir -p "$(dirname "$ENV_FILE")" "$STATE_DIR" "$SYSTEMD_USER_DIR"
+
+{
+  echo "# wtt-connect config for $NAME"
+  echo "# Keep local; contains agent secrets."
+  echo "WTT_BASE_URL=$BASE_URL"
+  echo "WTT_AGENT_ID=$AGENT_ID"
+  echo "WTT_TOKEN=$TOKEN"
+  echo "WTT_CONNECT_ADAPTERS=$ADAPTER"
+  echo "WTT_CONNECT_ADAPTER=$ADAPTER"
+  echo "WTT_CONNECT_WORKDIR=$WORKDIR"
+  echo "WTT_CONNECT_MODE=$MODE"
+  if [[ "$ALLOW_YOLO" == "1" ]]; then echo "WTT_CONNECT_ALLOW_YOLO=1"; fi
+  echo "WTT_CONNECT_ENABLE_CHAT=1"
+  echo "WTT_CONNECT_PUBLISH_PROGRESS=$PUBLISH_PROGRESS"
+  echo "WTT_CONNECT_TASK_TIMEOUT_SECONDS=$TIMEOUT_SECONDS"
+  echo "WTT_CONNECT_STATE_DIR=$STATE_DIR"
+  echo "WTT_REQUIRE_COMMIT_PUSH=1"
+  if [[ -n "$CODEX_BIN" ]]; then echo "WTT_CODEX_BIN=$CODEX_BIN"; fi
+  if [[ -n "$CLAUDE_BIN" ]]; then echo "WTT_CLAUDE_BIN=$CLAUDE_BIN"; fi
+} > "$ENV_FILE"
+chmod 600 "$ENV_FILE"
+
+cat > "$SERVICE_PATH" <<SERVICE
+[Unit]
+Description=WTT Connect Agent ($NAME)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=$ROOT
+Environment=PATH=/home/cecwxf/.local/npm-global/bin:/usr/local/bin:/usr/bin:/bin
+ExecStart=$NODE_BIN ${NODE_WS_FLAG[*]} $ROOT/bin/wtt-connect.js start --env-file $ENV_FILE
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+SERVICE
+
+systemctl --user daemon-reload
+if [[ "$START_NOW" == "1" ]]; then
+  systemctl --user enable --now "$SERVICE_NAME"
+else
+  systemctl --user enable "$SERVICE_NAME"
+fi
+
+if [[ "$ENABLE_LINGER" == "1" ]]; then
+  loginctl enable-linger "${USER}" || {
+    echo "warning: failed to enable linger; service will start when the user session starts" >&2
+  }
+fi
+
+echo "installed service: $SERVICE_NAME"
+echo "env file: $ENV_FILE"
+echo "state dir: $STATE_DIR"
+systemctl --user --no-pager --full status "$SERVICE_NAME" || true

package/scripts/uninstall-launchd.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+NAME=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name)
+      NAME="$2"; shift 2 ;;
+    *)
+      echo "unknown argument: $1" >&2
+      echo "usage: $0 [--name codex]" >&2
+      exit 2 ;;
+  esac
+done
+LABEL="com.wtt.connect${NAME:+.$NAME}"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+launchctl unload "$PLIST" >/dev/null 2>&1 || true
+rm -f "$PLIST"
+echo "uninstalled $PLIST"

package/scripts/uninstall-systemd-user.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+usage() {
+  local code="${1:-2}"
+  cat >&2 <<'USAGE'
+Usage:
+  uninstall-systemd-user.sh --name <name> [--delete-env]
+USAGE
+  exit "$code"
+}
+
+NAME=""
+DELETE_ENV=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name) NAME="$2"; shift 2 ;;
+    --delete-env) DELETE_ENV=1; shift ;;
+    -h|--help) usage 0 ;;
+    *) echo "unknown argument: $1" >&2; usage ;;
+  esac
+done
+
+[[ -n "$NAME" ]] || usage
+SAFE_NAME="$(printf '%s' "$NAME" | tr -cs 'A-Za-z0-9_.@-' '-' | sed 's/^-//; s/-$//')"
+[[ -n "$SAFE_NAME" ]] || { echo "invalid --name" >&2; exit 1; }
+
+SERVICE_NAME="wtt-connect-$SAFE_NAME.service"
+SERVICE_PATH="$HOME/.config/systemd/user/$SERVICE_NAME"
+ENV_FILE="$ROOT/.env.$SAFE_NAME"
+
+systemctl --user disable --now "$SERVICE_NAME" >/dev/null 2>&1 || true
+rm -f "$SERVICE_PATH"
+systemctl --user daemon-reload
+
+if [[ "$DELETE_ENV" == "1" ]]; then
+  rm -f "$ENV_FILE"
+fi
+
+echo "uninstalled service: $SERVICE_NAME"