@agent-native/core 0.228.2-nightly-20261113152307 → 0.228.2

package/dist/server/credential-provider.js

@@ -27,14 +27,14 @@ async function canReadDesignatedVaultFallback(vaultOrgId, credentialKey) {
     }
     try {
         const result = await getDbExec().execute({
+            // A grant names its key itself; legacy grants without `credential_key`
+            // match nothing until they are backfilled.
             sql: `SELECT 1
-        FROM vault_grants AS grants
-        INNER JOIN vault_secrets AS secrets ON secrets.id = grants.secret_id
-        WHERE grants.org_id = ?
-          AND grants.app_id = ?
-          AND grants.status = 'active'
-          AND secrets.org_id = grants.org_id
-          AND secrets.credential_key = ?
+        FROM vault_grants
+        WHERE org_id = ?
+          AND app_id = ?
+          AND status = 'active'
+          AND credential_key = ?
         LIMIT 1`,
             args: [vaultOrgId, appId, credentialKey],
         });

package/dist/server/first-touch-route.d.ts

@@ -17,8 +17,8 @@ export type FirstTouchSyncResult = {
  * browser's `an_ft` and `an_lt` again, so Safari keeps them their 30 days.
  */
 export declare function createFirstTouchHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     reason?: undefined;
+    error: string;
     stored?: undefined;
     firstTouch?: undefined;
 } | {

package/dist/server/transcribe-voice.d.ts

@@ -17,8 +17,8 @@
  * typed JSON-in / JSON-out).
  */
 export declare function createTranscribeVoiceHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     text?: undefined;
+    error: string;
 } | {
     error?: undefined;
     text: string;

package/dist/templates/workspace-core/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -120,6 +120,17 @@ resource CSP should include the exact origins of apps granted through Dispatch,
 not broad sources like `https:`. This lets Claude's transplant path fetch the
 signed target app HTML while keeping the connector's resource surface narrow.
 
+Side panel and app tools: every `embedApp()` resource sets
+`_meta.ui.preferredDisplayMode: "fullscreen"`, so Claude opens the app in its
+side panel beside the chat (other hosts ignore the field). The shell declares
+`availableDisplayModes` and `tools` in `ui/initialize` and answers the host's
+`tools/list` / `tools/call` on the open view: `read_view` returns the page's
+path, title, selection and visible text, `navigate_view` moves the open app to
+another same-origin path in place, and any page tools the app registered through
+WebMCP are passed through. Prefer these over a new `open_app` call when the user
+asks to change what the open panel shows, since each new UI tool call opens a
+new view.
+
 Host sizing rule: the MCP resource shell owns a bounded inline height and the
 embedded route should scroll internally. `embedApp({ height })` defaults to a
 `560px` shell, clamps to `320-900px`, and subtracts `44px` for the wrapper bar

package/docs/content/security.mdx

@@ -322,7 +322,7 @@ pnpm action db-check-scoping --require-org  # Also require org_id
 | OAuth tokens (Google, GitHub)      | `oauth_tokens` store via `saveOAuthTokens()`               |
 | Session tokens                     | Automatic (Better Auth handles this)                       |
 
-Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM. The Dispatch vault keeps no plaintext copy: `vault_secrets` holds names and metadata, and each value lives only in `app_secrets`. For a per-user/per-org credential, the key precedence is `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (app-scoped — useful in a multi-app workspace where apps shouldn't share one key) → `SECRETS_ENCRYPTION_KEY` → `BETTER_AUTH_SECRET`; production refuses to start without one of these set. The shared workspace vault (`app_secrets`, meant to decrypt the same in sibling apps) prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy combined `SECRETS_ENCRYPTION_KEY`, then material derived from `A2A_SECRET`, with `BETTER_AUTH_SECRET` and the app-scoped key retained as compatibility candidates. Successful fallback reads compare-and-swap re-encrypt the shared column under the preferred key. During a workspace-key rotation, set `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` to the old value until reads have migrated existing rows. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
+Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM. The Dispatch vault keeps no plaintext copy: each key's name, label, and encrypted value live together in its `app_secrets` row, and the vault's own tables hold only grants, requests, and the audit log. For a per-user/per-org credential, the key precedence is `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (app-scoped — useful in a multi-app workspace where apps shouldn't share one key) → `SECRETS_ENCRYPTION_KEY` → `BETTER_AUTH_SECRET`; production refuses to start without one of these set. The shared workspace vault (`app_secrets`, meant to decrypt the same in sibling apps) prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy combined `SECRETS_ENCRYPTION_KEY`, then material derived from `A2A_SECRET`, with `BETTER_AUTH_SECRET` and the app-scoped key retained as compatibility candidates. Successful fallback reads compare-and-swap re-encrypt the shared column under the preferred key. During a workspace-key rotation, set `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` to the old value until reads have migrated existing rows. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
 
 Never store secrets in `settings`, `application_state`, source code, or action responses. Use the credential / vault APIs above — they handle both encryption and per-user scoping.
 

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

@@ -17,7 +17,7 @@ This page is for engineers extending Dispatch or customizing the template: how t
   filename="packages/dispatch/src/server/lib/vault-store.ts"
   language="ts"
   code={
-    'export async function approveRequest(\n  requestId: string,\n  secretValue: string,\n  secretName?: string,\n  ctx: VaultCtx = requireVaultCtx(),\n) {\n  await assertCanManageVault();\n  const db = getDb();\n  const request = await getRequestForTenant(requestId, ctx);\n  if (!request) throw new Error("Request not found");\n\n  const timestamp = now();\n  const reviewer = ctx.ownerEmail;\n  const staleApplyingBefore = timestamp - 5 * 60 * 1000;\n\n  // Fence the transition on the current status — scoped to caller\'s tenant —\n  // so a concurrent approve can\'t both win: only the caller that flips\n  // pending -> applying proceeds to create the secret/grant. A crashed worker\n  // leaves an applying row behind, so a later reviewer may reclaim a lease\n  // that has been idle for five minutes. See\n  // claimAgentTeamRun in packages/core/src/server/agent-teams-run-queue.ts\n  // for the same pattern.\n  const claimed = await db\n    .update(schema.vaultRequests)\n    .set({\n      status: "applying",\n      updatedAt: timestamp,\n    })\n    .where(\n      and(\n        eq(schema.vaultRequests.id, requestId),\n        tenantScope(schema.vaultRequests, ctx),\n        or(\n          eq(schema.vaultRequests.status, "pending"),\n          and(\n            eq(schema.vaultRequests.status, "applying"),\n            sql`${schema.vaultRequests.updatedAt} < ${staleApplyingBefore}`,\n          ),\n        ),\n      ),\n    )\n    .returning();\n\n  if (claimed.length === 0) {\n    const current = await getRequestForTenant(requestId, ctx);\n    if (current?.status === "applying") {\n      throw new Error("Vault request is already being applied");\n    }\n    return current;\n  }\n\n  const claimedRequest = claimed[0];\n\n  // Secret + grant must land in the REQUEST\'s tenant, not the approver\'s\n  // (the approver may be acting on behalf of another user in the same org).\n  const requestCtx = ctxForRow(claimedRequest);\n\n  try {\n    // Check if secret already exists in the request\'s tenant for this key.\n    const existingSecrets = await db\n      .select()\n      .from(schema.vaultSecrets)\n      .where(\n        and(\n          eq(schema.vaultSecrets.credentialKey, claimedRequest.credentialKey),\n          ctxScope(schema.vaultSecrets, requestCtx),\n        ),\n      );\n    let secret = existingSecrets[0] ?? null;\n\n    if (!secret) {\n      secret = await createSecret(\n        {\n          credentialKey: claimedRequest.credentialKey,\n          value: secretValue,\n          name: secretName || claimedRequest.credentialKey,\n        },\n        requestCtx,\n      );\n    }\n\n    if (secret) {\n      // Create the grant in the request\'s tenant as well.\n      await createGrant(secret.id, claimedRequest.appId, requestCtx);\n    }\n  } catch (error) {\n    await db\n      .update(schema.vaultRequests)\n      .set({ status: "pending", updatedAt: now() })\n      .where(\n        and(\n          eq(schema.vaultRequests.id, requestId),\n          tenantScope(schema.vaultRequests, ctx),\n          eq(schema.vaultRequests.status, "applying"),\n        ),\n      );\n    throw error;\n  }\n\n  await db\n    .update(schema.vaultRequests)\n    .set({\n      status: "approved",\n      reviewedBy: reviewer,\n      reviewedAt: timestamp,\n      updatedAt: now(),\n    })\n    .where(\n      and(\n        eq(schema.vaultRequests.id, requestId),\n        tenantScope(schema.vaultRequests, ctx),\n        eq(schema.vaultRequests.status, "applying"),\n      ),\n    );\n\n  await recordVaultAudit({\n    action: "request.approved",\n    appId: claimedRequest.appId,\n    summary: `Approved ${claimedRequest.credentialKey} for ${claimedRequest.appId} (requested by ${claimedRequest.requestedBy})`,\n    metadata: { requestId, reviewer },\n  });\n\n  return getRequestForTenant(requestId, ctx);\n}'
+    'export async function approveRequest(\n  requestId: string,\n  secretValue: string,\n  secretName?: string,\n  ctx: VaultCtx = requireVaultCtx(),\n) {\n  await assertCanManageVault();\n  const db = getDb();\n  const request = await getRequestForTenant(requestId, ctx);\n  if (!request) throw new Error("Request not found");\n\n  const timestamp = now();\n  const reviewer = ctx.ownerEmail;\n  const staleApplyingBefore = timestamp - 5 * 60 * 1000;\n\n  // Fence the transition on the current status — scoped to caller\'s tenant —\n  // so a concurrent approve can\'t both win: only the caller that flips\n  // pending -> applying proceeds to create the secret/grant. A crashed worker\n  // leaves an applying row behind, so a later reviewer may reclaim a lease\n  // that has been idle for five minutes. See\n  // claimAgentTeamRun in packages/core/src/server/agent-teams-run-queue.ts\n  // for the same pattern.\n  const claimed = await db\n    .update(schema.vaultRequests)\n    .set({\n      status: "applying",\n      updatedAt: timestamp,\n    })\n    .where(\n      and(\n        eq(schema.vaultRequests.id, requestId),\n        tenantScope(schema.vaultRequests, ctx),\n        or(\n          eq(schema.vaultRequests.status, "pending"),\n          and(\n            eq(schema.vaultRequests.status, "applying"),\n            sql`${schema.vaultRequests.updatedAt} < ${staleApplyingBefore}`,\n          ),\n        ),\n      ),\n    )\n    .returning();\n\n  const claimedRequest = claimed.at(0);\n  if (!claimedRequest) {\n    const current = await getRequestForTenant(requestId, ctx);\n    if (current?.status === "applying") {\n      throw new Error("Vault request is already being applied");\n    }\n    return current;\n  }\n\n  // Secret + grant must land in the REQUEST\'s tenant, not the approver\'s\n  // (the approver may be acting on behalf of another user in the same org).\n  const requestCtx = ctxForRow(claimedRequest);\n\n  try {\n    // A key that already exists in the scope is only granted: the approver\'s\n    // value never overwrites a row, whether the Vault or an app wrote it.\n    let secretId = (await listScopeSecrets(requestCtx)).find(\n      (row) => row.credentialKey === claimedRequest.credentialKey,\n    )?.id;\n\n    if (!secretId) {\n      secretId = (\n        await createSecret(\n          {\n            credentialKey: claimedRequest.credentialKey,\n            value: secretValue,\n            name: secretName || claimedRequest.credentialKey,\n          },\n          requestCtx,\n        )\n      ).id;\n    }\n\n    await createGrant(secretId, claimedRequest.appId, requestCtx);\n  } catch (error) {\n    await db\n      .update(schema.vaultRequests)\n      .set({ status: "pending", updatedAt: now() })\n      .where(\n        and(\n          eq(schema.vaultRequests.id, requestId),\n          tenantScope(schema.vaultRequests, ctx),\n          eq(schema.vaultRequests.status, "applying"),\n        ),\n      );\n    throw error;\n  }\n\n  await db\n    .update(schema.vaultRequests)\n    .set({\n      status: "approved",\n      reviewedBy: reviewer,\n      reviewedAt: timestamp,\n      updatedAt: now(),\n    })\n    .where(\n      and(\n        eq(schema.vaultRequests.id, requestId),\n        tenantScope(schema.vaultRequests, ctx),\n        eq(schema.vaultRequests.status, "applying"),\n      ),\n    );\n\n  await recordVaultAudit({\n    action: "request.approved",\n    credentialKey: claimedRequest.credentialKey,\n    appId: claimedRequest.appId,\n    summary: `Approved ${claimedRequest.credentialKey} for ${claimedRequest.appId} (requested by ${claimedRequest.requestedBy})`,\n    metadata: { requestId, reviewer },\n  });\n\n  return getRequestForTenant(requestId, ctx);\n}'
   }
   annotations={[
     {
@@ -26,22 +26,22 @@ This page is for engineers extending Dispatch or customizing the template: how t
       note: "The claim only succeeds if the row is still pending, or stuck applying for over five minutes. Two simultaneous approvals can't both win: only one caller's update actually matches a row and returns it.",
     },
     {
-      lines: "44-50",
+      lines: "44-51",
       label: "Losing the race isn't an error",
       note: "If the claim matched nothing, the request is either already mid-flight elsewhere (throw) or was already resolved by the time this call ran (just return its current state).",
     },
     {
-      lines: "59-69",
-      label: "Reuse an existing secret instead of duplicating one",
-      note: "A second request for the same credential key finds the secret already created by an earlier approval and grants access to it, rather than creating a duplicate.",
+      lines: "58-77",
+      label: "Grant an existing key instead of overwriting it",
+      note: "A key that already exists in the scope is only granted, so a second request for the same credential key reuses it and the approver's value never replaces a row, whether the Vault or an app wrote it.",
     },
     {
-      lines: "86-98",
+      lines: "78-90",
       label: "Roll back the lock on failure",
       note: "If creating the secret or grant throws, the request goes back to pending instead of staying stuck in applying, which is what makes the five-minute stale-lease reclaim above necessary in the first place.",
     },
     {
-      lines: "100-114",
+      lines: "92-106",
       label: "Finalize only from the lock this call holds",
       note: "The final flip to approved is still scoped to status = applying, so it can only apply the transition this specific call claimed.",
     },

package/docs/content/template-dispatch-reference.mdx

@@ -136,21 +136,26 @@ Dispatch ships close to a hundred actions. Most of the UI-facing ones are alread
   id="doc-block-dispatch11"
   title="Secrets vault schema"
   summary={
-    "A secret is stored once. A grant gives a named app access. A request plus review gates sensitive access before a grant exists. The audit log records who used which secret, when. Defined in @agent-native/dispatch (packages/dispatch/src/db/schema.ts)."
+    "A key is stored once, encrypted, as a row of the credential store (app_secrets, owned by @agent-native/core). A grant gives a named app access to it by key name. A request plus review gates sensitive access before a grant exists. The audit log records who changed which key, when. The grant, request, and audit tables are defined in @agent-native/dispatch (packages/dispatch/src/db/schema.ts)."
   }
   entities={[
     {
       id: "secrets",
-      name: "vault_secrets",
-      note: "Stored credential values",
+      name: "app_secrets",
+      note: "Stored credentials, encrypted",
       fields: [
         { name: "id", type: "text", pk: true },
-        { name: "owner_email", type: "text" },
-        { name: "org_id", type: "text", nullable: true },
-        { name: "name", type: "text" },
-        { name: "credential_key", type: "text" },
-        { name: "value", type: "text", note: "secret value" },
+        {
+          name: "scope",
+          type: "text",
+          note: "org, or workspace for a solo vault",
+        },
+        { name: "scope_id", type: "text" },
+        { name: "key", type: "text", note: "credential key" },
+        { name: "encrypted_value", type: "text", note: "ciphertext only" },
+        { name: "label", type: "text", nullable: true },
         { name: "provider", type: "text", nullable: true },
+        { name: "created_by", type: "text", nullable: true },
       ],
     },
     {
@@ -159,7 +164,8 @@ Dispatch ships close to a hundred actions. Most of the UI-facing ones are alread
       note: "Per-app access grant",
       fields: [
         { name: "id", type: "text", pk: true },
-        { name: "secret_id", type: "text", fk: "vault_secrets.id" },
+        { name: "secret_id", type: "text", fk: "app_secrets.id" },
+        { name: "credential_key", type: "text", nullable: true },
         { name: "app_id", type: "text" },
         { name: "granted_by", type: "text" },
         { name: "status", type: "text" },
@@ -187,7 +193,7 @@ Dispatch ships close to a hundred actions. Most of the UI-facing ones are alread
         {
           name: "secret_id",
           type: "text",
-          fk: "vault_secrets.id",
+          fk: "app_secrets.id",
           nullable: true,
         },
         { name: "app_id", type: "text", nullable: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.228.2-nightly-20261113152307",
+  "version": "0.228.2",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -771,8 +771,8 @@
     "yaml": "^2.9.0",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/agentkit": "^0.228.2-nightly-20261113152307",
-    "@agent-native/recap-cli": "^0.5.102"
+    "@agent-native/agentkit": "^0.228.2",
+    "@agent-native/recap-cli": "^0.5.103"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",
@@ -845,7 +845,7 @@
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@agent-native/core-corpus": "0.228.2-nightly-20261113152307",
+    "@agent-native/core-corpus": ">=0.196.0",
     "@ai-sdk/anthropic": ">=3",
     "@ai-sdk/cohere": ">=3",
     "@ai-sdk/google": ">=3",

package/src/templates/workspace-core/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -120,6 +120,17 @@ resource CSP should include the exact origins of apps granted through Dispatch,
 not broad sources like `https:`. This lets Claude's transplant path fetch the
 signed target app HTML while keeping the connector's resource surface narrow.
 
+Side panel and app tools: every `embedApp()` resource sets
+`_meta.ui.preferredDisplayMode: "fullscreen"`, so Claude opens the app in its
+side panel beside the chat (other hosts ignore the field). The shell declares
+`availableDisplayModes` and `tools` in `ui/initialize` and answers the host's
+`tools/list` / `tools/call` on the open view: `read_view` returns the page's
+path, title, selection and visible text, `navigate_view` moves the open app to
+another same-origin path in place, and any page tools the app registered through
+WebMCP are passed through. Prefer these over a new `open_app` call when the user
+asks to change what the open panel shows, since each new UI tool call opens a
+new view.
+
 Host sizing rule: the MCP resource shell owns a bounded inline height and the
 embedded route should scroll internally. `embedApp({ height })` defaults to a
 `560px` shell, clamps to `320-900px`, and subtracts `44px` for the wrapper bar