@agent-native/core 0.114.16 → 0.115.3

package/src/templates/default/.agents/skills/app-permissions/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: app-permissions
+description: >-
+  How to enable browser feature permissions (camera, microphone, geolocation,
+  screen capture, clipboard, wake-lock) that the framework's default
+  Permissions-Policy header blocks. Use when the app must access a device or
+  browser capability that is silently failing.
+scope: dev
+metadata:
+  internal: true
+---
+
+# App Permissions — Enabling Browser Features
+
+## Rule
+
+When the app needs a browser feature that the default `Permissions-Policy`
+disables, re-enable it for first-party use in
+`server/plugins/permission-policy.ts` — change only the directive the feature
+needs, never weaken the others, and never edit the `@agent-native/*` framework
+package.
+
+## Why
+
+There are **two independent layers** between the app and a device capability, and
+this skill only touches the first one:
+
+1. **The `Permissions-Policy` gate.** This HTTP response header decides whether a
+   feature is even available in the document:
+   - `feature=()` — disabled everywhere. The JS API fails and **no browser prompt
+     is possible**.
+   - `feature=(self)` — allowed for same-origin (first-party) code.
+   - `feature=*` — allowed including cross-origin iframes.
+2. **The browser's own permission prompt.** The Allow/Block dialog only appears
+   when the app's JS actually calls the API (`getUserMedia`,
+   `navigator.geolocation.getCurrentPosition`, `getDisplayMedia`, …) **and** the
+   gate above allows the feature.
+
+So this skill's job is only to **open the gate**. It does not — and cannot —
+grant the permission itself; the user still approves the browser prompt when the
+app calls the API. If the gate is closed, the prompt never even shows and the
+call silently fails, which is the symptom that brings you here.
+
+The framework sets this default on every response (via `@agent-native/core`'s
+security-headers middleware, mounted before routes, last-write-wins):
+
+```
+camera=*, microphone=(self), geolocation=(), screen-wake-lock=()
+```
+
+Note the empty allowlists: `geolocation=()` and `screen-wake-lock=()` are
+disabled document-wide by default. Camera and microphone are already open.
+
+## How
+
+1. **Locate the plugin.** If `server/plugins/permission-policy.ts` already exists,
+   edit its `PERMISSIONS_POLICY` string to add or adjust the directive the feature
+   needs. If it does not exist, create it from the template below.
+2. **Change only what's needed.** Start from the framework default string and flip
+   only the directive(s) the feature requires — e.g. `geolocation=()` →
+   `geolocation=(self)`. Keep every other directive exactly as the default unless
+   the feature genuinely needs it relaxed. Prefer `(self)` over `*`; only use `*`
+   when a cross-origin iframe must use the feature (the default already does this
+   for `camera`).
+3. **Keep the first-request deferral.** The security middleware is registered
+   during bootstrap and `Permissions-Policy` is last-write-wins. If this plugin
+   called `getH3App(nitroApp).use(...)` at bootstrap time it would register
+   *before* the security middleware and be overwritten. Registering inside the
+   first `request` hook makes the handler append **after** the security
+   middleware, so its value wins. Do not "simplify" this into a bootstrap-time
+   `.use()`.
+4. **Typecheck.** Editing server source is a Tier 2 change — run `pnpm typecheck`
+   afterward (see `self-modifying-code`).
+
+Reference implementation (`server/plugins/permission-policy.ts`):
+
+```ts
+import { getH3App } from "@agent-native/core/server";
+import { defineEventHandler, setResponseHeader } from "h3";
+
+// Framework default: camera=*, microphone=(self), geolocation=(), screen-wake-lock=()
+// Empty allowlist () disables a feature document-wide (no browser prompt).
+// Re-enable only what the app needs, for first-party (self) use.
+// Registered on first request so this .use() appends AFTER the core
+// security middleware (last write wins for Permissions-Policy).
+const PERMISSIONS_POLICY =
+  "camera=*, microphone=(self), geolocation=(self), screen-wake-lock=()";
+
+export default (nitroApp: {
+  hooks?: { hook?: (name: string, cb: () => void) => void };
+}) => {
+  const hook = nitroApp?.hooks?.hook;
+  if (typeof hook !== "function") return;
+
+  let registered = false;
+  hook.call(nitroApp.hooks, "request", () => {
+    if (registered) return;
+    registered = true;
+    getH3App(nitroApp).use(
+      defineEventHandler((event) => {
+        setResponseHeader(event, "Permissions-Policy", PERMISSIONS_POLICY);
+      }),
+    );
+  });
+};
+```
+
+## Common directives
+
+Map the capability the app needs to the `Permissions-Policy` directive to add:
+
+| Capability | Directive | Recommended value |
+| --- | --- | --- |
+| Current location | `geolocation` | `geolocation=(self)` |
+| Camera | `camera` | `camera=*` (framework default) or `camera=(self)` |
+| Microphone | `microphone` | `microphone=(self)` |
+| Screen / tab capture | `display-capture` | `display-capture=(self)` |
+| Keep screen awake | `screen-wake-lock` | `screen-wake-lock=(self)` |
+| Clipboard read/write | `clipboard-read`, `clipboard-write` | `clipboard-read=(self), clipboard-write=(self)` |
+| Fullscreen | `fullscreen` | `fullscreen=(self)` |
+| Motion / orientation sensors | `accelerometer`, `gyroscope`, `magnetometer` | `accelerometer=(self)` (etc.) |
+
+Add directives to the comma-separated string; the browser ignores tokens it
+doesn't recognize, so unknown/experimental features degrade gracefully.
+
+**Not every capability is governed by `Permissions-Policy`.** The Notifications
+API and Web Push, for example, are gated only by their own browser prompt — they
+need no directive here. For surfacing alerts to the user in-app, see the
+`notifications` skill.
+
+## Don't
+
+- **Don't edit `@agent-native/*` package files** or the core security-headers
+  middleware — Tier 4, off limits (see `self-modifying-code`). Override the header
+  from this app-owned plugin instead.
+- **Don't register the handler at bootstrap time.** It will run before the
+  security middleware and its header value will be overwritten. Use the first
+  `request` hook as shown.
+- **Don't broaden a directive to `*`** when `(self)` is enough — `*` exposes the
+  feature to cross-origin iframes.
+- **Don't blanket-enable** features the app doesn't actually use; keep the closed
+  directives closed.
+- **Don't add `/api/*` routes or client-side hacks** to work around a blocked
+  feature — the fix is the header.
+
+## Related Skills
+
+- **security** — HTTP response headers and app-level data/access permissions
+  (distinct from these browser feature permissions).
+- **self-modifying-code** — editing server source is a Tier 2 change; typecheck
+  after and checkpoint with git.
+- **notifications** — user-facing alerts and the Notifications API, which this
+  skill does not cover.
+- **adding-a-feature** — the four-area checklist when the capability is part of a
+  larger feature.

package/src/templates/headless/.agents/skills/agent-native-docs/SKILL.md

@@ -66,6 +66,33 @@ state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
 deep-import its private source. Manual copying is only the fallback described by
 an unknown third-party package's add-style blueprint.
 
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
 ## Useful Slugs
 
 | Need                           | Slugs                                                         |

package/src/templates/workspace-core/.agents/skills/agent-native-docs/SKILL.md

@@ -66,6 +66,33 @@ state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
 deep-import its private source. Manual copying is only the fallback described by
 an unknown third-party package's add-style blueprint.
 
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
 ## Useful Slugs
 
 | Need                           | Slugs                                                         |

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

@@ -227,25 +227,29 @@ extension content:
 { "name": "My Dashboard", "contentFromAttachment": "latest" }
 ```
 
-`update-extension` accepts the same `contentFromAttachment` for full-body
-replacement, but full-body replacement requires `allowFullReplacement: true`.
-Inline `content` still works for everything you author yourself — use
-`contentFromAttachment` only to avoid regurgitating something the user already
-pasted.
+`update-extension` accepts the same `contentFromAttachment` inside its compact
+`payloadJson` string for a full-body replacement. Use `operation: "replace"`;
+that explicit operation is the safety acknowledgement for a broad rewrite.
+Inline `content` still works inside `payloadJson` for everything you author
+yourself — use `contentFromAttachment` only to avoid regurgitating something
+the user already pasted.
 
 ## Editing an extension
 
-Use the `update-extension` action. Prefer granular `edits` for surgical
-changes instead of regenerating the full HTML. For medium/large extensions,
-add stable section comments around major blocks so future agents can target
-them without touching unrelated indentation:
+Use the `update-extension` action with exactly `id`, `operation`, and
+`payloadJson`. The payload is encoded as a JSON string so model gateways cannot
+fill every optional field with empty placeholders. Prefer `operation: "edit"`
+with granular `edits` inside `payloadJson` for surgical changes instead of
+regenerating the full HTML. For medium/large extensions, add stable section
+comments around major blocks so future agents can target them without touching
+unrelated indentation:
 
 For data-only repairs, preserve the existing layout, CSS, copy, and
 interactions. Do not reconstruct and submit the entire body. The action and
-store reject full-body replacement unless `allowFullReplacement: true` is
-explicitly supplied for a user-requested visual rewrite or complete replacement
-body. If a focused edit fails, inspect the current body and adjust its target;
-do not retry unchanged arguments.
+store reject implicit full-body replacement; choose `operation: "replace"`
+only for a user-requested visual rewrite or complete replacement body. If a
+focused edit fails, inspect the current body and adjust its target; do not retry
+unchanged arguments.
 
 ```html
 <!-- agent-native:section npm-daily-chart -->
@@ -258,8 +262,8 @@ Then update just that section:
 ```json
 {
   "id": "EXTENSION_ID",
-  "edits": "[{\"op\":\"replace-section\",\"section\":\"npm-daily-chart\",\"content\":\"<section>...</section>\"}]",
-  "format": true
+  "operation": "edit",
+  "payloadJson": "{\"edits\":[{\"op\":\"replace-section\",\"section\":\"npm-daily-chart\",\"content\":\"<section>...</section>\"}],\"format\":true}"
 }
 ```
 
@@ -278,9 +282,8 @@ Supported `edits` operations:
 
 Use `expectedMatches` when ambiguity would be dangerous. Missing required
 targets fail instead of silently doing nothing. Pass `format: true` to run
-Prettier on the final HTML after the patch. Full `content` replacement is
-still available for broad rewrites when `allowFullReplacement: true` is
-supplied.
+Prettier on the final HTML after the patch. Full `content` replacement remains
+available for broad rewrites through `operation: "replace"`.
 
 Legacy `patches` still work for simple literal replacements:
 
@@ -304,6 +307,16 @@ PUT /_agent-native/extensions/:id
 { "content": "full new HTML", "allowFullReplacement": true }
 ```
 
+For the agent action, use the compact form instead:
+
+```json
+{
+  "id": "EXTENSION_ID",
+  "operation": "replace",
+  "payloadJson": "{\"content\":\"full new HTML\"}"
+}
+```
+
 ## History and rollback
 
 Extensions keep a snapshot history in SQL. A version is recorded when an

package/src/templates/workspace-core/.agents/skills/recurring-jobs/SKILL.md

@@ -21,6 +21,21 @@ Recurring jobs are scheduled tasks the agent executes automatically on a cron sc
 3. A scheduler polls every 60 seconds, finds due jobs, and executes them via `runAgentLoop`
 4. Job results are saved as chat threads
 
+## Connected MCPs in background jobs
+
+Jobs can use connected remote MCPs with the same server-side OAuth lifecycle as
+interactive chat. When creating a job that needs an MCP, bind the exact
+advertised `mcp__<server>__<tool>` names through `mcpTools`. The scheduler
+resolves only that allowlist under the job's persisted user/org request
+context; it never stores or exposes OAuth tokens, URLs, or arbitrary proxy
+targets. A revoked connector or missing tool fails the run clearly instead of
+silently widening access.
+
+Use an app-owned bounded import/upsert action for writes. Keep provider-specific
+response mapping, provenance, deduplication, and write policy in the app rather
+than in core. For example, a job can read meeting notes from any connected MCP
+and pass normalized action items to an app's idempotent `import` action.
+
 ## Job Tool (built in)
 
 | Tool          | Action     | Purpose                                                    |

package/src/triggers/actions.ts

@@ -124,6 +124,7 @@ async function handleDefine(
     condition: args.condition || undefined,
     mode: "agentic",
     domain: args.domain || undefined,
+    delegatedPolicyId: args.delegated_policy_id || undefined,
     createdBy: owner,
     runAs: "creator",
   };
@@ -163,6 +164,9 @@ async function handleUpdate(
   if (args.condition !== undefined) {
     meta.condition = args.condition || undefined;
   }
+  if (args.delegated_policy_id !== undefined) {
+    meta.delegatedPolicyId = args.delegated_policy_id || undefined;
+  }
   const newBody = args.body ?? body;
 
   await resourcePut(
@@ -235,8 +239,8 @@ export function createAutomationToolEntries(
 
 - **list-events**: List all registered event types that automations can subscribe to. Returns event names, descriptions, and payload schemas. Call this BEFORE defining an automation to discover available events.
 - **list**: List all automations (triggers). Shows name, event, condition, mode, status, and domain. Optional params: domain, enabled_only.
-- **define**: Create a new automation. IMPORTANT: Always confirm with the user before calling — show them a summary of what will be created. Required params: name, trigger_type, body. Optional: event, schedule, condition, mode, domain.
-- **update**: Update an existing automation's settings (enabled, condition, body, etc.). Required param: name. Optional: enabled, condition, body.
+- **define**: Create a new automation. IMPORTANT: Always confirm with the user before calling — show them a summary of what will be created. Required params: name, trigger_type, body. Optional: event, schedule, condition, mode, domain, delegated_policy_id.
+- **update**: Update an existing automation's settings (enabled, condition, body, delegated_policy_id, etc.). Required param: name.
 - **delete**: Delete an automation. Always confirm with the user first. Required param: name.
 - **fire-test**: Fire a test event to validate automations. Emits a test.event.fired event. Optional param: data (JSON string).`,
         parameters: {
@@ -284,6 +288,11 @@ export function createAutomationToolEntries(
               description:
                 "Domain tag for grouping (mail, calendar, clips, etc.). Used by define and list.",
             },
+            delegated_policy_id: {
+              type: "string",
+              description:
+                "Optional app-owned stored policy id. It is passed by the trusted trigger runtime, never as action input. Only use an id documented by the app.",
+            },
             body: {
               type: "string",
               description:

package/src/triggers/dispatcher.ts

@@ -94,6 +94,9 @@ export function parseTriggerFrontmatter(content: string): {
       case "domain":
         meta.domain = value;
         break;
+      case "delegatedPolicyId":
+        meta.delegatedPolicyId = value || undefined;
+        break;
       case "createdBy":
         meta.createdBy = value;
         break;
@@ -135,6 +138,16 @@ export function buildTriggerContent(
     lines.push(`condition: "${meta.condition.replace(/"/g, '\\"')}"`);
   lines.push(`mode: ${meta.mode}`);
   if (meta.domain) lines.push(`domain: ${meta.domain}`);
+  if (
+    meta.delegatedPolicyId &&
+    !/^[a-z0-9][a-z0-9._:-]{0,127}$/i.test(meta.delegatedPolicyId)
+  ) {
+    throw new Error(
+      "Delegated automation policy IDs must be 1-128 letters, numbers, dots, underscores, colons, or hyphens.",
+    );
+  }
+  if (meta.delegatedPolicyId)
+    lines.push(`delegatedPolicyId: ${meta.delegatedPolicyId}`);
   if (meta.createdBy) lines.push(`createdBy: ${meta.createdBy}`);
   if (meta.orgId) lines.push(`orgId: ${meta.orgId}`);
   if (meta.runAs) lines.push(`runAs: ${meta.runAs}`);
@@ -360,7 +373,7 @@ async function isTriggerRunAsStillValid(
 }
 
 async function dispatchAgentic(
-  resource: { path: string; owner: string; content: string },
+  resource: { id: string; path: string; owner: string; content: string },
   meta: TriggerFrontmatter,
   body: string,
   payload: unknown,
@@ -483,6 +496,12 @@ ${body}`;
             send: (event) => events.push(event),
             signal: controller.signal,
             threadId: thread.id,
+            actionCaller: "automation",
+            automation: {
+              triggerId: resource.id,
+              triggerName,
+              policyId: meta.delegatedPolicyId,
+            },
           });
         } finally {
           clearTimeout(timeout);

package/src/triggers/types.ts

@@ -25,6 +25,11 @@ export interface TriggerFrontmatter {
   mode: "agentic" | "deterministic";
   /** Domain tag for filtering in per-template UIs. */
   domain?: string;
+  /**
+   * Optional application-owned policy id carried into actions by the trusted
+   * trigger dispatcher. It is not model-supplied action input.
+   */
+  delegatedPolicyId?: string;
   createdBy?: string;
   orgId?: string;
   runAs?: "creator" | "shared";

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

@@ -187,7 +187,15 @@ function scanActionFiles(actionsDir: string): string[] {
       const content = fs.readFileSync(path.join(actionsDir, f), "utf-8");
       const reexportsDefaultAction =
         /export\s*\{\s*default\s*\}\s*from\s*["'][^"']+["']/.test(content);
-      if (!content.includes("defineAction") && !reexportsDefaultAction) {
+      const exportsActionFactory =
+        /export\s+default\s+(?:create[A-Z][A-Za-z0-9]*Action|defineActionFactory)\s*\(/.test(
+          content,
+        );
+      if (
+        !content.includes("defineAction") &&
+        !reexportsDefaultAction &&
+        !exportsActionFactory
+      ) {
         return false;
       }
     } catch {

package/corpus/templates/analytics/server/handlers/sql-query.ts

@@ -1,36 +0,0 @@
-import { readBody } from "@agent-native/core/server";
-import { defineEventHandler, setResponseStatus } from "h3";
-
-import { runApiHandlerWithContext } from "../lib/credentials";
-import {
-  isDashboardPanelSource,
-  normalizeDashboardPanelQuery,
-  runDashboardPanelQuery,
-} from "../lib/dashboard-panel-query";
-
-export const handleSqlQuery = defineEventHandler(async (event) => {
-  return runApiHandlerWithContext(event, async (ctx) => {
-    const { query: rawQuery, source } = (await readBody(event)) as {
-      query?: unknown;
-      source?: unknown;
-    };
-
-    if (!isDashboardPanelSource(source)) {
-      setResponseStatus(event, 400);
-      return {
-        error:
-          "Invalid source. Must be 'bigquery', 'ga4', 'amplitude', 'first-party', 'demo', 'prometheus', or 'program'",
-      };
-    }
-
-    try {
-      const query = normalizeDashboardPanelQuery(source, rawQuery);
-      return await runDashboardPanelQuery({ source, query, ctx });
-    } catch (error: any) {
-      const message = error?.message || String(error);
-      console.error(`SQL query error (${source}):`, message);
-      setResponseStatus(event, /DB query timed out/i.test(message) ? 504 : 400);
-      return { error: message };
-    }
-  });
-});

package/corpus/templates/analytics/server/routes/api/sql-query.post.ts

@@ -1 +0,0 @@
-export { handleSqlQuery as default } from "../../handlers/sql-query";