@poncho-ai/cli 0.12.0 → 0.14.0

package/src/index.ts

@@ -24,11 +24,20 @@ import {
   resolveStateConfig,
   type CronJobConfig,
   type PonchoConfig,
+  type Conversation,
   type ConversationStore,
   type UploadStore,
 } from "@poncho-ai/harness";
 import type { AgentEvent, FileInput, Message, RunInput } from "@poncho-ai/sdk";
 import { getTextContent } from "@poncho-ai/sdk";
+import {
+  AgentBridge,
+  ResendAdapter,
+  SlackAdapter,
+  type AgentRunner,
+  type MessagingAdapter,
+  type RouteRegistrar,
+} from "@poncho-ai/messaging";
 import Busboy from "busboy";
 import { Command } from "commander";
 import dotenv from "dotenv";
@@ -46,6 +55,7 @@ import {
   setCookie,
   verifyPassphrase,
 } from "./web-ui.js";
+import { buildOpenApiSpec, renderApiDocsHtml } from "./api-docs.js";
 import { createInterface } from "node:readline/promises";
 import {
   runInitOnboarding,
@@ -367,7 +377,7 @@ cp .env.example .env
 poncho dev
 \`\`\`
 
-Open \`http://localhost:3000\` for the web UI.
+Open \`http://localhost:3000\` for the web UI, or \`http://localhost:3000/api/docs\` for interactive API documentation.
 
 On your first interactive session, the agent introduces its configurable capabilities.
 While a response is streaming, you can stop it:
@@ -489,7 +499,7 @@ Core files:
 
 - \`AGENT.md\`: behavior, model selection, runtime guidance
 - \`poncho.config.js\`: runtime config (storage, auth, telemetry, MCP, tools)
-- \`.env\`: secrets and environment variables
+- \`.env\`: secrets and environment variables (loaded before the harness starts, so \`process.env\` is available in skill scripts)
 
 Example \`poncho.config.js\`:
 
@@ -515,18 +525,20 @@ export default {
       auth: { type: "bearer", tokenEnv: "GITHUB_TOKEN" },
     },
   ],
+  // Tool access: true (available), false (disabled), 'approval' (requires human approval)
   tools: {
-    defaults: {
-      list_directory: true,
-      read_file: true,
-      write_file: true, // still gated by environment/policy
-    },
+    write_file: true,           // gated by environment for writes
+    send_email: 'approval',     // requires human approval
     byEnvironment: {
       production: {
-        read_file: false, // example override
+        write_file: false,
+      },
+      development: {
+        send_email: true,       // skip approval in dev
       },
     },
   },
+  // webUi: false, // Disable built-in UI for API-only deployments
 };
 \`\`\`
 
@@ -567,6 +579,44 @@ cron:
 - Docker/Fly.io: scheduler runs automatically.
 - Trigger manually: \`curl http://localhost:3000/api/cron/daily-report\`
 
+## Messaging (Slack)
+
+Connect your agent to Slack so it responds to @mentions:
+
+1. Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps)
+2. Add Bot Token Scopes: \`app_mentions:read\`, \`chat:write\`, \`reactions:write\`
+3. Enable Event Subscriptions, set Request URL to \`https://<your-url>/api/messaging/slack\`, subscribe to \`app_mention\`
+4. Install to workspace, copy Bot Token and Signing Secret
+5. Set env vars:
+   \`\`\`
+   SLACK_BOT_TOKEN=xoxb-...
+   SLACK_SIGNING_SECRET=...
+   \`\`\`
+6. Add to \`poncho.config.js\`:
+   \`\`\`javascript
+   messaging: [{ platform: 'slack' }]
+   \`\`\`
+
+## Messaging (Email via Resend)
+
+Connect your agent to email so users can interact by sending emails:
+
+1. Set up a domain and enable Inbound at [resend.com](https://resend.com)
+2. Create a webhook for \`email.received\` pointing to \`https://<your-url>/api/messaging/resend\`
+3. Install the Resend SDK: \`npm install resend\`
+4. Set env vars:
+   \`\`\`
+   RESEND_API_KEY=re_...
+   RESEND_WEBHOOK_SECRET=whsec_...
+   RESEND_FROM=Agent <agent@yourdomain.com>
+   \`\`\`
+5. Add to \`poncho.config.js\`:
+   \`\`\`javascript
+   messaging: [{ platform: 'resend' }]
+   \`\`\`
+
+For full control over outbound emails, use **tool mode** (\`mode: 'tool'\`) — the agent gets a \`send_email\` tool instead of auto-replying. See the repo README for details.
+
 ## Deployment
 
 \`\`\`bash
@@ -1371,6 +1421,299 @@ export const createRequestHandler = async (options?: {
     workingDir,
     agentId: identity.id,
   });
+  // ---------------------------------------------------------------------------
+  // Messaging adapters (Slack, etc.) — routes bypass Poncho auth; each
+  // adapter handles its own request verification (e.g. Slack signing secret).
+  // ---------------------------------------------------------------------------
+  const messagingRoutes = new Map<string, Map<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>>>();
+  const messagingRouteRegistrar: RouteRegistrar = (method, path, routeHandler) => {
+    let byMethod = messagingRoutes.get(path);
+    if (!byMethod) {
+      byMethod = new Map();
+      messagingRoutes.set(path, byMethod);
+    }
+    byMethod.set(method, routeHandler);
+  };
+
+  const messagingRunner: AgentRunner = {
+    async getOrCreateConversation(conversationId, meta) {
+      const existing = await conversationStore.get(conversationId);
+      if (existing) {
+        return { messages: existing.messages };
+      }
+      const now = Date.now();
+      const conversation = {
+        conversationId,
+        title: meta.title ?? `${meta.platform} thread`,
+        messages: [] as Message[],
+        ownerId: meta.ownerId,
+        tenantId: null,
+        createdAt: now,
+        updatedAt: now,
+      };
+      await conversationStore.update(conversation);
+      return { messages: [] };
+    },
+    async run(conversationId, input) {
+      console.log("[messaging-runner] starting run for", conversationId, "task:", input.task.slice(0, 80));
+
+      const historyMessages = [...input.messages];
+      const userContent = input.task;
+
+      // Read-modify-write helper: always fetches the latest version from
+      // the store before writing, so concurrent writers (e.g. the approval
+      // handler's persistConversationPendingApprovals) don't get clobbered.
+      const updateConversation = async (
+        patch: (conv: Conversation) => void,
+      ): Promise<void> => {
+        const fresh = await conversationStore.get(conversationId);
+        if (!fresh) return;
+        patch(fresh);
+        fresh.updatedAt = Date.now();
+        await conversationStore.update(fresh);
+      };
+
+      // Persist user turn immediately so the web UI shows it while the agent runs.
+      await updateConversation((c) => {
+        c.messages = [...historyMessages, { role: "user" as const, content: userContent }];
+      });
+
+      let latestRunId = "";
+      let assistantResponse = "";
+      const toolTimeline: string[] = [];
+      const sections: Array<{ type: "text" | "tools"; content: string | string[] }> = [];
+      let currentTools: string[] = [];
+      let currentText = "";
+
+      const buildMessages = (): Message[] => {
+        const draftSections: Array<{ type: "text" | "tools"; content: string | string[] }> = [
+          ...sections.map((s) => ({
+            type: s.type,
+            content: Array.isArray(s.content) ? [...s.content] : s.content,
+          })),
+        ];
+        if (currentTools.length > 0) {
+          draftSections.push({ type: "tools", content: [...currentTools] });
+        }
+        if (currentText.length > 0) {
+          draftSections.push({ type: "text", content: currentText });
+        }
+        const hasDraftContent =
+          assistantResponse.length > 0 || toolTimeline.length > 0 || draftSections.length > 0;
+        if (!hasDraftContent) {
+          return [...historyMessages, { role: "user" as const, content: userContent }];
+        }
+        return [
+          ...historyMessages,
+          { role: "user" as const, content: userContent },
+          {
+            role: "assistant" as const,
+            content: assistantResponse,
+            metadata:
+              toolTimeline.length > 0 || draftSections.length > 0
+                ? ({
+                    toolActivity: [...toolTimeline],
+                    sections: draftSections.length > 0 ? draftSections : undefined,
+                  } as Message["metadata"])
+                : undefined,
+          },
+        ];
+      };
+
+      const persistDraftAssistantTurn = async (): Promise<void> => {
+        if (assistantResponse.length === 0 && toolTimeline.length === 0) return;
+        await updateConversation((c) => {
+          c.messages = buildMessages();
+        });
+      };
+
+      const runInput = {
+        task: input.task,
+        conversationId,
+        messages: input.messages,
+        files: input.files,
+        parameters: input.metadata ? {
+          __messaging_platform: input.metadata.platform,
+          __messaging_sender_id: input.metadata.sender.id,
+          __messaging_sender_name: input.metadata.sender.name ?? "",
+          __messaging_thread_id: input.metadata.threadId,
+        } : undefined,
+      };
+
+      try {
+        for await (const event of harness.runWithTelemetry(runInput)) {
+          if (event.type === "run:started") {
+            latestRunId = event.runId;
+            runOwners.set(event.runId, "local-owner");
+            runConversations.set(event.runId, conversationId);
+          }
+          if (event.type === "model:chunk") {
+            if (currentTools.length > 0) {
+              sections.push({ type: "tools", content: currentTools });
+              currentTools = [];
+            }
+            assistantResponse += event.content;
+            currentText += event.content;
+          }
+          if (event.type === "tool:started") {
+            if (currentText.length > 0) {
+              sections.push({ type: "text", content: currentText });
+              currentText = "";
+            }
+            const toolText = `- start \`${event.tool}\``;
+            toolTimeline.push(toolText);
+            currentTools.push(toolText);
+          }
+          if (event.type === "tool:completed") {
+            const toolText = `- done \`${event.tool}\` (${event.duration}ms)`;
+            toolTimeline.push(toolText);
+            currentTools.push(toolText);
+          }
+          if (event.type === "tool:error") {
+            const toolText = `- error \`${event.tool}\`: ${event.error}`;
+            toolTimeline.push(toolText);
+            currentTools.push(toolText);
+          }
+          if (event.type === "step:completed") {
+            await persistDraftAssistantTurn();
+          }
+          if (event.type === "tool:approval:required") {
+            const toolText = `- approval required \`${event.tool}\``;
+            toolTimeline.push(toolText);
+            currentTools.push(toolText);
+            await persistDraftAssistantTurn();
+            await persistConversationPendingApprovals(conversationId);
+          }
+          if (event.type === "tool:approval:granted") {
+            const toolText = `- approval granted (${event.approvalId})`;
+            toolTimeline.push(toolText);
+            currentTools.push(toolText);
+            await persistDraftAssistantTurn();
+          }
+          if (event.type === "tool:approval:denied") {
+            const toolText = `- approval denied (${event.approvalId})`;
+            toolTimeline.push(toolText);
+            currentTools.push(toolText);
+            await persistDraftAssistantTurn();
+          }
+          if (
+            event.type === "run:completed" &&
+            assistantResponse.length === 0 &&
+            event.result.response
+          ) {
+            assistantResponse = event.result.response;
+          }
+          if (event.type === "run:error") {
+            assistantResponse = assistantResponse || `[Error: ${event.error.message}]`;
+          }
+          broadcastEvent(conversationId, event);
+        }
+      } catch (err) {
+        console.error("[messaging-runner] run failed:", err instanceof Error ? err.message : err);
+        assistantResponse = assistantResponse || `[Error: ${err instanceof Error ? err.message : "Unknown error"}]`;
+      }
+
+      // Finalize sections (clear after pushing so buildMessages doesn't re-add)
+      if (currentTools.length > 0) {
+        sections.push({ type: "tools", content: currentTools });
+        currentTools = [];
+      }
+      if (currentText.length > 0) {
+        sections.push({ type: "text", content: currentText });
+        currentText = "";
+      }
+
+      await updateConversation((c) => {
+        c.messages = buildMessages();
+        c.runtimeRunId = latestRunId || c.runtimeRunId;
+        c.pendingApprovals = [];
+      });
+      finishConversationStream(conversationId);
+      await persistConversationPendingApprovals(conversationId);
+      if (latestRunId) {
+        runOwners.delete(latestRunId);
+        runConversations.delete(latestRunId);
+      }
+
+      console.log("[messaging-runner] run complete, response length:", assistantResponse.length);
+      const response = assistantResponse;
+
+      return { response };
+    },
+  };
+
+  const messagingBridges: AgentBridge[] = [];
+  if (config?.messaging && config.messaging.length > 0) {
+    let waitUntilHook: ((promise: Promise<unknown>) => void) | undefined;
+    if (process.env.VERCEL) {
+      try {
+        // Dynamic require via variable so TypeScript doesn't attempt static
+        // resolution of @vercel/functions (only present in Vercel deployments).
+        const modName = "@vercel/functions";
+        const mod = await import(/* webpackIgnore: true */ modName);
+        waitUntilHook = mod.waitUntil;
+      } catch {
+        // @vercel/functions not installed -- fall through to no-op.
+      }
+    }
+
+    for (const channelConfig of config.messaging) {
+      if (channelConfig.platform === "slack") {
+        const adapter = new SlackAdapter({
+          botTokenEnv: channelConfig.botTokenEnv,
+          signingSecretEnv: channelConfig.signingSecretEnv,
+        });
+        const bridge = new AgentBridge({
+          adapter,
+          runner: messagingRunner,
+          waitUntil: waitUntilHook,
+          ownerId: "local-owner",
+        });
+        adapter.registerRoutes(messagingRouteRegistrar);
+        try {
+          await bridge.start();
+          messagingBridges.push(bridge);
+          console.log(`  Slack messaging enabled at /api/messaging/slack`);
+        } catch (err) {
+          console.warn(
+            `  Slack messaging disabled: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      } else if (channelConfig.platform === "resend") {
+        const adapter = new ResendAdapter({
+          apiKeyEnv: channelConfig.apiKeyEnv,
+          webhookSecretEnv: channelConfig.webhookSecretEnv,
+          fromEnv: channelConfig.fromEnv,
+          allowedSenders: channelConfig.allowedSenders,
+          mode: channelConfig.mode,
+          allowedRecipients: channelConfig.allowedRecipients,
+          maxSendsPerRun: channelConfig.maxSendsPerRun,
+        });
+        const bridge = new AgentBridge({
+          adapter,
+          runner: messagingRunner,
+          waitUntil: waitUntilHook,
+          ownerId: "local-owner",
+        });
+        adapter.registerRoutes(messagingRouteRegistrar);
+        try {
+          await bridge.start();
+          messagingBridges.push(bridge);
+          const adapterTools = adapter.getToolDefinitions?.() ?? [];
+          if (adapterTools.length > 0) {
+            harness.registerTools(adapterTools);
+          }
+          const modeLabel = channelConfig.mode === "tool" ? "tool" : "auto-reply";
+          console.log(`  Resend email messaging enabled at /api/messaging/resend (mode: ${modeLabel})`);
+        } catch (err) {
+          console.warn(
+            `  Resend email messaging disabled: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+    }
+  }
+
   const sessionStore = new SessionStore();
   const loginRateLimiter = new LoginRateLimiter();
 
@@ -1379,6 +1722,7 @@ export const createRequestHandler = async (options?: {
   const authRequired = config?.auth?.required ?? false;
   const requireAuth = authRequired && authToken.length > 0;
 
+  const webUiEnabled = config?.webUi !== false;
   const isProduction = resolveHarnessEnvironment() === "production";
   const secureCookies = isProduction;
 
@@ -1404,42 +1748,64 @@ export const createRequestHandler = async (options?: {
     }
     const [pathname] = request.url.split("?");
 
-    if (request.method === "GET" && (pathname === "/" || pathname.startsWith("/c/"))) {
-      writeHtml(response, 200, renderWebUiHtml({ agentName }));
-      return;
-    }
+    if (webUiEnabled) {
+      if (request.method === "GET" && (pathname === "/" || pathname.startsWith("/c/"))) {
+        writeHtml(response, 200, renderWebUiHtml({ agentName }));
+        return;
+      }
 
-    if (pathname === "/manifest.json" && request.method === "GET") {
-      response.writeHead(200, { "Content-Type": "application/manifest+json" });
-      response.end(renderManifest({ agentName }));
-      return;
+      if (pathname === "/manifest.json" && request.method === "GET") {
+        response.writeHead(200, { "Content-Type": "application/manifest+json" });
+        response.end(renderManifest({ agentName }));
+        return;
+      }
+
+      if (pathname === "/sw.js" && request.method === "GET") {
+        response.writeHead(200, {
+          "Content-Type": "application/javascript",
+          "Service-Worker-Allowed": "/",
+        });
+        response.end(renderServiceWorker());
+        return;
+      }
+
+      if (pathname === "/icon.svg" && request.method === "GET") {
+        response.writeHead(200, { "Content-Type": "image/svg+xml" });
+        response.end(renderIconSvg({ agentName }));
+        return;
+      }
+
+      if ((pathname === "/icon-192.png" || pathname === "/icon-512.png") && request.method === "GET") {
+        response.writeHead(302, { Location: "/icon.svg" });
+        response.end();
+        return;
+      }
     }
 
-    if (pathname === "/sw.js" && request.method === "GET") {
-      response.writeHead(200, {
-        "Content-Type": "application/javascript",
-        "Service-Worker-Allowed": "/",
-      });
-      response.end(renderServiceWorker());
+    if (pathname === "/health" && request.method === "GET") {
+      writeJson(response, 200, { status: "ok" });
       return;
     }
 
-    if (pathname === "/icon.svg" && request.method === "GET") {
-      response.writeHead(200, { "Content-Type": "image/svg+xml" });
-      response.end(renderIconSvg({ agentName }));
+    if (pathname === "/api/openapi.json" && request.method === "GET") {
+      writeJson(response, 200, buildOpenApiSpec({ agentName }));
       return;
     }
 
-    if ((pathname === "/icon-192.png" || pathname === "/icon-512.png") && request.method === "GET") {
-      // Redirect to SVG — browsers that support PWA icons will use the SVG
-      response.writeHead(302, { Location: "/icon.svg" });
-      response.end();
+    if (pathname === "/api/docs" && request.method === "GET") {
+      writeHtml(response, 200, renderApiDocsHtml("/api/openapi.json"));
       return;
     }
 
-    if (pathname === "/health" && request.method === "GET") {
-      writeJson(response, 200, { status: "ok" });
-      return;
+    // Messaging adapter routes bypass Poncho auth (they verify requests
+    // using platform-specific mechanisms, e.g. Slack signing secret).
+    const messagingByMethod = messagingRoutes.get(pathname ?? "");
+    if (messagingByMethod) {
+      const routeHandler = messagingByMethod.get(request.method ?? "");
+      if (routeHandler) {
+        await routeHandler(request, response);
+        return;
+      }
     }
 
     const cookies = parseCookies(request);
@@ -1649,18 +2015,19 @@ export const createRequestHandler = async (options?: {
       });
       const stream = conversationEventStreams.get(conversationId);
       if (!stream) {
-        // No active run — close immediately
         response.write("event: stream:end\ndata: {}\n\n");
         response.end();
         return;
       }
-      // Replay buffered events
-      for (const bufferedEvent of stream.buffer) {
-        try {
-          response.write(formatSseEvent(bufferedEvent));
-        } catch {
-          response.end();
-          return;
+      const liveOnly = (request.url ?? "").includes("live_only=true");
+      if (!liveOnly) {
+        for (const bufferedEvent of stream.buffer) {
+          try {
+            response.write(formatSseEvent(bufferedEvent));
+          } catch {
+            response.end();
+            return;
+          }
         }
       }
       if (stream.finished) {
@@ -1711,11 +2078,14 @@ export const createRequestHandler = async (options?: {
         for (const approval of livePending) {
           mergedPendingById.set(approval.approvalId, approval);
         }
+        const activeStream = conversationEventStreams.get(conversationId);
+        const hasActiveRun = !!activeStream && !activeStream.finished;
         writeJson(response, 200, {
           conversation: {
             ...conversation,
             pendingApprovals: Array.from(mergedPendingById.values()),
           },
+          hasActiveRun,
         });
         return;
       }
@@ -1994,6 +2364,7 @@ export const createRequestHandler = async (options?: {
 
         for await (const event of harness.runWithTelemetry({
           task: messageText,
+          conversationId,
           parameters: {
             ...(bodyParameters ?? {}),
             __conversationRecallCorpus: recallCorpus,
@@ -2273,6 +2644,7 @@ export const createRequestHandler = async (options?: {
 
         for await (const event of harness.runWithTelemetry({
           task: cronJob.task,
+          conversationId: conversation.conversationId,
           parameters: { __activeConversationId: conversation.conversationId },
           messages: historyMessages,
           abortSignal: abortController.signal,
@@ -2459,6 +2831,7 @@ export const startDevServer = async (
             let currentText = "";
             for await (const event of harness.runWithTelemetry({
               task: config.task,
+              conversationId: conversation.conversationId,
               parameters: { __activeConversationId: conversation.conversationId },
               messages: [],
             })) {

package/src/init-feature-context.ts

@@ -29,11 +29,15 @@ const summarizeConfig = (config: PonchoConfig | undefined): string[] => {
   const memoryEnabled = config?.storage?.memory?.enabled ?? config?.memory?.enabled ?? false;
   const authRequired = config?.auth?.required ?? false;
   const telemetryEnabled = config?.telemetry?.enabled ?? true;
+  const messagingPlatforms = (config?.messaging ?? []).map((m) => m.platform);
   return [
     `storage: ${provider}`,
     `memory tools: ${memoryEnabled ? "enabled" : "disabled"}`,
     `auth: ${authRequired ? "required" : "not required"}`,
     `telemetry: ${telemetryEnabled ? "enabled" : "disabled"}`,
+    ...(messagingPlatforms.length > 0
+      ? [`messaging: ${messagingPlatforms.join(", ")}`]
+      : []),
   ];
 };
 
@@ -127,6 +131,7 @@ export const consumeFirstRunIntro = async (
     "- **Turn on telemetry**: Track usage with OpenTelemetry/OTLP",
     "- **Add MCP servers**: Connect external tool servers",
     "- **Schedule cron jobs**: Set up recurring tasks in AGENT.md frontmatter",
+    "- **Connect to Slack**: Set up messaging so users can @mention this agent in Slack",
     "",
     "Just let me know what you'd like to work on!\n",
   ].join("\n");

package/src/init-onboarding.ts

@@ -339,12 +339,33 @@ export const buildConfigFromOnboardingAnswers = (
   };
   maybeSet(telemetry, "otlp", answers["telemetry.otlp"]);
 
-  return {
+  const messagingPlatform = String(answers["messaging.platform"] ?? "none");
+
+  const config: PonchoConfig = {
     mcp: [],
     auth,
     storage,
     telemetry,
   };
+
+  if (messagingPlatform !== "none") {
+    const channelConfig: NonNullable<PonchoConfig["messaging"]>[number] = {
+      platform: messagingPlatform as "slack" | "resend",
+    };
+    if (messagingPlatform === "resend") {
+      const mode = String(answers["messaging.resend.mode"] ?? "auto-reply");
+      if (mode === "tool") {
+        channelConfig.mode = "tool";
+      }
+      const recipientsRaw = String(answers["messaging.resend.allowedRecipients"] ?? "");
+      if (recipientsRaw.trim().length > 0) {
+        channelConfig.allowedRecipients = recipientsRaw.split(",").map((s) => s.trim()).filter(Boolean);
+      }
+    }
+    config.messaging = [channelConfig];
+  }
+
+  return config;
 };
 
 export const isDefaultOnboardingConfig = (
@@ -354,7 +375,7 @@ export const isDefaultOnboardingConfig = (
     return true;
   }
   const topLevelKeys = Object.keys(config);
-  const allowedTopLevel = new Set(["mcp", "auth", "storage", "telemetry"]);
+  const allowedTopLevel = new Set(["mcp", "auth", "storage", "telemetry", "messaging"]);
   if (topLevelKeys.some((key) => !allowedTopLevel.has(key))) {
     return false;
   }