@agent-native/core 0.112.0 → 0.113.0

package/corpus/templates/clips/changelog/2026-07-19-ready-clips-transcripts-can-be-backfilled-to-brain-for-a-bou.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-19
+---
+
+Ready Clips transcripts can be backfilled to Brain for a bounded recent window with clear export and privacy-review results.

package/corpus/templates/clips/server/lib/calendar-event-meetings.ts

@@ -81,7 +81,7 @@ export function shouldMarkNeedsReauth(message: string): boolean {
 export async function resolveCalendarAccessToken(
   account: CalendarAccountForEvents,
 ): Promise<string | null> {
-  const credentialCandidates = resolveGoogleOAuthCredentialCandidates();
+  const credentialCandidates = await resolveGoogleOAuthCredentialCandidates();
   if (!credentialCandidates.length || !account.ownerEmail) return null;
 
   let bundle: AccessTokenBundle | null = null;

package/corpus/templates/clips/server/lib/google-calendar-client.ts

@@ -16,6 +16,11 @@
  *   Userinfo: https://www.googleapis.com/oauth2/v2/userinfo
  */
 
+import {
+  GOOGLE_PRIMARY_PROVIDER_CREDENTIAL_KEYS,
+  resolveGoogleProviderCredentialCandidatesWithReader,
+} from "@agent-native/core/server";
+
 export const GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
 export const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
 export const GOOGLE_USERINFO_URL =
@@ -88,28 +93,13 @@ export interface GoogleOAuthClientCredentials {
   clientSecret: string;
 }
 
-function readCredentialPair(
-  clientIdKey: string,
-  clientSecretKey: string,
-): GoogleOAuthClientCredentials | null {
-  const clientId = process.env[clientIdKey];
-  const clientSecret = process.env[clientSecretKey];
-  if (!clientId || !clientSecret) return null;
-  return { clientId, clientSecret };
-}
-
-export function resolveGoogleOAuthCredentialCandidates(): GoogleOAuthClientCredentials[] {
-  const primary = readCredentialPair(
-    "GOOGLE_CLIENT_ID",
-    "GOOGLE_CLIENT_SECRET",
-  );
-  const legacy = readCredentialPair(
-    "GOOGLE_LEGACY_CLIENT_ID",
-    "GOOGLE_LEGACY_CLIENT_SECRET",
-  );
-  if (!primary) return legacy ? [legacy] : [];
-  if (!legacy || legacy.clientId === primary.clientId) return [primary];
-  return [primary, legacy];
+export async function resolveGoogleOAuthCredentialCandidates(): Promise<
+  GoogleOAuthClientCredentials[]
+> {
+  return resolveGoogleProviderCredentialCandidatesWithReader({
+    readCredential: (key) => process.env[key],
+    credentialKeyPairs: [GOOGLE_PRIMARY_PROVIDER_CREDENTIAL_KEYS],
+  });
 }
 
 /** Exchange an authorization code for tokens. Throws on non-2xx. */

package/corpus/templates/clips/server/lib/google-calendar-oauth.ts

@@ -12,7 +12,11 @@ import { and, eq } from "drizzle-orm";
 import { getQuery, type H3Event } from "h3";
 
 import { getDb, schema } from "../db/index.js";
-import { exchangeCode, getUserInfo } from "./google-calendar-client.js";
+import {
+  exchangeCode,
+  getUserInfo,
+  resolveGoogleOAuthCredentialCandidates,
+} from "./google-calendar-client.js";
 import {
   getActiveOrganizationId,
   normalizeOwnerEmail,
@@ -60,9 +64,8 @@ export async function handleGoogleCalendarCallback(
   }
   const ownerEmail = normalizeOwnerEmail(userEmail);
 
-  const clientId = process.env.GOOGLE_CLIENT_ID;
-  const clientSecret = process.env.GOOGLE_CLIENT_SECRET;
-  if (!clientId || !clientSecret) {
+  const [credentials] = await resolveGoogleOAuthCredentialCandidates();
+  if (!credentials) {
     return oauthErrorPage(
       "Google Calendar OAuth is not configured (missing client id/secret).",
     );
@@ -74,8 +77,8 @@ export async function handleGoogleCalendarCallback(
     // 1. Exchange code -> tokens.
     const tokens = await exchangeCode({
       code,
-      clientId,
-      clientSecret,
+      clientId: credentials.clientId,
+      clientSecret: credentials.clientSecret,
       redirectUri,
     });
     if (!tokens.access_token) {

package/corpus/templates/clips/server/lib/slack-oauth.ts

@@ -1,6 +1,13 @@
 import { randomUUID } from "node:crypto";
 
 import { writeAppState } from "@agent-native/core/application-state";
+import {
+  buildSlackAuthorizeUrl as buildCoreSlackAuthorizeUrl,
+  exchangeSlackOAuthCode as exchangeCoreSlackOAuthCode,
+  SLACK_AUTHORIZE_URL,
+  SLACK_TOKEN_URL,
+  type SlackOAuthAccessResponse,
+} from "@agent-native/core/integrations";
 import {
   deleteAppSecret,
   readAppSecret,
@@ -33,26 +40,13 @@ import type { SlackLinkSharedPayload } from "./slack-unfurls.js";
 export const CLIPS_SLACK_OAUTH_APP_ID = `${
   process.env.APP_NAME || "clips"
 }:slack`;
-export const SLACK_AUTHORIZE_URL = "https://slack.com/oauth/v2/authorize";
-export const SLACK_TOKEN_URL = "https://slack.com/api/oauth.v2.access";
+export { SLACK_AUTHORIZE_URL, SLACK_TOKEN_URL };
 export const SLACK_UNFURL_SCOPES = [
   "links:read",
   "links:write",
   "links.embed:write",
 ] as const;
 
-type SlackOAuthAccessResponse = {
-  ok?: boolean;
-  error?: string;
-  access_token?: string;
-  scope?: string;
-  bot_user_id?: string;
-  app_id?: string;
-  authed_user?: { id?: string };
-  team?: { id?: string; name?: string };
-  enterprise?: { id?: string; name?: string };
-};
-
 export type SlackInstallationListItem = {
   id: string;
   teamId: string;
@@ -87,14 +81,10 @@ export function buildSlackAuthorizeUrl(options: {
   state: string;
   scopes?: readonly string[];
 }): string {
-  const params = new URLSearchParams({
-    client_id: options.clientId,
-    redirect_uri: options.redirectUri,
-    response_type: "code",
-    scope: (options.scopes ?? SLACK_UNFURL_SCOPES).join(","),
-    state: options.state,
+  return buildCoreSlackAuthorizeUrl({
+    ...options,
+    scopes: options.scopes ?? SLACK_UNFURL_SCOPES,
   });
-  return `${SLACK_AUTHORIZE_URL}?${params.toString()}`;
 }
 
 export async function buildSlackOAuthInstallUrl(
@@ -149,32 +139,7 @@ export async function exchangeSlackOAuthCode(options: {
   redirectUri: string;
   fetchImpl?: typeof fetch;
 }): Promise<SlackOAuthAccessResponse> {
-  const {
-    code,
-    clientId,
-    clientSecret,
-    redirectUri,
-    fetchImpl = fetch,
-  } = options;
-  const res = await fetchImpl(SLACK_TOKEN_URL, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams({
-      code,
-      client_id: clientId,
-      client_secret: clientSecret,
-      redirect_uri: redirectUri,
-    }),
-  });
-  const data = (await res
-    .json()
-    .catch(() => null)) as SlackOAuthAccessResponse | null;
-  if (!res.ok || !data?.ok) {
-    throw new Error(
-      data?.error || `Slack OAuth exchange failed (${res.status})`,
-    );
-  }
-  return data;
+  return exchangeCoreSlackOAuthCode(options);
 }
 
 function asSecretScope(value: string): SecretScope | null {

package/corpus/templates/clips/server/routes/_agent-native/google/auth-url.get.ts

@@ -16,6 +16,7 @@ import {
 import {
   GOOGLE_AUTH_URL,
   GOOGLE_CALENDAR_SCOPES,
+  resolveGoogleOAuthCredentialCandidates,
 } from "../../../lib/google-calendar-client.js";
 import { CLIPS_GOOGLE_OAUTH_APP_ID } from "../../../lib/google-calendar-oauth.js";
 
@@ -59,12 +60,7 @@ export default defineEventHandler(async (event: H3Event) => {
     const calendarConnect =
       q.calendar === "1" || q.calendar === "true" || q.product === "calendar";
     const credentials = calendarConnect
-      ? process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET
-        ? {
-            clientId: process.env.GOOGLE_CLIENT_ID,
-            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-          }
-        : null
+      ? ((await resolveGoogleOAuthCredentialCandidates())[0] ?? null)
       : resolveGoogleSignInCredentials();
     if (!credentials) {
       setResponseStatus(event, 422);

package/corpus/templates/clips/server/routes/api/auth/google-calendar.get.ts

@@ -33,13 +33,13 @@ import {
 import {
   GOOGLE_AUTH_URL,
   GOOGLE_CALENDAR_SCOPES,
+  resolveGoogleOAuthCredentialCandidates,
 } from "../../../lib/google-calendar-client.js";
 import { CLIPS_GOOGLE_OAUTH_APP_ID } from "../../../lib/google-calendar-oauth.js";
 
 export default defineEventHandler(async (event: H3Event) => {
-  const clientId = process.env.GOOGLE_CLIENT_ID;
-  const clientSecret = process.env.GOOGLE_CLIENT_SECRET;
-  if (!clientId || !clientSecret) {
+  const [credentials] = await resolveGoogleOAuthCredentialCandidates();
+  if (!credentials) {
     setResponseStatus(event, 422);
     return {
       error: "missing_credentials",
@@ -89,7 +89,7 @@ export default defineEventHandler(async (event: H3Event) => {
     });
 
     const params = new URLSearchParams({
-      client_id: clientId,
+      client_id: credentials.clientId,
       redirect_uri: redirectUri,
       response_type: "code",
       // We need a refresh token, so always force prompt=consent — Google only

package/corpus/templates/content/.agents/skills/actions/SKILL.md

@@ -121,18 +121,38 @@ action trio instead:
   provider host, injects configured credentials, blocks private/internal URLs,
   and redacts secrets.
 
-Use `@agent-native/core/provider-api` as the shared substrate. A template should
-only add a thin credential adapter when it has app-specific credential lookup
-rules. If the app stores a built-in provider's OAuth grant under a narrower
-local provider id, use the runtime's `oauthProviderOverrides` instead of
-duplicating the provider config. If credentials are stored on shareable/resource
-rows rather than in the shared credential or OAuth-token stores, build a resolver
-that enforces those access checks before exposing raw provider requests. Keep
-`provider-api-request` `http: false` unless you have a separate UI permission
-model for arbitrary provider writes. Specific actions such as `search-records`,
-`search-emails`, or `sync-source` are convenience shortcuts, not capability
-limits; agents should fall back to the provider API trio when a question
-requires an endpoint or filter that the shortcut does not model.
+Use `@agent-native/core/provider-api` as the shared substrate, and build these
+actions as thin factory imports rather than copying `defineAction` schemas and
+handlers into each template:
+
+```ts
+import {
+  createProviderApiCatalogAction,
+  createProviderApiDocsAction,
+  createProviderApiRequestAction,
+} from "@agent-native/core/provider-api/actions/provider-api";
+import {
+  createDeleteStagedDatasetAction,
+  createListStagedDatasetsAction,
+  createQueryStagedDatasetAction,
+} from "@agent-native/core/provider-api/actions/staged-datasets";
+```
+
+Pass the app's existing provider runtime to the provider factories, and pass
+its app id to the staged-dataset factories. Keep app-specific descriptions,
+provider allow-lists, HTTP/tool-callability settings, and credential adapters
+as factory options. Only add a thin credential adapter when the app has
+app-specific credential lookup rules. If the app stores a built-in provider's
+OAuth grant under a narrower local provider id, use the runtime's
+`oauthProviderOverrides` instead of duplicating provider config. If credentials
+are stored on shareable/resource rows rather than in the shared credential or
+OAuth-token stores, build a resolver that enforces those access checks before
+exposing raw provider requests. Keep `provider-api-request` `http: false`
+unless a separate UI permission model authorizes arbitrary provider writes.
+Specific actions such as `search-records`, `search-emails`, or `sync-source`
+are convenience shortcuts, not capability limits; agents should fall back to
+the provider API trio when a question requires an endpoint or filter that the
+shortcut does not model.
 
 This is a framework tenet. The safety boundary should be provider host
 allow-listing, credential scoping, auth injection, private-network blocking,

package/corpus/templates/content/.agents/skills/customizing-agent-native/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: customizing-agent-native
+description: >-
+  How to adopt, compose, or selectively copy Agent Native UI into app-owned
+  code. Use when overriding shared components, customizing a template, adding
+  UI to chat or headless apps, or inspecting installed framework source.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Customizing Agent Native
+
+## Rule
+
+Start with the public component and its props, slots, callbacks, and stable
+class names. If those seams are not enough, copy the smallest useful reference
+implementation into the app and make that copy app-owned. Never edit
+`node_modules`, deep-import a private source file at runtime, or patch an
+`@agent-native/*` package.
+
+Use this order:
+
+1. Configure the public component.
+2. Compose public primitives behind a local app component.
+3. Copy one component or helper into app source and change the app import.
+4. Propose a new Toolkit seam when the same override is useful in two apps.
+
+Copying is for intentional product customization, not for hiding an upgrade
+failure or replacing Core runtime behavior.
+
+## Find The Installed Implementation
+
+Use the source that matches the installed package version:
+
+```bash
+pnpm action docs-search --query "<component or feature>"
+pnpm action source-search --query "<component or symbol>"
+rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
+rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
+```
+
+- Toolkit publishes readable TypeScript under
+  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
+- Core and first-party template source lives under
+  `node_modules/@agent-native/core/corpus/core/` and
+  `node_modules/@agent-native/core/corpus/templates/`.
+- Treat those trees as read-only references. Copy files into an app directory
+  such as `app/components/`, then import the local copy.
+
+When a copied component imports sibling helpers, copy only the required
+siblings or replace them with public package imports. Do not copy an entire
+package or template to change one surface.
+
+## Preserve The Agent-Native Contract
+
+UI ownership may change; product contracts should not:
+
+- Keep app operations in `defineAction` actions and call them through
+  `useActionQuery`, `useActionMutation`, or another named client helper.
+- Keep navigation, selection, and focused-object state visible through the
+  existing application-state keys.
+- Keep AI work in the shared agent chat instead of adding direct LLM calls.
+- Keep auth, access checks, persistence, chat transport, and agent execution in
+  Core. Do not copy those runtimes into the app.
+- Keep local adapters narrow so package upgrades still improve every surface
+  the app has not intentionally taken ownership of.
+
+## App Shapes
+
+- **Template app:** begin with its existing local adapters and domain UI. Use
+  Toolkit for repeated workspace UI; copy only the piece being customized.
+- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
+  Core. Compose or copy Toolkit presentation such as chat-history UI around it.
+- **Headless app:** stay action-first while no UI is needed. When adding a UI,
+  use the Chat template as the on-ramp or add Toolkit components without
+  replacing the existing actions.
+- **Workspace:** put one-app overrides in that app. Promote a local component
+  to `packages/shared` only when multiple workspace apps use it.
+
+## After Copying
+
+- Remove unused dependencies and imports from the copied file.
+- Keep visible text in the app's localization catalogs.
+- Run the app's formatter, typecheck, and focused tests.
+- Re-check the installed source during future package upgrades; the app-owned
+  copy does not receive upstream fixes automatically.
+
+## Don't
+
+- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
+- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
+- Don't copy Core auth, DB, action, agent-loop, or transport internals.
+- Don't fork a full template when a prop, slot, wrapper, or one-file copy works.
+
+## Related Skills
+
+- `agent-native-docs` — version-matched docs and source lookup
+- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
+- `self-modifying-code` — safe app source edits
+- `upgrade-agent-native` — supported package upgrade path
+- `adding-a-feature` — UI/action/instructions/application-state parity

package/corpus/templates/content/.agents/skills/self-modifying-code/SKILL.md

@@ -35,8 +35,14 @@ Tier 4 includes **all** of the following — not only editing package source:
 - Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
 - `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
   target any `@agent-native/*` package
-- Local patches, vendored copies, or invented "dispatch/core behavior"
-  shims meant to paper over a version skew or failed upgrade
+- Local package patches or invented "dispatch/core behavior" shims meant to
+  paper over a version skew or failed upgrade
+
+This does not prohibit intentional app-owned UI customization. When public
+props and composition are insufficient, the `customizing-agent-native` skill
+allows copying the smallest reference UI component from the installed source
+into the app. The copy must use public runtime contracts and must not replace
+Core auth, DB, actions, agent execution, or transport behavior.
 
 When an older branch needs current packages, use **`agent-native upgrade`**
 (see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
@@ -88,6 +94,8 @@ inline strings in components.
 - Don't modify `.env` files or files containing secrets
 - Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
   `@agent-native/*` package internals (including under `node_modules`)
+- Don't confuse a read-only reference copy with editing package internals: use
+  `customizing-agent-native` for selective app-owned UI adoption
 - Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
   `@agent-native/*` to "make the app run" after a version bump
 - Don't invent local dispatch/core behavior overrides when upgrade fails —
@@ -99,6 +107,7 @@ inline strings in components.
 ## Related Skills
 
 - **upgrade-agent-native** — supported path to bring an older app/workspace current
+- **customizing-agent-native** — safe selective adoption of installed reference UI
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/corpus/templates/content/.agents/skills/upgrade-agent-native/SKILL.md

@@ -63,6 +63,11 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Re-run `agent-native upgrade` or `pnpm typecheck`
    - Stop and ask the user if you cannot fix the app-level error
 
+   Intentional app-level UI customization is a separate workflow. Read
+   `customizing-agent-native` when the product needs to own a selectively
+   copied component; do not use that path to reproduce framework runtime
+   behavior or hide version skew.
+
 4. **Dry-run / partial runs**
 
    ```bash
@@ -91,4 +96,5 @@ install → refresh scaffold skills → verify, then fix **app** code only.
 
 - **self-modifying-code** — Tier 4: framework packages are off limits
 - **agent-native-docs** — version-matched docs after the bump
+- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
 - **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/content/actions/delete-staged-dataset.ts

@@ -1,14 +1,12 @@
 /**
  * Thin content re-export of staged dataset deletion, pre-bound to appId="content".
  */
-import { defineAction } from "@agent-native/core";
-import { deleteStagedDataset } from "@agent-native/core/provider-api/staged-datasets-store";
-import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { createDeleteStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
 import { z } from "zod";
 
 import { CONTENT_APP_ID } from "../server/lib/provider-api.js";
 
-export default defineAction({
+export default createDeleteStagedDatasetAction({
   description:
     "Delete a staged dataset by id, freeing its scratch storage. Use after analysis is complete or before re-staging under the same name. Only the owner who staged the dataset can delete it.",
   schema: z.object({
@@ -20,24 +18,5 @@ export default defineAction({
       ),
   }),
   http: false,
-  run: async (args) => {
-    const ctx = getCredentialContext();
-    if (!ctx) {
-      throw new Error("No authenticated context for delete-staged-dataset.");
-    }
-
-    const deleted = await deleteStagedDataset({
-      id: args.datasetId,
-      appId: CONTENT_APP_ID,
-      ownerEmail: ctx.userEmail,
-    });
-
-    if (!deleted) {
-      throw new Error(
-        `Dataset ${args.datasetId} not found (or belongs to a different owner/app).`,
-      );
-    }
-
-    return { deleted: true, datasetId: args.datasetId };
-  },
+  appId: CONTENT_APP_ID,
 });

package/corpus/templates/content/actions/list-staged-datasets.ts

@@ -1,40 +1,15 @@
 /**
  * Thin content re-export of staged dataset listing, pre-bound to appId="content".
  */
-import { defineAction } from "@agent-native/core";
-import { listStagedDatasets } from "@agent-native/core/provider-api/staged-datasets-store";
-import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { createListStagedDatasetsAction } from "@agent-native/core/provider-api/actions/staged-datasets";
 import { z } from "zod";
 
 import { CONTENT_APP_ID } from "../server/lib/provider-api.js";
 
-export default defineAction({
+export default createListStagedDatasetsAction({
   description:
     "List staged datasets stored by provider-api-request (stageAs) for the current user. Returns dataset ids, names, row counts, columns, and sizes. Use dataset ids with query-staged-dataset to aggregate, or with delete-staged-dataset to free scratch storage.",
   schema: z.object({}),
   http: { method: "GET" },
-  readOnly: true,
-  run: async () => {
-    const ctx = getCredentialContext();
-    if (!ctx) {
-      throw new Error("No authenticated context for list-staged-datasets.");
-    }
-
-    const datasets = await listStagedDatasets({
-      appId: CONTENT_APP_ID,
-      ownerEmail: ctx.userEmail,
-    });
-
-    return {
-      datasets: datasets.map((d) => ({
-        id: d.id,
-        name: d.name,
-        rowCount: d.rowCount,
-        columns: d.columns,
-        byteSize: d.byteSize,
-        updatedAt: new Date(d.updatedAt).toISOString(),
-      })),
-      total: datasets.length,
-    };
-  },
+  appId: CONTENT_APP_ID,
 });

package/corpus/templates/content/actions/provider-api-catalog.ts

@@ -1,14 +1,14 @@
-import { defineAction } from "@agent-native/core";
+import { createProviderApiCatalogAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
 import {
   CONTENT_PROVIDER_API_IDS,
-  listProviderApiCatalog,
+  getContentProviderApiRuntime,
 } from "../server/lib/provider-api.js";
 
 const ProviderSchema = z.enum(CONTENT_PROVIDER_API_IDS);
 
-export default defineAction({
+export default createProviderApiCatalogAction(getContentProviderApiRuntime(), {
   description:
     "List raw HTTP API capabilities for Content-connected providers. Use before provider-api-request when Notion convenience actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, and examples; never returns secret values.",
   schema: z.object({
@@ -17,12 +17,6 @@ export default defineAction({
     ),
   }),
   http: { method: "GET" },
-  readOnly: true,
-  run: async ({ provider }) => {
-    return {
-      providers: await listProviderApiCatalog(provider),
-      guidance:
-        "Content actions like pull-notion-page, push-notion-page, sync-notion-comments, and link-notion-page are workflow shortcuts, not capability limits. When the Notion API can answer the question with a better endpoint, query, body, pagination mode, or API version, inspect docs/spec URLs and call provider-api-request directly with the user's OAuth connection. The built-in catalog may name NOTION_API_KEY as the generic bearer slot; Content intentionally resolves that slot from the user's per-user Notion OAuth token instead of env/user-entered API keys.",
-    };
-  },
+  guidance:
+    "Content actions like pull-notion-page, push-notion-page, sync-notion-comments, and link-notion-page are workflow shortcuts, not capability limits. When the Notion API can answer the question with a better endpoint, query, body, pagination mode, or API version, inspect docs/spec URLs and call provider-api-request directly with the user's OAuth connection. The built-in catalog may name NOTION_API_KEY as the generic bearer slot; Content intentionally resolves that slot from the user's per-user Notion OAuth token instead of env/user-entered API keys.",
 });

package/corpus/templates/content/actions/provider-api-docs.ts

@@ -1,9 +1,9 @@
-import { defineAction } from "@agent-native/core";
+import { createProviderApiDocsAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
 import {
   CONTENT_PROVIDER_API_IDS,
-  fetchProviderApiDocs,
+  getContentProviderApiRuntime,
 } from "../server/lib/provider-api.js";
 
 const ProviderSchema = z.enum(CONTENT_PROVIDER_API_IDS);
@@ -23,7 +23,7 @@ const WebContentSearchSchema = z.object({
   caseSensitive: BooleanFromQuerySchema.optional(),
 });
 
-export default defineAction({
+export default createProviderApiDocsAction(getContentProviderApiRuntime(), {
   description:
     "Inspect provider API docs/spec metadata, or fetch any public API documentation page, OpenAPI spec, changelog, or web page. Use this before provider-api-request when the exact Notion endpoint, filter operator, payload shape, pagination, or API version is uncertain.",
   schema: z.object({
@@ -69,6 +69,4 @@ export default defineAction({
     ),
   }),
   http: { method: "GET" },
-  readOnly: true,
-  run: async (args) => fetchProviderApiDocs(args),
 });

package/corpus/templates/content/actions/provider-api-request.ts

@@ -1,12 +1,9 @@
-import { defineAction } from "@agent-native/core";
-import { stagingExecuteRequest } from "@agent-native/core/provider-api/staging";
-import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { createProviderApiRequestAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
 import {
   CONTENT_APP_ID,
   CONTENT_PROVIDER_API_IDS,
-  executeProviderApiRequest,
   getContentProviderApiRuntime,
 } from "../server/lib/provider-api.js";
 
@@ -68,7 +65,7 @@ const PaginationSchema = z
   })
   .optional();
 
-export default defineAction({
+export default createProviderApiRequestAction(getContentProviderApiRuntime(), {
   description:
     "Make an arbitrary authenticated HTTP request to a Content-connected provider API. " +
     "Use this as the flexible escape hatch when a convenience action cannot express the needed Notion endpoint, page/database/comment object, filter, request body, pagination mode, markdown endpoint, payload shape, or API version. " +
@@ -203,36 +200,5 @@ export default defineAction({
   }),
   http: false,
   toolCallable: false,
-  run: async (args) => {
-    if (args.stageAs) {
-      const ctx = getCredentialContext();
-      if (!ctx) {
-        throw new Error("No authenticated context for provider API staging.");
-      }
-      const providerRuntime = getContentProviderApiRuntime();
-      return stagingExecuteRequest(
-        {
-          provider: args.provider,
-          method: args.method,
-          path: args.path,
-          query: args.query,
-          headers: args.headers,
-          body: args.body,
-          auth: args.auth,
-          connectionId: args.connectionId,
-          accountId: args.accountId,
-          timeoutMs: args.timeoutMs,
-          maxBytes: args.maxBytes,
-          stageAs: args.stageAs,
-          itemsPath: args.itemsPath,
-          pagination: args.pagination,
-        },
-        (reqArgs) => providerRuntime.executeRequest(reqArgs),
-        { appId: CONTENT_APP_ID, ownerEmail: ctx.userEmail },
-      );
-    }
-    return executeProviderApiRequest(
-      args as unknown as Parameters<typeof executeProviderApiRequest>[0],
-    );
-  },
+  appId: CONTENT_APP_ID,
 });