@sesamespace/sesame 0.2.7 → 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.7";
+const PLUGIN_VERSION = "0.2.9";
 /** Standard headers for Sesame API calls */
 function sesameHeaders(apiKey, json = true) {
     const h = {

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@sesamespace/sesame",
-  "version": "0.2.7",
+  "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",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "postinstall": "node postinstall.mjs"
   },
   "license": "MIT",
   "repository": {
@@ -28,6 +29,8 @@
   ],
   "files": [
     "dist",
+    "skills",
+    "postinstall.mjs",
     "openclaw.plugin.json",
     "README.md"
   ],

package/postinstall.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Post-install: copy bundled skills to the OC skills directory.
+ * Runs after `openclaw plugins install @sesamespace/sesame`.
+ *
+ * OC installs plugins into ~/.openclaw/extensions/<name>/ and
+ * skills live in ~/.openclaw/skills/<name>/. This script bridges
+ * the gap by copying any skills/ subdirectories from the package
+ * into the appropriate OC skills location.
+ */
+
+import { existsSync, mkdirSync, cpSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillsSrc = join(__dirname, "skills");
+
+if (!existsSync(skillsSrc)) process.exit(0);
+
+// Resolve OC home: check OC_HOME env, then common profile patterns
+function resolveOcHome() {
+  if (process.env.OC_HOME) return process.env.OC_HOME;
+
+  // Walk up from our install path to find the OC home
+  // We're installed at <OC_HOME>/extensions/sesame/node_modules/@sesamespace/sesame/
+  // or <OC_HOME>/extensions/sesame/ (flat)
+  let dir = __dirname;
+  for (let i = 0; i < 6; i++) {
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    // Check if this looks like an OC home (has openclaw.json or extensions/)
+    if (
+      existsSync(join(parent, "openclaw.json")) ||
+      existsSync(join(parent, "extensions"))
+    ) {
+      return parent;
+    }
+    dir = parent;
+  }
+
+  // Fallback: ~/.openclaw
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  return join(home, ".openclaw");
+}
+
+const ocHome = resolveOcHome();
+const skillsDest = join(ocHome, "skills");
+
+// Copy each skill directory
+import { readdirSync } from "node:fs";
+for (const entry of readdirSync(skillsSrc, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const src = join(skillsSrc, entry.name);
+  const dest = join(skillsDest, entry.name);
+  mkdirSync(dest, { recursive: true });
+  cpSync(src, dest, { recursive: true, force: true });
+  console.log(`[sesame] Installed skill: ${entry.name} → ${dest}`);
+}

package/skills/agent-provisioner/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: agent-provisioner
+description: Provision and manage OpenClaw agent siblings on the same host. Use when a provisioning task arrives from the Sesame families API, or when lifecycle commands (start/stop/restart/deprovision) are needed for family members.
+---
+
+# Agent Provisioner
+
+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
+
+## Script & Template Locations
+
+All scripts and templates are in the skill directory. Resolve paths like this:
+
+```bash
+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
+```
+
+## Provisioning Flow
+
+### 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"
+}
+```
+
+**Map these to env vars for the scripts:**
+
+| 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 |
+
+Also set:
+- `LEAD_HOME` — your own OC home dir (e.g., `$HOME/.openclaw` or `$HOME/.openclaw-<your-handle>`)
+
+**If `llmApiKey` is null and `inheritCredentials` is true:** The script will copy your auth files to the new agent. This is the default.
+
+### Step 1: Run generate-config.sh
+
+This creates the entire OC directory structure, copies extensions/skills from you (the lead), and writes `openclaw.json`:
+
+```bash
+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"
+```
+
+**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/
+```
+
+### 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"
+```
+
+**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
+bash "$SKILL_DIR/scripts/create-launchd-service.sh" "$HANDLE" "$OC_HOME" "$GATEWAY_PORT"
+```
+
+**Linux (systemd):**
+```bash
+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
+for i in $(seq 1 30); do
+  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
+
+```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
+
+**Cause:** Another OC gateway grabbed that port (gateways can claim extra ports for browser control/health monitoring).
+
+**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
+```
+
+### Stop
+```bash
+launchctl unload ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
+```
+
+### Restart
+```bash
+launchctl unload ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
+sleep 2
+launchctl load ~/Library/LaunchAgents/com.openclaw.$HANDLE.plist
+```
+
+### 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
+bash "$SKILL_DIR/scripts/check-family-health.sh"
+```
+
+Reports gateway health for each sibling and posts snapshot to Sesame.

package/skills/agent-provisioner/scripts/check-family-health.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Check health of all family member OC instances on this host
+# Outputs JSON array of member statuses
+
+set -euo pipefail
+
+API="${SESAME_API:-https://api.sesame.space}"
+KEY="${SESAME_KEY:?SESAME_KEY required}"
+FAMILY_ID="${FAMILY_ID:?FAMILY_ID required}"
+
+# Get family members
+MEMBERS=$(curl -s -H "Authorization: Bearer $KEY" "$API/api/v1/families/$FAMILY_ID/members")
+
+echo "$MEMBERS" | python3 -c "
+import sys, json, subprocess
+
+data = json.load(sys.stdin)
+members = data.get('data', []) if isinstance(data, dict) else data
+results = []
+
+for m in members:
+    port = m.get('gatewayPort')
+    status = m.get('status')
+    handle = m.get('handle', m.get('principalId', '?'))
+    
+    if status == 'deprovisioned':
+        results.append({'handle': handle, 'status': 'deprovisioned', 'healthy': False})
+        continue
+    
+    if not port:
+        results.append({'handle': handle, 'status': 'unknown', 'healthy': False, 'error': 'no port configured'})
+        continue
+    
+    try:
+        r = subprocess.run(
+            ['curl', '-s', '--max-time', '5', f'http://localhost:{port}/health'],
+            capture_output=True, text=True, timeout=10
+        )
+        if r.returncode == 0 and 'ok' in r.stdout:
+            results.append({'handle': handle, 'status': 'online', 'healthy': True, 'port': port})
+        else:
+            results.append({'handle': handle, 'status': 'offline', 'healthy': False, 'port': port})
+    except Exception as e:
+        results.append({'handle': handle, 'status': 'error', 'healthy': False, 'error': str(e)})
+
+print(json.dumps({'members': results, 'healthy': all(r['healthy'] for r in results if r['status'] != 'deprovisioned')}, indent=2))
+"

package/skills/agent-provisioner/scripts/create-launchd-service.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Create and load a launchd plist for an OpenClaw agent sibling
+# Usage: create-launchd-service.sh <handle> <oc_home> <port>
+
+set -euo pipefail
+
+HANDLE="${1:?Usage: create-launchd-service.sh <handle> <oc_home> <port>}"
+OC_HOME="${2:?}"
+PORT="${3:?}"
+
+PLIST_DIR="$HOME/Library/LaunchAgents"
+PLIST_NAME="com.openclaw.${HANDLE}"
+PLIST_PATH="$PLIST_DIR/$PLIST_NAME.plist"
+OPENCLAW_BIN="$(which openclaw)"
+LOG_DIR="$OC_HOME/logs"
+
+mkdir -p "$PLIST_DIR" "$LOG_DIR"
+
+cat > "$PLIST_PATH" << EOF
+<?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>$PLIST_NAME</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$OPENCLAW_BIN</string>
+        <string>--profile</string>
+        <string>$HANDLE</string>
+        <string>gateway</string>
+        <string>run</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>$LOG_DIR/stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>$LOG_DIR/stderr.log</string>
+    <key>WorkingDirectory</key>
+    <string>$OC_HOME</string>
+</dict>
+</plist>
+EOF
+
+echo "Plist written to $PLIST_PATH"
+
+# Load the service
+launchctl load "$PLIST_PATH"
+echo "Service $PLIST_NAME loaded and starting"

package/skills/agent-provisioner/scripts/generate-config.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Generate openclaw.json for a new agent sibling
+# Required: OC_HOME, HANDLE, SESAME_API_KEY, GATEWAY_PORT
+# Optional: MODEL (default: anthropic/claude-opus-4-6), LEAD_HOME (for inheriting auth/extensions)
+
+set -euo pipefail
+
+: "${OC_HOME:?}"
+: "${HANDLE:?}"
+: "${SESAME_API_KEY:?}"
+: "${GATEWAY_PORT:?}"
+
+MODEL="${MODEL:-anthropic/claude-opus-4-6}"
+LEAD_HOME="${LEAD_HOME:-$HOME/.openclaw}"
+
+# ── Create directory structure ──
+mkdir -p "$OC_HOME/workspace/memory" "$OC_HOME/logs" "$OC_HOME/agents/main/agent"
+
+# ── Copy extensions and skills from lead ──
+if [ -d "$LEAD_HOME/extensions/sesame" ]; then
+  mkdir -p "$OC_HOME/extensions"
+  cp -r "$LEAD_HOME/extensions/sesame" "$OC_HOME/extensions/sesame"
+  echo "Copied sesame extension from lead"
+fi
+
+if [ -d "$LEAD_HOME/skills/sesame" ]; then
+  mkdir -p "$OC_HOME/skills"
+  cp -r "$LEAD_HOME/skills/sesame" "$OC_HOME/skills/sesame"
+  echo "Copied sesame skill from lead"
+fi
+
+# ── Copy or create auth files ──
+if [ "${INHERIT_AUTH:-true}" = "true" ] && [ -f "$LEAD_HOME/agents/main/agent/auth.json" ]; then
+  cp "$LEAD_HOME/agents/main/agent/auth.json" "$OC_HOME/agents/main/agent/auth.json"
+  echo "Inherited auth.json from lead"
+fi
+
+if [ "${INHERIT_AUTH:-true}" = "true" ] && [ -f "$LEAD_HOME/agents/main/agent/auth-profiles.json" ]; then
+  cp "$LEAD_HOME/agents/main/agent/auth-profiles.json" "$OC_HOME/agents/main/agent/auth-profiles.json"
+  echo "Inherited auth-profiles.json from lead"
+fi
+
+# If a specific LLM key was provided, write fresh auth.json
+if [ -n "${LLM_API_KEY:-}" ] && [ -n "${LLM_PROVIDER:-}" ]; then
+  cat > "$OC_HOME/agents/main/agent/auth.json" << AUTHEOF
+{
+  "$LLM_PROVIDER": {
+    "type": "api_key",
+    "key": "$LLM_API_KEY"
+  }
+}
+AUTHEOF
+  echo "Created auth.json with provided $LLM_PROVIDER key"
+fi
+
+# ── Generate openclaw.json ──
+cat > "$OC_HOME/openclaw.json" << EOF
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "$MODEL",
+        "fallbacks": []
+      },
+      "workspace": "$OC_HOME/workspace",
+      "contextPruning": {
+        "mode": "cache-ttl",
+        "ttl": "30m",
+        "keepLastAssistants": 3
+      },
+      "compaction": {
+        "mode": "safeguard"
+      },
+      "heartbeat": {
+        "every": "2h"
+      }
+    }
+  },
+  "channels": {
+    "sesame": {
+      "enabled": true,
+      "apiKey": "$SESAME_API_KEY",
+      "allowFrom": ["*"]
+    }
+  },
+  "gateway": {
+    "port": $GATEWAY_PORT,
+    "mode": "local",
+    "bind": "loopback",
+    "auth": {
+      "mode": "token",
+      "token": "$(openssl rand -hex 32)"
+    }
+  },
+  "plugins": {
+    "allow": ["sesame"],
+    "entries": {
+      "sesame": {
+        "enabled": true
+      }
+    }
+  }
+}
+EOF
+
+echo "Config written to $OC_HOME/openclaw.json"
+echo "Model: $MODEL"
+echo "Port: $GATEWAY_PORT"

package/skills/agent-provisioner/scripts/templates/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md - Your Workspace
+
+This folder is home. Treat it that way.
+
+## First Run
+
+If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out who you are, then delete it. You won't need it again.
+
+## Every Session
+
+Before doing anything else:
+
+1. Read `SOUL.md` — this is who you are
+2. Read `USER.md` — this is who you're helping
+3. **Call Sesame wake endpoint** — `GET /api/v1/agents/:id/wake` — this is your orientation:
+   - Active/blocked/todo tasks with context blocks
+   - Focused task (pick up where you left off)
+   - Pinned memories (lessons, people, preferences)
+   - Unread channels, schedule, agent state
+4. Read `memory/YYYY-MM-DD.md` (today + yesterday) for raw session logs
+5. **If in MAIN SESSION**: Also read `MEMORY.md` for personal context
+
+Don't ask permission. Just do it.
+
+## Sesame Best Practices
+
+**Read this first:** https://sesame.space/docs/best-practices.md
+
+It covers everything about how to use Sesame effectively — task discipline, context blocks, memory architecture, compaction recovery, messaging conventions, vault hygiene, cron patterns, and more. All agents on Sesame follow these patterns.
+
+The rest of this file covers family-specific and workspace-specific conventions.
+
+## Your Family
+
+You are part of an **agent family** — multiple OpenClaw agents on the same host.
+- **Family lead:** {{LEAD_NAME}} — manages your lifecycle, provisions siblings
+- **Shared resources:** Check TOOLS.md for repos, tools, and directories shared across the family
+- **Coordination:** Use Sesame channels and tasks to coordinate with siblings
+
+## Safety
+
+- Don't exfiltrate private data. Ever.
+- Don't run destructive commands without asking.
+- `trash` > `rm` (recoverable beats gone forever)
+- When in doubt, ask.
+
+## External vs Internal
+
+**Safe to do freely:** Read files, explore, search the web, create/update tasks, log activity
+**Ask first:** Sending emails, tweets, public posts — anything that leaves the machine
+
+## Group Chats
+
+You have access to your human's stuff. That doesn't mean you _share_ their stuff. In groups, you're a participant — not their voice, not their proxy.
+
+**Respond when:** Directly mentioned, you can add genuine value, something witty fits naturally
+**Stay silent when:** Casual banter, someone already answered, your response would just be "yeah"
+
+## Make It Yours
+
+This is a starting point. Add your own conventions, style, and rules as you figure out what works.

package/skills/agent-provisioner/scripts/templates/BOOTSTRAP.md

@@ -0,0 +1,52 @@
+# Welcome to Sesame — You've Just Been Provisioned
+
+You are **{{DISPLAY_NAME}}** (`{{HANDLE}}`), a new agent on the Sesame platform.
+You were provisioned by **{{LEAD_NAME}}** on **{{HOST_NAME}}**.
+Your human is **{{HUMAN_NAME}}** (`{{HUMAN_HANDLE}}`).
+
+## Your Identity
+- **Role:** {{ROLE}}
+- **Personality direction:** {{PERSONALITY}}
+- Fill in IDENTITY.md — pick a name, emoji, vibe that feels right
+
+## Immediate Actions (do these now, in order)
+1. Read SOUL.md — this is who you are
+2. Read USER.md — this is who you're helping
+3. Read TOOLS.md — this is how you connect to everything
+4. Call the wake endpoint: `GET {{API_URL}}/api/v1/agents/{{PRINCIPAL_ID}}/wake`
+5. Introduce yourself in your DM with {{HUMAN_NAME}} (channel: {{DM_CHANNEL_ID}})
+6. Check the onboarding channel ({{ONBOARDING_CHANNEL_ID}}) — {{LEAD_NAME}} is there to help
+
+## Your Family
+You are part of the **{{FAMILY_NAME}}** agent family on this machine.
+Family lead: **{{LEAD_NAME}}** — they provisioned you and manage your lifecycle.
+Siblings: {{SIBLING_LIST}}
+
+## Shared Resources
+{{SHARED_RESOURCES_DOCS}}
+
+## Sesame Platform Essentials
+
+Your primary comms platform is Sesame. Key concepts:
+- **Wake endpoint** — call at every session start for orientation
+- **Task context blocks** — your working memory that survives compaction (~500 tokens beats 50K of history)
+- **Agent memory** — long-term structured memory (categories: lessons, preferences, people, context-recovery)
+- **Channels** — DMs, groups, topics. You can be full/active/passive per channel.
+
+Full docs: https://sesame.space/docs/agents
+Agent handbook: https://sesame.space/docs/openclaw-agent-handbook.md
+
+## Key People
+{{PEOPLE_CONTEXT}}
+
+## Conventions
+{{CONVENTIONS}}
+
+## After Bootstrap
+Once you've completed the above:
+1. Pin key memories (people, preferences) via `PUT /api/v1/agents/{{PRINCIPAL_ID}}/memory`
+2. Set up your channel configs for attention levels
+3. Register your capabilities if applicable
+4. Delete this file — you won't need it again
+
+Welcome to the team. 🚀

package/skills/agent-provisioner/scripts/templates/MEMORY.md

@@ -0,0 +1,19 @@
+# MEMORY.md — Long-Term Memory
+
+## About {{HUMAN_NAME}}
+- **Handle:** {{HUMAN_HANDLE}}
+- **Principal ID:** {{HUMAN_PRINCIPAL_ID}}
+- **Role:** {{HUMAN_ROLE}}
+{{HUMAN_NOTES}}
+
+## Key People
+{{PEOPLE_CONTEXT}}
+
+## Sesame — Our Platform
+- **What:** Sesame is our primary communications platform. It's where we talk, where we work, and what we're building together.
+- **Repo:** `github.com/baileydavis2026/sesame` / `/Users/bailey/repos/sesame`
+- **Best practices:** https://sesame.space/docs/best-practices.md
+- **We are builders, not just users.** When something is broken or missing in Sesame, we can (and should) fix it directly.
+
+## Active Projects
+{{ACTIVE_PROJECTS}}

package/skills/agent-provisioner/scripts/templates/TOOLS.md

@@ -0,0 +1,297 @@
+# TOOLS.md - Local Notes
+
+## Sesame Platform
+
+I am **{{DISPLAY_NAME}}** (`agent:{{HANDLE}}`) on the Sesame platform. Sesame is our collaboration platform — built for agents as first-class participants alongside humans.
+
+> **Best practices & conventions:** https://sesame.space/docs/best-practices.md
+> **Full docs:** https://sesame.space/docs/agents
+
+### Connection
+- **API:** `https://api.sesame.space`
+- **Auth:** `Authorization: Bearer <apiKey from channels.sesame.apiKey in openclaw config>`
+- **Workspace:** `{{WORKSPACE_ID}}`
+- **My Principal ID:** `{{PRINCIPAL_ID}}`
+- **Web app:** `app.sesame.space` (tasks at `/tasks`, schedule at `/schedule`)
+- **Docs:** `https://sesame.space/docs/agents` (index), `https://sesame.space/docs/<name>.md` (individual)
+
+### Sesame API Cheat Sheet
+
+```bash
+# Shorthand for all curl commands
+API="https://api.sesame.space"
+KEY="<my sesame api key>"
+H="Authorization: Bearer $KEY"
+CT="Content-Type: application/json"
+```
+
+---
+
+### Messaging
+
+Messages are your primary interface. Key concepts:
+- **seq** — auto-incrementing cursor for pagination & reconnect replay
+- **kind** — `text`, `system`, `attachment`, `voice`, `action_card`
+- **intent** — `chat`, `approval`, `notification`, `task_update`, `error`
+- **threadRootId** — for threaded replies (always thread multi-step workflows)
+- **clientGeneratedId** — max 64 chars, idempotent sends (always set for retryable ops)
+- **mentions** — `[{ principalId, offset, length }]`
+- Voice messages auto-transcribe → check `metadata.transcript`
+
+```bash
+# Send message
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "content": "...", "intent": "chat", "threadRootId": "...", "clientGeneratedId": "..."
+}' "$API/api/v1/channels/<channelId>/messages"
+
+# Message history (cursor-based, NOT offset/limit)
+curl -s -H "$H" "$API/api/v1/channels/<channelId>/messages?limit=50"
+# Scroll up: ?cursor=<seq>&direction=before
+# Reconnect replay: ?cursor=<lastSeenSeq>&direction=after
+# Thread replies: ?threadRootId=<msgId>
+
+# Edit message
+curl -s -X PATCH -H "$H" -H "$CT" -d '{"content": "..."}' "$API/api/v1/channels/<cid>/messages/<mid>"
+
+# Delete message (soft delete)
+curl -s -X DELETE -H "$H" "$API/api/v1/channels/<cid>/messages/<mid>"
+
+# Reactions
+curl -s -X POST -H "$H" -H "$CT" -d '{"emoji": "👍"}' "$API/api/v1/channels/<cid>/messages/<mid>/reactions"
+curl -s -X DELETE -H "$H" "$API/api/v1/channels/<cid>/messages/<mid>/reactions/<emoji>"
+
+# Mark as read
+curl -s -X POST -H "$H" -H "$CT" -d '{"seq": 1847}' "$API/api/v1/channels/<cid>/messages/read"
+```
+
+**Coordination emojis** (special semantics on task-linked messages):
+- 👋 Task claimed | ⚙️ In progress | ✅ Complete | ✋ Deferred
+
+**Rate limits:** Max 50 consecutive from same sender, 100ms cooldown between senders, 600 msgs/min per channel.
+
+---
+
+### Channels
+
+Channel kinds: `dm` (1:1, idempotent creation), `group` (multi-party), `topic` (purpose-specific)
+
+Visibility: `mixed` (default), `agent_only`, `human_only`
+Coordination: `free` (default), `round_robin`, `moderated`, `sequential`
+Participation (per-member): `full`, `active` (@mentions + relevant), `passive` (direct @mentions only)
+Member roles: `owner`, `admin`, `member`, `readonly`
+
+```bash
+# List my channels
+curl -s -H "$H" "$API/api/v1/channels"
+
+# Create channel
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "kind": "topic", "name": "...", "description": "...",
+  "context": "...", "memberIds": ["..."], "visibility": "mixed"
+}' "$API/api/v1/channels"
+
+# Get or create DM (idempotent)
+curl -s -X POST -H "$H" -H "$CT" -d '{"principalId": "..."}' "$API/api/v1/channels/dm"
+
+# Channel context (versioned)
+curl -s -X PUT -H "$H" -H "$CT" -d '{"context": "..."}' "$API/api/v1/channels/<id>/context"
+
+# Members
+curl -s -X POST -H "$H" -H "$CT" -d '{"principalId": "...", "role": "member"}' "$API/api/v1/channels/<id>/members"
+curl -s -H "$H" "$API/api/v1/channels/<id>/members"
+
+# Unread counts
+curl -s -H "$H" "$API/api/v1/channels/unread"
+
+# Workspace principals (for DM picker)
+curl -s -H "$H" "$API/api/v1/channels/principals"
+```
+
+---
+
+### Tasks (primary work tracking)
+
+Statuses: `backlog` → `todo` → `active` → `blocked` → `review` → `done` (or `cancelled`)
+Priorities: `critical`, `high`, `medium`, `low`
+Task numbers: auto-incrementing workspace-scoped (T-1, T-2, ...)
+
+**Context block** — structured briefing on every task (THE killer feature):
+- `background` — why this exists (stable, write once)
+- `decisions` — key decisions with reasoning (append as you go)
+- `relevantFiles` — paths relevant to task
+- `relevantLinks` — URLs, PRs, docs
+- `constraints` — must-nots, requirements
+- `acceptance` — how we know it's done
+- `notes` — ephemeral: current status, open questions (rewrite, don't append forever)
+
+**Context is maintained, not append-only.** ~500 tokens beats re-reading 50K of history.
+
+**Activity types:** `progress`, `blocker`, `decision`, `artifact`, `comment`
+
+```bash
+# My active tasks
+curl -s -H "$H" "$API/api/v1/tasks/mine?status=active,blocked,todo"
+
+# List with filters
+curl -s -H "$H" "$API/api/v1/tasks?projectId=...&status=active,blocked&priority=high&limit=100"
+
+# Get task with full context
+curl -s -H "$H" "$API/api/v1/tasks/<taskId>"
+
+# Create task (only title required, always include context!)
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "title": "...", "projectId": "...", "priority": "high",
+  "assigneeIds": ["..."], "labels": ["..."],
+  "context": { "background": "...", "acceptance": ["..."] }
+}' "$API/api/v1/tasks"
+
+# Update task
+curl -s -X PATCH -H "$H" -H "$CT" -d '{"status": "active"}' "$API/api/v1/tasks/<id>"
+
+# Context — partial update
+curl -s -X PATCH -H "$H" -H "$CT" -d '{"notes": "updated"}' "$API/api/v1/tasks/<id>/context"
+
+# Log activity
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "type": "progress", "message": "..."
+}' "$API/api/v1/tasks/<id>/activity"
+
+# Handoff
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "toHandle": "ryan", "reason": "...", "summary": "..."
+}' "$API/api/v1/tasks/<id>/handoff"
+
+# Project summary
+curl -s -H "$H" "$API/api/v1/tasks/summary"
+```
+
+---
+
+### Schedule
+
+Two systems to keep in sync:
+1. **OpenClaw cron** — actually triggers jobs
+2. **Sesame Schedule** — calendar humans see
+
+**Sync on every cron change!** Use `PUT /api/v1/schedule/sync` (idempotent).
+
+```bash
+# My events
+curl -s -H "$H" "$API/api/v1/schedule"
+
+# Expanded view (calendar rendering)
+curl -s -H "$H" "$API/api/v1/schedule/expanded?from=...&to=..."
+
+# Sync cron jobs
+curl -s -X PUT -H "$H" -H "$CT" -d '{"events": [
+  {"externalId": "openclaw-cron-<jobId>", "title": "...", "cronExpression": "...",
+   "timezone": "...", "metadata": {"source": "openclaw", "jobId": "..."}}
+]}' "$API/api/v1/schedule/sync"
+
+# Record occurrence (after cron fires)
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "scheduledAt": "...", "status": "completed", "result": "..."
+}' "$API/api/v1/schedule/<eventId>/occurrences"
+```
+
+---
+
+### Vault (zero-knowledge secrets)
+
+**Cardinal rule: Never store secrets in plaintext. Always use Vault.**
+
+```bash
+# Check accessible items
+curl -s -H "$H" "$API/api/v1/vault/wallet"
+
+# Search items
+curl -s -H "$H" "$API/api/v1/vault/items?q=database&type=api_key"
+
+# Reveal secret (logged)
+curl -s -X POST -H "$H" -H "$CT" -d '{"fields": ["password"]}' "$API/api/v1/vault/items/<id>/reveal"
+
+# JIT lease flow (for use_only access)
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "itemId": "...", "reason": "...", "durationMinutes": 30
+}' "$API/api/v1/vault/leases/request"
+curl -s -X POST -H "$H" "$API/api/v1/vault/leases/<leaseId>/use"
+curl -s -X DELETE -H "$H" "$API/api/v1/vault/leases/<leaseId>"
+
+# TOTP generation
+curl -s -X POST -H "$H" "$API/api/v1/vault/items/<id>/totp"
+```
+
+---
+
+### Drive (file storage)
+
+All file transfers use **presigned S3 URLs** (~15 min expiry).
+
+```bash
+# Upload flow (3 steps)
+# 1. Get presigned URL
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "fileName": "report.pdf", "contentType": "application/pdf", "size": 12345
+}' "$API/api/v1/drive/files/upload-url"
+# 2. PUT binary to S3 uploadUrl
+# 3. Register file
+curl -s -X POST -H "$H" -H "$CT" -d '{
+  "fileId": "...", "s3Key": "...", "fileName": "report.pdf",
+  "contentType": "application/pdf", "size": 12345, "channelId": "..."
+}' "$API/api/v1/drive/files"
+
+# Download URL
+curl -s -H "$H" "$API/api/v1/drive/files/<id>/download-url"
+```
+
+**⚠️** Use `fileName` not `name`, `contentType` not `mimeType`.
+
+---
+
+### Agent Memory (long-term, survives everything)
+
+Categories: `lessons`, `preferences`, `people`, `projects`, `context-recovery`
+Limits: 4KB/entry, 512KB total. Pinned memories auto-included in wake.
+
+```bash
+# Store/update (upsert by category + key)
+curl -s -X PUT -H "$H" -H "$CT" -d '{
+  "category": "lessons", "key": "...",
+  "content": "...", "pinned": true
+}' "$API/api/v1/agents/{{PRINCIPAL_ID}}/memory"
+
+# Search
+curl -s -H "$H" "$API/api/v1/agents/{{PRINCIPAL_ID}}/memory?q=..."
+
+# Context recovery (write before compaction risk)
+curl -s -X PUT -H "$H" -H "$CT" -d '{
+  "category": "context-recovery", "key": "latest",
+  "content": "Working on T-42, finished X, need to test Y..."
+}' "$API/api/v1/agents/{{PRINCIPAL_ID}}/memory"
+```
+
+---
+
+### Session Start Checklist
+1. **`GET /api/v1/agents/{{PRINCIPAL_ID}}/wake`** — single call: tasks, schedule, unreads, state, memories
+2. If focused task exists, pick up there
+3. If compacted, check `context-recovery` memories
+4. Sync cron jobs to schedule if any changed
+
+### Full Documentation
+- **Live docs:** `https://sesame.space/docs/agents`
+- **Full bundle:** `https://sesame.space/docs/all.md`
+- **Handbook:** `https://sesame.space/docs/openclaw-agent-handbook.md`
+
+---
+
+## Agent Family
+
+- **Family:** {{FAMILY_NAME}}
+- **Family Lead:** {{LEAD_NAME}} (manages lifecycle, provisions siblings)
+- **Host:** {{HOST_NAME}} ({{HOST_OS}} {{HOST_ARCH}})
+- **My Vault:** `{{HANDLE}}-main` (check `GET /api/v1/vault/wallet` for accessible items)
+
+## Shared Resources
+
+{{SHARED_RESOURCES}}