@sesamespace/sesame 0.2.7 → 0.2.8

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.8";
 /** 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.8",
   "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,155 @@
+---
+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.
+
+## 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:
+
+- **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
+
+```bash
+OC_HOME="$HOME/.openclaw-<handle>"
+mkdir -p "$OC_HOME/workspace" "$OC_HOME/workspace/memory"
+```
+
+### Step 2: Generate openclaw.json
+
+Run the script: `scripts/generate-config.sh`
+
+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
+
+### Step 3: Scaffold Workspace
+
+Write these files into `$OC_HOME/workspace/`:
+
+- **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
+
+### Step 3b: Create Agent Vault
+
+Create a personal vault for the new agent to store credentials securely.
+
+```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
+
+# 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"
+
+# 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"
+```
+
+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.
+
+### Step 4: Create and Start Service
+
+**macOS (launchd):**
+```bash
+scripts/create-launchd-service.sh "$HANDLE" "$OC_HOME" "$GATEWAY_PORT"
+```
+
+**Linux (systemd):**
+```bash
+scripts/create-systemd-service.sh "$HANDLE" "$OC_HOME" "$GATEWAY_PORT"
+```
+
+### Step 5: Verify Health
+
+```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
+done
+```
+
+### 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
+
+### Rollback on Failure
+
+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
+
+## 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
+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
+
+## Family Health Reporting
+
+On heartbeat, check all family members:
+```bash
+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}}