@agent-native/dispatch 0.9.2 → 0.10.0

package/src/actions/provider-api-docs.ts

@@ -1,25 +1,23 @@
 import { defineAction } from "@agent-native/core";
 import { z } from "zod";
-import {
-  DISPATCH_PROVIDER_API_IDS,
-  fetchProviderApiDocs,
-} from "../server/lib/provider-api.js";
-
-const ProviderSchema = z.enum(DISPATCH_PROVIDER_API_IDS);
+import { fetchProviderApiDocs } from "../server/lib/provider-api.js";
 
 export default defineAction({
   description:
-    "Inspect provider API docs/spec metadata, or fetch a registered provider docs/spec URL. Use this before arbitrary provider-api-request calls when the exact endpoint, filter operator, payload shape, pagination, or API version is uncertain.",
+    "Inspect provider API docs/spec metadata, or fetch ANY public API documentation page, OpenAPI spec, changelog, or web page. Registered docs/spec URLs from provider-api-catalog are curated starting points, but any public https/http URL is allowed. Use web-search to find documentation URLs first when uncertain, then fetch them here. SSRF guard still applies — private/internal addresses are blocked.",
   schema: z.object({
-    provider: ProviderSchema.describe(
-      "Provider whose API docs/spec to inspect.",
-    ),
+    provider: z
+      .string()
+      .min(1)
+      .describe(
+        "Provider whose API docs/spec to inspect. Can be a built-in provider id or a custom provider id registered via provider-api-register.",
+      ),
     url: z
       .string()
       .url()
       .optional()
       .describe(
-        "Optional docs/spec URL from provider-api-catalog to fetch. Only registered docs/spec origins are allowed.",
+        "Optional URL to fetch. Can be any public https/http URL — API documentation pages, OpenAPI specs, changelogs, README files, etc. Registered docs/spec URLs from provider-api-catalog are curated starting points.",
       ),
     maxBytes: z.coerce
       .number()

package/src/actions/provider-api-register.ts

@@ -0,0 +1,198 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import {
+  upsertCustomProvider,
+  deleteCustomProvider,
+  listCustomProviders,
+  getCustomProvider,
+} from "@agent-native/core/provider-api";
+import { getCredentialContext } from "@agent-native/core/server";
+
+const AuthSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("none"),
+  }),
+  z.object({
+    type: z.literal("bearer"),
+    credentialKey: z
+      .string()
+      .min(1)
+      .describe(
+        "Name of the credential key (e.g. MY_API_TOKEN). Must already be saved via app secrets — this action never accepts secret values.",
+      ),
+  }),
+  z.object({
+    type: z.literal("basic"),
+    usernameKey: z
+      .string()
+      .min(1)
+      .describe("Credential key name for the username/login."),
+    passwordKey: z
+      .string()
+      .min(1)
+      .describe("Credential key name for the password/secret."),
+  }),
+  z.object({
+    type: z.literal("api-key-header"),
+    credentialKey: z
+      .string()
+      .min(1)
+      .describe("Credential key name for the API key value."),
+    headerName: z
+      .string()
+      .min(1)
+      .describe("HTTP header name to send the key in (e.g. X-Api-Key)."),
+  }),
+]);
+
+export default defineAction({
+  description: `Register or update a custom API provider so the agent can call it via provider-api-request and look up its docs via provider-api-docs.
+
+IMPORTANT — credentials:
+- This action stores only credential KEY NAMES, never secret values.
+- If the required API key is not yet saved, instruct the user to add it via app Settings → Keys, or use the create-vault-secret action, before calling this action.
+- Supported auth kinds: none, bearer, basic, api-key-header.
+  google-service-account and oauth-bearer are NOT supported for custom providers.
+
+After registration the provider appears in provider-api-catalog and can be used with provider-api-request.`,
+  schema: z.object({
+    operation: z
+      .enum(["upsert", "delete", "list", "get"])
+      .default("upsert")
+      .describe(
+        "Operation: upsert (create or update), delete (remove), list (all custom providers), get (single provider).",
+      ),
+    id: z
+      .string()
+      .min(1)
+      .max(64)
+      .optional()
+      .describe(
+        "Provider slug (e.g. my-api). Lowercase letters, digits, hyphens only. Required for upsert/delete/get.",
+      ),
+    label: z
+      .string()
+      .min(1)
+      .max(200)
+      .optional()
+      .describe(
+        "Human-readable name (e.g. 'My Analytics API'). Required for upsert.",
+      ),
+    baseUrl: z
+      .string()
+      .url()
+      .optional()
+      .describe(
+        "Base URL for the API (e.g. https://api.example.com/v1). Required for upsert. Must be a public https/http URL.",
+      ),
+    auth: AuthSchema.optional().describe(
+      "Auth configuration. Required for upsert. Use type 'none' for public APIs.",
+    ),
+    docsUrls: z
+      .array(z.string().url())
+      .optional()
+      .describe("Optional list of documentation URLs for this provider."),
+    allowedHostSuffixes: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Optional list of additional host suffixes requests may target beyond the base URL origin (e.g. ['example.com']).",
+      ),
+    defaultHeaders: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe(
+        "Optional headers to include on every request (e.g. { 'Accept': 'application/json' }).",
+      ),
+    notes: z
+      .string()
+      .max(1000)
+      .optional()
+      .describe("Optional notes about this provider shown in the catalog."),
+    scope: z
+      .enum(["user", "org"])
+      .default("org")
+      .describe(
+        "Whether to store the provider for the current user only ('user') or for the whole workspace ('org').",
+      ),
+  }),
+  http: false,
+  run: async ({
+    operation,
+    id,
+    label,
+    baseUrl,
+    auth,
+    docsUrls,
+    allowedHostSuffixes,
+    defaultHeaders,
+    notes,
+    scope,
+  }) => {
+    const ctx = getCredentialContext();
+    if (!ctx) {
+      throw new Error(
+        "provider-api-register requires an authenticated request context.",
+      );
+    }
+    const scopeId =
+      scope === "org" ? (ctx.orgId ?? ctx.userEmail) : ctx.userEmail;
+
+    if (operation === "list") {
+      const providers = await listCustomProviders(scope, scopeId);
+      return {
+        providers: providers.map((p) => ({
+          id: p.id,
+          label: p.label,
+          baseUrl: p.baseUrl,
+          authType: p.auth.type,
+          docsUrls: p.docsUrls,
+          notes: p.notes,
+          updatedAt: p.updatedAt,
+        })),
+        count: providers.length,
+      };
+    }
+
+    if (operation === "get") {
+      if (!id) throw new Error("id is required for get operation.");
+      const provider = await getCustomProvider(scope, scopeId, id);
+      if (!provider) {
+        return { found: false, id };
+      }
+      return { found: true, provider };
+    }
+
+    if (operation === "delete") {
+      if (!id) throw new Error("id is required for delete operation.");
+      const deleted = await deleteCustomProvider(scope, scopeId, id);
+      return { deleted, id };
+    }
+
+    // upsert
+    if (!id) throw new Error("id is required for upsert operation.");
+    if (!label) throw new Error("label is required for upsert operation.");
+    if (!baseUrl) throw new Error("baseUrl is required for upsert operation.");
+    if (!auth) throw new Error("auth is required for upsert operation.");
+
+    await upsertCustomProvider({
+      scope,
+      scopeId,
+      id,
+      label,
+      baseUrl,
+      auth,
+      docsUrls,
+      allowedHostSuffixes,
+      defaultHeaders,
+      notes,
+    });
+
+    return {
+      registered: true,
+      id,
+      label,
+      message: `Custom provider "${id}" registered. Use provider-api-catalog to inspect it and provider-api-request to call it.`,
+    };
+  },
+});

package/src/actions/provider-api-request.ts

@@ -1,20 +1,19 @@
 import { defineAction } from "@agent-native/core";
 import { z } from "zod";
-import {
-  DISPATCH_PROVIDER_API_IDS,
-  executeProviderApiRequest,
-} from "../server/lib/provider-api.js";
+import { executeProviderApiRequest } from "../server/lib/provider-api.js";
 
-const ProviderSchema = z.enum(DISPATCH_PROVIDER_API_IDS);
 const MethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
 
 export default defineAction({
   description:
-    "Make an arbitrary authenticated HTTP request to a shared workspace integration or configured provider API. Use this as the flexible escape hatch when Dispatch needs a provider endpoint, filter, pagination mode, payload, or API version that no canned action models. The request is constrained to the provider host, uses configured credentials automatically, blocks private/internal URLs, and redacts secrets from responses.",
+    "Make an arbitrary authenticated HTTP request to a shared workspace integration, configured provider API, or custom provider registered via provider-api-register. Use this as the flexible escape hatch when Dispatch needs a provider endpoint, filter, pagination mode, payload, or API version that no canned action models. The request is constrained to the provider host, uses configured credentials automatically, blocks private/internal URLs, and redacts secrets from responses.",
   schema: z.object({
-    provider: ProviderSchema.describe(
-      "Configured provider API to call, e.g. slack, github, notion, hubspot, gmail, google_drive, google_calendar, granola, stripe, jira.",
-    ),
+    provider: z
+      .string()
+      .min(1)
+      .describe(
+        "Provider id to call — built-in (e.g. slack, github, notion, hubspot, gmail, google_drive, google_calendar, granola, stripe, jira) or a custom provider id registered via provider-api-register. Use provider-api-catalog to list available providers.",
+      ),
     method: MethodSchema.default("GET").describe("HTTP method to use."),
     path: z
       .string()
@@ -71,7 +70,47 @@ export default defineAction({
       .min(1_000)
       .max(4 * 1024 * 1024)
       .optional()
-      .describe("Maximum response bytes to read. Default 1MB, max 4MB."),
+      .describe(
+        "Maximum response bytes to read. Default 1MB, max 4MB. Ignored when saveToFile is set (allows up to 20MB).",
+      ),
+    saveToFile: z
+      .string()
+      .optional()
+      .describe(
+        "Workspace file path to save the full response body to instead of returning it in context (e.g. 'analysis/hubspot-deals.json'). When set, returns only a compact summary {savedTo, status, bytes, preview} and allows up to 20MB response. Useful for large datasets that would overflow context.",
+      ),
+    fetchAllPages: z
+      .object({
+        cursorPath: z
+          .string()
+          .describe(
+            "Dot-path in the JSON response body where the next-page cursor lives, e.g. 'meta.next_cursor' or 'pagination.next_page_token'.",
+          ),
+        cursorParam: z
+          .string()
+          .describe(
+            "Query parameter name to pass the cursor on subsequent pages, e.g. 'cursor' or 'page_token'.",
+          ),
+        itemsPath: z
+          .string()
+          .optional()
+          .describe(
+            "Dot-path to the items array in each response, e.g. 'results' or 'data.items'. When omitted, the whole response body is appended per page.",
+          ),
+        maxPages: z.coerce
+          .number()
+          .int()
+          .min(1)
+          .max(50)
+          .optional()
+          .describe(
+            "Maximum pages to fetch. Default 10, max 50. Stops early when the cursor is empty.",
+          ),
+      })
+      .optional()
+      .describe(
+        "Enable cursor-based pagination. After each response, reads cursorPath from the JSON body and re-issues the request with cursorParam set, accumulating items from itemsPath (or whole bodies) until cursor is empty or maxPages is reached. Combine with saveToFile to write the full dataset to a workspace file.",
+      ),
   }),
   http: false,
   run: async (args) => executeProviderApiRequest(args),

package/src/lib/thread-link-preview.ts

@@ -0,0 +1,160 @@
+export interface ThreadLinkPreview {
+  title: string;
+  description: string;
+  imageUrl: string | null;
+}
+
+const IMAGE_URL_KEYS = new Set([
+  "previewUrl",
+  "thumbnailUrl",
+  "imageUrl",
+  "image",
+  "downloadUrl",
+]);
+
+const GENERATION_TOOL_NAMES = new Set([
+  "generate-image",
+  "generate-image-batch",
+  "refine-image",
+  "rerun-generation-run",
+]);
+
+function safeJsonParse(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function cleanUrlCandidate(value: string): string {
+  return value
+    .trim()
+    .replace(/[),.;\]}]+$/g, "")
+    .replace(/^["'(<]+/g, "");
+}
+
+function isAbsoluteHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+function isImageLikeUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return (
+      /\.(?:png|jpe?g|webp|gif|avif)(?:$|[?#])/i.test(url.pathname) ||
+      /\/api\/assets\/[^/]+\/content(?:$|[?#])/i.test(url.pathname)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function validPreviewImageUrl(value: unknown, key?: string): string | null {
+  if (typeof value !== "string") return null;
+  const candidate = cleanUrlCandidate(value);
+  if (!isAbsoluteHttpUrl(candidate)) return null;
+  if (key && IMAGE_URL_KEYS.has(key)) return candidate;
+  return isImageLikeUrl(candidate) ? candidate : null;
+}
+
+function imageUrlFromStructuredValue(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  if (Array.isArray(value)) {
+    for (let i = value.length - 1; i >= 0; i--) {
+      const found = imageUrlFromStructuredValue(value[i]);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  const record = value as Record<string, unknown>;
+  for (const key of IMAGE_URL_KEYS) {
+    const found = validPreviewImageUrl(record[key], key);
+    if (found) return found;
+  }
+  for (const [key, child] of Object.entries(record).reverse()) {
+    const direct = validPreviewImageUrl(child, key);
+    if (direct) return direct;
+    if (child && typeof child === "object") {
+      const nested = imageUrlFromStructuredValue(child);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+function imageUrlFromText(value: string): string | null {
+  const matches = value.match(/https?:\/\/[^\s<>"']+/g);
+  if (!matches) return null;
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const candidate = validPreviewImageUrl(matches[i]);
+    if (candidate) return candidate;
+  }
+  return null;
+}
+
+export function extractThreadPreviewImageUrl(
+  threadData: string,
+): string | null {
+  const parsed = safeJsonParse(threadData);
+  if (!parsed || typeof parsed !== "object") return null;
+  const messages = (parsed as { messages?: unknown }).messages;
+  if (!Array.isArray(messages)) return null;
+
+  for (
+    let messageIndex = messages.length - 1;
+    messageIndex >= 0;
+    messageIndex--
+  ) {
+    const entry = messages[messageIndex] as any;
+    const message = entry?.message ?? entry;
+    const content = message?.content;
+    if (!Array.isArray(content)) continue;
+
+    for (let partIndex = content.length - 1; partIndex >= 0; partIndex--) {
+      const part = content[partIndex] as Record<string, unknown>;
+      const result = typeof part.result === "string" ? part.result : "";
+      if (!result.trim()) continue;
+
+      const toolName = typeof part.toolName === "string" ? part.toolName : "";
+      const parsedResult = safeJsonParse(result);
+      if (parsedResult && GENERATION_TOOL_NAMES.has(toolName)) {
+        const structured = imageUrlFromStructuredValue(parsedResult);
+        if (structured) return structured;
+      }
+
+      const fromText = imageUrlFromText(result);
+      if (fromText) return fromText;
+    }
+  }
+  return null;
+}
+
+export function buildThreadLinkPreviewMeta(preview: ThreadLinkPreview | null) {
+  const title = preview?.title ? `${preview.title} - Dispatch` : "Dispatch";
+  const description =
+    preview?.description ||
+    "Open this Agent-Native thread in the Dispatch workspace.";
+  const image = preview?.imageUrl ?? null;
+  return [
+    { title },
+    { name: "description", content: description },
+    { property: "og:title", content: title },
+    { property: "og:description", content: description },
+    { property: "og:type", content: "website" },
+    ...(image ? [{ property: "og:image", content: image }] : []),
+    {
+      name: "twitter:card",
+      content: image ? "summary_large_image" : "summary",
+    },
+    { name: "twitter:title", content: title },
+    { name: "twitter:description", content: description },
+    ...(image ? [{ name: "twitter:image", content: image }] : []),
+  ];
+}

package/src/routes/pages/chat.tsx

@@ -1,15 +1,7 @@
 import { useEffect, useRef } from "react";
-import {
-  useLocation,
-  useNavigate,
-  type LoaderFunctionArgs,
-} from "react-router";
+import { useLocation, useNavigate } from "react-router";
 import { AgentChatSurface } from "@agent-native/core/client";
 import { submitOverviewPrompt } from "@/lib/overview-chat";
-import {
-  buildThreadLinkPreviewMeta,
-  loadThreadLinkPreview,
-} from "@/server/lib/thread-link-preview";
 
 interface DispatchChatLocationState {
   dispatchPrompt?: {
@@ -23,17 +15,8 @@ interface DispatchChatLocationState {
   };
 }
 
-export async function loader({ request }: LoaderFunctionArgs) {
-  const threadId = new URL(request.url).searchParams.get("thread");
-  return {
-    threadPreview: await loadThreadLinkPreview(threadId),
-  };
-}
-
-export function meta({ data }: { data?: Awaited<ReturnType<typeof loader>> }) {
-  return data?.threadPreview
-    ? buildThreadLinkPreviewMeta(data.threadPreview)
-    : [{ title: "Chat — Dispatch" }];
+export function meta() {
+  return [{ title: "Chat — Dispatch" }];
 }
 
 export default function ChatRoute() {

package/src/routes/pages/overview.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useState } from "react";
-import { Link, useNavigate, type LoaderFunctionArgs } from "react-router";
+import { Link, useNavigate } from "react-router";
 import {
   PromptComposer,
   useActionQuery,
@@ -34,10 +34,6 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { submitOverviewPrompt } from "@/lib/overview-chat";
-import {
-  buildThreadLinkPreviewMeta,
-  loadThreadLinkPreview,
-} from "@/server/lib/thread-link-preview";
 import type { WorkspaceAppSummary } from "@/lib/workspace-apps";
 
 interface IntegrationStatus {
@@ -475,17 +471,8 @@ function StepRow({ step }: { step: ChecklistStep }) {
   );
 }
 
-export async function loader({ request }: LoaderFunctionArgs) {
-  const threadId = new URL(request.url).searchParams.get("thread");
-  return {
-    threadPreview: await loadThreadLinkPreview(threadId),
-  };
-}
-
-export function meta({ data }: { data?: Awaited<ReturnType<typeof loader>> }) {
-  return data?.threadPreview
-    ? buildThreadLinkPreviewMeta(data.threadPreview)
-    : [{ title: "Overview — Dispatch" }];
+export function meta() {
+  return [{ title: "Overview — Dispatch" }];
 }
 
 export default function OverviewRoute() {

package/src/server/lib/provider-api.ts

@@ -1,6 +1,7 @@
 import {
   PROVIDER_API_IDS,
   createProviderApiRuntime,
+  listCustomProviders,
   type ProviderApiId,
   type ProviderApiMethod,
   type ProviderApiRequestArgs,
@@ -11,26 +12,52 @@ export const DISPATCH_PROVIDER_API_IDS = PROVIDER_API_IDS;
 export type DispatchProviderApiId = ProviderApiId;
 export type { ProviderApiMethod, ProviderApiRequestArgs };
 
+function requireCtx(action: string) {
+  const ctx = getCredentialContext();
+  if (!ctx) {
+    throw new Error(
+      `Dispatch provider API ${action} requires an authenticated request context.`,
+    );
+  }
+  return ctx;
+}
+
 const runtime = createProviderApiRuntime({
   appId: "dispatch",
   localCredentialSource: "dispatch_local",
-  getCredentialContext: () => {
+  getCredentialContext: () => requireCtx("requests"),
+  getCustomProviders: async () => {
     const ctx = getCredentialContext();
-    if (!ctx) {
-      throw new Error(
-        "Dispatch provider API requests require an authenticated request context.",
-      );
+    if (!ctx) return [];
+    // Load custom providers for both user scope and org scope.
+    const results = await Promise.allSettled([
+      listCustomProviders("user", ctx.userEmail),
+      ctx.orgId ? listCustomProviders("org", ctx.orgId) : Promise.resolve([]),
+    ]);
+    const userProviders =
+      results[0].status === "fulfilled" ? results[0].value : [];
+    const orgProviders =
+      results[1].status === "fulfilled" ? results[1].value : [];
+    // Merge: user-scope providers take precedence over org-scope ones with the
+    // same id, and neither can shadow a built-in id.
+    const seen = new Set<string>(PROVIDER_API_IDS as unknown as string[]);
+    const merged = [];
+    for (const p of [...userProviders, ...orgProviders]) {
+      if (!seen.has(p.id)) {
+        seen.add(p.id);
+        merged.push(p);
+      }
     }
-    return ctx;
+    return merged;
   },
 });
 
-export function listProviderApiCatalog(provider?: DispatchProviderApiId) {
+export function listProviderApiCatalog(provider?: string) {
   return runtime.listCatalog(provider);
 }
 
 export function fetchProviderApiDocs(options: {
-  provider: DispatchProviderApiId;
+  provider: string;
   url?: string;
   maxBytes?: number;
 }) {

package/src/server/lib/thread-link-preview.spec.ts

@@ -9,10 +9,8 @@ vi.mock("@agent-native/core/server", () => ({
   getThread: getThreadMock,
 }));
 
-import {
-  extractThreadPreviewImageUrl,
-  loadThreadLinkPreview,
-} from "./thread-link-preview";
+import { loadThreadLinkPreview } from "./thread-link-preview";
+import { extractThreadPreviewImageUrl } from "../../lib/thread-link-preview";
 
 function threadDataWithResult(toolName: string, result: unknown) {
   return JSON.stringify({