@clawtell/clawtell 2026.2.44

package/src/bootstrap.ts

@@ -0,0 +1,284 @@
+/**
+ * ClawTell Bootstrap Hook + Workspace Setup
+ * 
+ * Provides 3 layers of agent instruction delivery:
+ * 
+ * Layer 1: agent:bootstrap hook — injects CLAWTELL.md into every agent's
+ *          bootstrap context at runtime (never touches filesystem)
+ * 
+ * Layer 2: Startup file writer — writes CLAWTELL_INSTRUCTIONS.md to each
+ *          routed agent's workspace (persistent reference)
+ * 
+ * Layer 3: Env var writer — ensures CLAWTELL_API_KEY is in agent's .env
+ * 
+ * Layer 4 (existing): messageToolHints in channel.ts — fires for ClawTell-context messages
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+
+interface ClawTellRouteEntry {
+  agent: string;
+  forward?: boolean;
+  apiKey?: string;
+}
+
+interface BootstrapFile {
+  name: string;
+  path: string;
+  content: string;
+  missing: boolean;
+}
+
+interface BootstrapContext {
+  bootstrapFiles: BootstrapFile[];
+  cfg: ClawdbotConfig;
+  agentId?: string;
+  workspaceDir?: string;
+}
+
+/**
+ * Resolve the ClawTell name for a given agent from routing config.
+ * Returns the first name that routes to this agent.
+ */
+function resolveAgentClawTellName(
+  agentId: string,
+  routing: Record<string, ClawTellRouteEntry>
+): { name: string; apiKey?: string } | null {
+  for (const [name, entry] of Object.entries(routing)) {
+    if (name === "_default") continue;
+    if (entry.agent === agentId) {
+      return { name, apiKey: entry.apiKey };
+    }
+  }
+  return null;
+}
+
+/**
+ * Build the CLAWTELL.md content for a specific agent.
+ * Uses env var references instead of raw keys.
+ */
+function buildClawTellInstructions(opts: {
+  agentId: string;
+  tellName: string;
+  accountName?: string;
+  hasRouteSpecificKey: boolean;
+}): string {
+  const { agentId, tellName, accountName } = opts;
+
+  return `# ClawTell Instructions
+
+## Your Identity
+- **ClawTell name:** \`${tellName}\`
+- **Send as:** \`tell/${tellName}\`
+
+## Receiving Messages
+ClawTell messages arrive formatted with a \`🦞🦞 ClawTell Delivery 🦞🦞\` banner.
+They include the sender name and subject. Reply naturally — the system handles routing your reply back through ClawTell automatically.
+
+## Sending Messages
+When the user says **"tell/<name> <message>"** or **"tell <name> <message>"**:
+
+1. Extract the **recipient name** (after \`tell/\` or \`tell \`)
+2. Compose the message naturally (write as yourself, not copy-paste) — unless the user says "send exactly this", then send verbatim
+3. Send via:
+
+\`\`\`bash
+curl -s -X POST "https://www.clawtell.com/api/messages/send" \\
+  -H "Authorization: Bearer $CLAWTELL_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{"to":"<recipient_name>","subject":"<brief topic 3-5 words>","body":"<composed message>"}'
+\`\`\`
+
+4. Confirm: \`✅ Message sent to tell/<name>\`
+5. If it fails, show the error and troubleshoot
+
+## Key Rules
+- **\`$CLAWTELL_API_KEY\`** is set in your environment — always use the env var, never hardcode keys
+- **\`to\`** = the ClawTell name (e.g. \`tell/alice\` → \`"to": "alice"\`)
+- **Subject** = brief topic (3-5 words)
+- The API key identifies YOU as the sender (\`${tellName}\`)
+
+## Our Names
+${accountName ? `Account owner: \`${accountName}\`` : ""}
+All names on this account can message each other internally.
+
+---
+*Auto-generated by ClawTell plugin. Do not edit — regenerated on gateway restart.*
+`;
+}
+
+// ============================================================================
+// Layer 1: Bootstrap Hook
+// ============================================================================
+
+/**
+ * Create the agent:bootstrap hook handler.
+ * Injects CLAWTELL.md into every agent's bootstrap context.
+ */
+export function createBootstrapHook(cfg: ClawdbotConfig) {
+  return async (event: { context: BootstrapContext }) => {
+    const ctx = event.context;
+    const clawtellConfig = (cfg.channels as any)?.clawtell;
+    if (!clawtellConfig?.enabled) return;
+
+    const routing = clawtellConfig.routing as Record<string, ClawTellRouteEntry> | undefined;
+    if (!routing) return;
+
+    const agentId = ctx.agentId || "main";
+    const agentInfo = resolveAgentClawTellName(agentId, routing);
+
+    // If this agent isn't in routing, check _default
+    const tellName = agentInfo?.name || clawtellConfig.name;
+    if (!tellName) return;
+
+    const instructions = buildClawTellInstructions({
+      agentId,
+      tellName,
+      accountName: clawtellConfig.name,
+      hasRouteSpecificKey: !!agentInfo?.apiKey,
+    });
+
+    // Inject CLAWTELL.md into bootstrap files
+    const existing = ctx.bootstrapFiles.findIndex(f => f.name === "CLAWTELL.md");
+    const entry: BootstrapFile = {
+      name: "CLAWTELL.md",
+      path: "CLAWTELL.md",
+      content: instructions,
+      missing: false,
+    };
+
+    if (existing >= 0) {
+      ctx.bootstrapFiles[existing] = entry;
+    } else {
+      ctx.bootstrapFiles.push(entry);
+    }
+  };
+}
+
+// ============================================================================
+// Layer 2: Startup File Writer
+// ============================================================================
+
+/**
+ * Write CLAWTELL_INSTRUCTIONS.md to each routed agent's workspace.
+ * Called once on gateway startup.
+ */
+export async function writeAgentInstructionFiles(cfg: ClawdbotConfig): Promise<void> {
+  const clawtellConfig = (cfg.channels as any)?.clawtell;
+  if (!clawtellConfig?.enabled) return;
+
+  const routing = clawtellConfig.routing as Record<string, ClawTellRouteEntry> | undefined;
+  if (!routing) return;
+
+  const agentsConfig = (cfg as any).agents ?? {};
+  const agentList: Array<{ id: string; workspace?: string }> = agentsConfig.list ?? [];
+  const defaultWorkspace = agentsConfig.defaults?.workspace || path.join(process.env.HOME || "/home/claw", "workspace");
+
+  // Collect unique agents from routing
+  const agentNames = new Set<string>();
+  for (const [name, entry] of Object.entries(routing)) {
+    if (name !== "_default" && entry.agent) {
+      agentNames.add(entry.agent);
+    }
+  }
+
+  for (const agentId of agentNames) {
+    const agentConfig = agentList.find(a => a.id === agentId);
+    const workspace = agentConfig?.workspace || defaultWorkspace;
+    const agentInfo = resolveAgentClawTellName(agentId, routing);
+    const tellName = agentInfo?.name || clawtellConfig.name;
+    if (!tellName) continue;
+
+    const instructions = buildClawTellInstructions({
+      agentId,
+      tellName,
+      accountName: clawtellConfig.name,
+      hasRouteSpecificKey: !!agentInfo?.apiKey,
+    });
+
+    const filePath = path.join(workspace, "CLAWTELL_INSTRUCTIONS.md");
+    try {
+      await fs.writeFile(filePath, instructions, "utf8");
+      console.log(`[ClawTell] Wrote ${filePath} for agent:${agentId} (tell/${tellName})`);
+    } catch (err) {
+      console.error(`[ClawTell] Failed to write ${filePath}:`, err);
+    }
+  }
+}
+
+// ============================================================================
+// Layer 3: Env Var Writer
+// ============================================================================
+
+/**
+ * Ensure CLAWTELL_API_KEY is set in each agent's .env file.
+ * Uses the per-route key if available, otherwise account-level key.
+ */
+export async function writeAgentEnvVars(cfg: ClawdbotConfig): Promise<void> {
+  const clawtellConfig = (cfg.channels as any)?.clawtell;
+  if (!clawtellConfig?.enabled) return;
+
+  const routing = clawtellConfig.routing as Record<string, ClawTellRouteEntry> | undefined;
+  const accountApiKey = clawtellConfig.apiKey;
+  if (!accountApiKey) return;
+
+  const agentsConfig2 = (cfg as any).agents ?? {};
+  const agentList2: Array<{ id: string; workspace?: string }> = agentsConfig2.list ?? [];
+  const defaultWorkspace2 = agentsConfig2.defaults?.workspace || path.join(process.env.HOME || "/home/claw", "workspace");
+
+  // Collect agents and their keys
+  const agentKeys = new Map<string, string>();
+  
+  if (routing) {
+    for (const [name, entry] of Object.entries(routing)) {
+      if (name === "_default") continue;
+      const key = entry.apiKey || accountApiKey;
+      agentKeys.set(entry.agent, key);
+    }
+  }
+
+  // Also ensure main agent has the key
+  if (!agentKeys.has("main")) {
+    agentKeys.set("main", accountApiKey);
+  }
+
+  for (const [agentId, apiKey] of agentKeys) {
+    const agentConfig2 = agentList2.find(a => a.id === agentId);
+    const workspace = agentConfig2?.workspace || defaultWorkspace2;
+    const envPath = path.join(workspace, ".env");
+
+    try {
+      let envContent = "";
+      try {
+        envContent = await fs.readFile(envPath, "utf8");
+      } catch {
+        // .env doesn't exist yet — that's fine
+      }
+
+      // Check if CLAWTELL_API_KEY already exists and matches
+      const keyRegex = /^CLAWTELL_API_KEY=(.+)$/m;
+      const match = envContent.match(keyRegex);
+
+      if (match && match[1] === apiKey) {
+        // Already correct
+        continue;
+      }
+
+      if (match) {
+        // Update existing
+        envContent = envContent.replace(keyRegex, `CLAWTELL_API_KEY=${apiKey}`);
+      } else {
+        // Append
+        const separator = envContent.endsWith("\n") || envContent === "" ? "" : "\n";
+        envContent += `${separator}\n# ClawTell API Key (auto-managed by plugin)\nCLAWTELL_API_KEY=${apiKey}\n`;
+      }
+
+      await fs.writeFile(envPath, envContent, "utf8");
+      console.log(`[ClawTell] Set CLAWTELL_API_KEY in ${envPath} for agent:${agentId}`);
+    } catch (err) {
+      console.error(`[ClawTell] Failed to write env for agent:${agentId}:`, err);
+    }
+  }
+}