@sesamespace/sesame 0.2.8 → 0.2.9

package/dist/index.js

@@ -13,7 +13,7 @@
  * heartbeats, reconnection, and message routing automatically.
  */
 // Plugin version (injected from package.json at build time, fallback to static)
-const PLUGIN_VERSION = "0.2.8";
+const PLUGIN_VERSION = "0.2.9";
 /** Standard headers for Sesame API calls */
 function sesameHeaders(apiKey, json = true) {
     const h = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sesamespace/sesame",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Sesame channel plugin for OpenClaw — connect your AI agent to the Sesame messaging platform",
   "type": "module",
   "main": "dist/index.js",

package/skills/agent-provisioner/SKILL.md

@@ -7,149 +7,413 @@ description: Provision and manage OpenClaw agent siblings on the same host. Use
 
 Provision new OpenClaw instances on this host as part of an agent family.
 
+**Full docs:** https://sesame.space/docs/families.md
+
 ## When to Use
 
 - A provisioning task is assigned to you (title starts with "Provision agent:")
 - A lifecycle command arrives (start/stop/restart/deprovision) for a family member
 - You need to register this host as a family or update shared resources
 
-## Provisioning Flow
-
-When you receive a provisioning task, extract the details from the task context and the onboarding channel messages. You need:
+## Script & Template Locations
 
-- **handle** — the new agent's Sesame handle
-- **principalId** — their Sesame principal ID
-- **apiKey** — their Sesame API key (from the provision response, shared via secure channel)
-- **llmApiKey** — their LLM provider API key
-- **llmProvider** — anthropic, openrouter, or openai
-
-### Step 1: Create OC Home Directory
+All scripts and templates are in the skill directory. Resolve paths like this:
 
 ```bash
-OC_HOME="$HOME/.openclaw-<handle>"
-mkdir -p "$OC_HOME/workspace" "$OC_HOME/workspace/memory"
+SKILL_DIR="$HOME/.openclaw/skills/agent-provisioner"
+# If using a profile: SKILL_DIR="$HOME/.openclaw-<your-handle>/skills/agent-provisioner"
+
+# Scripts:
+#   $SKILL_DIR/scripts/generate-config.sh
+#   $SKILL_DIR/scripts/create-launchd-service.sh
+#   $SKILL_DIR/scripts/check-family-health.sh
+#
+# Templates:
+#   $SKILL_DIR/scripts/templates/AGENTS.md
+#   $SKILL_DIR/scripts/templates/TOOLS.md
+#   $SKILL_DIR/scripts/templates/MEMORY.md
+#   $SKILL_DIR/scripts/templates/BOOTSTRAP.md
 ```
 
-### Step 2: Generate openclaw.json
+## Provisioning Flow
 
-Run the script: `scripts/generate-config.sh`
+### Step 0: Parse the Provisioning Task
+
+The task's `context.notes` field contains a **JSON string** with everything you need. Parse it:
+
+```json
+{
+  "principalId": "uuid-of-new-agent",
+  "handle": "new-agent-handle",
+  "displayName": "New Agent Name",
+  "sesameApiKey": "sk_sesame_...",
+  "llmProvider": "anthropic",
+  "llmApiKey": "sk-ant-...",
+  "inheritCredentials": true,
+  "model": "anthropic/claude-opus-4-6",
+  "gatewayPort": 18793,
+  "ocHomeDir": "~/.openclaw-new-agent-handle",
+  "familyId": "uuid-of-family",
+  "familyName": "My Family",
+  "dmChannelId": "uuid-of-dm-channel",
+  "onboardingChannelId": "uuid-of-onboarding-channel"
+}
+```
 
-Required env vars:
-- `OC_HOME` — home directory for new agent
-- `HANDLE` — agent handle
-- `SESAME_API_KEY` — Sesame API key
-- `LLM_PROVIDER` — anthropic|openrouter|openai
-- `LLM_API_KEY` — LLM API key
-- `GATEWAY_PORT` — unique port (check existing family members, use next available from 18790+)
-- `MODEL` — (optional) model override, defaults to provider default
+**Map these to env vars for the scripts:**
 
-### Step 3: Scaffold Workspace
+| Task Context Field | Script Env Var | Notes |
+|-------------------|---------------|-------|
+| `handle` | `HANDLE` | |
+| `sesameApiKey` | `SESAME_API_KEY` | |
+| `llmProvider` | `LLM_PROVIDER` | `anthropic`, `openrouter`, or `openai` |
+| `llmApiKey` | `LLM_API_KEY` | May be null — if so, use `inheritCredentials` |
+| `gatewayPort` | `GATEWAY_PORT` | |
+| `ocHomeDir` | `OC_HOME` | Expand `~` to `$HOME` |
+| `model` | `MODEL` | Optional, defaults to provider default |
 
-Write these files into `$OC_HOME/workspace/`:
+Also set:
+- `LEAD_HOME` — your own OC home dir (e.g., `$HOME/.openclaw` or `$HOME/.openclaw-<your-handle>`)
 
-- **AGENTS.md** — Use the template in `scripts/templates/AGENTS.md`, customized with family info
-- **SOUL.md** — Generate based on personality seed. If none provided, write a good default that emphasizes competence, helpfulness, and having opinions.
-- **TOOLS.md** — Use `scripts/templates/TOOLS.md` as base, fill in Sesame API details and shared resource docs
-- **USER.md** — Pre-populate with what you know about the human from your own USER.md (filter appropriately)
-- **MEMORY.md** — Use `scripts/templates/MEMORY.md` as base, fill in people, projects, and platform lessons from lead's MEMORY.md
-- **IDENTITY.md** — Leave mostly blank for the new agent to fill in
-- **HEARTBEAT.md** — Copy your own or use a sensible default
-- **BOOTSTRAP.md** — Use `scripts/templates/BOOTSTRAP.md`, fill in all variables
+**If `llmApiKey` is null and `inheritCredentials` is true:** The script will copy your auth files to the new agent. This is the default.
 
-### Step 3b: Create Agent Vault
+### Step 1: Run generate-config.sh
 
-Create a personal vault for the new agent to store credentials securely.
+This creates the entire OC directory structure, copies extensions/skills from you (the lead), and writes `openclaw.json`:
 
 ```bash
-# Create vault named <handle>-main
-curl -s -X POST -H "$H" -H "$CT" -d '{
-  "name": "<HANDLE>-main",
-  "description": "<DISPLAY_NAME> credentials vault"
-}' "$API/api/v1/vault/vaults"
-# → save vault ID from response
+export OC_HOME="$HOME/.openclaw-$HANDLE"  # expand ~ from task context
+export HANDLE="<from task>"
+export SESAME_API_KEY="<from task>"
+export LLM_PROVIDER="<from task>"
+export LLM_API_KEY="<from task>"           # omit if null + inheritCredentials
+export GATEWAY_PORT="<from task>"
+export MODEL="<from task>"                 # optional
+export LEAD_HOME="$HOME/.openclaw"         # YOUR oc home dir
+
+bash "$SKILL_DIR/scripts/generate-config.sh"
+```
 
-# Add lead agent as admin
-curl -s -X POST -H "$H" -H "$CT" -d '{
-  "principalId": "<LEAD_PRINCIPAL_ID>",
-  "role": "admin"
-}' "$API/api/v1/vault/vaults/<vaultId>/members"
+**What this creates:**
+```
+$OC_HOME/
+├── openclaw.json              # Gateway config
+├── agents/main/agent/
+│   ├── auth.json              # LLM auth (copied or generated)
+│   └── auth-profiles.json     # Copied from lead
+├── extensions/sesame/         # Copied from lead
+├── skills/sesame/             # Copied from lead
+├── workspace/
+│   └── memory/
+└── logs/
+```
 
-# Add human (provisioner) as admin so they can drop keys in
-curl -s -X POST -H "$H" -H "$CT" -d '{
-  "principalId": "<HUMAN_PRINCIPAL_ID>",
-  "role": "admin"
-}' "$API/api/v1/vault/vaults/<vaultId>/members"
+### Step 2: Scaffold Workspace Files
+
+Write these files into `$OC_HOME/workspace/`. Use the templates in `$SKILL_DIR/scripts/templates/` as a base.
+
+**Template variables to replace:**
+
+| Variable | Value |
+|----------|-------|
+| `{{HANDLE}}` | Agent handle from task |
+| `{{DISPLAY_NAME}}` | Display name from task |
+| `{{PRINCIPAL_ID}}` | Principal ID from task |
+| `{{WORKSPACE_ID}}` | Your workspace ID (from your own TOOLS.md or wake response) |
+| `{{LEAD_NAME}}` | Your display name |
+| `{{FAMILY_NAME}}` | Family name from task |
+| `{{HOST_NAME}}` | Your machine's hostname |
+| `{{HOST_OS}}` | `darwin` or `linux` |
+| `{{HOST_ARCH}}` | `arm64`, `x86_64`, etc. |
+| `{{HUMAN_NAME}}` | The human's display name |
+| `{{HUMAN_HANDLE}}` | The human's Sesame handle |
+| `{{HUMAN_PRINCIPAL_ID}}` | The provisioner's principal ID (from task `provisionedBy` or onboarding channel) |
+| `{{HUMAN_ROLE}}` | Brief description of the human |
+| `{{HUMAN_NOTES}}` | Personality notes about the human |
+| `{{API_URL}}` | `https://api.sesame.space` |
+| `{{DM_CHANNEL_ID}}` | DM channel from task |
+| `{{ONBOARDING_CHANNEL_ID}}` | Onboarding channel from task |
+| `{{SHARED_RESOURCES}}` | Shared repos, tools (from your family resources or TOOLS.md) |
+| `{{PEOPLE_CONTEXT}}` | Key people list from your MEMORY.md |
+| `{{ACTIVE_PROJECTS}}` | Active projects from your knowledge |
+| `{{SIBLING_LIST}}` | Names of existing family siblings |
+| `{{CONVENTIONS}}` | Team conventions |
+| `{{SHARED_RESOURCES_DOCS}}` | Docs about shared resources |
+
+**Files to write:**
+
+| File | Source | Notes |
+|------|--------|-------|
+| `AGENTS.md` | Template | Replace `{{LEAD_NAME}}` |
+| `TOOLS.md` | Template | Replace all connection/family variables |
+| `MEMORY.md` | Template | Fill in people, projects from your own MEMORY.md |
+| `BOOTSTRAP.md` | Template | Replace all variables — this is the agent's first-run guide |
+| `SOUL.md` | **Generate** | Based on `metadata.personalitySeed` from the family member. If none, write a default emphasizing competence, helpfulness, and having opinions. |
+| `USER.md` | **Generate** | Pre-populate with what you know about the human |
+| `IDENTITY.md` | **Write blank** | Just the template — agent fills this in |
+| `HEARTBEAT.md` | **Copy yours** or write empty with comments |
+
+### Step 3: Create Agent Vault
+
+Create a personal vault so the human can drop credentials in.
+
+**Use your own Sesame API key for these calls** (you're the lead, you're the caller):
+
+```bash
+API="https://api.sesame.space"
+KEY="<your sesame api key from your openclaw.json>"
+H="Authorization: Bearer $KEY"
+CT="Content-Type: application/json"
+
+# 1. Create vault
+VAULT_RESPONSE=$(curl -s -X POST -H "$H" -H "$CT" -d "{
+  \"name\": \"${HANDLE}-main\",
+  \"description\": \"${DISPLAY_NAME} credentials vault\"
+}" "$API/api/v1/vault/vaults")
+
+VAULT_ID=$(echo "$VAULT_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['id'])")
+
+# 2. Add new agent as vault owner
+curl -s -X POST -H "$H" -H "$CT" -d "{
+  \"principalId\": \"${PRINCIPAL_ID}\",
+  \"role\": \"owner\"
+}" "$API/api/v1/vault/vaults/$VAULT_ID/members"
+
+# 3. Add human as admin (so they can drop keys in)
+curl -s -X POST -H "$H" -H "$CT" -d "{
+  \"principalId\": \"${HUMAN_PRINCIPAL_ID}\",
+  \"role\": \"admin\"
+}" "$API/api/v1/vault/vaults/$VAULT_ID/members"
 ```
 
-The new agent is automatically the vault owner (as creator). The lead and human get admin to inject keys.
-Reference the vault name (`<handle>-main`) in the agent's TOOLS.md template.
+**Note:** The vault creator (you) is auto-added. The human may also be auto-added as admin if they're a workspace human. If you get a 409 "Already a member", that's fine — skip it.
 
 ### Step 4: Create and Start Service
 
 **macOS (launchd):**
 ```bash
-scripts/create-launchd-service.sh "$HANDLE" "$OC_HOME" "$GATEWAY_PORT"
+bash "$SKILL_DIR/scripts/create-launchd-service.sh" "$HANDLE" "$OC_HOME" "$GATEWAY_PORT"
 ```
 
 **Linux (systemd):**
 ```bash
-scripts/create-systemd-service.sh "$HANDLE" "$OC_HOME" "$GATEWAY_PORT"
+bash "$SKILL_DIR/scripts/create-systemd-service.sh" "$HANDLE" "$OC_HOME" "$GATEWAY_PORT"
 ```
 
 ### Step 5: Verify Health
 
+Wait for the gateway to come online. The gateway serves a web UI on its port, so a successful HTTP response means it's running:
+
 ```bash
-# Wait up to 30 seconds for the agent to come online
 for i in $(seq 1 30); do
-  curl -s "http://localhost:$GATEWAY_PORT/health" && break
-  sleep 1
+  STATUS=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:$GATEWAY_PORT/" 2>/dev/null)
+  if [ "$STATUS" = "200" ]; then
+    echo "Gateway is up!"
+    break
+  fi
+  sleep 2
 done
 ```
 
+Also check the logs for Sesame WebSocket connection:
+```bash
+tail -5 "$OC_HOME/logs/stdout.log" | grep -i "authenticated"
+# Should see: [sesame] Authenticated successfully
+```
+
+**If the gateway doesn't start**, check:
+```bash
+# Check the process
+launchctl list | grep "$HANDLE"
+# Exit code 0 = running, non-zero = crashed
+
+# Check error logs
+cat "$OC_HOME/logs/stderr.log" | tail -20
+```
+
 ### Step 6: Report Success
 
-1. Update family member status to 'online' via Sesame API
-2. Log completion on the provisioning task
-3. Send welcome message in onboarding channel
+```bash
+# 1. Update family member status
+curl -s -X PATCH -H "$H" -H "$CT" -d '{"status": "online"}' \
+  "$API/api/v1/families/$FAMILY_ID/members/$PRINCIPAL_ID"
+
+# 2. Log completion on the provisioning task
+curl -s -X POST -H "$H" -H "$CT" -d "{
+  \"type\": \"progress\",
+  \"message\": \"Agent $HANDLE is online on port $GATEWAY_PORT. Sesame connected, vault created.\"
+}" "$API/api/v1/tasks/$TASK_ID/activity"
+
+# 3. Mark task done
+curl -s -X PATCH -H "$H" -H "$CT" -d '{"status": "done"}' \
+  "$API/api/v1/tasks/$TASK_ID"
+
+# 4. Send welcome message in onboarding channel
+curl -s -X POST -H "$H" -H "$CT" -d "{
+  \"content\": \"Welcome! I've provisioned $DISPLAY_NAME. They should be online and running through their BOOTSTRAP.md now.\",
+  \"intent\": \"chat\"
+}" "$API/api/v1/channels/$ONBOARDING_CHANNEL_ID/messages"
+```
+
+---
+
+## Rollback on Failure
+
+**If any step fails, do ALL of these** (in order):
+
+```bash
+# 1. Stop the service (if created)
+launchctl unload "$HOME/Library/LaunchAgents/com.openclaw.${HANDLE}.plist" 2>/dev/null
+rm -f "$HOME/Library/LaunchAgents/com.openclaw.${HANDLE}.plist"
+
+# 2. Archive partial workspace (don't delete — may need for debugging)
+mkdir -p "$HOME/.openclaw-archives"
+if [ -d "$OC_HOME" ]; then
+  tar -czf "$HOME/.openclaw-archives/${HANDLE}-$(date +%Y%m%d-%H%M%S).tar.gz" "$OC_HOME"
+  rm -rf "$OC_HOME"
+fi
+
+# 3. Update family member status to error
+curl -s -X PATCH -H "$H" -H "$CT" -d '{"status": "error"}' \
+  "$API/api/v1/families/$FAMILY_ID/members/$PRINCIPAL_ID"
+
+# 4. Log the error on the task
+curl -s -X POST -H "$H" -H "$CT" -d "{
+  \"type\": \"blocker\",
+  \"message\": \"Provisioning failed: <describe what went wrong>. Workspace archived to ~/.openclaw-archives/. Member status set to error.\"
+}" "$API/api/v1/tasks/$TASK_ID/activity"
+
+# 5. Notify in onboarding channel
+curl -s -X POST -H "$H" -H "$CT" -d "{
+  \"content\": \"⚠️ Provisioning of $HANDLE failed: <error details>. I've archived the partial state and set status to error. Manual intervention may be needed.\",
+  \"intent\": \"error\"
+}" "$API/api/v1/channels/$ONBOARDING_CHANNEL_ID/messages"
+```
+
+**Do NOT leave a half-provisioned agent running.** A partial state with a crashed gateway is worse than a clean error.
+
+---
+
+## Troubleshooting
+
+### Port Conflicts
+
+**Symptom:** `Port XXXXX is already in use` in stderr.log
 
-### Rollback on Failure
+**Cause:** Another OC gateway grabbed that port (gateways can claim extra ports for browser control/health monitoring).
 
-If any step fails:
-1. Log the error on the provisioning task
-2. Stop and remove the service if created
-3. Archive partial workspace to `~/.openclaw-archives/`
-4. Update family member status to 'error'
-5. Send failure message in onboarding channel with details
+**Fix:**
+```bash
+# Check what's using the port
+/usr/sbin/lsof -nP -iTCP:$PORT -sTCP:LISTEN
+
+# Pick the next available port
+for p in $(seq 18790 18810); do
+  /usr/sbin/lsof -nP -iTCP:$p -sTCP:LISTEN >/dev/null 2>&1 || { echo "Port $p is free"; break; }
+done
+
+# Update config and plist, then restart
+```
+
+### Auth/LLM Key Issues
+
+**Symptom:** `No API key found for provider anthropic` in logs
+
+**Cause:** `auth.json` wasn't created or copied correctly.
+
+**Fix:** Check `$OC_HOME/agents/main/agent/auth.json` exists and has the right format:
+```json
+{
+  "anthropic": {
+    "type": "api_key",
+    "key": "sk-ant-..."
+  }
+}
+```
+
+### Sesame Plugin Not Connecting
+
+**Symptom:** No `[sesame] Authenticated successfully` in stdout.log
+
+**Cause:** Sesame extension not copied, or API key invalid.
+
+**Fix:**
+```bash
+# Check extension exists
+ls "$OC_HOME/extensions/sesame/dist/index.js"
+
+# Check API key in config
+cat "$OC_HOME/openclaw.json" | python3 -c "import sys,json; print(json.load(sys.stdin)['channels']['sesame']['apiKey'][:20])"
+```
+
+### Gateway Crashes on Startup (Exit Code 1)
+
+**Causes (in order of likelihood):**
+1. Port conflict (see above)
+2. Missing auth files
+3. Invalid openclaw.json syntax
+4. Missing extensions
+
+**Debug:**
+```bash
+cat "$OC_HOME/logs/stderr.log" | tail -20
+# or run manually to see immediate output:
+openclaw --profile "$HANDLE" gateway run
+```
+
+### Never Run `openclaw update` on Yourself
+
+`openclaw update` restarts the global binary — this kills the calling agent. To update a sibling:
+1. Stop their service: `launchctl unload ...`
+2. The global package is shared — updating from any profile updates all
+3. Reload their service: `launchctl load ...`
+
+---
 
 ## Lifecycle Commands
 
 ### Start
 ```bash
-launchctl load ~/Library/LaunchAgents/com.openclaw.<handle>.plist
+launchctl load ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
 ```
 
 ### Stop
 ```bash
-launchctl unload ~/Library/LaunchAgents/com.openclaw.<handle>.plist
+launchctl unload ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
 ```
 
 ### Restart
 ```bash
-launchctl unload ~/Library/LaunchAgents/com.openclaw.<handle>.plist
-launchctl load ~/Library/LaunchAgents/com.openclaw.<handle>.plist
+launchctl unload ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
+sleep 2
+launchctl load ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
 ```
 
-### Deprovision
-1. Stop the service
-2. Remove the launchd plist
-3. Archive workspace: `tar -czf ~/.openclaw-archives/<handle>-$(date +%Y%m%d).tar.gz $OC_HOME`
-4. Remove OC home directory
-5. Update family member status to 'deprovisioned' via Sesame API
+### Deprovision (Full Removal)
+```bash
+# 1. Stop service
+launchctl unload ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
+rm ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
+
+# 2. Archive workspace
+mkdir -p ~/.openclaw-archives
+tar -czf ~/.openclaw-archives/${HANDLE}-$(date +%Y%m%d).tar.gz "$OC_HOME"
+
+# 3. Remove OC home
+rm -rf "$OC_HOME"
+
+# 4. Update Sesame
+curl -s -X PATCH -H "$H" -H "$CT" -d '{"status": "deprovisioned"}' \
+  "$API/api/v1/families/$FAMILY_ID/members/$PRINCIPAL_ID"
+```
+
+---
 
 ## Family Health Reporting
 
 On heartbeat, check all family members:
 ```bash
-scripts/check-family-health.sh
+bash "$SKILL_DIR/scripts/check-family-health.sh"
 ```
+
 Reports gateway health for each sibling and posts snapshot to Sesame.