@poncho-ai/cli 0.13.0 → 0.14.1

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
@@ -1290,16 +1315,6 @@ export const createRequestHandler = async (options?: {
     runId: string | null;
   };
   const activeConversationRuns = new Map<string, ActiveConversationRun>();
-  type PendingApproval = {
-    ownerId: string;
-    runId: string;
-    conversationId: string | null;
-    tool: string;
-    input: Record<string, unknown>;
-    resolve: (approved: boolean) => void;
-  };
-  const pendingApprovals = new Map<string, PendingApproval>();
-
   // Per-conversation event streaming: buffer events and allow SSE subscribers
   type ConversationEventStream = {
     buffer: AgentEvent[];
@@ -1339,55 +1354,19 @@ export const createRequestHandler = async (options?: {
       setTimeout(() => conversationEventStreams.delete(conversationId), 30_000);
     }
   };
-  const persistConversationPendingApprovals = async (conversationId: string): Promise<void> => {
-    const conversation = await conversationStore.get(conversationId);
-    if (!conversation) {
-      return;
-    }
-    conversation.pendingApprovals = Array.from(pendingApprovals.entries())
-      .filter(
-        ([, pending]) =>
-          pending.ownerId === conversation.ownerId && pending.conversationId === conversationId,
-      )
-      .map(([approvalId, pending]) => ({
-        approvalId,
-        runId: pending.runId,
-        tool: pending.tool,
-        input: pending.input,
-      }));
-    await conversationStore.update(conversation);
-  };
   const clearPendingApprovalsForConversation = async (conversationId: string): Promise<void> => {
-    for (const [approvalId, pending] of pendingApprovals.entries()) {
-      if (pending.conversationId !== conversationId) {
-        continue;
-      }
-      pendingApprovals.delete(approvalId);
-      pending.resolve(false);
+    const conversation = await conversationStore.get(conversationId);
+    if (!conversation) return;
+    if (Array.isArray(conversation.pendingApprovals) && conversation.pendingApprovals.length > 0) {
+      conversation.pendingApprovals = [];
+      await conversationStore.update(conversation);
     }
-    await persistConversationPendingApprovals(conversationId);
   };
   const uploadStore = await createUploadStore(config?.uploads, workingDir);
   const harness = new AgentHarness({
     workingDir,
     environment: resolveHarnessEnvironment(),
     uploadStore,
-    approvalHandler: async (request) =>
-      new Promise<boolean>((resolveApproval) => {
-        const ownerIdForRun = runOwners.get(request.runId) ?? "local-owner";
-        const conversationIdForRun = runConversations.get(request.runId) ?? null;
-        pendingApprovals.set(request.approvalId, {
-          ownerId: ownerIdForRun,
-          runId: request.runId,
-          conversationId: conversationIdForRun,
-          tool: request.tool,
-          input: request.input,
-          resolve: resolveApproval,
-        });
-        if (conversationIdForRun) {
-          void persistConversationPendingApprovals(conversationIdForRun);
-        }
-      }),
   });
   await harness.initialize();
   const telemetry = new TelemetryEmitter(config?.telemetry);
@@ -1396,6 +1375,186 @@ export const createRequestHandler = async (options?: {
     workingDir,
     agentId: identity.id,
   });
+  // ---------------------------------------------------------------------------
+  // Resume a run from a persisted checkpoint after approval.
+  // Processes events the same way the interactive/messaging runners do.
+  // ---------------------------------------------------------------------------
+  const resumeRunFromCheckpoint = async (
+    conversationId: string,
+    conversation: Conversation,
+    checkpoint: NonNullable<Conversation["pendingApprovals"]>[number],
+    toolResults: Array<{ callId: string; toolName: string; result?: unknown; error?: string }>,
+  ): Promise<void> => {
+    const abortController = new AbortController();
+    activeConversationRuns.set(conversationId, {
+      ownerId: conversation.ownerId,
+      abortController,
+      runId: null,
+    });
+    let latestRunId = conversation.runtimeRunId ?? "";
+    let assistantResponse = "";
+    const toolTimeline: string[] = [];
+    const sections: Array<{ type: "text" | "tools"; content: string | string[] }> = [];
+    let currentText = "";
+    let currentTools: string[] = [];
+    let checkpointedRun = false;
+
+    const baseMessages = checkpoint.baseMessageCount != null
+      ? conversation.messages.slice(0, checkpoint.baseMessageCount)
+      : [];
+    const fullCheckpointMessages = [...baseMessages, ...checkpoint.checkpointMessages!];
+
+    try {
+      for await (const event of harness.continueFromToolResult({
+        messages: fullCheckpointMessages,
+        toolResults,
+        conversationId,
+        abortSignal: abortController.signal,
+      })) {
+        if (event.type === "run:started") {
+          latestRunId = event.runId;
+          runOwners.set(event.runId, conversation.ownerId);
+          runConversations.set(event.runId, conversationId);
+          const active = activeConversationRuns.get(conversationId);
+          if (active && active.abortController === abortController) {
+            active.runId = event.runId;
+          }
+        }
+        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 === "tool:approval:required") {
+          const toolText = `- approval required \`${event.tool}\``;
+          toolTimeline.push(toolText);
+          currentTools.push(toolText);
+        }
+        if (event.type === "tool:approval:checkpoint") {
+          const conv = await conversationStore.get(conversationId);
+          if (conv) {
+            conv.pendingApprovals = [{
+              approvalId: event.approvalId,
+              runId: latestRunId,
+              tool: event.tool,
+              toolCallId: event.toolCallId,
+              input: event.input,
+              checkpointMessages: [...fullCheckpointMessages, ...event.checkpointMessages],
+              baseMessageCount: 0,
+              pendingToolCalls: event.pendingToolCalls,
+            }];
+            conv.updatedAt = Date.now();
+            await conversationStore.update(conv);
+          }
+          checkpointedRun = true;
+        }
+        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}]`;
+        }
+        await telemetry.emit(event);
+        broadcastEvent(conversationId, event);
+      }
+    } catch (err) {
+      console.error("[resume-run] error:", err instanceof Error ? err.message : err);
+      assistantResponse = assistantResponse || `[Error: ${err instanceof Error ? err.message : "Unknown error"}]`;
+    }
+
+    if (currentTools.length > 0) {
+      sections.push({ type: "tools", content: currentTools });
+    }
+    if (currentText.length > 0) {
+      sections.push({ type: "text", content: currentText });
+    }
+
+    if (!checkpointedRun) {
+      const conv = await conversationStore.get(conversationId);
+      if (conv) {
+        const prevMessages = conv.messages;
+        const hasAssistantContent =
+          assistantResponse.length > 0 || toolTimeline.length > 0 || sections.length > 0;
+        if (hasAssistantContent) {
+          const lastMsg = prevMessages[prevMessages.length - 1];
+          if (lastMsg && lastMsg.role === "assistant" && lastMsg.metadata) {
+            const existingToolActivity = (lastMsg.metadata as Record<string, unknown>).toolActivity;
+            const existingSections = (lastMsg.metadata as Record<string, unknown>).sections;
+            const mergedTimeline = [
+              ...(Array.isArray(existingToolActivity) ? existingToolActivity as string[] : []),
+              ...toolTimeline,
+            ];
+            const mergedSections = [
+              ...(Array.isArray(existingSections) ? existingSections as Array<{ type: "text" | "tools"; content: string | string[] }> : []),
+              ...sections,
+            ];
+            const mergedText = (typeof lastMsg.content === "string" ? lastMsg.content : "") + assistantResponse;
+            conv.messages = [
+              ...prevMessages.slice(0, -1),
+              {
+                role: "assistant" as const,
+                content: mergedText,
+                metadata: {
+                  toolActivity: mergedTimeline,
+                  sections: mergedSections.length > 0 ? mergedSections : undefined,
+                } as Message["metadata"],
+              },
+            ];
+          } else {
+            conv.messages = [
+              ...prevMessages,
+              {
+                role: "assistant" as const,
+                content: assistantResponse,
+                metadata: (toolTimeline.length > 0 || sections.length > 0
+                  ? { toolActivity: toolTimeline, sections: sections.length > 0 ? sections : undefined }
+                  : undefined) as Message["metadata"],
+              },
+            ];
+          }
+        }
+        conv.runtimeRunId = latestRunId || conv.runtimeRunId;
+        conv.pendingApprovals = [];
+        conv.updatedAt = Date.now();
+        await conversationStore.update(conv);
+      }
+    }
+
+    finishConversationStream(conversationId);
+    activeConversationRuns.delete(conversationId);
+    if (latestRunId) {
+      runOwners.delete(latestRunId);
+      runConversations.delete(latestRunId);
+    }
+    console.log("[resume-run] complete for", conversationId);
+  };
+
   // ---------------------------------------------------------------------------
   // Messaging adapters (Slack, etc.) — routes bypass Poncho auth; each
   // adapter handles its own request verification (e.g. Slack signing secret).
@@ -1430,21 +1589,192 @@ 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 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 = "";
+      let checkpointedRun = false;
+
+      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();
+          }
+          if (event.type === "tool:approval:checkpoint") {
+            await updateConversation((c) => {
+              c.messages = buildMessages();
+              c.pendingApprovals = [{
+                approvalId: event.approvalId,
+                runId: latestRunId,
+                tool: event.tool,
+                toolCallId: event.toolCallId,
+                input: event.input,
+                checkpointMessages: event.checkpointMessages,
+                baseMessageCount: historyMessages.length,
+                pendingToolCalls: event.pendingToolCalls,
+              }];
+            });
+            checkpointedRun = true;
+          }
+          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 = "";
+      }
+
+      if (!checkpointedRun) {
+        await updateConversation((c) => {
+          c.messages = buildMessages();
+          c.runtimeRunId = latestRunId || c.runtimeRunId;
+          c.pendingApprovals = [];
+        });
+      }
+      finishConversationStream(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 +1805,7 @@ export const createRequestHandler = async (options?: {
           adapter,
           runner: messagingRunner,
           waitUntil: waitUntilHook,
+          ownerId: "local-owner",
         });
         adapter.registerRoutes(messagingRouteRegistrar);
         try {
@@ -1486,6 +1817,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 +1860,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 +1886,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;
     }
 
@@ -1696,6 +2070,7 @@ export const createRequestHandler = async (options?: {
           createdAt: conversation.createdAt,
           updatedAt: conversation.updatedAt,
           messageCount: conversation.messages.length,
+          hasPendingApprovals: Array.isArray(conversation.pendingApprovals) && conversation.pendingApprovals.length > 0,
         })),
       });
       return;
@@ -1721,40 +2096,93 @@ export const createRequestHandler = async (options?: {
     const approvalMatch = pathname.match(/^\/api\/approvals\/([^/]+)$/);
     if (approvalMatch && request.method === "POST") {
       const approvalId = decodeURIComponent(approvalMatch[1] ?? "");
-      const pending = pendingApprovals.get(approvalId);
-      if (!pending || pending.ownerId !== ownerId) {
-        // If the server restarted, an old pending approval can remain in
-        // conversation history without an active resolver. Prune stale entries.
-        const conversations = await conversationStore.list(ownerId);
-        let prunedStale = false;
-        for (const conversation of conversations) {
-          if (!Array.isArray(conversation.pendingApprovals)) {
-            continue;
-          }
-          const next = conversation.pendingApprovals.filter(
-            (approval) => approval.approvalId !== approvalId,
-          );
-          if (next.length !== conversation.pendingApprovals.length) {
-            conversation.pendingApprovals = next;
-            await conversationStore.update(conversation);
-            prunedStale = true;
-          }
+      const body = (await readRequestBody(request)) as { approved?: boolean };
+      const approved = body.approved === true;
+
+      // Find the approval in the conversation store (checkpoint-based flow)
+      const conversations = await conversationStore.list(ownerId);
+      let foundConversation: Conversation | undefined;
+      let foundApproval: NonNullable<Conversation["pendingApprovals"]>[number] | undefined;
+      for (const conv of conversations) {
+        if (!Array.isArray(conv.pendingApprovals)) continue;
+        const match = conv.pendingApprovals.find(a => a.approvalId === approvalId);
+        if (match) {
+          foundConversation = conv;
+          foundApproval = match;
+          break;
         }
+      }
+
+      if (!foundConversation || !foundApproval) {
         writeJson(response, 404, {
           code: "APPROVAL_NOT_FOUND",
-          message: prunedStale
-            ? "Approval request is no longer active"
-            : "Approval request not found",
+          message: "Approval request not found",
         });
         return;
       }
-      const body = (await readRequestBody(request)) as { approved?: boolean };
-      const approved = body.approved === true;
-      pendingApprovals.delete(approvalId);
-      if (pending.conversationId) {
-        await persistConversationPendingApprovals(pending.conversationId);
+
+      const conversationId = foundConversation.conversationId;
+
+      if (!foundApproval.checkpointMessages || !foundApproval.toolCallId) {
+        // Legacy approval without checkpoint data — cannot resume
+        foundConversation.pendingApprovals = (foundConversation.pendingApprovals ?? [])
+          .filter(a => a.approvalId !== approvalId);
+        await conversationStore.update(foundConversation);
+        writeJson(response, 404, {
+          code: "APPROVAL_NOT_FOUND",
+          message: "Approval request is no longer active (no checkpoint data)",
+        });
+        return;
       }
-      pending.resolve(approved);
+
+      // Clear this approval from the conversation before resuming
+      foundConversation.pendingApprovals = (foundConversation.pendingApprovals ?? [])
+        .filter(a => a.approvalId !== approvalId);
+      await conversationStore.update(foundConversation);
+
+      // Initialize the event stream so the web UI can connect immediately
+      broadcastEvent(conversationId,
+        approved
+          ? { type: "tool:approval:granted", approvalId }
+          : { type: "tool:approval:denied", approvalId },
+      );
+
+      // Resume the run asynchronously (tool execution + continuation)
+      void (async () => {
+        let toolResults: Array<{ callId: string; toolName: string; result?: unknown; error?: string }>;
+        if (approved) {
+          const toolContext = {
+            runId: foundApproval.runId,
+            agentId: identity.id,
+            step: 0,
+            workingDir,
+            parameters: {},
+          };
+          const execResults = await harness.executeTools(
+            [{ id: foundApproval.toolCallId!, name: foundApproval.tool, input: foundApproval.input }],
+            toolContext,
+          );
+          toolResults = execResults.map(r => ({
+            callId: r.callId,
+            toolName: r.tool,
+            result: r.output,
+            error: r.error,
+          }));
+        } else {
+          toolResults = [{
+            callId: foundApproval.toolCallId!,
+            toolName: foundApproval.tool,
+            error: "Tool execution denied by user",
+          }];
+        }
+        await resumeRunFromCheckpoint(
+          conversationId,
+          foundConversation!,
+          foundApproval!,
+          toolResults,
+        );
+      })();
+
       writeJson(response, 200, { ok: true, approvalId, approved });
       return;
     }
@@ -1779,18 +2207,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) {
@@ -1819,33 +2248,21 @@ export const createRequestHandler = async (options?: {
       }
       if (request.method === "GET") {
         const storedPending = Array.isArray(conversation.pendingApprovals)
-          ? conversation.pendingApprovals
+          ? conversation.pendingApprovals.map(a => ({
+              approvalId: a.approvalId,
+              runId: a.runId,
+              tool: a.tool,
+              input: a.input,
+            }))
           : [];
-        const livePending = Array.from(pendingApprovals.entries())
-          .filter(
-            ([, pending]) =>
-              pending.ownerId === ownerId && pending.conversationId === conversationId,
-          )
-          .map(([approvalId, pending]) => ({
-            approvalId,
-            runId: pending.runId,
-            tool: pending.tool,
-            input: pending.input,
-          }));
-        const mergedPendingById = new Map<string, (typeof livePending)[number]>();
-        for (const approval of storedPending) {
-          if (approval && typeof approval.approvalId === "string") {
-            mergedPendingById.set(approval.approvalId, approval);
-          }
-        }
-        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()),
+            pendingApprovals: storedPending,
           },
+          hasActiveRun,
         });
         return;
       }
@@ -2029,6 +2446,7 @@ export const createRequestHandler = async (options?: {
       let currentText = "";
       let currentTools: string[] = [];
       let runCancelled = false;
+      let checkpointedRun = false;
       let userContent: Message["content"] = messageText;
       if (files.length > 0) {
         try {
@@ -2124,6 +2542,7 @@ export const createRequestHandler = async (options?: {
 
         for await (const event of harness.runWithTelemetry({
           task: messageText,
+          conversationId,
           parameters: {
             ...(bodyParameters ?? {}),
             __conversationRecallCorpus: recallCorpus,
@@ -2183,17 +2602,40 @@ export const createRequestHandler = async (options?: {
             currentTools.push(toolText);
             await persistDraftAssistantTurn();
           }
-          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 === "tool:approval:checkpoint") {
+            const checkpointSections = [...sections];
+            if (currentTools.length > 0) {
+              checkpointSections.push({ type: "tools", content: [...currentTools] });
+            }
+            if (currentText.length > 0) {
+              checkpointSections.push({ type: "text", content: currentText });
+            }
+            conversation.messages = [
+              ...historyMessages,
+              { role: "user", content: userContent },
+              ...(assistantResponse.length > 0 || toolTimeline.length > 0 || checkpointSections.length > 0
+                ? [{
+                    role: "assistant" as const,
+                    content: assistantResponse,
+                    metadata: (toolTimeline.length > 0 || checkpointSections.length > 0
+                      ? { toolActivity: [...toolTimeline], sections: checkpointSections.length > 0 ? checkpointSections : undefined }
+                      : undefined) as Message["metadata"],
+                  }]
+                : []),
+            ];
+            conversation.pendingApprovals = [{
+              approvalId: event.approvalId,
+              runId: latestRunId,
+              tool: event.tool,
+              toolCallId: event.toolCallId,
+              input: event.input,
+              checkpointMessages: event.checkpointMessages,
+              baseMessageCount: historyMessages.length,
+              pendingToolCalls: event.pendingToolCalls,
+            }];
+            conversation.updatedAt = Date.now();
+            await conversationStore.update(conversation);
+            checkpointedRun = true;
           }
           if (
             event.type === "run:completed" &&
@@ -2218,29 +2660,31 @@ export const createRequestHandler = async (options?: {
         if (currentText.length > 0) {
           sections.push({ type: "text", content: currentText });
         }
-        const hasAssistantContent =
-          assistantResponse.length > 0 || toolTimeline.length > 0 || sections.length > 0;
-        conversation.messages = hasAssistantContent
-          ? [
-              ...historyMessages,
-              { role: "user", content: userContent },
-              {
-                role: "assistant",
-                content: assistantResponse,
-                metadata:
-                  toolTimeline.length > 0 || sections.length > 0
-                    ? ({
-                        toolActivity: toolTimeline,
-                        sections: sections.length > 0 ? sections : undefined,
-                      } as Message["metadata"])
-                    : undefined,
-              },
-            ]
-          : [...historyMessages, { role: "user", content: userContent }];
-        conversation.runtimeRunId = latestRunId || conversation.runtimeRunId;
-        conversation.pendingApprovals = [];
-        conversation.updatedAt = Date.now();
-        await conversationStore.update(conversation);
+        if (!checkpointedRun) {
+          const hasAssistantContent =
+            assistantResponse.length > 0 || toolTimeline.length > 0 || sections.length > 0;
+          conversation.messages = hasAssistantContent
+            ? [
+                ...historyMessages,
+                { role: "user", content: userContent },
+                {
+                  role: "assistant",
+                  content: assistantResponse,
+                  metadata:
+                    toolTimeline.length > 0 || sections.length > 0
+                      ? ({
+                          toolActivity: toolTimeline,
+                          sections: sections.length > 0 ? sections : undefined,
+                        } as Message["metadata"])
+                      : undefined,
+                },
+              ]
+            : [...historyMessages, { role: "user", content: userContent }];
+          conversation.runtimeRunId = latestRunId || conversation.runtimeRunId;
+          conversation.pendingApprovals = [];
+          conversation.updatedAt = Date.now();
+          await conversationStore.update(conversation);
+        }
       } catch (error) {
         if (abortController.signal.aborted || runCancelled) {
           const fallbackSections = [...sections];
@@ -2318,7 +2762,6 @@ export const createRequestHandler = async (options?: {
           activeConversationRuns.delete(conversationId);
         }
         finishConversationStream(conversationId);
-        await persistConversationPendingApprovals(conversationId);
         if (latestRunId) {
           runOwners.delete(latestRunId);
           runConversations.delete(latestRunId);
@@ -2403,6 +2846,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 +3033,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: [],
             })) {
@@ -2775,44 +3220,10 @@ export const runInteractive = async (
   dotenv.config({ path: resolve(workingDir, ".env") });
   const config = await loadPonchoConfig(workingDir);
 
-  // Approval bridge: the harness calls this handler which creates a pending
-  // promise. The Ink UI picks up the pending request and shows a Y/N prompt.
-  // The user's response resolves the promise.
-  type ApprovalRequest = {
-    tool: string;
-    input: Record<string, unknown>;
-    approvalId: string;
-    resolve: (approved: boolean) => void;
-  };
-  let pendingApproval: ApprovalRequest | null = null;
-  let onApprovalRequest: ((req: ApprovalRequest) => void) | null = null;
-
-  const approvalHandler = async (request: {
-    tool: string;
-    input: Record<string, unknown>;
-    runId: string;
-    step: number;
-    approvalId: string;
-  }): Promise<boolean> => {
-    return new Promise<boolean>((resolveApproval) => {
-      const req: ApprovalRequest = {
-        tool: request.tool,
-        input: request.input,
-        approvalId: request.approvalId,
-        resolve: resolveApproval,
-      };
-      pendingApproval = req;
-      if (onApprovalRequest) {
-        onApprovalRequest(req);
-      }
-    });
-  };
-
   const uploadStore = await createUploadStore(config?.uploads, workingDir);
   const harness = new AgentHarness({
     workingDir,
     environment: resolveHarnessEnvironment(),
-    approvalHandler,
     uploadStore,
   });
   await harness.initialize();
@@ -2826,7 +3237,6 @@ export const runInteractive = async (
         workingDir: string;
         config?: PonchoConfig;
         conversationStore: ConversationStore;
-        onSetApprovalCallback?: (cb: (req: ApprovalRequest) => void) => void;
       }) => Promise<void>
     )({
       harness,
@@ -2837,13 +3247,6 @@ export const runInteractive = async (
         workingDir,
         agentId: identity.id,
       }),
-      onSetApprovalCallback: (cb: (req: ApprovalRequest) => void) => {
-        onApprovalRequest = cb;
-        // If there's already a pending request, fire it immediately
-        if (pendingApproval) {
-          cb(pendingApproval);
-        }
-      },
     });
   } finally {
     await harness.shutdown();