@agent-native/core 0.204.0-nightly-20261008011018 → 0.204.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/dist/action.d.ts +1 -0
  2. package/dist/action.js +4 -2
  3. package/dist/cli/agent.js +2 -11
  4. package/dist/client/use-db-sync.d.ts +13 -0
  5. package/dist/client/use-db-sync.js +22 -1
  6. package/dist/collab/client.js +36 -3
  7. package/dist/collab/routes.d.ts +7 -2
  8. package/dist/collab/routes.js +15 -1
  9. package/dist/collab/struct-routes.d.ts +1 -1
  10. package/dist/deploy/build.js +15 -8
  11. package/dist/deploy/workspace-deploy.js +88 -13
  12. package/dist/jobs/actions/manage-recurring-job.d.ts +1 -1
  13. package/dist/mcp/actions/create-org-service-token.js +1 -0
  14. package/dist/mcp/build-server.js +12 -9
  15. package/dist/mcp-client/oauth-routes.js +2 -1
  16. package/dist/notifications/routes.d.ts +1 -1
  17. package/dist/observability/routes.d.ts +6 -6
  18. package/dist/progress/routes.d.ts +1 -1
  19. package/dist/provider-api/actions/custom-provider-registration.d.ts +3 -3
  20. package/dist/scripts/dev/index.js +2 -8
  21. package/dist/scripts/parse-args.d.ts +7 -0
  22. package/dist/scripts/parse-args.js +76 -0
  23. package/dist/scripts/utils.d.ts +1 -1
  24. package/dist/scripts/utils.js +1 -1
  25. package/dist/secrets/routes.d.ts +11 -11
  26. package/dist/server/action-discovery.js +4 -42
  27. package/dist/server/agent-chat/script-entries.js +3 -8
  28. package/dist/server/agent-chat-plugin.js +8 -42
  29. package/dist/server/agent-engine-default-model-route.d.ts +2 -2
  30. package/dist/server/agent-engine-ollama-models-route.d.ts +1 -1
  31. package/dist/server/auth.js +5 -2
  32. package/dist/server/google-oauth.js +8 -4
  33. package/dist/server/identity-sso.js +2 -1
  34. package/dist/server/index.d.ts +1 -0
  35. package/dist/server/index.js +1 -0
  36. package/dist/server/poll.d.ts +9 -0
  37. package/dist/server/poll.js +86 -7
  38. package/dist/server/query-echo-safe-redirect.d.ts +10 -0
  39. package/dist/server/query-echo-safe-redirect.js +102 -0
  40. package/dist/server/workspace-provider-oauth.js +2 -1
  41. package/dist/templates/chat/.agents/skills/actions/references/action-fields.md +1 -0
  42. package/dist/templates/default/.agents/skills/actions/references/action-fields.md +1 -0
  43. package/dist/templates/headless/.agents/skills/actions/references/action-fields.md +1 -0
  44. package/dist/templates/workspace-core/.agents/skills/actions/references/action-fields.md +1 -0
  45. package/dist/triggers/actions/manage-automation.d.ts +7 -7
  46. package/docs/content/external-agents-catalog.mdx +19 -0
  47. package/package.json +4 -4
  48. package/src/templates/chat/.agents/skills/actions/references/action-fields.md +1 -0
  49. package/src/templates/default/.agents/skills/actions/references/action-fields.md +1 -0
  50. package/src/templates/headless/.agents/skills/actions/references/action-fields.md +1 -0
  51. package/src/templates/workspace-core/.agents/skills/actions/references/action-fields.md +1 -0
@@ -43,6 +43,7 @@ export const POLL_CHANGE_EVENT = "poll-change";
43
43
  const ACCESS_CACHE_TTL_MS = 30_000;
44
44
  const ACCESS_CACHE_DENY_TTL_MS = 5_000;
45
45
  const ACCESS_CACHE_MAX = 500;
46
+ const ACCESS_CHECK_WAIT_MS = 1_000;
46
47
  const SCREEN_REFRESH_KEY = "__screen_refresh__";
47
48
  const SCREEN_REFRESH_QUERY_LIMIT = 256;
48
49
  const SEED_SYNC_VERSION_SQL = `
@@ -278,7 +279,7 @@ export class AppSyncState {
278
279
  screenRefreshHasMore = false;
279
280
  localEmittersWired = false;
280
281
  accessCache = new Map();
281
- accessInFlight = new Set();
282
+ accessInFlight = new Map();
282
283
  accessInvalidationEpoch = new Map();
283
284
  accessAllowTtlMs;
284
285
  constructor(options = {}) {
@@ -311,6 +312,40 @@ export class AppSyncState {
311
312
  getVersion() {
312
313
  return this.version;
313
314
  }
315
+ async getPollBaseline(useDurableEvents) {
316
+ let cursor = { version: this.version, id: "" };
317
+ if (compareSyncCursors(this.latestCursor, cursor) > 0) {
318
+ cursor = this.latestCursor;
319
+ }
320
+ if (useDurableEvents && !syncEventsDisabled()) {
321
+ try {
322
+ const result = await this.getDb().execute("SELECT version, id FROM sync_events WHERE version = (SELECT MAX(version) FROM sync_events) ORDER BY id DESC LIMIT 1");
323
+ const row = result.rows[0];
324
+ if (row) {
325
+ const version = Number(row.version);
326
+ if (!Number.isSafeInteger(version) ||
327
+ version < 0 ||
328
+ typeof row.id !== "string") {
329
+ throw new Error("Durable sync event cursor is invalid");
330
+ }
331
+ const durableCursor = { version, id: row.id };
332
+ if (compareSyncCursors(durableCursor, cursor) > 0) {
333
+ cursor = durableCursor;
334
+ }
335
+ }
336
+ }
337
+ catch (error) {
338
+ if (isMissingRelationError(error)) {
339
+ throw new SyncEventsTableUnavailableError();
340
+ }
341
+ throw error;
342
+ }
343
+ }
344
+ return {
345
+ version: Math.max(this.version, cursor.version),
346
+ cursor: encodeSyncCursor(cursor),
347
+ };
348
+ }
314
349
  getPollEmitter() {
315
350
  return this.pollEmitter;
316
351
  }
@@ -551,7 +586,7 @@ export class AppSyncState {
551
586
  if (key.endsWith(suffix))
552
587
  this.accessCache.delete(key);
553
588
  }
554
- for (const key of Array.from(this.accessInFlight)) {
589
+ for (const key of Array.from(this.accessInFlight.keys())) {
555
590
  if (key.endsWith(suffix))
556
591
  this.accessInFlight.delete(key);
557
592
  }
@@ -572,10 +607,10 @@ export class AppSyncState {
572
607
  scheduleAccessCheck(key, resourceType, resourceId, userEmail, orgId) {
573
608
  if (this.accessInFlight.has(key))
574
609
  return;
575
- this.accessInFlight.add(key);
576
610
  const resourceKey = accessResourceKey(resourceType, resourceId);
577
611
  const epoch = this.accessInvalidationEpoch.get(resourceKey) ?? 0;
578
- void (async () => {
612
+ let settled = false;
613
+ const check = (async () => {
579
614
  try {
580
615
  const access = await this.resolveAccessFn(resourceType, resourceId, {
581
616
  userEmail,
@@ -593,9 +628,12 @@ export class AppSyncState {
593
628
  this.setAccessCache(key, false, Date.now());
594
629
  }
595
630
  finally {
631
+ settled = true;
596
632
  this.accessInFlight.delete(key);
597
633
  }
598
634
  })();
635
+ if (!settled)
636
+ this.accessInFlight.set(key, check);
599
637
  }
600
638
  __resetAccessCacheForTests() {
601
639
  this.accessCache.clear();
@@ -896,7 +934,7 @@ export class AppSyncState {
896
934
  return { version: this.version, events: [] };
897
935
  }
898
936
  const readCursor = cursor ?? { version: since, id: "" };
899
- if (readCursor.version <= 0 && readCursor.id === "") {
937
+ if (!cursor && readCursor.version <= 0 && readCursor.id === "") {
900
938
  try {
901
939
  const result = await this.getDb().execute("SELECT MAX(version) as max_version FROM sync_events");
902
940
  return {
@@ -1044,6 +1082,23 @@ export class AppSyncState {
1044
1082
  }
1045
1083
  }
1046
1084
  async getCombinedChangesSinceForUser(since, userEmail, orgId, useDurableEvents, cursor) {
1085
+ const result = await this.readCombinedChangesSinceForUser(since, userEmail, orgId, useDurableEvents, cursor);
1086
+ if (!result.cursorLimited || this.accessInFlight.size === 0)
1087
+ return result;
1088
+ // A read stopped at an event whose access check had not finished. The
1089
+ // check is already running, so waiting for it here (bounded) delivers the
1090
+ // event now instead of one poll interval later.
1091
+ let timer;
1092
+ await Promise.race([
1093
+ Promise.allSettled(this.accessInFlight.values()),
1094
+ new Promise((resolve) => {
1095
+ timer = setTimeout(resolve, ACCESS_CHECK_WAIT_MS);
1096
+ }),
1097
+ ]);
1098
+ clearTimeout(timer);
1099
+ return this.readCombinedChangesSinceForUser(since, userEmail, orgId, useDurableEvents, cursor);
1100
+ }
1101
+ async readCombinedChangesSinceForUser(since, userEmail, orgId, useDurableEvents, cursor) {
1047
1102
  const memory = this.getChangesSinceForUser(since, userEmail, orgId, cursor);
1048
1103
  if (!useDurableEvents)
1049
1104
  return memory;
@@ -1066,8 +1121,7 @@ export class AppSyncState {
1066
1121
  if (cursor) {
1067
1122
  const limitedCursors = [memory, durable]
1068
1123
  .filter((result) => result.cursorLimited)
1069
- .map((result) => decodeSyncCursor(result.cursor))
1070
- .filter((value) => !!value);
1124
+ .map((result) => decodeSyncCursor(result.cursor) ?? cursor);
1071
1125
  if (limitedCursors.length > 0) {
1072
1126
  const boundary = limitedCursors.reduce((minimum, value) => compareSyncCursors(value, minimum) < 0 ? value : minimum);
1073
1127
  return {
@@ -1103,6 +1157,7 @@ export class AppSyncState {
1103
1157
  events: limitedVersions.length > 0
1104
1158
  ? events.filter((event) => event.version <= Math.min(...limitedVersions))
1105
1159
  : events,
1160
+ ...(limitedVersions.length > 0 ? { cursorLimited: true } : {}),
1106
1161
  };
1107
1162
  }
1108
1163
  async seedVersionFromDb() {
@@ -1356,6 +1411,30 @@ export function getDefaultAppSyncState() {
1356
1411
  export function getVersion() {
1357
1412
  return getDefaultAppSyncState().getVersion();
1358
1413
  }
1414
+ export async function getCurrentPollBaseline(state = getDefaultAppSyncState()) {
1415
+ if (syncEventsDisabled()) {
1416
+ await state.seedVersionFromDb();
1417
+ await state.checkExternalDbChanges({ durableEvents: false });
1418
+ return state.getPollBaseline(false);
1419
+ }
1420
+ const releaseOwnedServerlessPoll = isProductionServerlessFunctionRuntime() && appMigratesAtRelease();
1421
+ try {
1422
+ if (!releaseOwnedServerlessPoll) {
1423
+ await state.seedVersionFromDb();
1424
+ await state.checkExternalDbChanges({ durableEvents: true });
1425
+ }
1426
+ return await state.getPollBaseline(true);
1427
+ }
1428
+ catch (error) {
1429
+ if (!(error instanceof SyncEventsTableUnavailableError))
1430
+ throw error;
1431
+ if (releaseOwnedServerlessPoll)
1432
+ throw error;
1433
+ await state.seedVersionFromDb();
1434
+ await state.checkExternalDbChanges({ durableEvents: false });
1435
+ return state.getPollBaseline(false);
1436
+ }
1437
+ }
1359
1438
  export function getPollEmitter() {
1360
1439
  return getDefaultAppSyncState().getPollEmitter();
1361
1440
  }
@@ -0,0 +1,10 @@
1
+ import type { H3Event } from "h3";
2
+ /**
3
+ * Netlify's proxy copies the request's query string onto any redirect whose
4
+ * Location has none, so a bare 302 out of a sign-in callback lands the browser
5
+ * on a page still carrying the one-time `token`, OAuth `code`, or attribution
6
+ * params. Every later bare 302 in the chain inherits the query the same way,
7
+ * so no redirect-only route can shed it. Netlify leaves a 200 alone: a
8
+ * navigation gets an HTML page that replaces itself with the clean Location.
9
+ */
10
+ export declare function queryEchoSafeRedirect(event: H3Event, response: Response): Response;
@@ -0,0 +1,102 @@
1
+ import { getHeader } from "h3";
2
+ import { getAppBasePathFromViteEnv } from "./app-base-path.js";
3
+ function requestHasQuery(event) {
4
+ if (event.url?.search)
5
+ return true;
6
+ const raw = event.node?.req?.url ??
7
+ (typeof event.path === "string" ? event.path : "");
8
+ const queryStart = raw.indexOf("?");
9
+ return queryStart >= 0 && queryStart < raw.length - 1;
10
+ }
11
+ function isDocumentNavigation(event) {
12
+ const mode = getHeader(event, "sec-fetch-mode");
13
+ if (mode)
14
+ return mode === "navigate";
15
+ return (getHeader(event, "accept") ?? "").includes("text/html");
16
+ }
17
+ const PATH_BASE = "http://an.invalid";
18
+ // The page navigates with `location.replace`, which runs a `javascript:` URL
19
+ // that a 302 would refuse, so only http(s) destinations qualify. A path is
20
+ // resolved rather than pattern-matched: the URL parser drops tabs and
21
+ // newlines, so `/\t/evil.test` names another host.
22
+ function bareHttpDestination(location) {
23
+ try {
24
+ if (location.startsWith("/")) {
25
+ const target = new URL(location, PATH_BASE);
26
+ if (target.origin !== PATH_BASE || target.search)
27
+ return null;
28
+ return withAppBasePath(location);
29
+ }
30
+ const target = new URL(location);
31
+ if (target.protocol !== "https:" && target.protocol !== "http:") {
32
+ return null;
33
+ }
34
+ return target.search ? null : location;
35
+ // coercion-ok: a Location the URL parser rejects is not ours to rewrite.
36
+ }
37
+ catch {
38
+ return null;
39
+ }
40
+ }
41
+ // Workspace mounts and the dev gateway prefix an app's path Locations with its
42
+ // base path, but only on 3xx responses; the page has to carry the prefix.
43
+ function withAppBasePath(path) {
44
+ const base = getAppBasePathFromViteEnv();
45
+ if (!base)
46
+ return path;
47
+ const pathname = path.split(/[?#]/, 1)[0] || path;
48
+ if (pathname === base ||
49
+ pathname === `${base}.data` ||
50
+ pathname.startsWith(`${base}/`)) {
51
+ return path;
52
+ }
53
+ return pathname === "/" ? `${base}${path.slice(1)}` : `${base}${path}`;
54
+ }
55
+ function escapeHtmlAttr(value) {
56
+ return value
57
+ .replace(/&/g, "&amp;")
58
+ .replace(/</g, "&lt;")
59
+ .replace(/>/g, "&gt;")
60
+ .replace(/"/g, "&quot;");
61
+ }
62
+ /**
63
+ * Netlify's proxy copies the request's query string onto any redirect whose
64
+ * Location has none, so a bare 302 out of a sign-in callback lands the browser
65
+ * on a page still carrying the one-time `token`, OAuth `code`, or attribution
66
+ * params. Every later bare 302 in the chain inherits the query the same way,
67
+ * so no redirect-only route can shed it. Netlify leaves a 200 alone: a
68
+ * navigation gets an HTML page that replaces itself with the clean Location.
69
+ */
70
+ export function queryEchoSafeRedirect(event, response) {
71
+ // 307 and 308 replay the request method; a page that navigates would turn a
72
+ // POST into a GET.
73
+ if (![301, 302, 303].includes(response.status))
74
+ return response;
75
+ const location = response.headers.get("location");
76
+ if (!location || !requestHasQuery(event) || !isDocumentNavigation(event)) {
77
+ return response;
78
+ }
79
+ const destination = bareHttpDestination(location);
80
+ if (!destination)
81
+ return response;
82
+ const headers = new Headers();
83
+ for (const [key, value] of response.headers.entries()) {
84
+ const name = key.toLowerCase();
85
+ if (name === "location" ||
86
+ name === "set-cookie" ||
87
+ name === "content-length" ||
88
+ name === "content-type") {
89
+ continue;
90
+ }
91
+ headers.append(key, value);
92
+ }
93
+ for (const cookie of response.headers.getSetCookie()) {
94
+ headers.append("set-cookie", cookie);
95
+ }
96
+ headers.set("cache-control", "no-store");
97
+ headers.set("content-type", "text/html; charset=utf-8");
98
+ headers.set("referrer-policy", "no-referrer");
99
+ const href = escapeHtmlAttr(destination);
100
+ const script = JSON.stringify(destination).replace(/</g, "\\u003c");
101
+ return new Response(`<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="referrer" content="no-referrer"><meta http-equiv="refresh" content="0;url=${href}"><script>location.replace(${script})</script></head><body></body></html>`, { status: 200, headers });
102
+ }
@@ -11,6 +11,7 @@ import { getSession, redirectWithStagedCookies, safeReturnPath, } from "./auth.j
11
11
  import { resolveSecret } from "./credential-provider.js";
12
12
  import { canonicalFrameworkPathname } from "./framework-route-prefix.js";
13
13
  import { decodeOAuthState, encodeOAuthState, getAppUrl, logOAuthStateDecodeFailure, oauthErrorPage, resolveOAuthRedirectUri, } from "./google-oauth.js";
14
+ import { queryEchoSafeRedirect } from "./query-echo-safe-redirect.js";
14
15
  import { runWithRequestContext } from "./request-context.js";
15
16
  const SUPPORTED_PROVIDERS = new Set([
16
17
  "figma",
@@ -342,7 +343,7 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
342
343
  const returnPath = flow.returnUrl ??
343
344
  state.returnUrl ??
344
345
  `/settings/integrations?connected=${encodeURIComponent(providerId)}`;
345
- return redirectWithStagedCookies(event, getAppUrl(event, returnPath));
346
+ return queryEchoSafeRedirect(event, redirectWithStagedCookies(event, getAppUrl(event, returnPath)));
346
347
  });
347
348
  }
348
349
  export function buildWorkspaceProviderAuthorizationUrl(input) {
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22
 
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22
 
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22
 
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22
 
@@ -13,6 +13,8 @@ declare const _default: import("../../action.js").ActionDefinition<{
13
13
  executionEngine?: string;
14
14
  executionCwd?: string;
15
15
  }, {
16
+ deleted?: undefined;
17
+ enabled?: undefined;
16
18
  created: boolean;
17
19
  name: string;
18
20
  scope: "organization" | "personal";
@@ -23,33 +25,31 @@ declare const _default: import("../../action.js").ActionDefinition<{
23
25
  reasoningEffort: "auto" | "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh";
24
26
  webhookPath: string;
25
27
  nextRun: string;
26
- deleted?: undefined;
27
- enabled?: undefined;
28
28
  executionHostId?: undefined;
29
29
  executionEngine?: undefined;
30
30
  executionCwd?: undefined;
31
31
  } | {
32
- scope?: undefined;
32
+ enabled?: undefined;
33
+ nextRun?: undefined;
33
34
  created?: undefined;
35
+ scope?: undefined;
34
36
  triggerType?: undefined;
35
37
  event?: undefined;
36
38
  deleted: boolean;
37
39
  name: string;
38
- enabled?: undefined;
39
40
  schedule?: undefined;
40
41
  timezone?: undefined;
41
42
  reasoningEffort?: undefined;
42
43
  executionHostId?: undefined;
43
44
  executionEngine?: undefined;
44
45
  executionCwd?: undefined;
45
- nextRun?: undefined;
46
46
  webhookPath?: undefined;
47
47
  } | {
48
- scope?: undefined;
48
+ deleted?: undefined;
49
49
  created?: undefined;
50
+ scope?: undefined;
50
51
  triggerType?: undefined;
51
52
  event?: undefined;
52
- deleted?: undefined;
53
53
  name: string;
54
54
  enabled: boolean;
55
55
  schedule: string;
@@ -236,6 +236,25 @@ from the request origin, so deployments should not hard-code a production
236
236
 
237
237
  Once an agent is connected, it sees the [compact catalog](#catalog-tiers) by default: template-declared app actions plus the builtin cross-app verbs (`list_apps`, `open_app`, `ask_app`, and the app-only embed helper). Use `ask_app` to route a natural-language task through an app agent (the same cross-app entry point [A2A](/docs/a2a-protocol) uses).
238
238
 
239
+ ### Tool annotations {#tool-annotations}
240
+
241
+ Every catalog advertises an action's declared `mcpAnnotations`, including the
242
+ optional `idempotentHint`. Declare them wherever the derived hints would
243
+ misstate the effect: moving an item to recoverable Trash still removes it from
244
+ view, so it is `destructiveHint: true`, and a call guarded by an idempotency
245
+ key is `idempotentHint: true`. Without a declaration, `/mcp` derives
246
+ `readOnlyHint` from `readOnly` and `destructiveHint` from `needsApproval` or
247
+ `publicAgent.isConsequential`.
248
+
249
+ ```ts
250
+ mcpAnnotations: {
251
+ readOnlyHint: false,
252
+ destructiveHint: true,
253
+ idempotentHint: true,
254
+ openWorldHint: false,
255
+ },
256
+ ```
257
+
239
258
  ### MCP Apps compatibility {#mcp-apps-compatibility}
240
259
 
241
260
  Agent-Native apps also speak the official MCP Apps extension. When any action
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent-native/core",
3
- "version": "0.204.0-nightly-20261008011018",
3
+ "version": "0.204.0",
4
4
  "description": "The agentic application framework for building autonomous agents with intuitive UIs",
5
5
  "homepage": "https://github.com/BuilderIO/agent-native#readme",
6
6
  "bugs": {
@@ -682,8 +682,8 @@
682
682
  "yaml": "^2.9.0",
683
683
  "yjs": "^13.6.33",
684
684
  "zod": "^4.3.6",
685
- "@agent-native/recap-cli": "^0.5.66-nightly-20261008011018",
686
- "@agent-native/agentkit": "^0.204.0-nightly-20261008011018"
685
+ "@agent-native/agentkit": "^0.204.0",
686
+ "@agent-native/recap-cli": "^0.5.66"
687
687
  },
688
688
  "devDependencies": {
689
689
  "@ai-sdk/anthropic": "^3.0.71",
@@ -753,7 +753,7 @@
753
753
  "xlsx": "^0.18.5"
754
754
  },
755
755
  "peerDependencies": {
756
- "@agent-native/core-corpus": "0.204.0-nightly-20261008011018",
756
+ "@agent-native/core-corpus": ">=0.196.0",
757
757
  "@ai-sdk/anthropic": ">=3",
758
758
  "@ai-sdk/cohere": ">=3",
759
759
  "@ai-sdk/google": ">=3",
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22
 
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22
 
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22
 
@@ -16,6 +16,7 @@ Rules:
16
16
  - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
17
17
  - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
18
18
  - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
19
+ - MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
19
20
 
20
21
  Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
21
22