@agent-native/core 0.112.0 → 0.113.0

package/corpus/templates/analytics/.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/analytics/.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/analytics/.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/analytics/actions/delete-staged-dataset.ts

@@ -1,14 +1,12 @@
 /**
  * Thin analytics re-export of the core delete-staged-dataset action.
  */
-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 { ANALYTICS_APP_ID } from "../server/lib/provider-credentials";
 
-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. " +
@@ -22,23 +20,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: ANALYTICS_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: ANALYTICS_APP_ID,
 });

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

@@ -1,41 +1,17 @@
 /**
  * Thin analytics re-export of the core list-staged-datasets action.
  */
-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 { ANALYTICS_APP_ID } from "../server/lib/provider-credentials";
 
-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 space.",
   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: ANALYTICS_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: ANALYTICS_APP_ID,
 });

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

@@ -1,28 +1,25 @@
-import { defineAction } from "@agent-native/core";
+import { createProviderApiCatalogAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
 import {
   ANALYTICS_PROVIDER_API_IDS,
-  listProviderApiCatalog,
+  getAnalyticsProviderApiRuntime,
 } from "../server/lib/provider-api";
 
 const ProviderSchema = z.enum(ANALYTICS_PROVIDER_API_IDS);
 
-export default defineAction({
-  description:
-    "List raw HTTP API capabilities for configured Analytics providers. Use before provider-api-request when canned actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, examples, and reusable corpus recipes; never returns secret values.",
-  schema: z.object({
-    provider: ProviderSchema.optional().describe(
-      "Optional provider id to inspect. Omit to list every provider API escape hatch.",
-    ),
-  }),
-  http: { method: "GET" },
-  readOnly: true,
-  run: async ({ provider }) => {
-    return {
-      providers: await listProviderApiCatalog(provider),
-      guidance:
-        "First-class provider actions in this app are convenience shortcuts, not capability limits. When an action cannot express the needed endpoint, object type, filter, request body, pagination mode, API version, or source-record body coverage, inspect docs/spec URLs and corpusRecipes here, then call provider-api-request or provider-corpus-job with the exact provider API method/path/query/body.",
-    };
+export default createProviderApiCatalogAction(
+  getAnalyticsProviderApiRuntime(),
+  {
+    description:
+      "List raw HTTP API capabilities for configured Analytics providers. Use before provider-api-request when canned actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, examples, and reusable corpus recipes; never returns secret values.",
+    schema: z.object({
+      provider: ProviderSchema.optional().describe(
+        "Optional provider id to inspect. Omit to list every provider API escape hatch.",
+      ),
+    }),
+    http: { method: "GET" },
+    guidance:
+      "First-class provider actions in this app are convenience shortcuts, not capability limits. When an action cannot express the needed endpoint, object type, filter, request body, pagination mode, API version, or source-record body coverage, inspect docs/spec URLs and corpusRecipes here, then call provider-api-request or provider-corpus-job with the exact provider API method/path/query/body.",
   },
-});
+);

package/corpus/templates/analytics/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 {
   ANALYTICS_PROVIDER_API_IDS,
-  fetchProviderApiDocs,
+  getAnalyticsProviderApiRuntime,
 } from "../server/lib/provider-api";
 
 const ProviderSchema = z.enum(ANALYTICS_PROVIDER_API_IDS);
@@ -23,7 +23,7 @@ const WebContentSearchSchema = z.object({
   caseSensitive: BooleanFromQuerySchema.optional(),
 });
 
-export default defineAction({
+export default createProviderApiDocsAction(getAnalyticsProviderApiRuntime(), {
   description:
     "Inspect provider API docs/spec metadata, or fetch a public provider docs/spec/changelog URL. Use this before arbitrary provider-api-request calls when the exact 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),
 });