@poncho-ai/cli 0.13.0 → 0.14.0

package/src/index.ts

@@ -24,6 +24,7 @@ import {
   resolveStateConfig,
   type CronJobConfig,
   type PonchoConfig,
+  type Conversation,
   type ConversationStore,
   type UploadStore,
 } from "@poncho-ai/harness";
@@ -31,6 +32,7 @@ import type { AgentEvent, FileInput, Message, RunInput } from "@poncho-ai/sdk";
 import { getTextContent } from "@poncho-ai/sdk";
 import {
   AgentBridge,
+  ResendAdapter,
   SlackAdapter,
   type AgentRunner,
   type MessagingAdapter,
@@ -53,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,
@@ -374,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:
@@ -496,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\`:
 
@@ -522,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
 };
 \`\`\`
 
@@ -592,6 +597,26 @@ Connect your agent to Slack so it responds to @mentions:
    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
@@ -1430,21 +1455,188 @@ export const createRequestHandler = async (options?: {
       return { messages: [] };
     },
     async run(conversationId, input) {
-      const output = await harness.runToCompletion({
-        task: input.task,
-        messages: input.messages,
+      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 }];
       });
-      const response = output.result.response ?? "";
 
-      const conversation = await conversationStore.get(conversationId);
-      if (conversation) {
-        conversation.messages = [
-          ...input.messages,
-          { role: "user" as const, content: input.task },
-          { role: "assistant" as const, content: response },
+      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,
+          })),
         ];
-        await conversationStore.update(conversation);
+        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 };
     },
@@ -1475,6 +1667,7 @@ export const createRequestHandler = async (options?: {
           adapter,
           runner: messagingRunner,
           waitUntil: waitUntilHook,
+          ownerId: "local-owner",
         });
         adapter.registerRoutes(messagingRouteRegistrar);
         try {
@@ -1486,6 +1679,37 @@ export const createRequestHandler = async (options?: {
             `  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)}`,
+          );
+        }
       }
     }
   }
@@ -1498,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;
 
@@ -1523,41 +1748,52 @@ 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 === "/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 === "/icon.svg" && request.method === "GET") {
-      response.writeHead(200, { "Content-Type": "image/svg+xml" });
-      response.end(renderIconSvg({ agentName }));
+    if (pathname === "/health" && request.method === "GET") {
+      writeJson(response, 200, { status: "ok" });
       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/openapi.json" && request.method === "GET") {
+      writeJson(response, 200, buildOpenApiSpec({ agentName }));
       return;
     }
 
-    if (pathname === "/health" && request.method === "GET") {
-      writeJson(response, 200, { status: "ok" });
+    if (pathname === "/api/docs" && request.method === "GET") {
+      writeHtml(response, 200, renderApiDocsHtml("/api/openapi.json"));
       return;
     }
 
@@ -1779,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) {
@@ -1841,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;
       }
@@ -2124,6 +2364,7 @@ export const createRequestHandler = async (options?: {
 
         for await (const event of harness.runWithTelemetry({
           task: messageText,
+          conversationId,
           parameters: {
             ...(bodyParameters ?? {}),
             __conversationRecallCorpus: recallCorpus,
@@ -2403,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,
@@ -2589,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-onboarding.ts

@@ -349,7 +349,20 @@ export const buildConfigFromOnboardingAnswers = (
   };
 
   if (messagingPlatform !== "none") {
-    config.messaging = [{ platform: messagingPlatform as "slack" }];
+    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;