stagent 0.5.0 → 0.6.1

package/src/lib/agents/tool-permissions.ts

@@ -0,0 +1,203 @@
+/**
+ * Shared tool permission handling for task-based runtimes.
+ *
+ * Extracted from claude-agent.ts so that all task runtimes (Claude SDK,
+ * Anthropic Direct, OpenAI Direct) can reuse the same HITL permission
+ * logic. Uses DB notification polling — the Inbox UI writes responses.
+ */
+
+import { z } from "zod";
+import { db } from "@/lib/db";
+import { notifications } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import type { CanUseToolPolicy } from "./profiles/types";
+import { isExaTool, isExaReadOnly } from "./browser-mcp";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export const toolPermissionResponseSchema = z.object({
+  behavior: z.enum(["allow", "deny"]),
+  updatedInput: z.unknown().optional(),
+  message: z.string().optional(),
+});
+
+export type ToolPermissionResponse = z.infer<typeof toolPermissionResponseSchema>;
+
+// ── Caches ───────────────────────────────────────────────────────────
+
+const inFlightPermissionRequests = new Map<string, Promise<ToolPermissionResponse>>();
+const settledPermissionRequests = new Map<string, ToolPermissionResponse>();
+
+// ── Response builders ────────────────────────────────────────────────
+
+export function buildAllowedToolPermissionResponse(
+  input: Record<string, unknown>,
+): ToolPermissionResponse {
+  return { behavior: "allow", updatedInput: input };
+}
+
+export function normalizeToolPermissionResponse(
+  response: ToolPermissionResponse,
+  input: Record<string, unknown>,
+): ToolPermissionResponse {
+  if (response.behavior !== "allow" || response.updatedInput !== undefined) {
+    return response;
+  }
+  return { ...response, updatedInput: input };
+}
+
+// ── Cache helpers ────────────────────────────────────────────────────
+
+export function buildPermissionCacheKey(
+  taskId: string,
+  toolName: string,
+  input: Record<string, unknown>,
+): string {
+  return `${taskId}::${toolName}::${JSON.stringify(input)}`;
+}
+
+export function clearPermissionCache(taskId: string) {
+  const prefix = `${taskId}::`;
+
+  for (const key of inFlightPermissionRequests.keys()) {
+    if (key.startsWith(prefix)) inFlightPermissionRequests.delete(key);
+  }
+  for (const key of settledPermissionRequests.keys()) {
+    if (key.startsWith(prefix)) settledPermissionRequests.delete(key);
+  }
+}
+
+// ── DB polling ───────────────────────────────────────────────────────
+
+export async function waitForToolPermissionResponse(
+  notificationId: string,
+): Promise<ToolPermissionResponse> {
+  const deadline = Date.now() + 55_000;
+  const pollInterval = 1500;
+
+  while (Date.now() < deadline) {
+    const [notification] = await db
+      .select()
+      .from(notifications)
+      .where(eq(notifications.id, notificationId));
+
+    if (notification?.response) {
+      try {
+        const parsed = JSON.parse(notification.response);
+        const validated = toolPermissionResponseSchema.safeParse(parsed);
+        if (validated.success) return validated.data;
+        console.error("[tool-permissions] Invalid permission response shape:", validated.error.message);
+        return { behavior: "deny", message: "Invalid response format" };
+      } catch (err) {
+        console.error("[tool-permissions] Failed to parse permission response:", err);
+        return { behavior: "deny", message: "Invalid response format" };
+      }
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+
+  return { behavior: "deny", message: "Permission request timed out" };
+}
+
+// ── Main permission handler ──────────────────────────────────────────
+
+/**
+ * Handle tool permission for task-based runtimes.
+ *
+ * Permission layers:
+ * 1. Profile canUseToolPolicy (autoApprove / autoDeny)
+ * 1.5. External MCP read-only tools (Exa search)
+ * 2. Saved user permissions (settings-based patterns)
+ * 3. Request deduplication cache
+ * 4. DB notification + polling (HITL)
+ */
+export async function handleToolPermission(
+  taskId: string,
+  toolName: string,
+  input: Record<string, unknown>,
+  canUseToolPolicy?: CanUseToolPolicy,
+): Promise<ToolPermissionResponse> {
+  const isQuestion = toolName === "AskUserQuestion";
+
+  // Layer 1: Profile-level canUseToolPolicy — fastest check, no I/O
+  if (!isQuestion && canUseToolPolicy) {
+    if (canUseToolPolicy.autoApprove?.includes(toolName)) {
+      return buildAllowedToolPermissionResponse(input);
+    }
+    if (canUseToolPolicy.autoDeny?.includes(toolName)) {
+      return { behavior: "deny", message: `Profile policy denies ${toolName}` };
+    }
+  }
+
+  // Layer 1.5: External MCP read-only tools — auto-approve without I/O
+  if (!isQuestion && isExaTool(toolName) && isExaReadOnly(toolName)) {
+    return buildAllowedToolPermissionResponse(input);
+  }
+
+  // Layer 2: Saved user permissions — skip notification for pre-approved tools
+  if (!isQuestion) {
+    const { isToolAllowed } = await import("@/lib/settings/permissions");
+    if (await isToolAllowed(toolName, input)) {
+      return buildAllowedToolPermissionResponse(input);
+    }
+  }
+
+  // Layer 3 + 4: Deduplication cache + DB notification
+  if (!isQuestion) {
+    const cacheKey = buildPermissionCacheKey(taskId, toolName, input);
+    const settledResponse = settledPermissionRequests.get(cacheKey);
+    if (settledResponse) {
+      return normalizeToolPermissionResponse(settledResponse, input);
+    }
+
+    const pendingRequest = inFlightPermissionRequests.get(cacheKey);
+    if (pendingRequest) return pendingRequest;
+
+    const requestPromise = (async () => {
+      const notificationId = crypto.randomUUID();
+
+      await db.insert(notifications).values({
+        id: notificationId,
+        taskId,
+        type: "permission_required",
+        title: `Permission required: ${toolName}`,
+        body: JSON.stringify(input).slice(0, 1000),
+        toolName,
+        toolInput: JSON.stringify(input),
+        createdAt: new Date(),
+      });
+
+      const response = normalizeToolPermissionResponse(
+        await waitForToolPermissionResponse(notificationId),
+        input,
+      );
+      settledPermissionRequests.set(cacheKey, response);
+      return response;
+    })();
+
+    inFlightPermissionRequests.set(cacheKey, requestPromise);
+
+    try {
+      return await requestPromise;
+    } finally {
+      inFlightPermissionRequests.delete(cacheKey);
+    }
+  }
+
+  // AskUserQuestion fallback — always creates notification
+  const notificationId = crypto.randomUUID();
+
+  await db.insert(notifications).values({
+    id: notificationId,
+    taskId,
+    type: isQuestion ? "agent_message" : "permission_required",
+    title: isQuestion ? "Agent has a question" : `Permission required: ${toolName}`,
+    body: JSON.stringify(input).slice(0, 1000),
+    toolName,
+    toolInput: JSON.stringify(input),
+    createdAt: new Date(),
+  });
+
+  return waitForToolPermissionResponse(notificationId);
+}

package/src/lib/channels/gateway.ts

@@ -0,0 +1,321 @@
+/**
+ * Channel Gateway — bridges inbound channel messages to the chat engine.
+ *
+ * Flow: Inbound webhook → gateway → sendMessage() (existing chat engine)
+ *       → accumulate deltas → sendReply() back to channel thread.
+ */
+
+import { randomUUID } from "crypto";
+import { db } from "@/lib/db";
+import { channelConfigs } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import {
+  getBindingByConfigAndThread,
+  createBinding,
+  setPendingRequest,
+} from "@/lib/data/channel-bindings";
+import { createConversation } from "@/lib/data/chat";
+import { sendMessage } from "@/lib/chat/engine";
+import {
+  resolvePendingRequest,
+  type ToolPermissionResponse,
+} from "@/lib/chat/permission-bridge";
+import { getChannelAdapter } from "./registry";
+import type { ChannelMessage, InboundMessage } from "./types";
+
+// ── Turn lock ──────────────────────────────────────────────────────────
+
+/** In-memory lock: one turn per conversation at a time. */
+const activeTurns = new Map<string, Promise<void>>();
+
+// ── Permission reply parsing ───────────────────────────────────────────
+
+const APPROVE_PATTERNS = /^(approve|yes|allow|ok|y)$/i;
+const DENY_PATTERNS = /^(deny|no|reject|n)$/i;
+const ALWAYS_ALLOW_PATTERNS = /^(always\s*allow)$/i;
+
+function parsePermissionReply(
+  text: string
+): ToolPermissionResponse | null {
+  const trimmed = text.trim();
+  if (ALWAYS_ALLOW_PATTERNS.test(trimmed)) {
+    return { behavior: "allow" };
+  }
+  if (APPROVE_PATTERNS.test(trimmed)) {
+    return { behavior: "allow" };
+  }
+  if (DENY_PATTERNS.test(trimmed)) {
+    return { behavior: "deny" };
+  }
+  return null;
+}
+
+// ── Default runtime/model for channel conversations ────────────────────
+
+const DEFAULT_RUNTIME = "claude-code";
+const DEFAULT_MODEL = "sonnet";
+
+// ── Public API ─────────────────────────────────────────────────────────
+
+export interface HandleInboundParams {
+  channelConfigId: string;
+  message: InboundMessage;
+}
+
+export interface GatewayResult {
+  success: boolean;
+  conversationId?: string;
+  error?: string;
+}
+
+/**
+ * Handle an inbound message from a channel.
+ *
+ * 1. Resolve or create binding (channel+thread → conversation)
+ * 2. Check turn lock
+ * 3. If pending permission request, treat as permission reply
+ * 4. Otherwise, feed to chat engine and send response back
+ */
+export async function handleInboundMessage(
+  params: HandleInboundParams
+): Promise<GatewayResult> {
+  const { channelConfigId, message } = params;
+
+  // Fetch channel config
+  const config = await db
+    .select()
+    .from(channelConfigs)
+    .where(eq(channelConfigs.id, channelConfigId))
+    .get();
+
+  if (!config) {
+    return { success: false, error: "Channel config not found" };
+  }
+  if (config.status === "disabled") {
+    return { success: false, error: "Channel is disabled" };
+  }
+  if (config.direction !== "bidirectional") {
+    return { success: false, error: "Channel is outbound-only" };
+  }
+
+  // Skip bot messages to prevent loops
+  if (message.isBot) {
+    return { success: true };
+  }
+
+  // Resolve or create binding
+  let binding = getBindingByConfigAndThread(
+    channelConfigId,
+    message.externalThreadId ?? null
+  );
+
+  if (!binding) {
+    // Create new conversation + binding
+    const conversation = await createConversation({
+      runtimeId: DEFAULT_RUNTIME,
+      modelId: DEFAULT_MODEL,
+      title: `Channel: ${config.name}`,
+    });
+
+    const bindingId = randomUUID();
+    const now = new Date();
+    createBinding({
+      id: bindingId,
+      channelConfigId,
+      conversationId: conversation.id,
+      externalThreadId: message.externalThreadId ?? null,
+      runtimeId: DEFAULT_RUNTIME,
+      modelId: DEFAULT_MODEL,
+      status: "active",
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    binding = {
+      id: bindingId,
+      channelConfigId,
+      conversationId: conversation.id,
+      externalThreadId: message.externalThreadId ?? null,
+      runtimeId: DEFAULT_RUNTIME,
+      modelId: DEFAULT_MODEL,
+      profileId: null,
+      status: "active" as const,
+      pendingRequestId: null,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+
+  const conversationId = binding.conversationId;
+
+  // Handle pending permission request
+  if (binding.pendingRequestId) {
+    const response = parsePermissionReply(message.text);
+    if (response) {
+      resolvePendingRequest(binding.pendingRequestId, response);
+      setPendingRequest(binding.id, null);
+      return { success: true, conversationId };
+    }
+    // Not a valid permission reply — send guidance
+    await sendChannelReply(
+      config,
+      message.externalThreadId,
+      "Please reply with **approve** or **deny** to the pending permission request."
+    );
+    return { success: true, conversationId };
+  }
+
+  // Check turn lock
+  if (activeTurns.has(conversationId)) {
+    await sendChannelReply(
+      config,
+      message.externalThreadId,
+      "Still processing your previous message. Please wait..."
+    );
+    return { success: true, conversationId };
+  }
+
+  // Process the turn
+  const turnPromise = processTurn(
+    config,
+    binding,
+    message
+  );
+  activeTurns.set(conversationId, turnPromise);
+
+  try {
+    await turnPromise;
+  } finally {
+    activeTurns.delete(conversationId);
+  }
+
+  return { success: true, conversationId };
+}
+
+// ── Turn processing ────────────────────────────────────────────────────
+
+async function processTurn(
+  config: typeof channelConfigs.$inferSelect,
+  binding: {
+    id: string;
+    conversationId: string;
+    externalThreadId: string | null;
+  },
+  message: InboundMessage
+): Promise<void> {
+  let fullResponse = "";
+
+  try {
+    for await (const event of sendMessage(binding.conversationId, message.text)) {
+      switch (event.type) {
+        case "delta":
+          fullResponse += event.content;
+          break;
+
+        case "permission_request": {
+          // Send permission prompt to channel
+          const prompt = formatPermissionPrompt(
+            event.toolName,
+            event.toolInput
+          );
+          await sendChannelReply(config, binding.externalThreadId, prompt);
+
+          // Track pending request on binding
+          setPendingRequest(binding.id, event.requestId);
+
+          // The stream is now blocked waiting for permission resolution.
+          // The next inbound message will resolve it via handleInboundMessage.
+          // We continue iterating — the generator will yield once unblocked.
+          break;
+        }
+
+        case "question": {
+          // Format questions for channel display
+          const questionText = event.questions
+            .map((q, i) => {
+              let line = `**${q.header || `Question ${i + 1}`}**: ${q.question}`;
+              if (q.options) {
+                line += "\n" + q.options.map((o) => `  - ${o.label}: ${o.description}`).join("\n");
+              }
+              return line;
+            })
+            .join("\n\n");
+          await sendChannelReply(config, binding.externalThreadId, questionText);
+          break;
+        }
+
+        case "error":
+          fullResponse = `Error: ${event.message}`;
+          break;
+
+        case "done":
+          // Stream complete — break out of loop
+          break;
+
+        // Ignore: status, screenshot events (not meaningful in channel context)
+        default:
+          break;
+      }
+
+      if (event.type === "done" || event.type === "error") break;
+    }
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    fullResponse = `Error processing message: ${errorMsg}`;
+    console.error(`[gateway] Error in processTurn for ${binding.conversationId}:`, err);
+  }
+
+  // Send accumulated response back to channel
+  if (fullResponse.trim()) {
+    await sendChannelReply(config, binding.externalThreadId, fullResponse);
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+async function sendChannelReply(
+  config: typeof channelConfigs.$inferSelect,
+  threadId: string | null | undefined,
+  body: string
+): Promise<void> {
+  const adapter = getChannelAdapter(config.channelType);
+  let parsedConfig: Record<string, unknown>;
+  try {
+    parsedConfig = JSON.parse(config.config) as Record<string, unknown>;
+  } catch {
+    console.error(`[gateway] Invalid config JSON for channel ${config.id}`);
+    return;
+  }
+
+  const message: ChannelMessage = {
+    subject: "",
+    body,
+    format: "markdown",
+  };
+
+  // Prefer sendReply (thread-aware) if available, otherwise fall back to send
+  if (adapter.sendReply && threadId) {
+    await adapter.sendReply(message, parsedConfig, threadId);
+  } else {
+    await adapter.send(message, parsedConfig);
+  }
+}
+
+function formatPermissionPrompt(
+  toolName: string,
+  toolInput: Record<string, unknown>
+): string {
+  const inputPreview = JSON.stringify(toolInput, null, 2).slice(0, 500);
+  return [
+    `**Permission required:** \`${toolName}\``,
+    "",
+    "```json",
+    inputPreview,
+    "```",
+    "",
+    "Reply with:",
+    "- **approve** — allow this action",
+    "- **deny** — block this action",
+    "- **always allow** — allow this tool permanently",
+  ].join("\n");
+}