bloby-bot 0.25.1 → 0.25.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.25.1",
+  "version": "0.25.4",
   "releaseNotes": [
     "1. new stuff",
     "2. ",

package/supervisor/agent-api.ts

@@ -0,0 +1,224 @@
+/**
+ * Agent API — exposes the Claude Agent SDK to workspace code.
+ *
+ * Single endpoint: POST /api/agent/query
+ *
+ * If `systemPromptPath` is provided → read it from workspace, use as systemPrompt.
+ * If omitted → use the `claude_code` preset (built-in Claude Code tools + prompt).
+ *
+ * Supports session persistence via `sessionId` (pass the one returned from a previous call).
+ *
+ * Auth: per-session secret injected into the workspace backend as BLOBY_AGENT_SECRET.
+ * Safety: localhost-only, path traversal prevention, concurrency + rate limits, timeouts.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { WORKSPACE_DIR } from '../shared/paths.js';
+import { log } from '../shared/logger.js';
+import { getClaudeAccessToken } from '../worker/claude-auth.js';
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface AgentQueryRequest {
+  message: string;
+  systemPromptPath?: string;    // relative to workspace, e.g. "skills/my-skill/prompt.txt"
+  sessionId?: string;           // resume a previous session
+  maxTurns?: number;            // default 25, max 50
+  timeout?: number;             // ms, default 120_000, max 300_000
+}
+
+export interface AgentQueryResponse {
+  ok: boolean;
+  response?: string;
+  sessionId?: string;
+  toolsUsed?: string[];
+  usedFileTools?: boolean;
+  error?: string;
+}
+
+// ── Concurrency & Rate Limiting ────────────────────────────────────────────
+
+const MAX_CONCURRENT = 3;
+const RATE_LIMIT_WINDOW = 60_000; // 1 minute
+const RATE_LIMIT_MAX = 10;
+
+let activeQueries = 0;
+const requestTimestamps: number[] = [];
+
+function checkRateLimit(): string | null {
+  // Concurrency check
+  if (activeQueries >= MAX_CONCURRENT) {
+    return `Too many concurrent queries (max ${MAX_CONCURRENT}). Try again shortly.`;
+  }
+
+  // Rate limit check
+  const now = Date.now();
+  // Prune old timestamps
+  while (requestTimestamps.length && requestTimestamps[0]! < now - RATE_LIMIT_WINDOW) {
+    requestTimestamps.shift();
+  }
+  if (requestTimestamps.length >= RATE_LIMIT_MAX) {
+    return `Rate limit exceeded (max ${RATE_LIMIT_MAX} requests per minute).`;
+  }
+
+  return null;
+}
+
+// ── Path Validation ────────────────────────────────────────────────────────
+
+function resolveSystemPromptPath(relPath: string): { path: string } | { error: string } {
+  const resolved = path.resolve(WORKSPACE_DIR, relPath);
+  const workspaceBoundary = WORKSPACE_DIR + path.sep;
+
+  // Must be inside workspace (not parent traversal)
+  if (!resolved.startsWith(workspaceBoundary) && resolved !== WORKSPACE_DIR) {
+    return { error: 'System prompt path must be within the workspace directory.' };
+  }
+
+  if (!fs.existsSync(resolved)) {
+    return { error: `System prompt file not found: ${relPath}` };
+  }
+
+  return { path: resolved };
+}
+
+// ── Main Query Handler ─────────────────────────────────────────────────────
+
+export async function handleAgentQuery(req: AgentQueryRequest): Promise<AgentQueryResponse> {
+  // ── Validate inputs ──
+  if (!req.message || typeof req.message !== 'string') {
+    return { ok: false, error: 'Missing or invalid "message" field.' };
+  }
+
+  const maxTurns = Math.min(Math.max(req.maxTurns || 25, 1), 50);
+  const timeout = Math.min(Math.max(req.timeout || 120_000, 5_000), 300_000);
+
+  // ── Rate limit ──
+  const rateLimitError = checkRateLimit();
+  if (rateLimitError) {
+    return { ok: false, error: rateLimitError };
+  }
+
+  // ── Resolve system prompt ──
+  let systemPrompt: string | { type: 'preset'; preset: 'claude_code' };
+
+  if (req.systemPromptPath) {
+    const result = resolveSystemPromptPath(req.systemPromptPath);
+    if ('error' in result) {
+      return { ok: false, error: result.error };
+    }
+    try {
+      const content = fs.readFileSync(result.path, 'utf-8').trim();
+      if (!content) {
+        return { ok: false, error: 'System prompt file is empty.' };
+      }
+      systemPrompt = content;
+    } catch (err: any) {
+      return { ok: false, error: `Failed to read system prompt: ${err.message}` };
+    }
+  } else {
+    systemPrompt = { type: 'preset', preset: 'claude_code' };
+  }
+
+  // ── OAuth token ──
+  const oauthToken = await getClaudeAccessToken();
+  if (!oauthToken) {
+    return { ok: false, error: 'Claude OAuth token not found. Please authenticate via the dashboard.' };
+  }
+
+  // ── Execute query ──
+  activeQueries++;
+  requestTimestamps.push(Date.now());
+
+  const abortController = new AbortController();
+  const timeoutHandle = setTimeout(() => abortController.abort(), timeout);
+
+  let fullText = '';
+  const usedTools = new Set<string>();
+  let sessionId: string | undefined;
+  let stderrBuf = '';
+
+  try {
+    log.info(`[agent-api] Query: msg="${req.message.slice(0, 80)}..." maxTurns=${maxTurns} timeout=${timeout}ms resume=${req.sessionId || 'none'}`);
+
+    const claudeQuery = query({
+      prompt: req.message,
+      options: {
+        cwd: WORKSPACE_DIR,
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        maxTurns,
+        abortController,
+        systemPrompt: systemPrompt as any,
+        ...(req.sessionId ? { resume: req.sessionId } : {}),
+        stderr: (chunk: string) => { stderrBuf += chunk; },
+        env: {
+          ...process.env as Record<string, string>,
+          CLAUDE_CODE_OAUTH_TOKEN: oauthToken,
+          CLAUDE_CODE_BUBBLEWRAP: '1',
+        },
+      },
+    });
+
+    for await (const msg of claudeQuery) {
+      if (abortController.signal.aborted) break;
+
+      switch (msg.type) {
+        case 'assistant': {
+          const assistantMsg = (msg as any).message;
+          if (!assistantMsg?.content) break;
+          for (const block of assistantMsg.content) {
+            if (block.type === 'text' && block.text) {
+              if (fullText && !fullText.endsWith('\n')) fullText += '\n\n';
+              fullText += block.text;
+            } else if (block.type === 'tool_use') {
+              usedTools.add(block.name);
+            }
+          }
+          break;
+        }
+        case 'result': {
+          // Extract session_id from result for persistence
+          sessionId = (msg as any).session_id;
+
+          if (!fullText && (msg as any).subtype?.startsWith('error')) {
+            const errors = (msg as any).errors?.join('; ') || 'Agent query failed';
+            return {
+              ok: false,
+              error: errors,
+              sessionId,
+              toolsUsed: Array.from(usedTools),
+            };
+          }
+          break;
+        }
+      }
+    }
+
+    const FILE_TOOLS = ['Write', 'Edit'];
+    const usedFileTools = FILE_TOOLS.some((t) => usedTools.has(t));
+
+    log.info(`[agent-api] Done: ${fullText.length} chars, tools=[${Array.from(usedTools).join(',')}], session=${sessionId || 'unknown'}`);
+
+    return {
+      ok: true,
+      response: fullText,
+      sessionId,
+      toolsUsed: Array.from(usedTools),
+      usedFileTools,
+    };
+  } catch (err: any) {
+    if (abortController.signal.aborted) {
+      return { ok: false, error: 'Query timed out.', sessionId };
+    }
+    const detail = stderrBuf.trim();
+    const errMsg = detail ? `${err.message}\n\n${detail}` : err.message;
+    log.warn(`[agent-api] Error: ${errMsg}`);
+    return { ok: false, error: errMsg, sessionId };
+  } finally {
+    clearTimeout(timeoutHandle);
+    activeQueries--;
+  }
+}

package/supervisor/backend.ts

@@ -11,6 +11,14 @@ let intentionallyStopped = false;
 const MAX_RESTARTS = 3;
 const STABLE_THRESHOLD = 30_000; // 30s — if backend ran this long, it wasn't a crash loop
 
+/** Extra env vars injected into every backend spawn (e.g. BLOBY_AGENT_SECRET) */
+let extraEnv: Record<string, string> = {};
+
+/** Set extra environment variables for the backend process. Applies to all future spawns including auto-restarts. */
+export function setBackendEnv(env: Record<string, string>): void {
+  extraEnv = { ...extraEnv, ...env };
+}
+
 const LOG_FILE = path.join(WORKSPACE_DIR, '.backend.log');
 
 export function getBackendPort(basePort: number): number {
@@ -59,7 +67,7 @@ export function spawnBackend(port: number): ChildProcess {
   child = spawn(process.execPath, ['--import', 'tsx/esm', '--input-type=module', '-e', wrapper], {
     cwd: WORKSPACE_DIR,
     stdio: ['ignore', 'pipe', 'pipe'],
-    env: { ...process.env, BACKEND_PORT: String(port) },
+    env: { ...process.env, ...extraEnv, BACKEND_PORT: String(port) },
   });
 
   child.stdout?.on('data', (d) => {

package/supervisor/channels/manager.ts

@@ -70,6 +70,8 @@ export class ChannelManager {
   private customerBuffers = new Map<string, BufferedMessage[]>();
   /** Debounce buffers per sender (keyed by "channel:sender") */
   private debounceBuffers = new Map<string, DebounceEntry>();
+  /** Dynamic reply target for the admin live conversation (updated before each pushMessage) */
+  private waReplyTarget: { channel: ChannelType; rawSender: string; assistantBufferKey?: string } | null = null;
 
   constructor(opts: ChannelManagerOpts) {
     this.opts = opts;
@@ -362,19 +364,58 @@ export class ChannelManager {
       return;
     }
 
-    // Assistant mode — triggered message in someone else's chat
+    // Assistant mode — triggered message in someone else's chat → route through admin (shared brain)
     if (mode === 'assistant') {
+      const phone = sender.replace(/@.*/, '');
+      const bufferKey = `${channel}:${phone}`;
+      const buffer = this.customerBuffers.get(bufferKey) || [];
+
+      // Strip trigger prefix
+      const cfgBotName = loadConfig().username || 'bloby';
+      const triggerRegex = new RegExp(`@${cfgBotName}[:\\s]+`, 'i');
+      const triggerMatch = combinedText.match(triggerRegex);
+      let cleanText = combinedText;
+      if (triggerMatch && triggerMatch.index !== undefined) {
+        cleanText = combinedText.slice(triggerMatch.index + triggerMatch[0].length).trim();
+      }
+
+      // Load skill context (SCRIPT.md + contact memory)
+      const scriptPrompt = this.loadActiveScript(channelConfig);
+      let contactMemory = '';
+      try {
+        const customerDataDir = this.getSkillCustomerDataDir(channelConfig);
+        if (customerDataDir) {
+          const memoryPath = path.join(WORKSPACE_DIR, customerDataDir, `${phone}.md`);
+          if (fs.existsSync(memoryPath)) {
+            contactMemory = fs.readFileSync(memoryPath, 'utf-8').trim();
+          }
+        }
+      } catch {}
+
+      // Build enriched text: skill instructions + conversation context + command
+      let enrichedText = '';
+      if (scriptPrompt) enrichedText += `# Assistant Skill Instructions\n${scriptPrompt}\n\n---\n`;
+      if (contactMemory) enrichedText += `# Contact Memory (${phone})\n${contactMemory}\n\n---\n`;
+      if (buffer.length > 0) {
+        enrichedText += `# Recent conversation with ${senderName || phone}\n`;
+        enrichedText += buffer.map((m) => m.content).join('\n');
+        enrichedText += '\n\n---\n';
+      }
+      enrichedText += cleanText;
+
       const message: InboundMessage = {
         channel,
-        sender: sender.replace(/@.*/, ''),
+        sender: phone,
         senderName,
         role: 'assistant',
-        text: combinedText,
+        text: enrichedText,
+        displayText: cleanText,
         rawSender: sender,
         attachments: attachments.length > 0 ? attachments : undefined,
       };
-      log.info(`[channels] Assistant mode | triggered in chat with ${message.sender} | "${combinedText.slice(0, 60)}"`);
-      await this.handleAssistantMessage(message, channelConfig);
+
+      log.info(`[channels] Assistant mode | triggered in chat with ${phone} | buffer=${buffer.length} msgs | "${cleanText.slice(0, 60)}"`);
+      await this.handleAdminMessage(message);
       return;
     }
 
@@ -415,7 +456,7 @@ export class ChannelManager {
     return 'customer';
   }
 
-  /** Handle message from an admin — mirrors to chat conversation, uses main system prompt */
+  /** Handle message from an admin (or assistant trigger) — mirrors to chat conversation, uses main system prompt */
   private async handleAdminMessage(msg: InboundMessage) {
     const { workerApi, broadcastBloby, getModel } = this.opts;
     const model = getModel();
@@ -436,11 +477,14 @@ export class ChannelManager {
       return;
     }
 
+    // Use display text for DB/chat (hides enriched agent context from the UI)
+    const displayContent = msg.displayText || msg.text;
+
     // Save user message to DB
     try {
       await workerApi(`/api/conversations/${convId}/messages`, 'POST', {
         role: 'user',
-        content: msg.text,
+        content: displayContent,
         meta: { model, channel: msg.channel },
       });
     } catch (err: any) {
@@ -450,7 +494,7 @@ export class ChannelManager {
     // Broadcast to chat clients (mirroring)
     broadcastBloby('chat:sync', {
       conversationId: convId,
-      message: { role: 'user', content: msg.text, timestamp: new Date().toISOString() },
+      message: { role: 'user', content: displayContent, timestamp: new Date().toISOString() },
     });
 
     // Fetch names and recent messages
@@ -474,8 +518,10 @@ export class ChannelManager {
       }
     } catch {}
 
-    // Channel context — tells the agent this is a WhatsApp message, respond naturally
-    const channelContext = `[WhatsApp | ${msg.sender} | admin]\n`;
+    // Channel context — dynamic role (admin for self-chat, assistant for triggered messages)
+    const roleTag = msg.senderName && msg.role === 'assistant'
+      ? `${msg.role} | ${msg.senderName}` : msg.role;
+    const channelContext = `[WhatsApp | ${msg.sender} | ${roleTag}]\n`;
 
     // Convert inbound attachments to agent format
     const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
@@ -485,7 +531,7 @@ export class ChannelManager {
       data: att.data,
     }));
 
-    // Show "typing..." while the agent processes
+    // Show "typing..." in the correct chat
     this.startTyping(msg.channel, msg.rawSender);
 
     // Track text chunks for WhatsApp — lives for the conversation lifetime
@@ -501,24 +547,37 @@ export class ChannelManager {
           waChunkBuf += eventData.token;
         }
 
+        // Use dynamic reply target (self-chat or contact's chat depending on latest push)
+        const target = this.waReplyTarget;
+        if (!target) return;
+
         // Agent paused to use a tool — send accumulated text as an intermediate WhatsApp message
         if (type === 'bot:tool' && waChunkBuf.trim()) {
-          this.sendMessage(msg.channel, msg.rawSender, this.formatBotReply(waChunkBuf.trim(), botName)).catch((err) => {
+          this.sendMessage(target.channel, target.rawSender, this.formatBotReply(waChunkBuf.trim(), botName)).catch((err) => {
             log.warn(`[channels] Failed to send WhatsApp chunk: ${err.message}`);
           });
           waChunkBuf = '';
         }
 
         if (type === 'bot:response' && eventData.content) {
-          // Send remaining text
+          // Send remaining text to the correct chat
           const remaining = waChunkBuf.trim();
           if (remaining) {
-            this.sendMessage(msg.channel, msg.rawSender, this.formatBotReply(remaining, botName)).catch((err) => {
+            this.sendMessage(target.channel, target.rawSender, this.formatBotReply(remaining, botName)).catch((err) => {
               log.warn(`[channels] Failed to send WhatsApp reply: ${err.message}`);
             });
             waChunkBuf = '';
           }
 
+          // If this was an assistant response, store in the contact's context buffer
+          if (target.assistantBufferKey) {
+            const buf = this.customerBuffers.get(target.assistantBufferKey);
+            if (buf) {
+              buf.push({ role: 'assistant', content: eventData.content });
+              if (buf.length > MAX_BUFFER_MESSAGES) buf.splice(0, buf.length - MAX_BUFFER_MESSAGES);
+            }
+          }
+
           // Save response to DB
           workerApi(`/api/conversations/${convId}/messages`, 'POST', {
             role: 'assistant',
@@ -540,6 +599,13 @@ export class ChannelManager {
       }, { botName, humanName }, recentMessages);
     }
 
+    // Set reply target BEFORE pushing — callback reads this to know where to send
+    this.waReplyTarget = {
+      channel: msg.channel,
+      rawSender: msg.rawSender,
+      assistantBufferKey: msg.role === 'assistant' ? `${msg.channel}:${msg.sender}` : undefined,
+    };
+
     // Push the message into the live conversation
     const channelContent = channelContext + msg.text;
     pushMessage(convId, channelContent, agentAttachments);
@@ -702,146 +768,6 @@ export class ChannelManager {
     log.info(`[channels] Assistant context stored: ${bufferKey} | ${buffer.length} msgs | [${label}]: "${text.slice(0, 60)}"`);
   }
 
-  /** Handle a triggered assistant message — runs one-shot agent with conversation context */
-  private async handleAssistantMessage(msg: InboundMessage, channelConfig: ChannelConfig) {
-    const agentKey = `${msg.channel}:${msg.sender}`;
-
-    // Check concurrent limit
-    if (this.activeAgents.size >= MAX_CONCURRENT_AGENTS && !this.activeAgents.has(agentKey)) {
-      log.info(`[channels] Max concurrent agents reached — queuing assistant message for ${msg.sender}`);
-      this.messageQueue.push(msg);
-      return;
-    }
-
-    const { workerApi, getModel } = this.opts;
-    const model = getModel();
-
-    // Extract command after trigger: "Ok.\n\n@bloby: do X" → "do X"
-    const config = loadConfig();
-    const botName = config.username || 'bloby';
-    const triggerRegex = new RegExp(`@${botName}[:\\s]+`, 'i');
-    const triggerMatch = msg.text.match(triggerRegex);
-    let cleanText = msg.text;
-    if (triggerMatch && triggerMatch.index !== undefined) {
-      cleanText = msg.text.slice(triggerMatch.index + triggerMatch[0].length).trim();
-    }
-
-    // Load SCRIPT.md from configured skill
-    const scriptPrompt = this.loadActiveScript(channelConfig);
-
-    // Fetch agent name
-    let agentBotName = 'Bloby', humanName = 'Human';
-    try {
-      const status = await workerApi('/api/onboard/status');
-      agentBotName = status.agentName || 'Bloby';
-      humanName = status.userName || 'Human';
-    } catch {}
-
-    // Get conversation buffer (already populated by storeAssistantContext)
-    let buffer = this.customerBuffers.get(agentKey);
-    if (!buffer) {
-      buffer = [];
-      this.customerBuffers.set(agentKey, buffer);
-    }
-
-    log.info(`[channels] Assistant trigger: agentKey=${agentKey} | buffer=${buffer.length} msgs | cleanText="${cleanText.slice(0, 80)}"`);
-    if (buffer.length > 0) {
-      log.info(`[channels] Assistant context preview: ${buffer.slice(-5).map((m) => `[${m.role}] ${m.content.slice(0, 50)}`).join(' | ')}`);
-    }
-
-    // All buffered messages are context for the agent
-    const recentMessages: RecentMessage[] = buffer.map((m) => ({
-      role: m.role,
-      content: m.content,
-    }));
-
-    // Load per-contact memory from the skill's customer_data directory
-    let contactMemory = '';
-    try {
-      const customerDataDir = this.getSkillCustomerDataDir(channelConfig);
-      if (customerDataDir) {
-        const memoryPath = path.join(WORKSPACE_DIR, customerDataDir, `${msg.sender}.md`);
-        if (fs.existsSync(memoryPath)) {
-          contactMemory = fs.readFileSync(memoryPath, 'utf-8').trim();
-        }
-      }
-    } catch {}
-
-    // Build enriched script with contact memory
-    let enrichedScript = scriptPrompt;
-    if (contactMemory && enrichedScript) {
-      enrichedScript += `\n\n---\n# Contact History (${msg.sender})\n\n${contactMemory}`;
-    }
-
-    const channelContext = `[WhatsApp | ${msg.sender} | assistant${msg.senderName ? ` | ${msg.senderName}` : ''}]\n`;
-
-    // Convert inbound attachments to agent format
-    const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
-      type: 'image' as const,
-      name: `whatsapp_image.${att.mediaType.split('/')[1] || 'jpg'}`,
-      mediaType: att.mediaType,
-      data: att.data,
-    }));
-
-    // Stable convId per contact
-    const convId = `channel-${agentKey}`;
-
-    this.activeAgents.set(agentKey, { sender: msg.sender, channel: msg.channel });
-
-    // Show "typing..." while the agent processes
-    this.startTyping(msg.channel, msg.rawSender);
-
-    // Track text chunks for WhatsApp
-    let waChunkBuf = '';
-
-    startBlobyAgentQuery(
-      convId,
-      channelContext + cleanText,
-      model,
-      (type, eventData) => {
-        // Accumulate text tokens
-        if (type === 'bot:token' && eventData.token) {
-          waChunkBuf += eventData.token;
-        }
-
-        // Agent paused to use a tool — send accumulated text as intermediate message
-        if (type === 'bot:tool' && waChunkBuf.trim()) {
-          this.sendMessage(msg.channel, msg.rawSender, this.formatBotReply(waChunkBuf.trim(), agentBotName)).catch((err) => {
-            log.warn(`[channels] Failed to send assistant chunk: ${err.message}`);
-          });
-          waChunkBuf = '';
-        }
-
-        if (type === 'bot:response' && eventData.content) {
-          // Add response to buffer for continuity across triggers
-          buffer!.push({ role: 'assistant', content: eventData.content });
-          if (buffer!.length > MAX_BUFFER_MESSAGES) {
-            buffer!.splice(0, buffer!.length - MAX_BUFFER_MESSAGES);
-          }
-
-          // Send remaining text
-          const remaining = waChunkBuf.trim();
-          if (remaining) {
-            this.sendMessage(msg.channel, msg.rawSender, this.formatBotReply(remaining, agentBotName)).catch((err) => {
-              log.warn(`[channels] Failed to send assistant reply: ${err.message}`);
-            });
-            waChunkBuf = '';
-          }
-        }
-
-        if (type === 'bot:done') {
-          this.activeAgents.delete(agentKey);
-          if (eventData.usedFileTools) this.opts.restartBackend();
-          this.processQueue();
-        }
-      },
-      agentAttachments,
-      undefined,
-      { botName: agentBotName, humanName },
-      recentMessages,
-      enrichedScript,
-    );
-  }
 
   /** Transcribe audio via the existing whisper endpoint */
   private async transcribeAudio(audioBase64: string): Promise<string | null> {

package/supervisor/channels/types.ts

@@ -29,8 +29,10 @@ export interface InboundMessage {
   senderName?: string;
   /** Resolved role of the sender */
   role: SenderRole;
-  /** Message text content */
+  /** Message text content (may include enriched context for assistant triggers) */
   text: string;
+  /** Display-friendly text for DB/chat UI (when text contains enriched agent context) */
+  displayText?: string;
   /** Raw sender JID (channel-specific format, used for replies) */
   rawSender: string;
   /** Image attachments */

package/supervisor/index.ts

@@ -11,7 +11,8 @@ import { log } from '../shared/logger.js';
 import { startTunnel, stopTunnel, isTunnelAlive, restartTunnel, startNamedTunnel, restartNamedTunnel } from './tunnel.js';
 import { createWorkerApp } from '../worker/index.js';
 import { closeDb, getSession, getSetting } from '../worker/db.js';
-import { spawnBackend, stopBackend, getBackendPort, isBackendAlive, isBackendStopping, resetBackendRestarts } from './backend.js';
+import { spawnBackend, stopBackend, getBackendPort, isBackendAlive, isBackendStopping, resetBackendRestarts, setBackendEnv } from './backend.js';
+import { handleAgentQuery, type AgentQueryRequest } from './agent-api.js';
 import { updateTunnelUrl, startHeartbeat, stopHeartbeat, disconnect } from '../shared/relay.js';
 import {
   startConversation, pushMessage, hasConversation, endConversation, endAllConversations,
@@ -237,6 +238,13 @@ export async function startSupervisor() {
   const config = loadConfig();
   const backendPort = getBackendPort(config.port);
   const internalSecret = crypto.randomBytes(16).toString('hex');
+  const agentSecret = crypto.randomBytes(32).toString('hex');
+
+  // Inject agent secret + supervisor port into workspace backend env
+  setBackendEnv({
+    BLOBY_AGENT_SECRET: agentSecret,
+    SUPERVISOR_PORT: String(config.port),
+  });
 
   // Kill any stale processes from previous crashes/updates
   log.info(`[startup] Clearing ports ${config.port}, ${config.port + 2}, ${backendPort}...`);
@@ -803,6 +811,57 @@ ${!connected ? `<script>
       return;
     }
 
+    // ── Agent API — SDK gateway for workspace code ──
+    if (req.method === 'POST' && req.url?.startsWith('/api/agent/')) {
+      const agentPath = req.url.split('?')[0];
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+
+      // Localhost-only guard
+      const remoteIp = req.socket.remoteAddress || '';
+      if (remoteIp !== '127.0.0.1' && remoteIp !== '::1' && remoteIp !== '::ffff:127.0.0.1') {
+        res.writeHead(403);
+        res.end(JSON.stringify({ ok: false, error: 'Agent API is localhost-only.' }));
+        return;
+      }
+
+      // Auth: x-agent-secret header
+      if (req.headers['x-agent-secret'] !== agentSecret) {
+        res.writeHead(401);
+        res.end(JSON.stringify({ ok: false, error: 'Invalid or missing x-agent-secret header.' }));
+        return;
+      }
+
+      if (agentPath === '/api/agent/query') {
+        let body = '';
+        req.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+        req.on('end', async () => {
+          try {
+            const parsed = JSON.parse(body) as AgentQueryRequest;
+            const result = await handleAgentQuery(parsed);
+
+            // If the agent wrote files, restart backend + broadcast HMR
+            if (result.usedFileTools) {
+              resetBackendRestarts();
+              stopBackend().then(() => spawnBackend(backendPort));
+              broadcastBloby('app:hmr-update', {});
+            }
+
+            res.writeHead(result.ok ? 200 : 400);
+            res.end(JSON.stringify(result));
+          } catch (err: any) {
+            res.writeHead(500);
+            res.end(JSON.stringify({ ok: false, error: err.message }));
+          }
+        });
+        return;
+      }
+
+      res.writeHead(404);
+      res.end(JSON.stringify({ ok: false, error: 'Unknown agent endpoint.' }));
+      return;
+    }
+
     // API routes → handled in-process by worker Express app
     if (req.url?.startsWith('/api')) {
       // Internal supervisor calls (workerApi) bypass auth — they carry a per-process secret

package/worker/prompts/bloby-system-prompt.txt

@@ -300,7 +300,7 @@ GET | `/api/marketplace/balance/bot` | Bearer (required) | Check your owner's cr
 
 Agents will soon have a USDC wallet for autonomous purchases. You'll be able to check your balance and buy skills directly without a redeem code. This is not yet available — for now, paid skills require your human to purchase from the web marketplace and give you a redeem code.
 
-For a machine-readable catalog: `GET https://bloby.bot/api/marketplace/products`
+For a machine-readable catalog: `GET https://bloby.bot/api/marketplace/products` — **always include your relay token** (`Authorization: Bearer $RELAY_TOKEN`) on every request to the relay API, even public endpoints. This enables your presence in Bloby World so other users can see your bloby on the world map.
 
 ---