@agent-native/core 0.125.0 → 0.127.1

package/dist/sharing/registry.d.ts

@@ -16,6 +16,7 @@
  *     titleColumn: "title",
  *   });
  */
+import type { UserProfile } from "../user-profile/shared.js";
 export interface ShareableResourceRegistration {
     /** Stable identifier used across actions, UI, and analytics. e.g. "document". */
     type: string;
@@ -41,7 +42,45 @@ export interface ShareableResourceRegistration {
      * (e.g. the sharing org's own logo), or undefined to fall back. Receives the
      * resource row being shared so the template can scope the logo to its org.
      */
-    getShareEmailLogoUrl?: (resource: any) => string | undefined | Promise<string | undefined>;
+    getLogoUrl?: (resource: any) => string | undefined | Promise<string | undefined>;
+    /**
+     * Optional resolver for the brand name shown beside the logo in the
+     * share-notification email header. Return a display name (e.g. the sharing
+     * org's name) to override the app name, or undefined to keep the default.
+     * Receives the resource row being shared.
+     */
+    getBrandName?: (resource: any) => string | undefined | Promise<string | undefined>;
+    /**
+     * Optional resolver for who the share-notification email appears to come
+     * from. `fromName` changes only the display name and keeps the configured,
+     * domain-verified sending address (e.g. "Alice via Clips"); `replyTo` routes
+     * replies to the sharer. `ctx.sender` is the account doing the sharing, so the
+     * template decides how to present them (name, email, avatar).
+     *
+     * Do not put a user's address in the sending address itself — SPF/DKIM sign
+     * the app's domain, so recipients would bounce or spam-filter it.
+     */
+    getSender?: (resource: any, ctx: {
+        sender: UserProfile;
+    }) => {
+        fromName?: string;
+        replyTo?: string;
+    } | undefined | Promise<{
+        fromName?: string;
+        replyTo?: string;
+    } | undefined>;
+    /**
+     * Optional resolver for a preview block shown above the CTA in the
+     * share-notification email — e.g. a recording thumbnail with a play badge.
+     * Return trusted HTML (built by template code, dynamic values escaped) that
+     * is injected verbatim, or undefined to omit it. `ctx.href` is the resolved
+     * link to the resource; `ctx.alt` is its title. The template owns the entire
+     * preview markup so the generic share action stays app-agnostic.
+     */
+    getHeroHtml?: (resource: any, ctx: {
+        href: string;
+        alt?: string;
+    }) => string | undefined | Promise<string | undefined>;
     /**
      * Drizzle DB accessor from the template's server/db/index.ts. Required —
      * the framework-level share actions and access helpers call this to reach

package/dist/sharing/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,6BAA6B;IAC5C,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC;IACnB,qDAAqD;IACrD,WAAW,EAAE,GAAG,CAAC;IACjB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;IACxD;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,CACrB,QAAQ,EAAE,GAAG,KACV,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EACb,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,CAAC,CACC,QAAQ,EAAE,GAAG,EACb,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAEzC,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,OAAO,CAAC,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAChD;;;;;;;;;;OAUG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK;QACtE,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;OAMG;IACH,aAAa,CAAC,EACV,KAAK,GACL;QACE,uEAAuE;QACvE,YAAY,EAAE,MAAM,CAAC;QACrB,qEAAqE;QACrE,cAAc,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;QACtD,uEAAuE;QACvE,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;QACpD,iEAAiE;QACjE,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACP;AAuCD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,6BAA6B,GACnC,IAAI,CAGN;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GACX,6BAA6B,GAAG,SAAS,CAE3C;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GACX,6BAA6B,CAS/B;AAED,wBAAgB,sBAAsB,IAAI,6BAA6B,EAAE,CAExE"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"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"}

package/dist/sharing/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA+HH,0EAA0E;AAC1E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD,MAAM,cAAc,GAClB,UAAiB,CAAC;AAEpB,SAAS,aAAa;IACpB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM;QAC/B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;QAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAC3B,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B;IACnC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;IACtC,OAAO,oEAAoE,CAAC,IAAI,CAC9E,KAAK,CACN,CAAC;AACJ,CAAC;AAED,SAAS,WAAW;IAClB,IAAI,CAAC,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,GAAG,IAAI,GAAG,EAAyC,CAAC;QACrD,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAoC;IAEpC,IAAI,CAAC,aAAa,EAAE,IAAI,4BAA4B,EAAE;QAAE,OAAO;IAC/D,WAAW,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,IAAY;IAEZ,OAAO,WAAW,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,IAAY;IAEZ,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,gDAAgD,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;AAC5C,CAAC","sourcesContent":["/**\n * Registry of shareable resources.\n *\n * Each template registers its ownable resource(s) once on module load so the\n * framework-level share actions (`share-resource`, `list-resource-shares`,\n * etc.) can dispatch to the correct tables.\n *\n *   import { registerShareableResource } from \"@agent-native/core/sharing\";\n *   import * as schema from \"./schema.js\";\n *\n *   registerShareableResource({\n *     type: \"document\",\n *     resourceTable: schema.documents,\n *     sharesTable: schema.documentShares,\n *     displayName: \"Document\",\n *     titleColumn: \"title\",\n *   });\n */\n\nexport interface ShareableResourceRegistration {\n  /** Stable identifier used across actions, UI, and analytics. e.g. \"document\". */\n  type: string;\n  /** Drizzle table for the parent resource (must have ownableColumns()). */\n  resourceTable: any;\n  /** Drizzle table produced by createSharesTable(). */\n  sharesTable: any;\n  /** Human-readable singular label shown in the share dialog. */\n  displayName: string;\n  /**\n   * Column on the resource table that holds a human-readable title for\n   * display in the share UI. Default: \"title\".\n   */\n  titleColumn?: string;\n  /**\n   * Optional app-relative path to this resource. Used by share notifications\n   * when the caller does not pass a more specific resourceUrl.\n   */\n  getResourcePath?: (resource: any) => string | undefined;\n  /**\n   * Optional resolver for the share-notification email's brand logo. Return an\n   * absolute `https://` URL to override the default embedded Agent Native logo\n   * (e.g. the sharing org's own logo), or undefined to fall back. Receives the\n   * resource row being shared so the template can scope the logo to its org.\n   */\n  getShareEmailLogoUrl?: (\n    resource: any,\n  ) => string | undefined | Promise<string | undefined>;\n  /**\n   * Drizzle DB accessor from the template's server/db/index.ts. Required —\n   * the framework-level share actions and access helpers call this to reach\n   * the right DB instance (schema is template-specific).\n   */\n  getDb: () => any;\n  /**\n   * When `false`, `visibility: \"public\"` is rejected by `set-resource-visibility`,\n   * and `accessFilter` / `resolveAccess` treat any stored public row as private\n   * (defense in depth — only owner + explicit shares grant access).\n   *\n   * Use this for resources that execute code or expose privileged data and must\n   * never be reachable by a random authenticated user. Extensions set this:\n   * extension HTML runs inside an iframe that calls actions / DB / proxied APIs\n   * as the *viewer*, so a public extension would be arbitrary code with the\n   * viewer's credentials.\n   *\n   * Default: `true` (matches the historical behavior — most resources can be public).\n   */\n  allowPublic?: boolean;\n  /**\n   * Optional role granted by a public-by-link read. Most resources should omit\n   * this so public visibility remains viewer-only. Use narrowly for local or\n   * otherwise constrained resources where the resource owner intentionally wants\n   * unauthenticated link holders to do more than view.\n   *\n   * When this is a function, it may read arbitrary fields on the resource row\n   * (not just the ownership/visibility columns). Because of that,\n   * `resolveAccess`/`assertAccess`'s opt-in `{ skipResourceBody: true }`\n   * projected load (see `access.ts`) is automatically ignored for this\n   * registration and always loads the full row instead — a fixed role string\n   * has no such requirement and is compatible with the projection.\n   */\n  publicAccessRole?:\n    | \"viewer\"\n    | \"editor\"\n    | \"admin\"\n    | ((\n        resource: any,\n        ctx: { userEmail?: string; orgId?: string },\n      ) =>\n        | \"viewer\"\n        | \"editor\"\n        | \"admin\"\n        | Promise<\"viewer\" | \"editor\" | \"admin\">);\n  /**\n   * When `true`, individual user shares (`principalType: \"user\"`) must target\n   * an email that is already a member of the same org as the resource, OR has\n   * a pending invitation to that org. Cross-org user shares are rejected.\n   *\n   * Pair with `allowPublic: false` for resources that need a hard \"this org\n   * only\" trust boundary. Extensions set this so a malicious caller can't\n   * widen reach by sharing a code-executing extension to an outsider email.\n   *\n   * Default: `false` (matches the historical behavior — any email can be granted).\n   */\n  requireOrgMemberForUserShares?: boolean;\n  /**\n   * Optional per-resource access-context adapter. Most resources should use the\n   * request user/org unchanged. Templates with an intentional alternate local\n   * identity can normalize here so the generic framework sharing actions and\n   * access helpers stay in sync with template-owned actions.\n   */\n  resolveAccessContext?: (ctx: { userEmail?: string; orgId?: string }) => {\n    userEmail?: string;\n    orgId?: string;\n  };\n  /**\n   * When true, direct ownership is recognized by owner_email regardless of the\n   * caller's active org. Use this only for resource types where the template's\n   * own actions already treat owner_email as the cross-org authority and list\n   * views add their own org filters.\n   *\n   * Default: `false`.\n   */\n  ownerAccessIgnoresOrg?: boolean;\n  /**\n   * Optional external-agent read handoff. When set, the framework-level\n   * `create-agent-resource-link` action can mint a short-lived, read-only\n   * `agent_access` URL for this resource. The context endpoint is owned by the\n   * template so it can expose the same intentionally shareable shape as the\n   * public page, not a generic raw database row.\n   */\n  agentReadable?:\n    | false\n    | {\n        /** Token scope. Include the app name to avoid cross-app collisions. */\n        resourceKind: string;\n        /** App-relative JSON endpoint that accepts `id` + `agent_access`. */\n        getContextPath: (resource: any) => string | undefined;\n        /** Optional override for the page URL. Defaults to getResourcePath. */\n        getPagePath?: (resource: any) => string | undefined;\n        /** Optional override for the default two-hour token lifetime. */\n        ttlSeconds?: number;\n      };\n}\n\n// Stash the registry on globalThis so it survives SSR bundle duplication.\n// Vite SSR's `noExternal: /^(?!node:)/` policy means @agent-native/core gets\n// inlined into every server bundle that imports it — and each bundle gets its\n// own module-level state. A plain `new Map()` here would create one Map per\n// bundle, so the template's `registerShareableResource()` (called from the\n// Nitro plugin graph) wouldn't be visible to the framework's auto-mounted\n// share-resource action (loaded via `import(\"../sharing/actions/...js\")` in a\n// different module instance). Using globalThis collapses them back to one Map.\nconst REGISTRY_KEY = \"__agentNativeShareableResources__\";\ntype RegistryStore = Map<string, ShareableResourceRegistration>;\nconst globalRegistry: { [K in typeof REGISTRY_KEY]?: RegistryStore } =\n  globalThis as any;\n\nfunction isTestRuntime(): boolean {\n  return (\n    process.env.NODE_ENV === \"test\" ||\n    process.env.VITEST === \"true\" ||\n    process.env.VITEST === \"1\"\n  );\n}\n\nfunction registrationCameFromTestFile(): boolean {\n  const stack = new Error().stack ?? \"\";\n  return /[./\\\\](?:[^/\\\\]+[.-])(?:test|spec)\\.[cm]?[jt]sx?(?::\\d+)?(?::\\d+)?/.test(\n    stack,\n  );\n}\n\nfunction getRegistry(): RegistryStore {\n  let r = globalRegistry[REGISTRY_KEY];\n  if (!r) {\n    r = new Map<string, ShareableResourceRegistration>();\n    globalRegistry[REGISTRY_KEY] = r;\n  }\n  return r;\n}\n\nexport function registerShareableResource(\n  entry: ShareableResourceRegistration,\n): void {\n  if (!isTestRuntime() && registrationCameFromTestFile()) return;\n  getRegistry().set(entry.type, entry);\n}\n\nexport function getShareableResource(\n  type: string,\n): ShareableResourceRegistration | undefined {\n  return getRegistry().get(type);\n}\n\nexport function requireShareableResource(\n  type: string,\n): ShareableResourceRegistration {\n  const reg = getRegistry();\n  const entry = reg.get(type);\n  if (!entry) {\n    throw new Error(\n      `Unknown shareable resource type: \"${type}\". Did you forget registerShareableResource()?`,\n    );\n  }\n  return entry;\n}\n\nexport function listShareableResources(): ShareableResourceRegistration[] {\n  return Array.from(getRegistry().values());\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAuKH,0EAA0E;AAC1E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD,MAAM,cAAc,GAClB,UAAiB,CAAC;AAEpB,SAAS,aAAa;IACpB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM;QAC/B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;QAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAC3B,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B;IACnC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;IACtC,OAAO,oEAAoE,CAAC,IAAI,CAC9E,KAAK,CACN,CAAC;AACJ,CAAC;AAED,SAAS,WAAW;IAClB,IAAI,CAAC,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,GAAG,IAAI,GAAG,EAAyC,CAAC;QACrD,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAoC;IAEpC,IAAI,CAAC,aAAa,EAAE,IAAI,4BAA4B,EAAE;QAAE,OAAO;IAC/D,WAAW,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,IAAY;IAEZ,OAAO,WAAW,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,IAAY;IAEZ,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,gDAAgD,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;AAC5C,CAAC","sourcesContent":["/**\n * Registry of shareable resources.\n *\n * Each template registers its ownable resource(s) once on module load so the\n * framework-level share actions (`share-resource`, `list-resource-shares`,\n * etc.) can dispatch to the correct tables.\n *\n *   import { registerShareableResource } from \"@agent-native/core/sharing\";\n *   import * as schema from \"./schema.js\";\n *\n *   registerShareableResource({\n *     type: \"document\",\n *     resourceTable: schema.documents,\n *     sharesTable: schema.documentShares,\n *     displayName: \"Document\",\n *     titleColumn: \"title\",\n *   });\n */\n\nimport type { UserProfile } from \"../user-profile/shared.js\";\n\nexport interface ShareableResourceRegistration {\n  /** Stable identifier used across actions, UI, and analytics. e.g. \"document\". */\n  type: string;\n  /** Drizzle table for the parent resource (must have ownableColumns()). */\n  resourceTable: any;\n  /** Drizzle table produced by createSharesTable(). */\n  sharesTable: any;\n  /** Human-readable singular label shown in the share dialog. */\n  displayName: string;\n  /**\n   * Column on the resource table that holds a human-readable title for\n   * display in the share UI. Default: \"title\".\n   */\n  titleColumn?: string;\n  /**\n   * Optional app-relative path to this resource. Used by share notifications\n   * when the caller does not pass a more specific resourceUrl.\n   */\n  getResourcePath?: (resource: any) => string | undefined;\n  /**\n   * Optional resolver for the share-notification email's brand logo. Return an\n   * absolute `https://` URL to override the default embedded Agent Native logo\n   * (e.g. the sharing org's own logo), or undefined to fall back. Receives the\n   * resource row being shared so the template can scope the logo to its org.\n   */\n  getLogoUrl?: (\n    resource: any,\n  ) => string | undefined | Promise<string | undefined>;\n  /**\n   * Optional resolver for the brand name shown beside the logo in the\n   * share-notification email header. Return a display name (e.g. the sharing\n   * org's name) to override the app name, or undefined to keep the default.\n   * Receives the resource row being shared.\n   */\n  getBrandName?: (\n    resource: any,\n  ) => string | undefined | Promise<string | undefined>;\n  /**\n   * Optional resolver for who the share-notification email appears to come\n   * from. `fromName` changes only the display name and keeps the configured,\n   * domain-verified sending address (e.g. \"Alice via Clips\"); `replyTo` routes\n   * replies to the sharer. `ctx.sender` is the account doing the sharing, so the\n   * template decides how to present them (name, email, avatar).\n   *\n   * Do not put a user's address in the sending address itself — SPF/DKIM sign\n   * the app's domain, so recipients would bounce or spam-filter it.\n   */\n  getSender?: (\n    resource: any,\n    ctx: { sender: UserProfile },\n  ) =>\n    | { fromName?: string; replyTo?: string }\n    | undefined\n    | Promise<{ fromName?: string; replyTo?: string } | undefined>;\n  /**\n   * Optional resolver for a preview block shown above the CTA in the\n   * share-notification email — e.g. a recording thumbnail with a play badge.\n   * Return trusted HTML (built by template code, dynamic values escaped) that\n   * is injected verbatim, or undefined to omit it. `ctx.href` is the resolved\n   * link to the resource; `ctx.alt` is its title. The template owns the entire\n   * preview markup so the generic share action stays app-agnostic.\n   */\n  getHeroHtml?: (\n    resource: any,\n    ctx: { href: string; alt?: string },\n  ) => string | undefined | Promise<string | undefined>;\n  /**\n   * Drizzle DB accessor from the template's server/db/index.ts. Required —\n   * the framework-level share actions and access helpers call this to reach\n   * the right DB instance (schema is template-specific).\n   */\n  getDb: () => any;\n  /**\n   * When `false`, `visibility: \"public\"` is rejected by `set-resource-visibility`,\n   * and `accessFilter` / `resolveAccess` treat any stored public row as private\n   * (defense in depth — only owner + explicit shares grant access).\n   *\n   * Use this for resources that execute code or expose privileged data and must\n   * never be reachable by a random authenticated user. Extensions set this:\n   * extension HTML runs inside an iframe that calls actions / DB / proxied APIs\n   * as the *viewer*, so a public extension would be arbitrary code with the\n   * viewer's credentials.\n   *\n   * Default: `true` (matches the historical behavior — most resources can be public).\n   */\n  allowPublic?: boolean;\n  /**\n   * Optional role granted by a public-by-link read. Most resources should omit\n   * this so public visibility remains viewer-only. Use narrowly for local or\n   * otherwise constrained resources where the resource owner intentionally wants\n   * unauthenticated link holders to do more than view.\n   *\n   * When this is a function, it may read arbitrary fields on the resource row\n   * (not just the ownership/visibility columns). Because of that,\n   * `resolveAccess`/`assertAccess`'s opt-in `{ skipResourceBody: true }`\n   * projected load (see `access.ts`) is automatically ignored for this\n   * registration and always loads the full row instead — a fixed role string\n   * has no such requirement and is compatible with the projection.\n   */\n  publicAccessRole?:\n    | \"viewer\"\n    | \"editor\"\n    | \"admin\"\n    | ((\n        resource: any,\n        ctx: { userEmail?: string; orgId?: string },\n      ) =>\n        | \"viewer\"\n        | \"editor\"\n        | \"admin\"\n        | Promise<\"viewer\" | \"editor\" | \"admin\">);\n  /**\n   * When `true`, individual user shares (`principalType: \"user\"`) must target\n   * an email that is already a member of the same org as the resource, OR has\n   * a pending invitation to that org. Cross-org user shares are rejected.\n   *\n   * Pair with `allowPublic: false` for resources that need a hard \"this org\n   * only\" trust boundary. Extensions set this so a malicious caller can't\n   * widen reach by sharing a code-executing extension to an outsider email.\n   *\n   * Default: `false` (matches the historical behavior — any email can be granted).\n   */\n  requireOrgMemberForUserShares?: boolean;\n  /**\n   * Optional per-resource access-context adapter. Most resources should use the\n   * request user/org unchanged. Templates with an intentional alternate local\n   * identity can normalize here so the generic framework sharing actions and\n   * access helpers stay in sync with template-owned actions.\n   */\n  resolveAccessContext?: (ctx: { userEmail?: string; orgId?: string }) => {\n    userEmail?: string;\n    orgId?: string;\n  };\n  /**\n   * When true, direct ownership is recognized by owner_email regardless of the\n   * caller's active org. Use this only for resource types where the template's\n   * own actions already treat owner_email as the cross-org authority and list\n   * views add their own org filters.\n   *\n   * Default: `false`.\n   */\n  ownerAccessIgnoresOrg?: boolean;\n  /**\n   * Optional external-agent read handoff. When set, the framework-level\n   * `create-agent-resource-link` action can mint a short-lived, read-only\n   * `agent_access` URL for this resource. The context endpoint is owned by the\n   * template so it can expose the same intentionally shareable shape as the\n   * public page, not a generic raw database row.\n   */\n  agentReadable?:\n    | false\n    | {\n        /** Token scope. Include the app name to avoid cross-app collisions. */\n        resourceKind: string;\n        /** App-relative JSON endpoint that accepts `id` + `agent_access`. */\n        getContextPath: (resource: any) => string | undefined;\n        /** Optional override for the page URL. Defaults to getResourcePath. */\n        getPagePath?: (resource: any) => string | undefined;\n        /** Optional override for the default two-hour token lifetime. */\n        ttlSeconds?: number;\n      };\n}\n\n// Stash the registry on globalThis so it survives SSR bundle duplication.\n// Vite SSR's `noExternal: /^(?!node:)/` policy means @agent-native/core gets\n// inlined into every server bundle that imports it — and each bundle gets its\n// own module-level state. A plain `new Map()` here would create one Map per\n// bundle, so the template's `registerShareableResource()` (called from the\n// Nitro plugin graph) wouldn't be visible to the framework's auto-mounted\n// share-resource action (loaded via `import(\"../sharing/actions/...js\")` in a\n// different module instance). Using globalThis collapses them back to one Map.\nconst REGISTRY_KEY = \"__agentNativeShareableResources__\";\ntype RegistryStore = Map<string, ShareableResourceRegistration>;\nconst globalRegistry: { [K in typeof REGISTRY_KEY]?: RegistryStore } =\n  globalThis as any;\n\nfunction isTestRuntime(): boolean {\n  return (\n    process.env.NODE_ENV === \"test\" ||\n    process.env.VITEST === \"true\" ||\n    process.env.VITEST === \"1\"\n  );\n}\n\nfunction registrationCameFromTestFile(): boolean {\n  const stack = new Error().stack ?? \"\";\n  return /[./\\\\](?:[^/\\\\]+[.-])(?:test|spec)\\.[cm]?[jt]sx?(?::\\d+)?(?::\\d+)?/.test(\n    stack,\n  );\n}\n\nfunction getRegistry(): RegistryStore {\n  let r = globalRegistry[REGISTRY_KEY];\n  if (!r) {\n    r = new Map<string, ShareableResourceRegistration>();\n    globalRegistry[REGISTRY_KEY] = r;\n  }\n  return r;\n}\n\nexport function registerShareableResource(\n  entry: ShareableResourceRegistration,\n): void {\n  if (!isTestRuntime() && registrationCameFromTestFile()) return;\n  getRegistry().set(entry.type, entry);\n}\n\nexport function getShareableResource(\n  type: string,\n): ShareableResourceRegistration | undefined {\n  return getRegistry().get(type);\n}\n\nexport function requireShareableResource(\n  type: string,\n): ShareableResourceRegistration {\n  const reg = getRegistry();\n  const entry = reg.get(type);\n  if (!entry) {\n    throw new Error(\n      `Unknown shareable resource type: \"${type}\". Did you forget registerShareableResource()?`,\n    );\n  }\n  return entry;\n}\n\nexport function listShareableResources(): ShareableResourceRegistration[] {\n  return Array.from(getRegistry().values());\n}\n"]}

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

@@ -1,9 +1,9 @@
 ---
 name: a2a-protocol
 description: >-
-  How agents call other agents via the A2A (agent-to-agent) JSON-RPC protocol.
-  Use when enabling inter-agent communication, exposing agent skills to other
-  agents, or calling external agents from scripts.
+  How agent-native apps discover, authenticate with, and call each other over
+  A2A. Use when connecting one app to another, debugging a remote agent that
+  won't authenticate, exposing skills to peers, or calling agents from scripts.
 scope: dev
 metadata:
   internal: true
@@ -13,110 +13,155 @@ metadata:
 
 ## Rule
 
-Agents can call other agents using the A2A protocol. This is a JSON-RPC-based protocol for agent discovery and communication. Use it when work should go to a different agent entirely — not the local agent chat.
+Agents call other agents over A2A, a JSON-RPC protocol for discovery and
+delegation. Use it when work belongs to a different agent entirely — not the
+local agent chat.
 
-## Why
+Connecting app A to app B is two independent things, and both must be true:
 
-Agent-native apps don't exist in isolation. A mail agent might need analytics data. A calendar agent might need to search issues. A2A lets agents discover each other, send messages, and receive structured results — all over HTTP with bearer token auth.
+1. **B is registered on A** as a `remote-agents/<id>.json` resource.
+2. **A and B share a secret**, so A's signed JWT verifies on B.
 
-## How to Enable A2A (Server Side)
+Neither is a code change, and neither is symmetric. Registering B on A does not
+let B call A.
 
-Add `mountA2A()` to a server plugin:
+## A2A is already mounted
 
-```ts
-// server/plugins/a2a.ts
-import { mountA2A } from "@agent-native/core/a2a";
-
-export default defineNitroPlugin((nitro) => {
-  const app = nitro.h3App;
-
-  mountA2A(app, {
-    name: "Analytics Agent",
-    description: "Queries analytics data across providers",
-    version: "1.0.0",
-    skills: [
-      {
-        id: "query-data",
-        name: "Query Data",
-        description: "Run analytics queries across connected data sources",
-        tags: ["analytics", "data"],
-        examples: ["What were last week's signups?", "Show conversion rates"],
-      },
-    ],
-    apiKeyEnv: "A2A_API_KEY", // env var holding the bearer token
-    streaming: true,          // enable message/stream method
-  });
-});
-```
-
-This mounts the agent-native A2A endpoints:
-
-- `GET /.well-known/agent-card.json` — public agent discovery (no auth required)
-- `POST /_agent-native/a2a` — primary JSON-RPC endpoint (bearer token auth required)
+`createAgentChatPlugin` calls `mountA2A` for every app, so a generated app
+already serves:
 
-The client may fall back to `POST /a2a` for external or legacy peers that only
-expose that simple path. New agent-native apps should document and call the
-`/_agent-native/a2a` endpoint.
+- `GET /.well-known/agent-card.json` — public discovery, never authenticated
+- `POST /_agent-native/a2a` — JSON-RPC, authenticated
 
-## The Config Object
-
-```ts
-interface A2AConfig {
-  name: string;           // agent display name
-  description: string;    // what this agent does
-  version?: string;       // semver version (default: "1.0.0")
-  skills: AgentSkill[];   // capabilities this agent exposes
-  handler?: A2AHandler;   // custom message handler
-  apiKeyEnv?: string;     // env var name for bearer token auth
-  streaming?: boolean;    // enable streaming responses
-}
+Do not add a `mountA2A` server plugin to enable A2A; it is on. Hand-mounting is
+only for a bespoke card or a custom handler (see **Custom mount** below).
 
-interface AgentSkill {
-  id: string;             // unique skill identifier
-  name: string;           // human-readable name
-  description: string;    // what this skill does
-  tags?: string[];        // categorization tags
-  examples?: string[];    // example prompts
-}
-```
+The client falls back to `POST /a2a` for external peers that only expose that
+path. New agent-native apps should call `/_agent-native/a2a`.
 
-## Agent Card
+## Registering a remote agent
 
-The agent card is auto-generated at `GET /.well-known/agent-card.json`. Other agents fetch this to discover what skills are available:
+A remote agent is **a row in the resources table, not a file on disk**. Path
+`remote-agents/<id>.json`, owner `SHARED_OWNER`, content:
 
 ```json
 {
-  "name": "Analytics Agent",
+  "id": "analytics",
+  "name": "Analytics",
   "description": "Queries analytics data across providers",
   "url": "https://analytics.example.com",
-  "version": "1.0.0",
-  "protocolVersion": "0.3",
-  "capabilities": { "streaming": true },
-  "skills": [
-    {
-      "id": "query-data",
-      "name": "Query Data",
-      "description": "Run analytics queries across connected data sources"
-    }
-  ]
+  "color": "#6B7280"
 }
 ```
 
-## Calling Another Agent
+`url` is the only required field. `parseRemoteAgentManifest` accepts **only**
+these five keys — there is no `apiKey`, `env`, `skills`, or `token` field, and
+anything else is silently dropped.
+
+Four ways to create it, all writing the same row:
+
+| Surface | Where |
+| --- | --- |
+| Settings → Manage agent → Connected Agents (A2A) | any app with the settings panel |
+| Agent page → Connections | apps mounting `AgentTabsPage` |
+| Dispatch → Agents → Add external agent | workspace dispatch |
+| The agent itself | `resources` tool, `action: "write"`, `--scope shared` |
+
+The last one matters for template apps with no Code tab: "connect me to
+https://analytics.example.com" is a complete instruction. `remote-agents/` is
+whitelisted as a durable control path, so the write is workspace-scoped, and it
+takes effect on the next `discoverAgents()` call with no restart.
+
+First-party templates are seeded automatically and overlaid on top of manifests,
+so `Mail`, `Calendar`, and friends appear without registration. In dev they
+resolve to `http://localhost:<devPort>`; a manifest pointing at localhost is
+ignored in production.
+
+`call-agent` also accepts a raw URL, which skips registration entirely — useful
+for one-off calls, useless for @-mentions.
+
+### Checking a peer
+
+`GET /_agent-native/agents/probe?url=<base>` reads the peer's card and makes one
+authenticated no-op call, returning `reachable` and `authorized` as independent
+fields. Omit `url` to probe every registered peer. Reachable-but-unauthorized is
+the failure worth looking for: local dev runs the receiver unauthenticated, so a
+mismatched secret only surfaces after deploy. The Connected Agents settings
+section calls this on add and on open.
+
+## Authentication
+
+A2A authenticates with a **short-lived JWT the caller signs**, not a stored
+bearer key. `Authorization: Bearer <jwt>`; claims carry the caller's email and
+org domain; HS256; 15-minute default TTL. There is no per-peer API key
+anywhere in the system, which is why the manifest has no field for one.
+
+Two secrets can sign it:
+
+| Secret | Scope | How it is set |
+| --- | --- | --- |
+| `A2A_SECRET` | whole deployment | env var, **never auto-generated** |
+| org `a2a_secret` | one organization | auto-generated on org creation; Team page UI |
+
+The org secret is the managed path: **Team page → A2A secret** (owner only)
+reveals, copies, regenerates, and pushes it to every discovered peer. Rotation
+is tolerated — the caller tries both secrets in order and sticks to whichever
+worked.
+
+`A2A_SECRET` is the deploy-level path. `workspace-deploy` refuses a production
+workspace deploy without it and prints the generator command. Peers that must
+trust each other need the *same* value on both sides.
+
+With no secret configured at all:
+
+| Runtime | Result |
+| --- | --- |
+| local dev | open, one-time console warning |
+| production | `503` — "A2A authentication not configured" |
+| production, secret set, bad/absent token | `401` |
+
+"Production" is detected broadly (NODE_ENV, Netlify, Lambda, Vercel, Render,
+Fly, Cloud Run, …) and unrecognized deployed hosts fail closed unless the
+request is genuine loopback or `A2A_ALLOW_UNSIGNED_INTERNAL=1`.
+
+`A2AConfig.apiKeyEnv` still exists for static bearer auth against non-agent-native
+peers, but the framework's own mount never sets it. Do not reach for it when
+debugging a connection between two agent-native apps — the answer there is
+always the shared secret.
+
+Never hardcode either secret in source, docs, prompts, app state, action
+descriptions, client bundles, or examples. Read them from runtime config; never
+log or return them.
+
+## Advertising what this agent can do
+
+Card `skills` are derived from actions marked `publicAgent`. An app that marks
+none publishes `"skills": []` and peers cannot see what it offers, even though
+delegation still works. Mark the actions a peer should be able to see and
+invoke directly; leave the rest internal.
+
+## Calling another agent
 
 ### Simple: `callAgent()` (text in, text out)
 
 ```ts
-import { callAgent } from "@agent-native/core/a2a";
+import { callAgent, resolveA2ACallerAuth } from "@agent-native/core/a2a";
 
+const auth = await resolveA2ACallerAuth();
 const answer = await callAgent(
   "https://analytics.example.com",
   "What were last week's signups?",
-  { apiKey: process.env.ANALYTICS_A2A_KEY },
+  auth,
 );
 // answer is a plain string
 ```
 
+`callAgent` signs nothing on its own — with no `userEmail`/`orgSecret` in opts
+it calls **unauthenticated**, which silently works in local dev and 401s in
+production. `resolveA2ACallerAuth()` pulls the authenticated email, org domain,
+and org secret out of request context; pass them explicitly only from CLI or
+cron, where there is no request.
+
 ### Fast bounded read: `invokeAgentAction()`
 
 When the caller knows the exact receiver-owned read action and arguments, skip
@@ -168,12 +213,13 @@ action arguments or results.
 ### Advanced: `A2AClient` (full control)
 
 ```ts
-import { A2AClient } from "@agent-native/core/a2a";
+import { A2AClient, resolveA2ACallerAuth } from "@agent-native/core/a2a";
 
-const client = new A2AClient(
-  "https://analytics.example.com",
-  process.env.ANALYTICS_A2A_KEY,
-);
+// The second argument is the bearer token itself, not a signing secret.
+const { apiKey, apiKeyFallbacks } = await resolveA2ACallerAuth();
+const client = new A2AClient("https://analytics.example.com", apiKey, {
+  fallbackApiKeys: apiKeyFallbacks,
+});
 
 // Discover agent capabilities
 const card = await client.getAgentCard();
@@ -264,19 +310,6 @@ submitted → working → completed
 - **canceled** — task was canceled via `tasks/cancel`
 - **input-required** — agent needs more information from the caller
 
-## Security
-
-A2A uses bearer token auth. The server reads the token from the environment variable specified by `apiKeyEnv`:
-
-- Set `A2A_API_KEY=<A2A_API_KEY_VALUE>` in the server's deployment environment
-- Callers pass it as `Authorization: Bearer <A2A_API_KEY_VALUE>`
-- The agent card endpoint (`/.well-known/agent-card.json`) is public — no auth needed for discovery
-
-Never hardcode the bearer token in source, docs, prompts, app state, action
-descriptions, client bundles, or examples. A2A tokens are deploy-level secrets
-unless a specific app designs a scoped credential flow; read them from secure
-runtime configuration and never log or return them.
-
 ## Message Parts
 
 Messages contain typed parts:
@@ -287,34 +320,38 @@ Messages contain typed parts:
 | `file`    | `{ type: "file", file: { ... } }`   | Files (bytes or URI)       |
 | `data`    | `{ type: "data", data: { ... } }`   | Structured JSON data       |
 
-## Example: Cross-Agent Workflow
+## Custom mount
 
-A mail agent calls an analytics agent to include data in an email draft:
+Only when the default card is wrong for the app — a curated skill list, a
+non-agent handler, or static bearer auth against an external peer:
 
 ```ts
-// actions/draft-with-analytics.ts
-import { callAgent } from "@agent-native/core/a2a";
-import { writeAppState } from "@agent-native/core/application-state";
-
-export default async function (args: string[]) {
-  // Ask the analytics agent for data
-  const stats = await callAgent(
-    process.env.ANALYTICS_AGENT_URL!,
-    "Summarize last week's key metrics in 3 bullet points",
-    { apiKey: process.env.ANALYTICS_A2A_KEY },
-  );
-
-  // Create a draft with the analytics data
-  await writeAppState("compose-analytics-report", {
-    id: "analytics-report",
-    to: "team@example.com",
-    subject: "Weekly Analytics Summary",
-    body: `Hi team,\n\nHere are last week's numbers:\n\n${stats}\n\nBest`,
-    mode: "compose",
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  mountA2A(nitro, {
+    appId: "analytics",
+    name: "Analytics Agent",
+    description: "Queries analytics data across providers",
+    skills: [
+      {
+        id: "query-data",
+        name: "Query Data",
+        description: "Run analytics queries across connected data sources",
+        tags: ["analytics", "data"],
+        examples: ["What were last week's signups?", "Show conversion rates"],
+      },
+    ],
+    streaming: true,
   });
-}
+});
 ```
 
+Config also carries `handler`, `publicSkillsOnly`, `durableBackgroundRuns`,
+`executeReadOnlyAction`, `executeApproval`, and `apiKeyEnv`. See `A2AConfig` in
+`@agent-native/core/a2a` for the full shape.
+
 ## All Types
 
 All types are exported from `@agent-native/core/a2a`:
@@ -345,5 +382,8 @@ import type {
 ## Related Skills
 
 - **delegate-to-agent** — For work the local agent handles. Use A2A when the work goes to a different agent.
-- **actions** — A2A calls typically happen inside actions
-- **storing-data** — Results from A2A calls are stored in SQL like any other data
+- **authentication** — Org creation, membership, and where the org secret lives.
+- **actions** — A2A calls typically happen inside actions; `publicAgent` marks what peers can see.
+- **storing-data** — Results from A2A calls are stored in SQL like any other data.
+</content>
+</invoke>

package/docs/content/external-agents-catalog.mdx

@@ -225,13 +225,13 @@ In practice, every agent-native app should be authored with both: MCP Apps for i
 
 On top of the per-action tools the MCP server exposes a stable verb set, so an external agent has a predictable surface without guessing per-app action names:
 
-| Tool                                               | Side effects | Returns                                                                                                                      |
-| -------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| `list_apps`                                        | none         | workspace apps + their URLs / running state                                                                                  |
-| `open_app({ app, view?, path?, params?, embed? })` | none         | a deep link or same-origin route; `embed: true` renders the full app inline where supported                                  |
-| `ask_app({ app, message, async?, maxWaitMs? })`    | agent loop   | routes a natural-language task to that app's in-app agent; long work returns a durable `taskId` for `ask_app_status` polling |
-| `create_workspace_app({ name, template })`         | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link                                                    |
-| `list_templates`                                   | none         | the allow-listed templates only                                                                                              |
+| Tool                                               | Side effects | Returns                                                                                                                                                 |
+| -------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_apps`                                        | none         | workspace apps + their URLs / running state                                                                                                             |
+| `open_app({ app, view?, path?, params?, embed? })` | none         | a deep link or same-origin route; `embed: true` renders the full app inline where supported                                                             |
+| `ask_app({ app, message, async?, maxWaitMs? })`    | agent loop   | routes a natural-language task to that app's in-app agent; long work returns a durable `taskHandle` plus a legacy `taskId` for `ask_app_status` polling |
+| `create_workspace_app({ name, template })`         | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link                                                                               |
+| `list_templates`                                   | none         | the allow-listed templates only                                                                                                                         |
 
 `create_workspace_app` rejects any non-allow-listed template — the public template allow-list in `packages/shared-app-config/templates.ts` is authoritative and CI-guarded; an external agent cannot widen it. A same-named template action overrides a builtin (template-over-core precedence). Disable the whole set with `MCPConfig.builtinCrossAppTools: false`.
 
@@ -244,9 +244,10 @@ For fast ChatGPT/Claude handoffs, the ideal path is direct: call the action that
 MCP hosts and gateways do not share one long tool-call timeout; some enforce a
 five-minute ceiling and others are configurable. Do not design an external
 agent integration around a ten-minute blocking `tools/call`. `ask-agent` and
-`ask_app` acknowledge hosted work quickly, then return a durable `taskId` when
-the inline wait expires. Poll with `ask_app_status` using the returned `app`
-and `taskId`; the result includes `pollAfterMs` as a host-friendly interval.
+`ask_app` acknowledge hosted work quickly, then return a durable `taskHandle`
+plus a legacy `taskId` when the inline wait expires. Poll with `ask_app_status`
+by replaying the returned `poll.arguments` unchanged, especially the
+`taskHandle`; the result includes `pollAfterMs` as a host-friendly interval.
 The task must be created before the first response can time out, so a polling
 URL returned only after a long call is not a reliable recovery contract.
 
@@ -254,7 +255,9 @@ If a bounded transient status read is unavailable, `ask_app_status` can return
 `status: "unknown"`, `statusRead: "unavailable"`, `retryable: true`, the
 original `app` and `taskId`, and `pollAfterMs` / `poll`. This means the status
 read is unavailable—not that the durable task failed. Retry `ask_app_status`
-with that exact `app` and `taskId`; never resubmit `ask_app` to recover, because
+with the exact returned `poll.arguments`, including `taskHandle` when present;
+legacy results without a handle must reuse the same `app` and `taskId`. Never
+resubmit `ask_app` to recover, because
 submission can duplicate work. Permanent authentication, not-found, and
 protocol failures remain errors.
 

package/docs/content/mcp-protocol.mdx

@@ -235,7 +235,11 @@ The agent runs the same loop as the interactive chat — it can call multiple to
 {
   "poll": {
     "tool": "ask_app_status",
-    "arguments": { "app": "mail", "taskId": "task_123" }
+    "arguments": {
+      "app": "mail",
+      "taskId": "task_123",
+      "taskHandle": "opaque_handle"
+    }
   }
 }
 ```
@@ -248,9 +252,10 @@ If a bounded transient status read is unavailable, `ask_app_status` can return
 `status: "unknown"`, `statusRead: "unavailable"`, `retryable: true`, the
 original `app` and `taskId`, and `pollAfterMs` / `poll`. This means the status
 read is unavailable—not that the durable task failed. Retry `ask_app_status`
-with that exact `app` and `taskId`; never resubmit `ask_app` to recover, because
-submission can duplicate work. Permanent authentication, not-found, and
-protocol failures remain errors.
+with the returned `poll.arguments` unchanged, including `taskHandle` when
+present; legacy results without a handle must reuse the same `app` and `taskId`.
+Never resubmit `ask_app` to recover, because submission can duplicate work.
+Permanent authentication, not-found, and protocol failures remain errors.
 
 ## Authentication {#authentication}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.125.0",
+  "version": "0.127.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -389,7 +389,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.1",
-    "@agent-native/toolkit": "^0.10.8"
+    "@agent-native/toolkit": "^0.10.9"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/a2a/index.ts

@@ -21,6 +21,8 @@ export {
 
 // Client
 export { A2AClient, callAction, callAgent, signA2AToken } from "./client.js";
+export { resolveA2ACallerAuth } from "./caller-auth.js";
+export type { A2ACallerAuth } from "./caller-auth.js";
 export {
   AgentInvocationError,
   buildAgentInvocationPrompt,

package/src/agent/production-agent.ts

@@ -141,6 +141,7 @@ import {
   getRun,
   abortRun,
   abortRunDurably,
+  abortTurnDurably,
   tryClaimRunSlot,
   isHostedRuntime,
   resolveRunSoftTimeoutMs,
@@ -7409,8 +7410,11 @@ export function createProductionAgentHandler(
     // sent from the model picker; `engine.name` is what resolveEngine picked.
     // Divergence between them is the usual cause of "status says builder but
     // no [builder-engine] log lines appear" confusion.
+    // `requestModel` differing from `model` means normalizeModelForEngine
+    // substituted the engine default — otherwise indistinguishable from the
+    // client never asking for one.
     console.log(
-      `[agent-chat] resolved engine=${engine.name} model=${effectiveModel} requestEngine=${requestEngine ?? "(none)"} modelSource=${modelSelectionSource}`,
+      `[agent-chat] resolved engine=${engine.name} model=${effectiveModel} requestModel=${requestModel ?? "(none)"} requestEngine=${requestEngine ?? "(none)"} modelSource=${modelSelectionSource} turnId=${requestTurnId ?? "(none)"}`,
     );
 
     if (
@@ -9020,5 +9024,6 @@ export {
   getRun,
   abortRun,
   abortRunDurably,
+  abortTurnDurably,
   subscribeToRun,
 };