@openparachute/agent 0.1.0

package/.claude/skills/add-vercel/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: add-vercel
+description: Add Vercel deployment capability to NanoClaw agents. Installs the Vercel CLI in agent containers and sets up OneCLI credential injection for api.vercel.com. Use when the user wants agents to deploy web applications to Vercel.
+---
+
+# Add Vercel
+
+This skill gives NanoClaw agents the ability to deploy web applications to Vercel. It installs the Vercel CLI in agent containers and configures OneCLI to inject Vercel credentials automatically.
+
+**Principle:** Do the work — don't tell the user to do it. Only ask for their input when it genuinely requires manual action (pasting a token).
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if the container skill exists:
+
+```bash
+test -d container/skills/vercel-cli && echo "INSTALLED" || echo "NOT_INSTALLED"
+```
+
+If `INSTALLED`, skip to Phase 3 (Configure Credentials).
+
+### Check prerequisites
+
+Verify OneCLI is working (required for credential injection):
+
+```bash
+onecli version 2>/dev/null && echo "ONECLI_OK" || echo "ONECLI_MISSING"
+```
+
+If `ONECLI_MISSING`, tell the user to run `/init-onecli` first, then retry `/add-vercel`. Stop here.
+
+## Phase 2: Install Container Skill
+
+Copy the bundled container skill into the container skills directory:
+
+```bash
+rsync -a .claude/skills/add-vercel/container-skills/ container/skills/
+```
+
+Verify:
+
+```bash
+head -5 container/skills/vercel-cli/SKILL.md
+```
+
+## Phase 3: Configure Credentials
+
+### Check if Vercel credential already exists
+
+```bash
+onecli secrets list 2>/dev/null | grep -i vercel
+```
+
+If a Vercel credential already exists, skip to Phase 4.
+
+### Set up Vercel API credential
+
+The agent needs a Vercel personal access token. Tell the user:
+
+> I need your Vercel personal access token. Go to https://vercel.com/account/tokens and create one with these settings:
+>
+> - **Token name:** `nanoclaw` (or any name you'll recognize)
+> - **Scope:** "Full Account" — the agent needs to create projects, deploy, and manage domains
+> - **Expiration:** "No expiration" recommended (avoids credential rotation), or pick a date if your security policy requires it
+>
+> After creating the token, copy it — you'll only see it once.
+
+Once the user provides the token, add it to OneCLI:
+
+```bash
+onecli secrets create \
+  --name "Vercel API Token" \
+  --type generic \
+  --value "<TOKEN>" \
+  --host-pattern "api.vercel.com" \
+  --header-name "Authorization" \
+  --value-format "Bearer {value}"
+```
+
+Verify:
+
+```bash
+onecli secrets list | grep -i vercel
+```
+
+### Assign the secret to all agents
+
+OneCLI uses selective secret mode — secrets must be explicitly assigned to each agent. Get the Vercel secret ID from the output above, then assign it to every agent:
+
+```bash
+# For each agent, add the Vercel secret to its assigned secrets list.
+# First get current assignments, then set them with the new secret appended.
+VERCEL_SECRET_ID=$(onecli secrets list 2>/dev/null | grep -B2 "Vercel" | grep '"id"' | head -1 | sed 's/.*"id": "//;s/".*//')
+for agent in $(onecli agents list 2>/dev/null | grep '"id"' | sed 's/.*"id": "//;s/".*//'); do
+  CURRENT=$(onecli agents secrets --id "$agent" 2>/dev/null | grep '"' | grep -v hint | grep -v data | sed 's/.*"//;s/".*//' | tr '\n' ',' | sed 's/,$//')
+  onecli agents set-secrets --id "$agent" --secret-ids "${CURRENT:+$CURRENT,}$VERCEL_SECRET_ID"
+done
+```
+
+## Phase 4: Ensure Vercel CLI in Container Image
+
+Check if `vercel` is already in the Dockerfile:
+
+```bash
+grep -q 'vercel' container/Dockerfile && echo "PRESENT" || echo "MISSING"
+```
+
+If `MISSING`, add `vercel` to the global npm install line in `container/Dockerfile`, then rebuild:
+
+```bash
+./container/build.sh
+```
+
+If `PRESENT`, skip — no rebuild needed.
+
+## Phase 5: Sync Skills to Running Agent Groups
+
+Container skills are copied once at group creation and not auto-synced. After installing or updating a container skill, sync it to all existing agent groups:
+
+```bash
+for session_dir in data/v2-sessions/ag-*; do
+  if [ -d "$session_dir/.claude-shared/skills" ]; then
+    rsync -a container/skills/ "$session_dir/.claude-shared/skills/"
+    echo "Synced skills to: $session_dir"
+  fi
+done
+```
+
+## Phase 6: Restart Running Containers
+
+Stop all running agent containers so they pick up the new skills on next wake:
+
+```bash
+docker ps --format "{{.ID}} {{.Names}}" | grep nanoclaw-v2 | awk '{print $1}' | xargs -r docker stop
+```
+
+## Done
+
+The agent can now deploy web applications to Vercel. Key commands:
+
+- `vercel deploy --yes --prod --token placeholder` — deploy to production
+- `vercel ls --token placeholder` — list deployments
+- `vercel whoami --token placeholder` — check auth
+
+For the full command reference, the agent has the `vercel-cli` container skill loaded automatically.

package/.claude/skills/add-vercel/container-skills/vercel-cli/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: vercel-cli
+description: Deploy apps to Vercel. Use when asked to deploy, ship, or publish a web application, or manage Vercel projects, domains, and environment variables.
+---
+
+# Vercel CLI
+
+You can deploy web applications to Vercel using the `vercel` CLI.
+
+## Auth
+
+Auth is handled by OneCLI — the HTTPS_PROXY injects the real token into API requests automatically. The Vercel CLI requires a token to be present to skip its local credential check, so **always pass `--token placeholder`** on every command. OneCLI replaces this with the real token at the proxy level.
+
+Before any Vercel operation, verify auth:
+
+```bash
+vercel whoami --token placeholder
+```
+
+If this fails with an auth error, ask the user to add a Vercel token to OneCLI. They can create one at https://vercel.com/account/tokens and register it via `onecli secrets create` on the host. Once added, retry `vercel whoami`.
+
+## Deploying
+
+Always use `--yes` to skip interactive prompts and `--token placeholder` for auth (OneCLI replaces with real token).
+
+```bash
+# Deploy to production
+vercel deploy --yes --prod --token placeholder
+
+# Deploy from a specific directory
+vercel deploy --yes --prod --token placeholder --cwd /path/to/project
+
+# Preview deployment (not production)
+vercel deploy --yes --token placeholder
+```
+
+After deploying, verify the live URL:
+
+```bash
+# Check deployment status
+vercel inspect <deployment-url> --token placeholder
+```
+
+## Pre-Send Checks (do this before sharing the URL)
+
+Don't send the deployment URL to the user until you've confirmed it's actually working. At minimum:
+
+1. **Local build passes** — run `npm run build` (or the project's build command) before `vercel deploy`. If the build fails locally, fix it first; don't deploy broken code.
+2. **Deployment succeeded** — the `vercel deploy` output shows a "Production: https://..." URL and the status is READY (confirm with `vercel inspect`).
+3. **Live URL responds** — `curl -sI <url> | head -1` should return `HTTP/2 200` (or another 2xx/3xx). A 404/500 means something's broken even though Vercel reported success.
+4. **Optional visual check** — if `agent-browser` is loaded, open the URL and eyeball it. Helpful for catching broken layouts that a 200 response wouldn't reveal.
+
+If any check fails, fix the issue and redeploy before reporting to the user.
+
+## Project Management
+
+```bash
+# Link to an existing Vercel project (non-interactive)
+vercel link --yes --token placeholder
+
+# List recent deployments
+vercel ls --token placeholder
+
+# List all projects
+vercel project ls --token placeholder
+```
+
+## Domains
+
+```bash
+# List domains
+vercel domains ls --token placeholder
+
+# Add a domain to the current project
+vercel domains add example.com --token placeholder
+```
+
+## Environment Variables
+
+```bash
+# Pull env vars from Vercel to local .env
+vercel env pull --token placeholder
+
+# Add an env var (use echo to pipe the value — avoids interactive prompt)
+echo "value" | vercel env add VAR_NAME production --token placeholder
+```
+
+## Common Errors
+
+| Error | Fix |
+|-------|-----|
+| `Error: No framework detected` | Ensure the project has a `package.json` with a `build` script, or set the framework in `vercel.json` |
+| `Error: Rate limited` | Wait and retry. Don't loop — report to user |
+| `Error: You have reached your project limit` | User needs to upgrade Vercel plan or delete unused projects |
+| `ENOTFOUND api.vercel.com` | Network issue. Check proxy connectivity |
+| Auth error after `vercel whoami` | Credential may be expired. Ask the user to refresh the Vercel token in OneCLI |
+
+## Best Practices
+
+- Run `npm run build` locally before deploying to catch build errors early
+- Use `--cwd` instead of `cd` to keep your working directory stable
+- For Next.js projects, `vercel deploy` auto-detects the framework — no extra config needed
+- Use `vercel.json` only when you need custom build settings, rewrites, or headers

package/.claude/skills/add-webex/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Webex Channel
+
+1. Comment out `import './webex.js'` in `src/channels/index.ts`
+2. Remove `WEBEX_BOT_TOKEN` and `WEBEX_WEBHOOK_SECRET` from `.env`
+3. `pnpm uninstall @bitbasti/chat-adapter-webex`
+4. Rebuild and restart

package/.claude/skills/add-webex/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: add-webex
+description: Add Webex channel integration via Chat SDK.
+---
+
+# Add Webex Channel
+
+Adds Cisco Webex support via the Chat SDK bridge.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Webex adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/webex.ts` exists
+- `src/channels/index.ts` contains `import './webex.js';`
+- `@bitbasti/chat-adapter-webex` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/webex.ts > src/channels/webex.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './webex.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @bitbasti/chat-adapter-webex@0.1.0
+```
+
+### 5. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+1. Go to [developer.webex.com](https://developer.webex.com/my-apps/new/bot) and create a new bot
+2. Copy the **Bot Access Token**
+3. Set up a webhook:
+   - Use the Webex API or Developer Portal to create a webhook pointing to `https://your-domain/webhook/webex`
+   - Set a webhook secret for signature verification
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+WEBEX_BOT_TOKEN=your-bot-token
+WEBEX_WEBHOOK_SECRET=your-webhook-secret
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `webex`
+- **terminology**: Webex has "spaces." A space can be a group conversation or a 1:1 direct message with the bot.
+- **how-to-find-id**: Open the space in Webex, click the space name > Settings — the Space ID is listed there. Or use the Webex API (`GET /rooms`) to list spaces and their IDs.
+- **supports-threads**: yes
+- **typical-use**: Interactive chat — team spaces or direct messages
+- **default-isolation**: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive information.

package/.claude/skills/add-webex/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Webex Channel
+
+Add the bot to a Webex space or send it a direct message. The bot should respond within a few seconds.

package/.claude/skills/add-wechat/REMOVE.md

@@ -0,0 +1,49 @@
+# Remove WeChat Channel
+
+Undo `/add-wechat`.
+
+### 1. Remove credentials
+
+Delete WeChat lines from `.env`:
+
+```bash
+sed -i.bak '/^WECHAT_ENABLED=/d' .env && rm -f .env.bak
+cp .env data/env/env
+```
+
+### 2. Remove adapter and import
+
+```bash
+rm -f src/channels/wechat.ts
+sed -i.bak "/import '\.\/wechat\.js';/d" src/channels/index.ts && rm -f src/channels/index.ts.bak
+```
+
+### 3. Uninstall the package
+
+```bash
+pnpm remove wechat-ilink-client
+```
+
+### 4. Remove saved auth + sync state
+
+```bash
+rm -rf data/wechat
+```
+
+### 5. Remove DB wiring
+
+```sql
+-- Remove any sessions first (foreign key)
+DELETE FROM sessions WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type = 'wechat');
+DELETE FROM messaging_group_agents WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type = 'wechat');
+DELETE FROM messaging_groups WHERE channel_type = 'wechat';
+```
+
+### 6. Rebuild and restart
+
+```bash
+pnpm run build
+systemctl --user restart nanoclaw   # Linux
+# or
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```

package/.claude/skills/add-wechat/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: add-wechat
+description: Add WeChat (personal) channel integration via Tencent's official iLink Bot API. Uses long-polling and QR scan — no webhook, no ToS risk, no paid token.
+---
+
+# Add WeChat Channel
+
+Adds WeChat support via **iLink Bot API** — the first-party Tencent API for personal WeChat bots (different from WeCom / Official Account).
+
+**Why this is different from wechaty/PadLocal:**
+
+- Official Tencent API — no ToS violation, no ban risk
+- Free — no PadLocal token required
+- No public webhook URL needed — uses long-poll
+- Works with any personal WeChat account
+
+## Prerequisites
+
+- A **personal WeChat account** with the mobile app installed
+- A phone to scan the QR code for login
+- Node.js >= 20 (already required by NanoClaw)
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the WeChat adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/wechat.ts` exists
+- `src/channels/index.ts` contains `import './wechat.js';`
+- `wechat-ilink-client` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/wechat.ts > src/channels/wechat.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './wechat.js';
+```
+
+### 4. Install the library (pinned)
+
+```bash
+pnpm install wechat-ilink-client@0.1.0
+```
+
+### 5. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+Unlike most channels, WeChat requires **no pre-configured API keys**. Auth happens via QR code scan from your phone.
+
+### 1. Enable the channel
+
+Add to `.env`:
+
+```bash
+WECHAT_ENABLED=true
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+### 2. Start the service and scan the QR
+
+Restart NanoClaw:
+
+```bash
+systemctl --user restart nanoclaw   # Linux
+# or
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+The adapter will print a **QR URL** to the logs and save it to `data/wechat/qr.txt`:
+
+```bash
+tail -f logs/nanoclaw.log | grep WeChat
+# or
+cat data/wechat/qr.txt
+```
+
+Open the URL in a browser (it renders a QR code), then:
+
+1. Open WeChat on your phone
+2. Use its built-in QR scanner (top-right "+" → Scan)
+3. Approve the authorization on your phone
+4. Auth credentials are saved to `data/wechat/auth.json` — do not commit this file
+
+The bot is now connected as your WeChat account.
+
+## Wire your first DM
+
+A successful QR login alone isn't enough — the adapter still needs to be wired to an agent group before it can respond.
+
+### 1. Trigger the first inbound message
+
+Have a different WeChat account send a message to the bot account. This auto-creates a `messaging_groups` row with the sender's `platform_id`.
+
+### 2. Run the wire script
+
+```bash
+pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts
+```
+
+Interactive flow: the script lists all unwired WeChat messaging groups, asks which agent group to wire it to, and creates the `messaging_group_agents` row with sensible defaults (sender policy `request_approval`, session mode `shared`).
+
+With `request_approval`, the next DM from the stranger fires an approval card to the admin — admin taps Approve/Deny, approved users are added as members and their queued message replays through the agent.
+
+Non-interactive:
+
+```bash
+pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts \
+  --platform-id wechat:wxid_xxxxx \
+  --agent-group ag-xxxxx \
+  --non-interactive
+```
+
+Flags:
+
+- `--platform-id <id>` — wire a specific messaging group (default: most recent unwired)
+- `--agent-group <id>` — target agent group (default: prompt; or solo admin group in non-interactive)
+- `--sender-policy public|strict|request_approval` — default `request_approval` (fires an admin approval card on unknown-sender DMs)
+- `--session-mode shared|per-thread` — default `shared`
+
+### 3. Test
+
+Have the sender message the bot again — the agent should respond.
+
+## Operational notes
+
+- **Only one instance can use a given token at a time.** Don't run multiple NanoClaw instances pointing to the same `data/wechat/auth.json`.
+- **Re-login on session expiry:** if you see `WeChat: session expired` in logs, delete `data/wechat/auth.json` and restart — you'll be asked to re-scan.
+- **Sync cursor persistence:** `data/wechat/sync-buf.txt` holds the long-poll cursor. Deleting it replays recent history on next start; don't delete it in normal operation.
+- **Account safety:** this uses the official Tencent API, so account bans for bot automation aren't a risk. That said, don't spam — normal rate limits still apply.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, restart the service to pick up the new channel and wiring.
+
+## Channel Info
+
+- **type**: `wechat`
+- **terminology**: WeChat has "contacts" (DMs) and "group chats" (rooms). Each DM or group is a separate messaging group.
+- **how-to-find-id**: Send a message to the bot from the target account; the adapter auto-creates a messaging group and logs `WeChat inbound platformId=wechat:<id>`. Use `wechat:<user_id>` for DMs, `wechat:<group_id>` for rooms.
+- **admin-user-id**: The operator's WeChat user_id (for `init-first-agent.ts --admin-user-id`) is saved to `data/wechat/auth.json` as `operatorUserId` after the QR scan. Read it with `cat data/wechat/auth.json | jq -r .operatorUserId` and prefix with `wechat:` (i.e. `wechat:<operatorUserId>`).
+- **supports-threads**: no (WeChat has no reply threads)
+- **typical-use**: Long-poll — the adapter holds a persistent connection to Tencent's iLink API and receives messages in real time. No webhook URL needed.
+- **default-isolation**: `shared` session mode per messaging group (DM or room). Use `strict` sender policy if you want only specific users to reach the agent; `public` opens it to anyone who messages the bot.
+- **post-install-wiring**: Use the `wire-dm.ts` helper (see the "Wire your first DM" section above) if running this skill standalone. If running as part of `bash nanoclaw.sh`, `init-first-agent.ts` handles wiring — just pass the `platform-id` and `admin-user-id` captured above.