@agent-native/core 0.113.0 → 0.114.0

package/src/file-upload/pre-upload-attachments.ts

@@ -0,0 +1,305 @@
+import type { AgentChatAttachment } from "../agent/types.js";
+import { getActiveFileUploadProvider, uploadFile } from "./registry.js";
+
+export interface PreUploadedImageAttachment {
+  name?: string;
+  url: string;
+  provider: string;
+  contentType?: string;
+}
+
+/**
+ * A file/non-image attachment that was successfully uploaded to a hosted URL.
+ * Consumers can use the URL in place of the base64 data to avoid persisting
+ * large blobs in the thread repo and SQL.
+ */
+export interface PreUploadedFileAttachment {
+  name?: string;
+  url: string;
+  provider: string;
+  contentType?: string;
+  sizeBytes?: number;
+  referenceOnly?: boolean;
+  securityNote?: string;
+}
+
+export interface PreUploadAttachmentsResult {
+  /** Same array reference. Each image attachment that was uploaded also gets a
+   *  `url` property attached (non-breaking; consumers that don't read it are
+   *  unaffected). */
+  attachments: AgentChatAttachment[];
+  /** Set when at least one image was uploaded. List of hosted URLs the agent
+   *  can embed in HTML, slide content, documents, etc. */
+  uploaded: PreUploadedImageAttachment[];
+  /** Uploaded non-image files (PDF, generic binary). Parallel to `uploaded`
+   *  but for the file/document attachment type. */
+  uploadedFiles: PreUploadedFileAttachment[];
+  /** True if at least one image attachment failed to upload because no
+   *  file-upload provider is configured. Templates use this to render a
+   *  "Connect Builder.io" suggestion. */
+  providerMissing: boolean;
+  /** A pre-formatted block to inject into the user message text so the agent
+   *  has each hosted URL inline. Null when nothing was uploaded or no provider
+   *  is configured. */
+  injectedText: string | null;
+}
+
+const FILE_DATA_URL_RE = /^data:([^;]+);base64,(.+)$/;
+const SVG_REFERENCE_SECURITY_NOTE =
+  "SVG content may contain active markup; use this URL as a file reference unless the target app sanitizes it.";
+
+function normalizeContentType(value: string | undefined): string | undefined {
+  return value?.split(";")[0]?.trim().toLowerCase() || undefined;
+}
+
+function hasSvgFilename(name: string | undefined): boolean {
+  return /\.svg$/i.test(name ?? "");
+}
+
+function isSvgAttachment(args: {
+  name?: string;
+  contentType?: string;
+}): boolean {
+  return (
+    normalizeContentType(args.contentType) === "image/svg+xml" ||
+    hasSvgFilename(args.name)
+  );
+}
+
+function isSvgPayload(args: { name?: string; contentType?: string }): boolean {
+  const contentType = normalizeContentType(args.contentType);
+  return (
+    contentType === "image/svg+xml" ||
+    ((contentType === undefined ||
+      contentType === "application/octet-stream") &&
+      hasSvgFilename(args.name))
+  );
+}
+
+function markReferenceOnlySvgAttachment(
+  att: AgentChatAttachment,
+  contentType: string | undefined,
+) {
+  att.type = "file";
+  att.contentType = normalizeContentType(contentType) ?? "image/svg+xml";
+  (att as any).referenceOnly = true;
+  (att as any).securityNote = SVG_REFERENCE_SECURITY_NOTE;
+}
+
+function escapeXmlAttr(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Returns true when a file-upload provider is currently configured.
+ * Used to decide whether to attempt upload-first or fall back to base64.
+ */
+export function isFileUploadProviderConfigured(): boolean {
+  return getActiveFileUploadProvider() !== null;
+}
+
+/**
+ * Pre-upload chat image attachments through the active file-upload provider
+ * (Builder.io by default) so the agent can embed hosted URLs in HTML, slide
+ * content, and outbound messages. Keeps the original base64 data URL on the
+ * attachment so multimodal vision still works — only adds a hosted `url`.
+ *
+ * Safe to call when no provider is configured: it returns the attachments
+ * untouched with `providerMissing: true` so callers can surface a connect-
+ * Builder.io hint to the agent.
+ */
+export async function preUploadImageAttachments(opts: {
+  attachments: AgentChatAttachment[] | undefined;
+  ownerEmail: string | null | undefined;
+}): Promise<PreUploadAttachmentsResult> {
+  return preUploadAttachments({ ...opts, includeFiles: false });
+}
+
+/**
+ * Pre-upload ALL chat attachments (images AND files/PDFs) through the active
+ * file-upload provider. When a provider is configured, each attachment gets a
+ * `url` property injected so downstream code can store/send URLs instead of
+ * base64. The base64 data is kept in-memory for the current turn so vision and
+ * file-reading still work; callers that persist the attachment can drop the
+ * data when a URL exists.
+ *
+ * Falls back gracefully when no provider is configured: returns untouched
+ * attachments with `providerMissing: true` for image-type failures.
+ */
+export async function preUploadAttachments(opts: {
+  attachments: AgentChatAttachment[] | undefined;
+  ownerEmail: string | null | undefined;
+  /** When false, only images are uploaded (legacy behaviour). Default: true */
+  includeFiles?: boolean;
+}): Promise<PreUploadAttachmentsResult> {
+  const list = Array.isArray(opts.attachments) ? opts.attachments : [];
+  const includeFiles = opts.includeFiles !== false;
+  const uploaded: PreUploadedImageAttachment[] = [];
+  const uploadedFiles: PreUploadedFileAttachment[] = [];
+  let providerMissing = false;
+
+  if (list.length === 0) {
+    return {
+      attachments: list,
+      uploaded,
+      uploadedFiles,
+      providerMissing: false,
+      injectedText: null,
+    };
+  }
+
+  for (const att of list) {
+    const isImage = att.type === "image";
+    const isFile = att.type === "file" || att.type === "document";
+    if (!isImage && !(includeFiles && isFile)) continue;
+    if (typeof att.data !== "string") continue;
+
+    if ((att as any).url) {
+      // Already pre-uploaded earlier in the pipeline — reuse it.
+      const isReferenceOnlySvg = isSvgAttachment(att);
+      if (isReferenceOnlySvg) {
+        markReferenceOnlySvgAttachment(att, att.contentType);
+      }
+      const entry = {
+        name: att.name,
+        url: (att as any).url as string,
+        provider: ((att as any).uploadProvider as string) || "unknown",
+        contentType: att.contentType,
+        ...(isReferenceOnlySvg
+          ? {
+              referenceOnly: true,
+              securityNote: SVG_REFERENCE_SECURITY_NOTE,
+            }
+          : {}),
+      };
+      if (isImage && !isReferenceOnlySvg) {
+        uploaded.push(entry);
+      } else {
+        uploadedFiles.push(entry);
+      }
+      continue;
+    }
+
+    const match = att.data.match(FILE_DATA_URL_RE);
+    if (!match) continue;
+    const dataUrlMimeType = normalizeContentType(match[1]);
+    const mimeType =
+      dataUrlMimeType || normalizeContentType(att.contentType) || match[1];
+    const uploadAsImage =
+      isImage && !isSvgPayload({ name: att.name, contentType: mimeType });
+    const uploadAsFile =
+      !uploadAsImage && (isImage || (includeFiles && isFile));
+    if (!uploadAsImage && !uploadAsFile) continue;
+
+    let bytes: Uint8Array;
+    try {
+      bytes = new Uint8Array(Buffer.from(match[2], "base64"));
+    } catch {
+      continue;
+    }
+
+    try {
+      const result = await uploadFile({
+        data: bytes,
+        filename: att.name,
+        mimeType,
+        ownerEmail: opts.ownerEmail || undefined,
+      });
+      if (!result) {
+        if (uploadAsImage) providerMissing = true;
+        continue;
+      }
+      (att as any).url = result.url;
+      (att as any).uploadProvider = result.provider;
+      const isReferenceOnlySvg = isSvgPayload({
+        name: att.name,
+        contentType: mimeType,
+      });
+      if (isReferenceOnlySvg) {
+        markReferenceOnlySvgAttachment(att, mimeType);
+      }
+      const entry = {
+        name: att.name,
+        url: result.url,
+        provider: result.provider,
+        contentType: isReferenceOnlySvg ? att.contentType : mimeType,
+        sizeBytes: bytes.byteLength,
+        ...(isReferenceOnlySvg
+          ? {
+              referenceOnly: true,
+              securityNote: SVG_REFERENCE_SECURITY_NOTE,
+            }
+          : {}),
+      };
+      if (uploadAsImage) {
+        uploaded.push(entry);
+      } else {
+        uploadedFiles.push(entry);
+      }
+    } catch (err) {
+      // Real upload failure (network, API). Keep the base64 so the model
+      // can still see the image/file, but don't crash the turn.
+      console.warn(
+        "[agent-native] pre-upload of chat attachment failed:",
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  let injectedText: string | null = null;
+  if (uploaded.length > 0 || uploadedFiles.length > 0) {
+    const lines: string[] = [];
+    for (const u of uploaded) {
+      const attrs = [
+        u.name ? `name="${escapeXmlAttr(u.name)}"` : null,
+        `url="${escapeXmlAttr(u.url)}"`,
+        u.contentType ? `contentType="${escapeXmlAttr(u.contentType)}"` : null,
+        `provider="${escapeXmlAttr(u.provider)}"`,
+      ].filter(Boolean);
+      lines.push(`<chat-image-attachment ${attrs.join(" ")} />`);
+    }
+    for (const f of uploadedFiles) {
+      const attrs = [
+        f.name ? `name="${escapeXmlAttr(f.name)}"` : null,
+        `url="${escapeXmlAttr(f.url)}"`,
+        f.contentType ? `contentType="${escapeXmlAttr(f.contentType)}"` : null,
+        `provider="${escapeXmlAttr(f.provider)}"`,
+        f.referenceOnly ? `referenceOnly="true"` : null,
+        f.securityNote
+          ? `securityNote="${escapeXmlAttr(f.securityNote)}"`
+          : null,
+      ].filter(Boolean);
+      lines.push(`<chat-file-attachment ${attrs.join(" ")} />`);
+    }
+    const hasReferenceOnlySvg = uploadedFiles.some(
+      (file) => file.referenceOnly && isSvgAttachment(file),
+    );
+    injectedText = [
+      hasReferenceOnlySvg
+        ? '<chat-attachments note="The user attached these files. Image attachment URLs may be used for embedding. File attachment URLs are references; SVG files are unsanitized vector source and must not be inlined as HTML or embedded in outbound content unless the target app sanitizes or stores them safely.">'
+        : '<chat-attachments note="The user attached these files. Image attachment URLs may be used for embedding in HTML, slide content, or outbound messages. File attachment URLs are references for reading or attaching in target apps.">',
+      ...lines,
+      "</chat-attachments>",
+    ].join("\n");
+  } else if (providerMissing) {
+    injectedText = [
+      "<chat-image-attachment-upload-error>",
+      "The user attached one or more images, but no file-upload provider is configured for this app.",
+      "If `connect-builder` is available, use it to render the inline Builder.io connection card. Workspaces with a custom storage provider can also use one registered via registerFileUploadProvider().",
+      "Until that's done, you can still SEE the image, but you do NOT have a URL to embed it in HTML or share with other apps.",
+      "</chat-image-attachment-upload-error>",
+    ].join("\n");
+  }
+
+  return {
+    attachments: list,
+    uploaded,
+    uploadedFiles,
+    providerMissing,
+    injectedText,
+  };
+}

package/src/file-upload/registry.ts

@@ -0,0 +1,125 @@
+import { builderFileUploadProvider } from "./builder.js";
+import type {
+  FileUploadInput,
+  FileUploadProvider,
+  FileUploadResult,
+} from "./types.js";
+
+// Why globalThis: in dev (Vite HMR) and in some Nitro/Rollup bundle splits,
+// this module can be evaluated more than once — the plugin file that
+// registers a provider lands in one module instance and the request handler
+// that reads providers lands in another, so the call site sees an empty map
+// even though `registerFileUploadProvider` succeeded. Pinning the singletons
+// on `globalThis` guarantees one set of providers per Node process,
+// independent of how the bundler split the chunks.
+interface FileUploadGlobals {
+  __agentNativeFileUploadProviders?: Map<string, FileUploadProvider>;
+  __agentNativeFileUploadWarnedFallback?: { value: boolean };
+}
+const globals = globalThis as typeof globalThis & FileUploadGlobals;
+const providers: Map<string, FileUploadProvider> =
+  (globals.__agentNativeFileUploadProviders ??= new Map());
+const warnedFallbackRef: { value: boolean } =
+  (globals.__agentNativeFileUploadWarnedFallback ??= { value: false });
+
+/**
+ * Register a file upload provider. Call from a server plugin or app
+ * bootstrap. Idempotent per id — later calls with the same id replace.
+ */
+export function registerFileUploadProvider(provider: FileUploadProvider): void {
+  providers.set(provider.id, provider);
+}
+
+export function unregisterFileUploadProvider(id: string): void {
+  providers.delete(id);
+}
+
+export function listFileUploadProviders(): FileUploadProvider[] {
+  return [...providers.values()];
+}
+
+/**
+ * Returns the first configured provider, checking user-registered ones first
+ * and falling back to the built-in Builder.io provider when its env is set.
+ * Returns `null` when nothing is configured — callers should then use the
+ * SQL fallback.
+ */
+export function getActiveFileUploadProvider(): FileUploadProvider | null {
+  for (const provider of providers.values()) {
+    if (provider.isConfigured()) return provider;
+  }
+  if (builderFileUploadProvider.isConfigured()) {
+    return builderFileUploadProvider;
+  }
+  return null;
+}
+
+export async function getActiveFileUploadProviderForRequest(): Promise<FileUploadProvider | null> {
+  for (const provider of providers.values()) {
+    if (provider.isConfigured()) return provider;
+    if (provider.isConfiguredForRequest) {
+      try {
+        if (await provider.isConfiguredForRequest()) return provider;
+      } catch {
+        // Treat failed scoped credential lookups as unavailable. The upload
+        // call will surface real provider errors after a provider is selected.
+      }
+    }
+  }
+  if (builderFileUploadProvider.isConfigured()) {
+    return builderFileUploadProvider;
+  }
+  return null;
+}
+
+/**
+ * Upload a file via the active provider, or `null` if no provider is
+ * configured. Callers use `null` as the signal to fall back to SQL
+ * storage. On the first fallback we log a one-time warning because
+ * storing files in SQL is not optimal for production.
+ */
+export async function uploadFile(
+  input: FileUploadInput,
+): Promise<FileUploadResult | null> {
+  const provider = await getActiveFileUploadProviderForRequest();
+  // User-registered providers (S3, etc.) may be configured by sync runtime
+  // state or request-scoped DB secrets. Builder still gets an explicit async
+  // credential check below because its sync isConfigured() only checks env.
+  if (provider && provider !== builderFileUploadProvider) {
+    return provider.upload(input);
+  }
+
+  // Resolve credentials asynchronously (works when request context is set
+  // via runWithRequestContext — actions always have one via action-routes.ts).
+  // Two separate try-catch blocks ensure a real upload failure is never
+  // silently swallowed as a "no credentials" case.
+  let builderKey: string | null = null;
+  try {
+    const { resolveBuilderPrivateKey } =
+      await import("../server/credential-provider.js");
+    builderKey = await resolveBuilderPrivateKey();
+  } catch (err) {
+    // DB unavailable or credential store not ready — can't resolve key.
+    // Log and fall through to the SQL fallback below.
+    console.warn(
+      "[agent-native] Builder credential check failed:",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+
+  if (builderKey) {
+    // Credentials confirmed — attempt the upload. Real errors (network,
+    // API, rate-limit) propagate to the caller; do NOT catch them here.
+    return await builderFileUploadProvider.upload(input);
+  }
+
+  if (!warnedFallbackRef.value) {
+    warnedFallbackRef.value = true;
+    console.warn(
+      "[agent-native] No file upload provider configured. " +
+        "Connect or reconnect Builder.io in Settings → File uploads, " +
+        "or register a custom provider (S3, R2, GCS, …) via registerFileUploadProvider().",
+    );
+  }
+  return null;
+}

package/src/file-upload/types.ts

@@ -0,0 +1,89 @@
+/**
+ * File upload framework primitive.
+ *
+ * Templates call `uploadFile()` to upload a file and get back a URL.
+ * The framework dispatches to whichever provider is registered (Builder.io
+ * built-in, or a user-supplied one). If no provider is active, it falls back
+ * to the SQL resources store — fine for dev, not recommended for production.
+ */
+
+export interface FileUploadInput {
+  /** File contents. */
+  data: Uint8Array | Buffer;
+  /** Original filename, used for extension/display. */
+  filename?: string;
+  /** MIME type, e.g. "image/png". */
+  mimeType?: string;
+  /** Optional owner email for per-user scoping in fallback storage. */
+  ownerEmail?: string;
+  /** Builder.io upload hint: return one stable URL while compression finishes asynchronously. */
+  stableUrl?: boolean;
+  /** Builder.io upload hint: set false for internal artifacts that should not appear in the asset library. */
+  recordAsset?: boolean;
+}
+
+export interface FileUploadResult {
+  /** Public URL where the file can be fetched. */
+  url: string;
+  /** Optional provider-specific id (e.g. resource id, Builder asset id). */
+  id?: string;
+  /** The provider that handled the upload. */
+  provider: string;
+}
+
+/** Opaque session handle returned by {@link FileUploadProvider.resumable.startSession}.
+ * `sessionId` is provider-specific (GCS Location URI, S3 UploadId, etc.).
+ * `meta` holds any provider state needed for subsequent relay and complete calls. */
+export interface ResumableUploadSession {
+  sessionId: string;
+  meta: Record<string, unknown>;
+}
+
+export interface ResumableChunkResult {
+  ok: boolean;
+  status: number;
+  /** Providers that need per-chunk state (e.g. S3 ETags) return updated meta
+   * here; the chunk route merges it back into the stored session. */
+  updatedMeta?: Record<string, unknown>;
+}
+
+export interface FileUploadProvider {
+  /** Unique id, e.g. "builder", "s3". */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Returns true if this provider is configured from synchronous runtime state. */
+  isConfigured: () => boolean;
+  /**
+   * Returns true if this provider is configured for the active request.
+   * Use for DB-backed user/org/workspace secrets that require request context.
+   */
+  isConfiguredForRequest?: () => Promise<boolean>;
+  /** Upload a file and return a URL. Throw on failure. */
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+  /**
+   * Optional resumable/streaming upload capability.
+   * When present, create-recording will initialise a session and stream chunks
+   * during recording instead of assembling the full blob after stop().
+   */
+  resumable?: {
+    startSession(
+      filename: string,
+      mimeType: string,
+      maxBytes: number,
+    ): Promise<ResumableUploadSession>;
+    relayChunk(
+      session: ResumableUploadSession,
+      contentRange: string,
+      bytes: Uint8Array,
+      options?: { mimeType?: string },
+    ): Promise<ResumableChunkResult>;
+    completeSession(
+      session: ResumableUploadSession,
+      filename: string,
+      options?: { stableUrl?: boolean; recordAsset?: boolean },
+    ): Promise<string>;
+    /** Best-effort provider cleanup for a session the caller will not resume. */
+    abortSession?(session: ResumableUploadSession): Promise<void>;
+  };
+}

package/src/guards/db-tool-scoping.ts

@@ -0,0 +1,129 @@
+/**
+ * scanDbToolScoping — ported from `scripts/guard-db-tool-scoping.mjs`.
+ *
+ * The agent's raw DB tools (`db-query`, `db-exec`, `db-patch`) can only
+ * safely expose tables with an explicit tenant scope (`owner_email` and/or
+ * `org_id`) or a documented, reviewed exception. This guard keeps schema
+ * drift visible: any table without raw-DB scope must either add
+ * `owner_email`/`org_id`, or be added to the denylist with a
+ * reviewer-readable reason.
+ *
+ * Conditional guard — per report 005's V1 guard set table: the original
+ * walks every `templates/*\/server/db/schema.ts` and keys its denylist
+ * `"<template>:<table>"`. A generated app has exactly one
+ * `server/db/schema.ts` (confirmed convention), so this port scans that
+ * single file and uses bare `"<table>"` denylist keys. The denylist itself
+ * comes from `agent-native.json`'s `doctor.dbToolScopingDenylist` (see
+ * `../cli/doctor.ts`) — empty by default; app authors add entries with the
+ * same reviewer-readable-reason convention as the original constant.
+ *
+ * Not ported: the original also resolves `export * from
+ * "@agent-native/<pkg>/schema"` re-exports back to that package's
+ * `packages/<pkg>/src/schema/*.ts` monorepo source, so template schemas
+ * that re-export scheduling/dispatch tables get scanned too. In a
+ * generated app those packages are compiled `node_modules` output (no
+ * `.ts` source to brace-parse), and report 005's parameterization note
+ * doesn't cover that case, so re-export resolution is intentionally
+ * dropped for app mode: a re-exported table from an `@agent-native/*`
+ * package is not scanned here (false-negative, not false-positive) — see
+ * the plan's STOP-condition guidance ("report rather than invent new
+ * detection logic").
+ */
+
+import { readFileSafe, relPosix, walk } from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+export interface DbToolScopingOptions extends GuardScanOptions {
+  /** Table name -> reviewer-readable reason. Default `{}`. */
+  denylist?: Record<string, string>;
+}
+
+interface TableCall {
+  exportName: string;
+  sqlName: string;
+  body: string;
+}
+
+function extractTableCalls(contents: string): TableCall[] {
+  const out: TableCall[] = [];
+  const headerRegex =
+    /export\s+const\s+([a-zA-Z_$][\w$]*)\s*=\s*(?:[a-zA-Z_$][\w$]*Table|table)\s*\(\s*"([^"]+)"\s*,\s*\{/gm;
+  let match: RegExpExecArray | null;
+  while ((match = headerRegex.exec(contents)) !== null) {
+    const exportName = match[1];
+    const sqlName = match[2];
+    const start = headerRegex.lastIndex - 1;
+    let depth = 0;
+    let inStr: string | null = null;
+    let bodyEnd = -1;
+    for (let i = start; i < contents.length; i++) {
+      const c = contents[i];
+      const prev = contents[i - 1];
+      if (inStr) {
+        if (c === inStr && prev !== "\\") inStr = null;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === "`") {
+        inStr = c;
+        continue;
+      }
+      if (c === "{") depth++;
+      else if (c === "}") {
+        depth--;
+        if (depth === 0) {
+          bodyEnd = i;
+          break;
+        }
+      }
+    }
+    if (bodyEnd === -1) continue;
+    out.push({ exportName, sqlName, body: contents.slice(start + 1, bodyEnd) });
+  }
+  return out;
+}
+
+function hasRawDbScope(tableBody: string): boolean {
+  return (
+    /\.\.\.ownableColumns\s*\(/.test(tableBody) ||
+    /\b[\w$]+\s*:\s*text\s*\(\s*["']owner_email["']/.test(tableBody) ||
+    /\b[\w$]+\s*:\s*text\s*\(\s*["']org_id["']/.test(tableBody)
+  );
+}
+
+export function scanDbToolScoping(options: DbToolScopingOptions): GuardResult {
+  const { root, denylist = {} } = options;
+  const findings: GuardFinding[] = [];
+  const seenAllowed = new Set<string>();
+
+  for (const file of walk(root)) {
+    if (!file.endsWith("/server/db/schema.ts")) continue;
+    const contents = readFileSafe(file);
+    if (contents === null) continue;
+    const rel = relPosix(root, file);
+    const tables = extractTableCalls(contents);
+    for (const table of tables) {
+      if (hasRawDbScope(table.body)) continue;
+      if (Object.hasOwn(denylist, table.sqlName)) {
+        seenAllowed.add(table.sqlName);
+        continue;
+      }
+      findings.push({
+        file: rel,
+        line: 1,
+        message: `Table "${table.sqlName}" (export ${table.exportName}) has no owner_email/org_id scope and is not on the doctor.dbToolScopingDenylist — add tenant scope, or add it to agent-native.json's "doctor.dbToolScopingDenylist" with a reason.`,
+      });
+    }
+  }
+
+  for (const key of Object.keys(denylist)) {
+    if (!seenAllowed.has(key)) {
+      findings.push({
+        file: "agent-native.json",
+        line: 1,
+        message: `Stale doctor.dbToolScopingDenylist entry "${key}" — no matching table found in server/db/schema.ts. Remove it.`,
+      });
+    }
+  }
+
+  return { name: "db-tool-scoping", findings };
+}

package/src/guards/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `agent-native doctor`'s guard functions — the source-code safety
+ * invariants ported from this monorepo's `scripts/guard-*.mjs` CI guards
+ * (see report `advisor-plans/reports/005-doctor-design.md` for the
+ * classification and per-guard parameterization). Each guard is a pure,
+ * synchronous function that scans an app root and returns a `GuardResult`.
+ *
+ * `../cli/doctor.ts` is the only in-package caller; this module is also
+ * published under the `./guards` export subpath for advanced/CI use
+ * outside the CLI.
+ */
+
+export { scanDbToolScoping } from "./db-tool-scoping.js";
+export type { DbToolScopingOptions } from "./db-tool-scoping.js";
+export { scanDrizzlePush } from "./no-drizzle-push.js";
+export { scanEnvCredentials } from "./no-env-credentials.js";
+export { scanEnvMutation } from "./no-env-mutation.js";
+export { scanLocalhostFallback } from "./no-localhost-fallback.js";
+export type { LocalhostFallbackOptions } from "./no-localhost-fallback.js";
+export { scanUnscopedCredentials } from "./no-unscoped-credentials.js";
+export { scanUnscopedQueries } from "./no-unscoped-queries.js";
+export type { UnscopedQueriesOptions } from "./no-unscoped-queries.js";
+export type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";