@agent-native/core 0.107.2 → 0.109.0

package/corpus/core/src/templates/headless/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags

package/corpus/core/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -117,6 +117,33 @@ const answer = await callAgent(
 // answer is a plain string
 ```
 
+### Fast bounded read: `invokeAgentAction()`
+
+When the caller knows the exact receiver-owned read action and arguments, skip
+the receiver's model loop:
+
+```ts
+import { invokeAgentAction } from "@agent-native/core/a2a";
+
+const { result } = await invokeAgentAction({
+  target: "analytics",
+  action: "gong-calls",
+  input: { company: "Acme", days: 90, includeTranscripts: true },
+  userEmail,
+  orgDomain,
+  orgSecret,
+});
+```
+
+The receiver still owns schema validation, credentials, access scoping, audit
+attribution, and exposure policy. Direct invocation is available only for
+cataloged, authenticated, explicitly exposed read-only actions that do not
+require approval. Its JWT is audience-bound to the receiving app. Use normal
+message delegation for planning, synthesis, multi-step work, or mutations.
+
+Inside an agent loop, `call-agent` exposes the same path with `action` + `input`;
+omit `message` and `taskId` in that mode.
+
 ### Advanced: `A2AClient` (full control)
 
 ```ts
@@ -178,6 +205,7 @@ cannot carry these grants.
 | ---------------- | -------------------------------- | ------------- |
 | `message/send`   | Send a message, get a task back  | Yes           |
 | `message/stream` | Send a message, stream responses | Yes           |
+| `actions/invoke` | Invoke one exposed read action   | Yes, JWT      |
 | `tasks/get`      | Get task status by ID            | Yes           |
 | `tasks/cancel`   | Cancel a running task            | Yes           |
 

package/corpus/core/src/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -42,6 +42,11 @@ The main agent should discover available siblings before assuming capability:
 - In the agent loop, use `call-agent` with the sibling app id when another app
   owns the work or data. Never call the current app through `call-agent`; use
   local actions instead.
+- When the exact sibling-owned read action and input are already known, use
+  `invokeAgentAction()` or `call-agent` with `action` + `input`. This preserves
+  the receiver's credentials and access checks while skipping its second model
+  loop. Use prompt-based `invokeAgent()` only when the sibling must reason,
+  synthesize, mutate, or perform a multi-step workflow.
 
 Send narrow prompts to siblings: name the exact question, relevant ids, date
 ranges, and expected output shape. Preserve returned ids and URLs verbatim.

package/corpus/core/src/templates/workspace-core/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags

package/corpus/core/src/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -99,6 +99,19 @@ index the growing tables first.
   `await`s — each `await` is another round-trip.
 - Prefer **one composed endpoint** over several dependent calls.
 
+For provider wrappers, inspect the upstream API before building a list-then-
+enrich flow. Prefer the richest endpoint that can apply the real filters and
+return the needed associations or participants in one paginated operation.
+Cursor pagination is already serial; adding a serial detail/enrichment request
+to every page doubles its critical path. Exhaustive records belong in corpus
+recipes or data programs with explicit coverage, not one agent tool call per
+page or item.
+
+First-class provider actions should represent one stable conceptual operation.
+Keep arbitrary endpoint, filter, and pagination access in the provider API
+substrate; do not turn a convenience action into a capability ceiling or
+duplicate the provider transport, auth, quota, and cache implementation.
+
 ## 4. Avoid client-side waterfalls
 
 - Don't gate query B on query A's result unless B truly needs it. Fire

package/corpus/core/src/templates/workspace-core/AGENTS.md

@@ -20,7 +20,7 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
   `node_modules/@agent-native/core/corpus/` for source examples.
 - For advanced workspace features, start with `workspace`, `multi-app-workspace`,
   `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
-  `external-agents`, `mcp-protocol`, `sharing`, and `security`.
+  `external-agents`, `mcp-protocol`, `feature-flags`, `sharing`, and `security`.
 
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and this `AGENTS.md` plus `.agents/skills/` for

package/corpus/core/src/templates/workspace-root/AGENTS.md

@@ -22,7 +22,7 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
   examples.
 - For advanced workspace features, start with `workspace`, `multi-app-workspace`,
   `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
-  `external-agents`, `mcp-protocol`, `sharing`, and `security`.
+  `external-agents`, `mcp-protocol`, `feature-flags`, `sharing`, and `security`.
 
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and `packages/shared/AGENTS.md` plus

package/corpus/core/src/vite/action-types-plugin.ts

@@ -38,6 +38,18 @@ const SKIP_FILES = new Set([
  * their own `actions/` directory — the merge below is skip-existing.
  */
 const CORE_SHARING_ACTIONS: Array<{ name: string; specifier: string }> = [
+  {
+    name: "get-feature-flags",
+    specifier: "@agent-native/core/feature-flags/actions/get-feature-flags",
+  },
+  {
+    name: "list-feature-flags",
+    specifier: "@agent-native/core/feature-flags/actions/list-feature-flags",
+  },
+  {
+    name: "set-feature-flag",
+    specifier: "@agent-native/core/feature-flags/actions/set-feature-flag",
+  },
   {
     name: "share-resource",
     specifier: "@agent-native/core/sharing/actions/share-resource",

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -83,7 +83,7 @@ When the user asks for a dashboard:
 2. If a metric definition, date range, or grain is ambiguous and the choice would change the panel's numbers, use the `ask-question` clarifying tool once before building. Skip it when the dictionary or the user already settled it.
 3. If a metric is not documented, do not guess column names. Ask for the table/columns or introspect the provider schema, then propose a dictionary entry with `save-data-dictionary-entry`.
 4. Build a complete `SqlDashboardConfig` with `name` and `panels`. Optionally set top-level `columns` (1–6, default 2) to control how many grid columns the panels before any section use.
-5. Every panel needs `id`, `title`, `source`, `chartType`, `width`, and `sql`. `width` is the number of grid columns the panel spans (1..6, clamped to the active section's column count). Section panels skip `source` and `sql` and may set their own `columns` (1–6) to override the dashboard default for the panels following the section. Extension panels (`chartType: "extension"`) also skip `source` and `sql`; use `config.extensionSlotId` for new panels, with legacy `config.extensionId` supported for existing direct embeds (see "Embedding An Extension As A Panel").
+5. Every panel needs `id`, `title`, `source`, `chartType`, `width`, and `sql`. `width` is the number of grid columns the panel spans (1..6, clamped to the active section's column count). Section panels skip `source` and `sql` and may set their own `columns` (1–6) to override the dashboard default for the panels following the section. Extension panels (`chartType: "extension"`) also skip `source` and `sql`; use `config.extensionId` for ordinary author-selected shared embeds. Use `config.extensionSlotId` only when the user explicitly asks for a personal/per-viewer slot (see "Embedding An Extension As A Panel").
 6. Persist with `update-dashboard`, not raw SQL or settings writes.
 7. Navigate to it with `pnpm action navigate --view=adhoc --dashboardId=<id>`.
 
@@ -115,8 +115,27 @@ rather than forcing it into a native dashboard config.
 ## Embedding An Extension As A Panel
 
 Use `chartType: "extension"` to add an extension box alongside normal SQL
-charts. The panel skips `source` and `sql`. New boxes use a stable slot id in
-`config.extensionSlotId`:
+charts. The panel skips `source` and `sql`. For ordinary requests such as "put
+X in this dashboard," save the author-selected extension id in
+`config.extensionId`. This makes the selection part of the shared dashboard and
+keeps the widget present in scheduled report captures:
+
+```jsonc
+{
+  "id": "pipeline-widget",
+  "title": "Pipeline Widget",
+  "chartType": "extension",
+  "width": 3,
+  "config": { "extensionId": "extension-123" },
+}
+```
+
+Direct embeds receive the dashboard id, name, description, current filters,
+and panel context. Embedding does not grant extension access, so share the
+extension with the dashboard audience.
+
+Use a stable `config.extensionSlotId` only when the user explicitly wants each
+viewer to choose or install their own widget:
 
 ```text
 analytics.dashboard.<dashboard-id>.panel.<panel-id>
@@ -141,14 +160,14 @@ Empty slots show the normal install affordance instead of a broken iframe.
 
 Notes:
 
-- Slot-backed extensions receive the dashboard id, name, description, current
-  filters, and panel id/title/slot id as live context.
+- Both direct and slot-backed extensions receive dashboard and panel context.
 - Installs and extension access are per viewer. Sharing the dashboard does not
   automatically install or grant access to its extension for other viewers.
-- `config.extensionId` remains supported for legacy direct embeds. Use it only
-  when preserving an existing dashboard; new boxes should use a slot.
+- Slot installs are per-user preferences. Different viewers can see different
+  widgets, and scheduled reports running as a service identity may show an
+  empty slot. This is why slots are opt-in rather than the default.
 
-## Cloning A Legacy Direct-Extension Dashboard (e.g. per-customer copies)
+## Cloning A Direct-Extension Dashboard (e.g. per-customer copies)
 
 When the user asks for a copy of an existing extension-backed dashboard for a
 different customer/org (for example "make an Intuit version of the Roku usage
@@ -159,7 +178,7 @@ from that written file — never by pulling the body into chat context first or
 re-typing it as a `content` argument.
 
 1. `get-sql-dashboard` with `includeConfig: true` on the source dashboard and
-   confirm the target panel is a legacy `chartType: "extension"` panel with
+   confirm the target panel is a `chartType: "extension"` panel with
    `config.extensionId`; grab that extension id. For a slot-backed panel, clone
    the dashboard panel with a new stable `extensionSlotId`, then target and
    install the desired extension into that slot instead of using this body-copy
@@ -405,7 +424,7 @@ type PanelInput = PanelPatch & {
   chartType: NonNullable<PanelPatch["chartType"]>;
   source?: PanelPatch["source"]; // required for non-section / non-extension panels
   sql?: string; // required for non-section / non-extension panels
-  // For chartType "extension": use config.extensionSlotId; extensionId is legacy direct embed compatibility.
+  // For chartType "extension": use config.extensionId by default; extensionSlotId is opt-in per-viewer content.
 };
 
 type PanelFilter = {