@agent-native/core 0.214.0 → 0.216.0

package/dist/templates/factory/.agents/skills/review-latest-feedback/references/slack-reaction-replies.md

@@ -13,53 +13,35 @@ record as history; the root remains held without a thread read or status reply.
 Capture
 the exact Slack actor ID used by the connected tool at sweep start. A mark is
 owned by this task only when its reaction owner ID matches that actor ID. Each
-unheld owned root needs a current disposition and a matching status reply by
-that same actor under that same parent, even when the root has only `✅` or `🎫`. A
-same-run fix gets its final reply after verification; continuing work gets a
-concrete progress reply. An earlier generic “taking a look” does not satisfy
-this update. If an existing reply already names the exact canonical disposition
-label and includes its recorded evidence verbatim, read it back and record its
-timestamp and author ID instead of duplicating it. Do not accept a vague or
-negated substring such as `Not fixed` as the `Fixed` label; reject the whole
-reply if a `Fixed` label is later contradicted by a claim that the scope remains
-not fixed, unfixed, or broken. Use `Partially fixed` while any distinct scope
-remains unfinished or a human/team handoff is still `unassigned` or `accepted`.
-A completed handoff is retained history, not an open follow-up.
-This is one current status reply per owned root, not a reply on every sweep.
-Reuse the existing same-actor reply while its disposition and evidence remain
-current; send an update when either materially changes. For a recent
-unanswered reporter question, reuse the existing same-actor question/update as
-the status reply when it states the disposition and evidence. If it does not,
-post at most one concise status update that points to the existing unanswered
-question without asking it again; then wait silently. Do not send another
-question or progress ping before the four-day rule below. When a disposition
-includes human handoffs, the status reply must name each handoff's recorded
-owner and action; include its scope when the report context does not make it
-clear.
+unheld owned root needs a current same-actor status reply under the same parent.
+Reuse it while the disposition remains current; send one short update when it
+materially changes. Write one short sentence in plain, non-technical language,
+then end with the exact bot disclosure
+`this was sent from a bot.` Say what changed. Use `🎫` only for unresolved
+work; when it is used, briefly say what still needs investigation or action and
+name its owner when known. Do not explain absent reactions or mention a closed,
+historical `🎫`. Keep scope, evidence, and handoff details in the internal
+ledger.
 
-Interpret the three root reactions independently from the current disposition:
+Do not send a routine second reply just to announce a merge or publication.
 
-- `👀` is a permanent claim/history mark, not an open/closed indicator.
-- `✅` is permanent history for named scopes that passed direct post-change
-  proof. Add it as soon as any scope passes; do not wait for other scopes or
-  merge. Keep it if later evidence changes the scope's status, and explain the
-  historical mark in the current reply and inventory.
-- `🎫` is permanent history for a distinct human action, including an
-  unassigned team action or reporter request. Keep it after completion,
-  answer, or four-day abandonment; label it historical in the current reply
-  and inventory when it no longer blocks progress.
+For a recent unanswered reporter question, reuse the existing same-actor
+question/update as the status reply when it still reflects the disposition. If
+it does not, post at most one concise update that points to the question
+without asking it again; then wait silently. Do not send another question or
+progress ping before the four-day rule below. An evidence-only addendum or
+correction is not a current status; edit it into a concise disposition when
+possible, or send one status after the latest human reply.
 
-The current status reply is the source for whether work remains open. When a
-root has only `👀`, say that no scope has passed the proof bar for `✅`, whether
-the next step belongs to this workflow, and why no separate human action needs
-`🎫`. Reuse a current reply rather than posting again on every sweep.
-
-An evidence-only addendum or a correction is not a current status. When your
-newest own reply is one of those, edit that reply into the full canonical
-disposition when possible; otherwise send one final status after the latest
-human reply. Name the verified `✅` scope or why none applies, every open scope,
-and each `🎫` action with its owner or why none applies. Keep the exact bot
-disclosure and read the visible final reply and root reactions back.
+Keep full proof, scope, and handoff details in the internal ledger. When an
+active `🎫` action remains, record its brief plain-language summary as
+`statusReply.pendingActionSummary` and include that summary in the short reply.
+When `unfinishedScopes` is nonempty, also record a brief
+`statusReply.unfinishedScopeSummary` that names remaining work using wording
+grounded in its recorded scope or evidence and says it is still open; include it
+in the public reply even when there is no active `🎫`.
+Do not explain absent reactions or list every scope. End with the exact bot
+disclosure and read the visible reply and root reactions back.
 
 When editing an ordinary Slack reply, pass its visible body as
 `message.markdown_text` to `slack_edit_message`; `message.text` is a fallback
@@ -166,7 +148,8 @@ then immediately update and read back each applicable root reaction before
 advancing to the next report. Add `✅` as soon as any reported scope passes the
 direct post-change proof bar, including before merge; use
 **Partially fixed** for the overall disposition when another scope remains,
-and describe both scopes separately in the reply. Do not wait for an entire
+and record both scopes in the internal ledger. Keep the reply short; do not
+wait for an entire
 multi-symptom report to be resolved before checking off its verified scope.
 Keep all existing reactions after scopes close. Post the final disposition and
 read back the final reply and reactions; the status shows closure while the
@@ -174,7 +157,7 @@ eye remains as history. Never remove or clean up any reaction. An open PR can
 earn `✅` as soon as the relevant
 `verifying-changes` proof bar passes. During that period, `✅` marks the
 verified scope and `👀` may remain whether or not another scope or merge is
-open; the marks are independent. The current disposition says what remains.
+open; the marks are independent. The internal ledger records what remains.
 For UI behavior, a focused
 regression qualifies only if it exercises the changed component and asserts the
 reported visible result or persisted state; callback-only assertions, mocked
@@ -182,24 +165,28 @@ children, class-name checks, and source inspection do not. For clipping,
 wrapping, contrast, or alignment, inspect rendered geometry at the reported
 viewport or replay the flow in the running app. Use an app/preview replay when
 the regression does not meet that bar. For non-UI scopes, use the area-specific
-action, query, or test proof. Say that merge or rollout is still pending; the
-checkmark records the verified scope and does not claim it is shipped or live.
+action, query, or test proof. Record merge or rollout state in the internal
+ledger; the checkmark records verified scope and does not claim it is shipped
+or live.
 Before leaving each report, compare verified scopes and human/team handoffs
 with a fresh root-reaction read. Ensure one `✅` is present when any scope passed the
 proof bar and one `🎫` whenever any distinct unfinished action requires another
 person or team to act, even before ownership is assigned or accepted. Keep the
 mark as history after completion; read back each changed root reaction and
-verify its owner. If either mark does
-not apply, the current reply must say why. Emoji text in a reply is not a
+verify its owner. Record why a mark is absent in the internal ledger. Never
+explain absent `👀` or `✅` in a Slack reply. Emoji text in a reply is not a
 reaction. Preserve every existing reaction. If later proof invalidates a prior
 checkmark, move that scope out of active `fixedScopes[]` and add a
 `historicalReactionMarks[]` entry with `emoji`, `scope`, `reason`, and the exact
-prior `previousStatus`; the current status and reaction decision must explain
-why the retained mark is historical. If the owner withdraws an accepted action
+prior `previousStatus`; keep the explanation in the internal ledger rather
+than the Slack reply. If the owner withdraws an accepted action
 tracked by `🎫`, also preserve the exact earlier accepted `handoff` and owner
-`withdrawalReply`, move it out of current `handoffs[]`, and explain the history
-in the current status. The checker validates these records against the captured
-thread; never remove or clean up a reaction.
+`withdrawalReply`, and move it out of current `handoffs[]`. Keep that history
+in the internal ledger. Preserve the recorded evidence and historical action in
+the ledger; do not repeat a closed handoff in Slack unless a current action
+remains. When a recorded action has a validated `publicActionSummary`, it may
+be used for a current `🎫` summary. The checker validates it against the
+recorded action and captured thread; never remove or clean up a reaction.
 Add `🎫` for each distinct unfinished team or engineering action that another
 person or team must perform outside this workflow, whether or not a named
 person has accepted it or an external tracker ticket exists. Record each such
@@ -245,8 +232,9 @@ Keep its original `scope`, `action`, `requestReply`, and ticket-bearing
 `resolution: "answered"` and include the exact human `closureReply` from the
 same thread. For an unanswered request,
 set `resolution: "abandoned_no_answer"` only after four days with no later human
-reply, and omit `closureReply`. The current status must identify the historical
-action and explain why its mark remains. Link an external tracker ticket only
+reply, and omit `closureReply`. The internal ledger must identify the
+historical action and explain why its mark remains; do not explain it in the
+Slack reply unless a current follow-up remains. Link an external tracker ticket only
 if one already exists; do not create or promise one without authorization. If a
 human later refuses the accepted action, preserve `🎫` as history and update
 the status with the refusal and blocker.
@@ -282,10 +270,11 @@ do not send a second owner update. If another task owns it or ownership is
 unclear, preserve the eye, record the source in the ledger, and stop. Keep
 distinct scopes and their status clear.
 
-Compare each reported symptom with the evidence. State what is fixed and what
-is not. Use one root `✅` when at least one fixed scope is verified; it covers every
-verified scope listed in `fixedScopes[]`, which the status must name with its
-proof. Use one root `🎫` whenever at least one distinct unfinished action
+Compare each reported symptom with the evidence. If the report is only partly
+fixed, say so briefly and keep the scope details in the ledger. Use one root
+`✅` when at least one fixed scope is verified; it covers every
+verified scope listed in `fixedScopes[]`, which the internal ledger must name
+with its proof. Use one root `🎫` whenever at least one distinct unfinished action
 requires another person to act; it covers the actions listed in `handoffs[]`
 and active requests in `reporterRequests[]`. Handoffs include unassigned
 actions and completed actions whose evidence and `status: "completed"` remain
@@ -299,18 +288,6 @@ team handoff also gets `🎫`. Do not create or promise an external tracker
 ticket without authorization. Never imply a
 partial fix resolved the whole report.
 
-For beta app fixes, check the matching merge-triggered publisher and keep
-details in the recap. Do not post a routine second reply for merge or rollout.
-If a reporter-facing reply is otherwise due, link the merged PR and state the
-beta status in plain language. Say it is live only after checking it there. If
-publication is pending, say it should follow soon without an exact date. If
-the app or behavior cannot be checked, name that limit. If the publisher is
-missing or failed, give no ETA and name the next action and owner. Keep hashes,
-branch names, CI, workflow details, and run IDs out of reporter replies. For
-package work, distinguish the source PR from any release PR and registry proof;
-source merge alone does not establish publication. Give no ETA for a pending
-package release.
-
 For every reply in each final full-thread snapshot, record a read-back of the
 workflow reactions on that reply. If the connector shows `👀`, `✅`, or `🎫`,
 call `slack_get_reactions` for the reply's own timestamp and record exact owner

package/dist/templates/headless/.agents/skills/actions/references/action-fields.md

@@ -140,6 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
-Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other direct HTTP caller (bearer or API key, MCP OAuth token, org service token, extension iframe, or mobile app) gets `409 approval_required`, and a service identity can never approve. A2A tasks use their separate approval flow. The task pauses until its owner approves, then replays the approved tool call under its approval lease. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. The agent loop, plan mode registry, HTTP action route, generated Workers entry, and MCP dispatch evaluate the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. The local `pnpm action ...` CLI calls `handler.run()` directly and does not evaluate `needsApproval`. Treat it as a local development tool, not an approval boundary. A caller that must run unattended needs a different action, never a bypass of the gate.
 
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/dist/templates/workspace-core/.agents/skills/actions/references/action-fields.md

@@ -140,6 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
-Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other direct HTTP caller (bearer or API key, MCP OAuth token, org service token, extension iframe, or mobile app) gets `409 approval_required`, and a service identity can never approve. A2A tasks use their separate approval flow. The task pauses until its owner approves, then replays the approved tool call under its approval lease. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. The agent loop, plan mode registry, HTTP action route, generated Workers entry, and MCP dispatch evaluate the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. The local `pnpm action ...` CLI calls `handler.run()` directly and does not evaluate `needsApproval`. Treat it as a local development tool, not an approval boundary. A caller that must run unattended needs a different action, never a bypass of the gate.
 
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/dist/templates/workspace-core/.agents/skills/turn-into-app/SKILL.md

@@ -13,15 +13,16 @@ metadata:
 
 # Turn Into App
 
-Give a proven workflow the face of an app and the brain of an agent. The first
-screen shows the user's world, populated. Controls on those objects hand work
-to the in-app agent, the object shows it is working, and the result lands back
-in the UI. A form under a stepper bar is the failure to prevent.
+Give a proven workflow an Agent-Native app face and agent brain. Start with
+populated domain screens. Object controls send work to the agent; the object
+shows progress and receives the result. Avoid form-under-stepper layouts.
 
 ## Host, source, and when to ask
 
 ### Classify the host
 
+- Local scaffolding needs Node.js 22.22.0 or newer (including npm/npx) and
+  pnpm.
 - **Local host**: a terminal, a filesystem, and a target checkout (Claude Code,
   Codex, Cursor, or an Agent-Native agent that can edit files). Build the app in
   that checkout with steps 1-6. Never call `start-workspace-app-creation` or
@@ -105,9 +106,8 @@ opens on a mapping or setup screen.
 
 ## Workflow
 
-Copy this checklist and keep it current. Pace: aim for about 45 minutes; note
-the start time (`date`), and if 35 minutes have passed when the review starts,
-run one pass and list the open criteria.
+Copy and update this checklist. Aim for 45 minutes; note the start time
+(`date`). If review starts after 35 minutes, run one pass and list open criteria.
 
 ```text
 - [ ] 0 Host classified, source picked
@@ -160,13 +160,12 @@ without waiting.
 
 ### 3. Create the real scaffold
 
-Before the first command, say once what the run executes (install, scaffold,
-checks, a dev server, a headless browser), so permission prompts do not read
-as trouble.
+Before the first command, name the steps (install, scaffold, checks, dev server,
+headless browser) and estimate work time from the source and host. Separate
+external setup waits, so delays are expected.
 
-Choose a short slug and never overwrite an existing app. For a standalone app,
-run from the directory that should contain it (the app is its own git
-repository; say so when it sits inside another checkout):
+Choose a short slug and never overwrite an app. Run standalone creation from
+its parent directory, noting that the nested app is its own Git repository:
 
 ```bash
 npx --yes @agent-native/core@latest create <slug> --standalone --template chat
@@ -182,11 +181,10 @@ from the workspace root:
 pnpm exec agent-native add-app <slug> --template chat
 ```
 
-Read the generated `AGENTS.md`, and its `build-an-app` skill when the scaffold
-ships one. Where that guidance skips the design record, screenshots, or build,
-leaves `DESIGN.md` alone, says not to set `AUTH_DISABLED`, or says to stop the
-dev server, this skill's steps win for this run. Use another first-party
-template only when it materially fits.
+Read the generated `AGENTS.md` and any `build-an-app` skill. This skill
+overrides guidance that skips the design record, screenshots, or build; leaves
+`DESIGN.md` unchanged; omits `AUTH_DISABLED` or says not to set it; or stops
+the dev server. Use another first-party template only if it materially fits.
 
 If a scaffold or install step fails, times out (no output for 5 minutes), or is
 denied, the app does not exist yet. Retry once where a retry could help, then
@@ -195,6 +193,10 @@ hand-build the app in another stack, edit a pinned dependency version to force
 an install, or continue in a half-created directory; a workaround the user
 requests is named in the report.
 
+Before resuming, inspect the target and verify completed stages. Tell the user
+what exists, the next stage, and estimated active work; resume at the first
+unverified stage without rerunning scaffolding or replacing completed work.
+
 Then save the brief as `docs/brief.md`, append the domain surface's design to
 `DESIGN.md` (UI direction guide, section 4), and follow
 [the run and deploy guide](references/local-run-and-deploy.md) to set

package/dist/triggers/actions/manage-automation.d.ts

@@ -93,6 +93,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     previouslyEnabled?: undefined;
     requestedEnabled?: undefined;
 } | {
+    scope?: undefined;
     enabled?: undefined;
     nextRun?: undefined;
     created?: undefined;
@@ -100,7 +101,6 @@ declare const _default: import("../../action.js").ActionDefinition<{
     resourceId: string;
     name: string;
     updated?: undefined;
-    scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
     schedule?: undefined;

package/dist/usage/actions/get-usage-metrics.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
-import { defineAction } from "../../action.js";
-import { ALL_USAGE_APPS, listAppUsageMetrics, USAGE_APP_FILTER_ALL, USAGE_APP_FILTER_CURRENT, } from "../metrics-store.js";
+import { defineAction, fail } from "../../action.js";
+import { isOrgMember } from "../../org/membership.js";
+import { ALL_USAGE_APPS, canViewWorkspaceUsage, listAppUsageMetrics, USAGE_APP_FILTER_ALL, USAGE_APP_FILTER_CURRENT, } from "../metrics-store.js";
 import { resolveUsageAppKey } from "../store.js";
 function resolveAppSelection(app, appId) {
     if (appId !== undefined) {
@@ -16,12 +17,17 @@ function resolveAppSelection(app, appId) {
     return app;
 }
 export default defineAction({
-    description: 'Get LLM usage metrics for Settings › Usage: lookback totals, the daily trend split by feature, app, model and surface (dailyBy), top features, models, apps, chats and people, tool calls per day, recent prompts, and the apps with usage. Covers every app unless app names one. Members see only their own usage; scope "workspace" (everyone in the organization) is for owners and admins. billing.unit identifies Builder.io credits, estimated dollars, mixed billing, or unknown when historical engine metadata is missing.',
+    description: 'Reports this workspace\'s own agent/LLM usage (Settings › Usage) for members of this organization only; it does NOT cover usage, credits, or activity of external customers, accounts, companies, or product usage, which belong to the app that owns that data (see <relevant-apps>, or search with describe-workspace-apps). Returns lookback totals, the daily trend (dailyBy feature, app, model and surface), top features, models, apps, chats and people, tool calls per day, and recent prompts, across every app unless app names one. Members see only their own usage; scope "workspace" (everyone in the organization) is for owners and admins. billing.unit identifies Builder.io credits, estimated dollars, mixed billing, or unknown.',
     http: { method: "GET" },
     schema: z.object({
         sinceDays: z.coerce.number().int().min(1).max(365).default(30),
         scope: z.enum(["me", "workspace"]).default("me"),
-        userEmail: z.string().trim().min(1).optional(),
+        userEmail: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("Email of a member of this organization to filter usage to. Not for customers or other external accounts."),
         app: z
             .string()
             .trim()
@@ -39,6 +45,23 @@ export default defineAction({
     run: async ({ sinceDays, scope, userEmail, app, appId }, ctx) => {
         if (!ctx?.userEmail)
             throw new Error("Not authenticated.");
+        // scope "me" ignores userEmail, so only a workspace lookup is checked.
+        if (scope === "workspace" &&
+            userEmail &&
+            ctx.orgId &&
+            userEmail.toLowerCase() !== ctx.userEmail.toLowerCase()) {
+            // Unauthorized callers get one answer whether or not the email is a
+            // member, so the lookup cannot be used to probe the roster.
+            if (!(await canViewWorkspaceUsage({
+                ownerEmail: ctx.userEmail,
+                orgId: ctx.orgId,
+            }))) {
+                fail("Only organization owners and admins can look up another person's usage with get-usage-metrics. Usage, credits, or activity for customers, accounts, or companies belongs to the app that owns that data (see <relevant-apps> or run describe-workspace-apps with a query).", { errorCode: "usage_user_lookup_forbidden", statusCode: 403 });
+            }
+            if (!(await isOrgMember(ctx.orgId, userEmail))) {
+                fail(`${userEmail} is not a member of this organization. get-usage-metrics only covers this workspace's own agent usage; usage, credits, or activity for customers, accounts, or companies belongs to the app that owns that data (see <relevant-apps> or run describe-workspace-apps with a query).`, { errorCode: "usage_user_not_org_member", statusCode: 404 });
+            }
+        }
         const selection = resolveAppSelection(app, appId);
         return listAppUsageMetrics({ sinceDays, scope, userEmail, builderCreditsEnabled: true }, {
             ownerEmail: ctx.userEmail,

package/dist/usage/actions/manage-usage-alert.js

@@ -15,6 +15,11 @@ export default defineAction({
         channels: z.array(channel).min(1).optional(),
         enabled: z.boolean().optional(),
     }),
+    mcpAnnotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: false,
+    },
     run: async ({ operation, scope, ruleId, appId, unit, period, limit, channels, enabled }, ctx) => {
         if (!ctx?.userEmail)
             throw new Error("Not authenticated.");

package/dist/vite/client.js

@@ -982,7 +982,6 @@ function getDefaultOptimizeDeps(cwd) {
             specifier: "@modelcontextprotocol/ext-apps/app-bridge",
             packageName: "@modelcontextprotocol/ext-apps",
         },
-        { specifier: "@paper-design/shaders-react" },
         { specifier: "@radix-ui/react-accordion" },
         { specifier: "@radix-ui/react-alert-dialog" },
         { specifier: "@radix-ui/react-aspect-ratio" },
@@ -3482,11 +3481,14 @@ const DEFAULT_VITE_WATCH_IGNORED_DIRS = new Set([
     "build",
 ]);
 export function defaultViteWatchIgnored(root) {
-    return (file) => path
-        .relative(root, file)
-        .split(/[\\/]/)
-        .slice(0, -1)
-        .some((segment) => DEFAULT_VITE_WATCH_IGNORED_DIRS.has(segment));
+    return (file) => {
+        const segments = path.relative(root, file).split(/[\\/]/);
+        return segments
+            .slice(0, -1)
+            .some((segment, index) => segment === ".generated" && index === 0 && segments[1] === "bridge"
+            ? false
+            : DEFAULT_VITE_WATCH_IGNORED_DIRS.has(segment));
+    };
 }
 function forceServeOnly(pluginOrPreset) {
     if (Array.isArray(pluginOrPreset))

package/dist/workspace-connections/actions/bulk-update-workspace-user-groups.js

@@ -12,6 +12,11 @@ export default defineAction({
             .describe("Workspace member email addresses to change."),
         operation: z.enum(["add", "remove"]).describe("Membership operation."),
     }),
+    mcpAnnotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: false,
+    },
     run: async (args, ctx) => {
         await assertWorkspaceUserGroupManager(ctx?.orgId, ctx?.userEmail);
         return updateWorkspaceUserGroupMembers({

package/dist/workspace-connections/actions/delete-workspace-user-group.js

@@ -7,6 +7,11 @@ export default defineAction({
     schema: z.object({
         id: z.string().min(1).describe("User group ID to delete."),
     }),
+    mcpAnnotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: false,
+    },
     run: async ({ id }, ctx) => {
         await assertWorkspaceUserGroupManager(ctx?.orgId, ctx?.userEmail);
         const orgId = ctx?.orgId ?? "";

package/dist/workspace-connections/actions/upsert-workspace-user-group.js

@@ -11,6 +11,11 @@ export default defineAction({
             .default([])
             .describe("Workspace member email addresses in this group."),
     }),
+    mcpAnnotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: false,
+    },
     run: async (args, ctx) => {
         await assertWorkspaceUserGroupManager(ctx?.orgId, ctx?.userEmail);
         return upsertWorkspaceUserGroup({

package/docs/content/actions-access-control.mdx

@@ -164,9 +164,9 @@ A handful of actions are too consequential to let the agent run on its own, like
 
 When `needsApproval` is omitted, behavior is byte-for-byte unchanged. There is no extra cost on the common path.
 
-This works the same way for legacy `parameters`-style actions and for schema-based actions. It also works the same way for the in-app agent, sub-agents, A2A, and MCP callers, because every agent surface routes through the same loop.
+This works the same way for legacy `parameters`-style actions and for schema-based actions. The in-app agent and sub-agents pause in the agent loop. MCP and A2A use their own approval flows.
 
-Calls over the [HTTP API](/docs/http-api) cannot give approval. When a call needs it, the route refuses with a `409` and `errorCode: "approval_required"`, whether the caller holds a bearer token, an API key, an MCP OAuth token, an org service token, or an A2A identity. A service identity can never approve. Only the app's own signed-in UI runs such a call directly, because the person using it is the one approving. A browser call proves it comes from that UI with a short-lived UI capability. A call that claims to be the app without one gets a `403` with `errorCode: "ui_capability_required"`, and the app's client mints the capability and retries once. To have an agent's calls approved, connect it over [MCP](/docs/external-agents) or have it ask in the app's agent chat.
+Direct calls to the [HTTP API](/docs/http-api) cannot provide human approval. The action route runs a gated call only for the proven app UI or the app's MCP directory widget. Other direct HTTP callers receive a `409` with `errorCode: "approval_required"`, and a service identity cannot approve. The shared client sends a short-lived UI capability with signed-in writes. A call without proof receives `403` with `errorCode: "ui_capability_required"`, then the client mints the capability and retries once. A2A tasks use their own approval flow, not this HTTP response. The task pauses until its owner approves, then replays the approved tool call. The local `pnpm action ...` CLI calls `handler.run()` directly and does not evaluate `needsApproval`. Treat this field as an approval flow, not an authorization boundary.
 
 ### How the loop pauses {#loop}
 
@@ -403,12 +403,12 @@ A create action calls neither helper. It only needs to stamp `ownerEmail` (and `
 
 The four mechanisms are not interchangeable:
 
-| Mechanism                         | Question it answers                                   | Applies to                       |
-| --------------------------------- | ----------------------------------------------------- | -------------------------------- |
-| `access`                          | Does the caller hold the declared role or membership? | All six dispatch sites           |
-| `authorize`                       | May this caller perform the operation at all?         | All six dispatch sites           |
-| `needsApproval`                   | Should a human approve this specific permitted call?  | Every surface                    |
-| `accessFilter()`/`assertAccess()` | Which rows may this permitted caller see or write?    | Inside `run()`, per query or row |
+| Mechanism                         | Question it answers                                   | Applies to                                                      |
+| --------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------- |
+| `access`                          | Does the caller hold the declared role or membership? | All six dispatch sites                                          |
+| `authorize`                       | May this caller perform the operation at all?         | All six dispatch sites                                          |
+| `needsApproval`                   | Should a human approve this specific permitted call?  | Agent, MCP, A2A. HTTP gates unproven calls. Local CLI bypasses. |
+| `accessFilter()`/`assertAccess()` | Which rows may this permitted caller see or write?    | Inside `run()`, per query or row                                |
 
 A restricted write action typically needs both `authorize` and a row check. The first keeps non-coaches out of the operation. The second keeps a coach out of another org's plan. The row check is `assertAccess()`, or `access` when the row's id is an input field. `needsApproval` is a separate axis. It never restricts who may call, only whether the agent may proceed unattended.
 

package/docs/content/actions-defining.mdx

@@ -385,14 +385,15 @@ A network drop, a proxy's HTML error page, and a bare status line author no mess
 
 ### What each throw produces {#failure-shapes}
 
-| Thrown from `run()`                             | HTTP status       | Response body                                | Reported to error tracking |
-| ----------------------------------------------- | ----------------- | -------------------------------------------- | -------------------------- |
-| `fail(msg)`                                     | 400               | `{ error: msg, errorCode: "action_failed" }` | No                         |
-| `fail(msg, { errorCode, statusCode, details })` | your `statusCode` | `{ error, errorCode, details }`              | No                         |
-| `new ActionContractError(msg, { errorCode })`   | 409               | `{ error, errorCode, details }`              | No                         |
-| `new AgentActionStopError(msg)`                 | 500               | `{ error: msg }`                             | No                         |
-| `new Error(msg)`                                | 500               | `{ error: "Internal server error" }`         | Yes                        |
-| Input that fails `schema`                       | 400               | `{ error: "Invalid action parameters..." }`  | No                         |
+| Thrown from `run()`                                                | HTTP status       | Response body                                  | Reported to error tracking |
+| ------------------------------------------------------------------ | ----------------- | ---------------------------------------------- | -------------------------- |
+| `fail(msg)`                                                        | 400               | `{ error: msg, errorCode: "action_failed" }`   | No                         |
+| `fail(msg, { errorCode, statusCode, details })`                    | your `statusCode` | `{ error, errorCode, details }`                | No                         |
+| `new ActionContractError(msg, { errorCode })`                      | 409               | `{ error, errorCode, details }`                | No                         |
+| `new AgentActionStopError(msg)`                                    | 500               | `{ error: msg }`                               | No                         |
+| A PostgreSQL deadlock (`40P01`) or serialization failure (`40001`) | 409               | `{ error, errorCode: "transaction_conflict" }` | No                         |
+| `new Error(msg)`                                                   | 500               | `{ error: "Internal server error" }`           | Yes                        |
+| Input that fails `schema`                                          | 400               | `{ error: "Invalid action parameters..." }`    | No                         |
 
 `AgentActionStopError` is the one to throw when the agent should end its turn rather than read the failure and try again. `ActionContractError` is what `fail()` raises for you, so reach for it directly only when 409 is the status you want.
 

package/docs/content/template-design-developers.mdx

@@ -134,15 +134,15 @@ Every design-specific operation is a TypeScript file in
 
 ### Motion and shaders
 
-| Action                   | What it does                                |
-| ------------------------ | ------------------------------------------- |
-| `get-motion-timeline`    | Read an element's motion timeline           |
-| `apply-motion-edit`      | Add or edit a keyframe on a motion timeline |
-| `remove-motion-timeline` | Remove a motion timeline                    |
-| `apply-shader`           | Apply a shader effect                       |
-| `apply-shader-fill`      | Apply a shader as a fill                    |
-| `preview-shader-fill`    | Preview a shader fill before applying it    |
-| `get-shader`             | Read a shader's current parameters          |
+| Action                   | What it does                                          |
+| ------------------------ | ----------------------------------------------------- |
+| `get-motion-timeline`    | Read an element's motion timeline                     |
+| `apply-motion-edit`      | Add or edit a keyframe on a motion timeline           |
+| `remove-motion-timeline` | Remove a motion timeline                              |
+| `get-shader`             | Inspect native definitions and saved effect manifests |
+| `edit-native-shader`     | Apply, edit, approve, or remove native effects        |
+
+Native WebGPU effects use WGSL. Custom authoring uses `edit-native-shader` with `define-definition`, `get-shader` to read the saved `executionHash`, `approve-definition` with that `expectedExecutionHash`, then `apply` with the exact definition ID/version. Each edit requires `designId`, `fileId`, and the current `expectedVersionHash`. Re-read the file hash after each write. CPU schema validation does not compile GPU code, so verify the Design preview. Previously saved GLSL effects remain renderable and removable.
 
 ### Quality {#quality}
 

package/docs/content/template-design-features.mdx

@@ -175,9 +175,7 @@ when they apply to the current selection:
 
 - **Fill** and **Stroke**: color, gradient, or image paint, with a
   document color palette to reuse existing colors.
-- **Effects**: drop shadow, layer blur, background blur, and a
-  code-backed shader effect with named sliders (speed, color, center
-  point) and a Code panel for the raw GLSL.
+- **Effects**: Drop shadow, layer blur, background blur, and native WebGPU effects with editable properties. Shader creation opens the agent chat to author native WGSL. Previously saved GLSL effects remain renderable and removable.
 - **Position & layout**, **Typography**, **Appearance** (corner radius,
   blend mode, visibility): the standard per-element property groups.
 - **Layout** and **Auto layout**: flex-style arrangement for a frame's

package/docs/content/turn-into-app.mdx

@@ -43,6 +43,10 @@ A host counts as local when it has a real working directory, a terminal, and a w
 
 On a browser host the skill requires the Agent-Native Dispatch MCP connector (`https://dispatch.agent-native.com/mcp`, OAuth) and calls its `start-workspace-app-creation` action. The host cannot run or inspect the app, so the report stays pending or unverified until the branch Dispatch returns is built. The skill reports what Dispatch actually returned and never invents a branch URL. For a ChatGPT Project, or any host that only exposes MCP, put the skill instructions in the Project instructions or knowledge files.
 
+## Local prerequisites
+
+On a local host, install Node.js 22.22.0 or newer (which includes npm and npx) and pnpm before starting. Browser hosts use Dispatch and do not run these commands.
+
 ## Sources {#sources}
 
 - **Threads.** The last concrete, repeatable job is the product.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.214.0",
+  "version": "0.216.0",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -527,6 +527,7 @@
     "./client/changelog/use-changelog-seen": "./dist/client/changelog/use-changelog-seen.js",
     "./client/chat-model-groups": "./dist/client/chat-model-groups.js",
     "./client/client-status-requests": "./dist/client/client-status-requests.js",
+    "./client/consent": "./dist/client/consent.js",
     "./client/context-xray/format": "./dist/client/context-xray/format.js",
     "./client/dev-overlay/builtins": "./dist/client/dev-overlay/builtins.js",
     "./client/error-reporting": "./dist/client/error-reporting.js",
@@ -727,8 +728,8 @@
     "yaml": "^2.9.0",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/agentkit": "^0.214.0",
-    "@agent-native/recap-cli": "^0.5.83"
+    "@agent-native/agentkit": "^0.216.0",
+    "@agent-native/recap-cli": "^0.5.85"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",