@agent-native/core 0.210.2 → 0.211.0

package/dist/templates/factory/.agents/skills/review-latest-feedback/references/channel-inventory.md

@@ -3,15 +3,27 @@
 Use this procedure before investigating, claiming, or using a CI rollup in
 place of Slack source messages.
 
+At the start of a sweep, capture one Slack timestamp as `windowEndTs`. Use it
+as the inclusive `before` argument on the source scan and all three `hasmy`
+ownership searches in every scoped channel. Use the same inclusive `after` on
+the source scan and ownership searches. Record the bounds in `scanQuery` and
+each owned search's `query`. Keep `after` fixed through the sweep. Keep the
+exact upper bound for the whole sweep; page-cap recovery slices may narrow only
+`before` using the existing one-microsecond boundary rule. Messages newer than
+`windowEndTs` belong to the next scheduled sweep. Never advance either bound to
+chase arrivals or expand a finite catch-up request into an all-history audit.
+
 - For the exhaustive channel source scan, use `slack_search_public` with only
-  `filters=in:<#CHANNEL>`, `after=<channel cutoff>`, `keywords=[]`, an empty
+  `filters=in:<#CHANNEL>`, `after=<channel cutoff>`,
+  `before=<windowEndTs>`, `keywords=[]`, an empty
   `natural_language_query`, `include_bots=true`, `include_context=false`,
   `content_types=messages`, `limit=20`, `sort=timestamp`, `sort_dir=desc`, and
   `response_format=detailed`. Do not add lexical, semantic, date, author, or
   reaction filters: they silently hide reports. Record these exact arguments
   under that channel's `scanQuery`; the inventory checker rejects a missing or
-  narrowed query. `after` is inclusive and must equal that channel's effective
-  cutoff. Follow every `next_cursor` newest-first to Slack exhaustion, even
+  narrowed query. `after` and `before` are inclusive and must equal that
+  channel's effective lower cutoff and the sweep's fixed upper bound. Follow
+  every `next_cursor` newest-first to Slack exhaustion, even
   after reaching the cutoff, because later pages can contain replies to older
   roots. Page and
   source-row timestamps must descend across the full chain. This is separate
@@ -50,9 +62,18 @@ place of Slack source messages.
   `ts >= effectiveCutoffTs`, and record the exact `oldest` in `oldestQuery`.
 - Record `scope.channelIds` as the exact IDs requested and scanned. The default
   sweep lists all three default feedback channels. For an explicitly narrowed
-  invocation, inspect the active user request itself; it must explicitly limit
-  scope and name every selected channel by exact ID or `#channel-name`. A
-  permalink or time anchor does not narrow channel scope. Ask the user if the
+  invocation, inspect the active user request itself. It can name the exact
+  channel set with an explicit limit such as “only” and exact IDs or
+  `#channel-name`s. It can also select exactly two channels by linking one
+  report permalink in the first channel and directly asking for “the same in
+  channel-name” (with or without `#`) in the second; that direct linked-report
+  form selects exactly those two channels and does not need an exclusivity
+  word. It requires exactly one linked root and one direct “same in” target. In
+  that clause only, accept a single adjacent transposition in the channel name
+  only when it uniquely resolves to one canonical channel in the requested
+  set. Do not infer scope from incidental or quoted channel mentions or a
+  channel-name prefix. A permalink or time anchor by itself does not narrow
+  channel scope. Ask the user if the
   requested channels are unclear. Store the exact instruction in
   `scope.userRequest` and `scope.narrowingJudgment`, then create a separate
   `.tmp/feedback-scope-confirmation.json` from that active request with
@@ -85,10 +106,12 @@ place of Slack source messages.
   `administrative` decision, and a human rationale tied to that text. This is
   an attributed human triage judgment; the checker verifies its presence and
   source-text linkage but cannot prove the interpretation is correct.
-  For every classified root, including administrative posts, capture a
+  For every unheld classified root, including administrative posts, capture a
   complete thread read and make `sourceText` exactly match its `rootText`.
-  Search output can confuse user-authored `Files:` or `Reactions:` lines with
-  connector metadata, so do not classify from a truncated search excerpt.
+  A held root keeps the exact channel-scan `sourceText` and direct reaction
+  evidence but has no thread-derived fields. Search output can confuse
+  user-authored `Files:` or `Reactions:` lines with connector metadata, so do
+  not classify from a truncated search excerpt.
   For a canonical Slack message permalink, inspect its `thread_ts` query value:
   if it differs from the message's `ts`, the message is a reply and that value
   is its root. A self-valued `thread_ts` or a canonical root permalink without
@@ -194,9 +217,9 @@ place of Slack source messages.
   root message.
   Read and capture a complete, oldest-first `threadSnapshot` after the final
   channel page for every in-scope classified root, including administrative
-  posts, unmarked roots, and roots with no replies. The checker rejects a
-  classified root without this read or with `rootText` that differs from its
-  `sourceText`.
+  posts, unmarked roots, and roots with no replies, except roots held by the
+  reaction ownership boundary below. The checker rejects a classified root
+  without this read or with `rootText` that differs from its `sourceText`.
   Supplemental roots must strictly predate the oldest `sourceTimestamps` entry
   across every scanned page, as well as `cutoffTs`; a root inside the scanned
   source range must have its own source-manifest row even when it predates the
@@ -205,8 +228,8 @@ place of Slack source messages.
   `ts === threadParentTs` and must not be duplicated in `threadRoots`. A
   supplemental root exists to resolve an in-window reply;
   its presence does not make the older report a new in-scope claim. Read its
-  exact root reactions and complete thread, then apply the ownership gate to
-  the root itself. Do not add `👀`, `✅`, or `🎫`, or post a status, just because
+  exact root reactions, then apply the ownership gate before opening the thread.
+  Do not add `👀`, `✅`, or `🎫`, or post a status, just because
   an unowned older root appears as context. If this actor already owns a mark
   on that older root, reconcile its current status and scopes as usual; record
   another actor's marks as ownership evidence and leave them untouched. Their
@@ -214,29 +237,53 @@ place of Slack source messages.
   shows an open disposition; a later closed status makes that eye historical.
   Keep
   the root disposition and any open scope in the audit row without claiming it.
-  The inventory checker still requires a complete, oldest-first
-  `threadSnapshot` for each supplemental root, including unowned roots, so a
-  reply cannot predate or otherwise contradict its reported root.
-- After the regular bounded channel scans, discover this actor's older owned
-  roots with three separate unbounded `slack_search_public` queries per scoped
-  channel: `in:<#CHANNEL> hasmy::eyes`,
-  `in:<#CHANNEL> hasmy::white_check_mark`, and
-  `in:<#CHANNEL> hasmy::ticket`. Use the same bot-inclusive detailed search
-  arguments as the channel scan, but omit `after`, `before`, keywords, semantic
-  search, and all other filters. Follow every cursor to explicit exhaustion. If
-  Slack caps a cursor before exhaustion, preserve that capped page and record
-  the exact `page_limit_exceeded` response in that search's
+  For an unheld supplemental root, the inventory checker still requires a
+  complete, oldest-first `threadSnapshot`, so a reply cannot predate or
+  otherwise contradict its reported root.
+- **Held thread:** If the exact root reaction read shows another actor owns any
+  workflow mark (`👀`, `✅`, or `🎫`), or this actor owns `:mag:`, do not open or
+  read the thread, inspect reply reactions, react, or reply. Record an
+  `ownershipSkip` with the root timestamp and `foreign_workflow_mark` or
+  `mag_opt_out`; use `Skipped` and leave thread-derived fields empty. If this
+  actor also owns a workflow mark, use `mag_opt_out` and preserve the exact
+  direct root reaction-owner record as history. The checker treats it as held
+  and requires no thread snapshot or status. Mark every
+  channel reply linked to that root with the same skip reference. The checker
+  requires direct root reaction evidence and the matching skip reason, but no
+  full-thread snapshot. For a linked pre-window root without source text, use
+  `unclassified`; do not guess from its in-window reply. This boundary also
+  applies when the other actor's eye has no visible status reply: ownership is
+  not permission to inspect. The direct root-reaction read must still be fresh
+  and after the final source page; it is the only read allowed for a held root.
+  Preserve the source's exact file ID, name, and MIME type when its raw search
+  result includes `Files:`. If that result omits file metadata, leave the held
+  root's `files` field absent to represent unknown; do not record `[]`. For an
+  unheld root, use the full thread read to record files and require the source
+  row and snapshot to agree.
+- After each bounded channel scan, run three separate bounded ownership
+  searches for this actor's `👀`, `✅`, and `🎫` with `slack_search_public`. Each
+  query uses only `in:<#CHANNEL> hasmy::EMOJI:` plus the same inclusive `after`
+  and `before` as the source scan. These searches cover only this invocation's
+  finite window; do not search unrelated channel history. An older root is in
+  scope only when an in-window reply links to it. Resolve that reply's true
+  parent, read the older root's exact reactions, and apply the held-thread gate
+  before opening it. Reconcile every candidate in the window and each linked
+  older root; unheld roots need exact reaction and full-thread evidence in the
+  source or supplemental-root audit. A candidate missing either audit is
+  unresolved, not outside scope.
+  If Slack caps a cursor before exhaustion, preserve that capped page and
+  record the exact `page_limit_exceeded` response in that search's
   `pageLimitRecoveries[]`, including its failed cursor and request args, raw
   response, read time, and the capped page's oldest result as `boundaryTs`.
-  Restart the same exact `hasmy` query at `cursor: null` with an inclusive
-  `before` exactly one microsecond below that boundary. Keep that `before` on
-  every page in the restarted cursor slice and in each raw request wrapper; the
-  base `filters` query remains unchanged. Follow the restarted slice to
-  exhaustion, and repeat this recovery for every later cap. The checker proves
-  each failed cursor against exactly one restarted slice, checks the boundary
-  and read order, and requires explicit exhaustion. If Slack does not let you
-  recover a capped tail, report the historical ownership search as incomplete;
-  do not claim every owned mark was reconciled.
+  Restart the same `hasmy` query at `cursor: null` with the same fixed `after`
+  and a `before` exactly one microsecond below that boundary. Keep both bounds
+  on every page in the restarted cursor slice and in each raw request wrapper.
+  Follow the restarted slice to exhaustion and repeat this recovery for every
+  later cap. The checker proves each failed cursor against exactly one
+  restarted slice, checks the boundary and read order, and requires explicit
+  exhaustion. If Slack does not let you recover a capped tail, report the
+  bounded ownership search as incomplete; do not claim every in-window owned
+  mark was reconciled.
   Record each exact query and page in `ownedMarkSearches`; save raw wrappers
   named `owned-marks-{channelName}-{eyes|white_check_mark|ticket}-00.json` and
   continue numbering for each cursor page. Each wrapper preserves exact
@@ -252,16 +299,19 @@ place of Slack source messages.
   evidence; if the exact read fails or is incomplete, leave ownership
   unresolved rather than treating the query as confirmation. A result with
   `ts !== root` is reply-level evidence: resolve and preserve its parent, but
-  never count it as a root checkoff. Verify reply reactions from the exact
-  reply read-back in its complete thread snapshot; if that historical reply
-  cannot be read back, report reply-level reconciliation as incomplete.
-  Deduplicate confirmed roots across the three searches. For any
-  exact-readback-confirmed root missing from the bounded source pages and
-  `threadRootAudits`, add a
-  full root audit row to `ownedRootAudits`; an in-scope root must instead
-  appear in the source pages. Reconcile each discovered root's latest human
-  message, status reply, scopes, and exact current reaction state. Read its
-  full thread after the final ownership-search page and preserve every raw
+  never count it as a root checkoff. For an unheld root, verify reply reactions
+  from the exact reply read-back in its complete thread snapshot; if that
+  historical reply cannot be read back, report reply-level reconciliation as
+  incomplete. For a held root, preserve the reply parent and matching skip
+  reason without opening the thread.
+  Deduplicate confirmed roots across the three searches. Every in-window root
+  candidate must appear in the source pages. An older root linked by an
+  in-window reply belongs in `threadRoots` and `threadRootAudits`. If a bounded
+  search hit has no matching source row or linked supplemental root, rerun the
+  source scan and include the missing evidence; do not invent an audit row.
+  Reconcile each unheld discovered root's latest human message, status reply,
+  scopes, and exact current reaction state. Read its full thread after the final
+  ownership-search page and preserve every raw
   `slack_read_thread` page under `thread-{channelName}-{rootTs}-00.json` and
   contiguous page numbers. Each wrapper records exact request `args`,
   requested `cursor`, raw response, and `readAt`; the raw response must
@@ -387,9 +437,13 @@ place of Slack source messages.
   and every source `{ ts, root }` row with the reviewed inventory and raw Slack
   responses. If it finds a mismatch,
   rebuild the inventory from the captured Slack pages and rerun the check; never
-  edit the receipt to fit the inventory. Each receipt page must also be fresh
-  within the checker's 15-minute window, so repeat the complete channel scan and
-  required final thread/reaction reads before recap when that window expires.
+  edit the receipt to fit the inventory. Source and ownership-search pages are
+  immutable evidence for the fixed `after`/`before` interval; their age does not
+  restart the sweep. The 15-minute freshness window applies to current root and
+  reply reaction reads and full-thread snapshots. If one expires, reread only
+  that exact state. After one targeted retry, if a required current-state read
+  is still stale or unavailable, mark the inventory incomplete and stop; do
+  not restart the channel-wide search or loop.
   It rejects any root mark this actor owns without a current same-actor
   status reply, a
   assigned-human handoff without that person's explicit acceptance, an
@@ -434,19 +488,18 @@ verified disposition may retain the eye as history. Never remove or clean up a
 reaction. Slack thread replies appear under the root's reply count, not as
 separate channel posts; do not broadcast routine status replies.
 
-After any long investigation, CI/deploy wait, or handoff, a newest-first scan
-from the saved high-water mark can identify new activity. Immediately before
-recap, however, rerun the exact original channel-wide `slack_search_public`
-query for every scoped channel, including its recorded `scanQuery.after`, and
-follow every cursor to Slack exhaustion. Replace the saved page responses,
-timestamps, source manifests, and source rows. Do not
-append a delta to an older page chain or refresh its `readAt` without rereading
-the page. Resolve every newly found reply to its actual root, refresh root
-reactions, and reconcile human answers before replacement. Then reopen every
-marked root thread after the last channel page, read all replies, and refresh
-reply-level workflow reaction owners. If this final scan or any thread read is
-older than 15 minutes, repeat the full bounded scan and marked-thread reads
-before checking the inventory. Only a complete fresh pass can certify coverage.
+After a long investigation, CI/deploy wait, or handoff, do one final exhaustive
+pass of the exact original channel-wide query for every scoped channel, using
+the same recorded `scanQuery.after` and `scanQuery.before`. Replace the saved
+page responses, timestamps, source manifests, and source rows; never append a
+delta or refresh `readAt` without rereading the page. This is one bounded
+reconciliation pass, not a moving high-water mark. Resolve newly found replies
+to their actual roots and reconcile them inside the fixed interval. Then reread
+current root reactions and full threads for marked roots after the final source
+and ownership-search pages. If an exact current-state read expires, reread that
+target once. If it still cannot pass freshness, mark coverage incomplete and
+stop; do not restart the global scan. Activity newer than `windowEndTs` is for
+the next scheduled sweep.
 
 Channel history does not include the contents of existing thread replies. In
 that final pass, also enumerate every distinct root thread carrying this
@@ -492,21 +545,22 @@ read time as `reactionReadAt`; when this sweep writes a reaction, record
 also requires each owned root reaction read and the full-thread reaction reads
 to follow the final channel page.
 
-The normal inventory check also requires every source, owned-mark search, and
-thread page or snapshot to have been read within the last 15 minutes, allows at
-most one minute of local clock skew, and requires owned-root reaction and thread
-read-backs to follow all three exhaustive mark searches. An old, complete
-inventory is stale: rerun the channel scan and historical mark searches, then
-read every marked root thread again before recap. This freshness gate prevents
-a complete earlier scan from silently omitting reports or replies that arrived
-during investigation.
+The inventory checker requires source pages to use one recorded inclusive
+`after`/`before` window and ownership-census pages to use the fixed `before`
+upper bound with no `after`. Both page chains must remain in cursor order and
+have valid local ISO read times. Their age does not invalidate those fixed
+bounds. Current root and reply reaction reads and full-thread snapshots must be
+within 15 minutes, allow at most one minute of local clock skew, and follow the
+final source and ownership-search pages. Refresh only a stale current-state
+target; if one targeted reread is still stale or unavailable, mark coverage
+incomplete and stop instead of repeating the full sweep.
 
 The inventory checker requires a complete `threadSnapshot` for every in-scope
-classified root, every supplemental root included to resolve an in-scope reply,
-and every older root discovered by the exhaustive owned-mark searches. It checks
-raw thread page cursor exhaustion, Slack's reply count, exact source text,
-attachments, and snapshot order, and rejects a newer human or sweep reply than
-the recorded status. A failed check means the sweep is not reconciled.
+classified root and every supplemental root included to resolve an in-scope
+reply, except roots recorded under the held-thread boundary. For unheld roots it
+checks raw thread page cursor exhaustion, Slack's reply count, exact source
+text, attachments, and snapshot order, and rejects a newer human or sweep reply
+than the recorded status. A failed check means the sweep is not reconciled.
 
 A grouped CI report or attachment is a discovery index, never a replacement for
 the channel-message inventory.

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

@@ -2,12 +2,19 @@
 
 Use the connected Slack integration for every Slack read and write. Never use a browser, screenshots, or UI automation to operate Slack.
 
-At sweep exit, reconcile every report root in the scoped inventory that has
-this task's `👀`, `✅`, or `🎫`, including marks left by earlier runs. Capture
+At sweep exit, reconcile every unheld report root in the scoped inventory that
+has this task's `👀`, `✅`, or `🎫`, including marks left by earlier runs. A
+root is held when a direct reaction read shows another actor owns any workflow
+mark or this actor owns `:mag:`. For held roots, record the root and safe-skip
+reason, then stop: do not open the thread, inspect reply reactions, write any
+reaction, or post a status. When this actor owns both `:mag:` and a workflow
+mark, use `mag_opt_out` and preserve the exact direct root reaction-owner
+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
-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
+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
@@ -30,6 +37,23 @@ 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.
 
+Interpret the three root reactions independently from the current disposition:
+
+- `👀` 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.
+
+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
@@ -101,10 +125,13 @@ slack_search: "this was sent from a bot." in:<#CHANNEL>
   sort=timestamp sort_dir=asc include_context=true max_context_length=300
 ```
 
-Also scan channel messages from the saved reply cursor; on the first run, scan
-available history. Since `after:` is date-only, start one day before the cursor,
-exhaust pages, resolve hits to their root, and advance the cursor only through
-processed messages. Read inherited threads carrying any of this actor's root marks (`👀`, `✅`,
+Also scan channel messages from the saved reply cursor within the current
+invocation's fixed window; on the first run, use the default five-day window,
+not all available history. Since `after:` is date-only, start one day before
+the later of the saved cursor and window start, exhaust pages, resolve hits to
+their root, and advance the cursor only through processed messages. An older
+root is eligible only when an in-window reply links to it. Read inherited
+threads carrying any of this actor's root marks (`👀`, `✅`,
 or `🎫`): a checkmark closes only its verified scope, not a newer reporter
 answer or another open scope. Do not reply or react on another actor's root when work is handed off for investigation; that handoff permits local investigation only. A separate explicit authorization is required to post a status or reporter reply there.
 
@@ -130,9 +157,10 @@ human/team actions, including actions with no named owner yet. The eye alone
 does not mean work remains open. One root `✅` covers every verified scope
 listed in `fixedScopes[]`; one root `🎫` covers every action listed in
 `handoffs[]`, including unassigned, accepted, and completed actions. Completion
-evidence changes its status, not the historical `🎫` reaction. For every root
-carrying any of this actor's marks, post or reuse a current status in that root's thread;
-unclaimed items and another actor's marks are not ours to reply to. Reconcile
+evidence changes its status, not the historical `🎫` reaction. For every
+unheld root carrying any of this actor's marks, post or reuse a current status
+in that root's thread; unclaimed items, held roots, and another actor's marks
+are not ours to reply to. Reconcile
 each report as one unit: send or verify its current same-thread status reply,
 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

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

@@ -95,9 +95,9 @@ MCP clients see no `outputSchema` by default. Set `mcpOutputSchema: true` (requi
 
 `authorize` decides whether the caller may run the action at all. It wraps
 `run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
-hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
-agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
-to ask a human to bless one call a permitted caller is already allowed to make.
+hook, MCP, A2A, CLI. Use `authorize` for "not everyone may do this"; use
+`needsApproval` to ask a human to bless one call a permitted caller is already
+allowed to make.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -140,4 +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.
+
 **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

@@ -95,9 +95,9 @@ MCP clients see no `outputSchema` by default. Set `mcpOutputSchema: true` (requi
 
 `authorize` decides whether the caller may run the action at all. It wraps
 `run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
-hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
-agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
-to ask a human to bless one call a permitted caller is already allowed to make.
+hook, MCP, A2A, CLI. Use `authorize` for "not everyone may do this"; use
+`needsApproval` to ask a human to bless one call a permitted caller is already
+allowed to make.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -140,4 +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.
+
 **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/triggers/actions/manage-automation.d.ts

@@ -14,7 +14,6 @@ declare const _default: import("../../action.js").ActionDefinition<{
     executionCwd?: string;
 }, {
     deleted?: undefined;
-    enabled?: undefined;
     created: boolean;
     name: string;
     scope: "organization" | "personal";
@@ -25,24 +24,25 @@ declare const _default: import("../../action.js").ActionDefinition<{
     reasoningEffort: "auto" | "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh";
     webhookPath: string;
     nextRun: string;
+    enabled?: undefined;
     executionHostId?: undefined;
     executionEngine?: undefined;
     executionCwd?: undefined;
 } | {
-    enabled?: undefined;
-    nextRun?: undefined;
     created?: undefined;
     scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
     deleted: boolean;
     name: string;
+    enabled?: undefined;
     schedule?: undefined;
     timezone?: undefined;
     reasoningEffort?: undefined;
     executionHostId?: undefined;
     executionEngine?: undefined;
     executionCwd?: undefined;
+    nextRun?: undefined;
     webhookPath?: undefined;
 } | {
     deleted?: undefined;

package/dist/vite/client.js

@@ -2789,9 +2789,10 @@ function silenceConnectionResets() {
         const message = String(e?.message ?? "");
         return (code === "ECONNRESET" ||
             code === "ECONNABORTED" ||
+            code === "ECANCELED" ||
             code === "EPIPE" ||
             isClosedWebStreamController(err) ||
-            /^(read ECONNRESET|write ECONNRESET|socket hang up|aborted|write EPIPE)$/i.test(message));
+            /^(read ECONNRESET|write ECONNRESET|write ECANCELED|socket hang up|aborted|write EPIPE)$/i.test(message));
     };
     const isBenignErrorPayload = (payload) => {
         const p = payload;

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

@@ -166,13 +166,13 @@ When `needsApproval` is omitted, behavior is byte-for-byte unchanged. There is n
 
 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.
 
-Calls made over the [HTTP API](/docs/http-api) with a bearer token or API key skip the approval card: the route runs the action directly, as it does for the app's own UI. To have an agent's calls approved, connect it over [MCP](/docs/external-agents) instead of calling the HTTP routes.
+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.
 
 ### How the loop pauses {#loop}
 
 When the agent calls a gated action and this specific call has **not** already been approved, the loop does **not** execute `run()`. Instead it:
 
-1. Resolves the gate. For a predicate, the loop calls `needsApproval(input, ctx)`. If that call throws an error, the loop treats it the same as a `true` result, so the action requires approval.
+1. Resolves the gate. The loop first prepares the call: it validates the arguments and applies the schema's defaults and coercions. An invalid call stops here with its validation error, and nobody is asked to approve it. For a predicate, the loop then calls `needsApproval(args, ctx)` with the prepared arguments, the ones `run()` would receive. If that call throws an error, the loop treats it the same as a `true` result, so the action requires approval.
 2. Emits a `tool_start` event (so the UI shows the call) followed immediately by an **`approval_required`** event, then stops the turn. The action's side effect never happens.
 
 The `approval_required` event carries everything the client needs to render an affordance:
@@ -407,7 +407,7 @@ The four mechanisms are not interchangeable:
 | --------------------------------- | ----------------------------------------------------- | -------------------------------- |
 | `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?  | The agent loop only              |
+| `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 |
 
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.210.2",
+  "version": "0.211.0",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -711,8 +711,8 @@
     "yaml": "^2.9.0",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/agentkit": "^0.210.2",
-    "@agent-native/recap-cli": "^0.5.77"
+    "@agent-native/agentkit": "^0.211.0",
+    "@agent-native/recap-cli": "^0.5.78"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.agents/skills/actions/references/action-fields.md

@@ -95,9 +95,9 @@ MCP clients see no `outputSchema` by default. Set `mcpOutputSchema: true` (requi
 
 `authorize` decides whether the caller may run the action at all. It wraps
 `run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
-hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
-agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
-to ask a human to bless one call a permitted caller is already allowed to make.
+hook, MCP, A2A, CLI. Use `authorize` for "not everyone may do this"; use
+`needsApproval` to ask a human to bless one call a permitted caller is already
+allowed to make.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -140,4 +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.
+
 **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/src/templates/default/.agents/skills/actions/references/action-fields.md

@@ -95,9 +95,9 @@ MCP clients see no `outputSchema` by default. Set `mcpOutputSchema: true` (requi
 
 `authorize` decides whether the caller may run the action at all. It wraps
 `run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
-hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
-agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
-to ask a human to bless one call a permitted caller is already allowed to make.
+hook, MCP, A2A, CLI. Use `authorize` for "not everyone may do this"; use
+`needsApproval` to ask a human to bless one call a permitted caller is already
+allowed to make.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -140,4 +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.
+
 **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.