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

package/dist/secrets/storage.d.ts

@@ -18,9 +18,10 @@
  * Secret values are NEVER logged and NEVER returned from any route handler.
  */
 import type { SecretScope } from "./register.js";
+import { VAULT_SYNC_DESCRIPTION_PREFIX } from "./vault-managed.js";
+export { VAULT_SYNC_DESCRIPTION_PREFIX };
 export declare const appSecretsStore: import("../db/store-registry.js").Store;
 export declare function ensureTable(): Promise<void>;
-export declare const VAULT_SYNC_DESCRIPTION_PREFIX = "Synced from Dispatch vault:";
 export declare function last4(value: string): string;
 export interface SecretRef {
     key: string;
@@ -31,6 +32,19 @@ export interface WriteSecretArgs extends SecretRef {
     value: string;
     description?: string;
     urlAllowlist?: string;
+    /** Display name. A write that omits it keeps the stored one. */
+    label?: string | null;
+    /** Provider tag. A write that omits it keeps the stored one. */
+    provider?: string | null;
+    /**
+     * Who created the key through the Dispatch Vault, which marks the row as
+     * Vault-managed. The first creator is kept: later writes never replace it.
+     */
+    createdBy?: string | null;
+}
+export declare class AppSecretKeyConflictError extends Error {
+    readonly statusCode = 409;
+    constructor(key: string);
 }
 export declare class AppSecretKeyMismatchError extends Error {
     constructor(ref: SecretRef);
@@ -75,12 +89,29 @@ export declare function getAppSecretMeta(ref: SecretRef): Promise<{
     updatedAt: number;
 } | null>;
 export interface SecretMeta {
+    id: string;
     key: string;
     scope: SecretScope;
     scopeId: string;
     last4: string;
     description: string | null;
     urlAllowlist: string[] | null;
+    label: string | null;
+    provider: string | null;
+    createdBy: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** A stored key's metadata with nothing derived from its value. */
+export interface AppSecretSummary {
+    id: string;
+    key: string;
+    scope: SecretScope;
+    scopeId: string;
+    description: string | null;
+    label: string | null;
+    provider: string | null;
+    createdBy: string | null;
     createdAt: number;
     updatedAt: number;
 }
@@ -97,6 +128,57 @@ export declare function readAppSecretMeta(ref: SecretRef): Promise<SecretMeta |
  * user-created keys.
  */
 export declare function listAppSecretsForScope(scope: SecretScope, scopeId: string): Promise<SecretMeta[]>;
+/** The key's metadata by stored id, within one scope. Null when that scope holds no such row. */
+export declare function readAppSecretMetaById(target: {
+    id: string;
+    scope: SecretScope;
+    scopeId: string;
+}): Promise<SecretMeta | null>;
+/**
+ * Every key in one scope with nothing derived from its value, so no
+ * decryption: the cheap read for pickers, counts and lookups. Use
+ * `listAppSecretsForScope` when the masked preview is needed.
+ */
+export declare function listAppSecretSummaries(scope: SecretScope, scopeId: string): Promise<AppSecretSummary[]>;
+export interface UpdateAppSecretPatch {
+    /** Rename the key; the row keeps its id, value and creator. */
+    key?: string;
+    /** Replace the value. Omit to leave the stored ciphertext untouched. */
+    value?: string;
+    label?: string | null;
+    provider?: string | null;
+    description?: string | null;
+    /**
+     * The Dispatch Vault is writing this row, so it is Vault-managed from now
+     * on. Recorded as the creator only when the row has none.
+     */
+    adoptedBy?: string;
+}
+/**
+ * Edit one stored key by its id within a scope, in one statement: rename,
+ * replace the value, and change the display fields together or alone. A field
+ * the patch leaves out keeps its stored value; `null` clears `label`,
+ * `provider` and `description`. Returns the key now stored and the one it
+ * replaced, or null when that scope holds no row with this id.
+ */
+export declare function updateAppSecretById(target: {
+    id: string;
+    scope: SecretScope;
+    scopeId: string;
+}, patch: UpdateAppSecretPatch): Promise<{
+    key: string;
+    previousKey: string;
+} | null>;
+/**
+ * Delete one row by its id within a scope. Unlike `deleteAppSecret` this cannot
+ * remove a different row that took over the key name after a rename. Returns
+ * whether a row was removed.
+ */
+export declare function deleteAppSecretById(target: {
+    id: string;
+    scope: SecretScope;
+    scopeId: string;
+}): Promise<boolean>;
 export declare function deleteAppSecret(ref: SecretRef): Promise<boolean>;
 /**
  * Delete only if the stored ciphertext is still the version the caller read.

package/dist/secrets/storage.js

@@ -29,6 +29,8 @@ import { encryptSecretValue as encryptLegacyValue, encryptSharedSecretValue as e
 import { AppSecretDecryptionError } from "./errors.js";
 import { invalidateOptionalKeyCache } from "./optional-key-cache.js";
 import { APP_SECRETS_CREATE_SQL } from "./schema.js";
+import { VAULT_SYNC_DESCRIPTION_PREFIX } from "./vault-managed.js";
+export { VAULT_SYNC_DESCRIPTION_PREFIX };
 export const appSecretsStore = defineStore({
     id: "app_secrets",
     migrations: [
@@ -42,12 +44,19 @@ export const appSecretsStore = defineStore({
                 await ensureColumnExists("app_secrets", "shared_encrypted_value", `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS shared_encrypted_value TEXT`);
             },
         },
+        {
+            name: "vault-metadata-columns",
+            run: async () => {
+                await ensureColumnExists("app_secrets", "label", `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS label TEXT`);
+                await ensureColumnExists("app_secrets", "provider", `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS provider TEXT`);
+                await ensureColumnExists("app_secrets", "created_by", `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS created_by TEXT`);
+            },
+        },
     ],
 });
 export function ensureTable() {
     return appSecretsStore.ready();
 }
-export const VAULT_SYNC_DESCRIPTION_PREFIX = "Synced from Dispatch vault:";
 export function last4(value) {
     if (!value)
         return "";
@@ -55,6 +64,13 @@ export function last4(value) {
         return "••••";
     return "••••" + value.slice(-4);
 }
+export class AppSecretKeyConflictError extends Error {
+    statusCode = 409;
+    constructor(key) {
+        super(`Credential key "${key}" is already in use`);
+        this.name = "AppSecretKeyConflictError";
+    }
+}
 export class AppSecretKeyMismatchError extends Error {
     constructor(ref) {
         super(`Refusing to write secret "${ref.key}" (${ref.scope} scope): this development process is connected to a shared database, and the secrets stored there use encryption key material it does not prefer. Set WORKSPACE_SECRETS_ENCRYPTION_KEY to match the deployments that use this database, or point DATABASE_URL at a local database.`);
@@ -102,7 +118,7 @@ async function assertWriteKeepsSecretsReadable(ref) {
  */
 export async function writeAppSecret(args) {
     await ensureTable();
-    const { key, value, scope, scopeId, description, urlAllowlist } = args;
+    const { key, value, scope, scopeId, description, urlAllowlist, label, provider, createdBy, } = args;
     if (!key || !value || !scope || !scopeId) {
         throw new Error("writeAppSecret: key, value, scope, and scopeId are all required");
     }
@@ -138,13 +154,20 @@ export async function writeAppSecret(args) {
     // `populateSharedAppSecret`, which fills a NULL column or compare-and-swap
     // replaces the exact legacy ciphertext it just decrypted. A temporary miss
     // is safer than serving rotated-away plaintext.
-    const upsertSql = `INSERT INTO app_secrets (id, scope, scope_id, key, encrypted_value, shared_encrypted_value, description, url_allowlist, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    //
+    // label, provider and created_by follow the opposite rule: a write that does
+    // not pass them (every writer but the Dispatch Vault) leaves the stored
+    // values alone, and the first creator is never replaced.
+    const upsertSql = `INSERT INTO app_secrets (id, scope, scope_id, key, encrypted_value, shared_encrypted_value, description, url_allowlist, label, provider, created_by, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT (scope, scope_id, key) DO UPDATE SET
       encrypted_value = excluded.encrypted_value,
       shared_encrypted_value = excluded.shared_encrypted_value,
       description = excluded.description,
       url_allowlist = COALESCE(excluded.url_allowlist, app_secrets.url_allowlist),
+      label = COALESCE(excluded.label, app_secrets.label),
+      provider = COALESCE(excluded.provider, app_secrets.provider),
+      created_by = COALESCE(app_secrets.created_by, excluded.created_by),
       updated_at = excluded.updated_at`;
     const upsertArgs = [
         id,
@@ -155,6 +178,9 @@ export async function writeAppSecret(args) {
         sharedEncrypted,
         description ?? null,
         urlAllowlist ?? null,
+        label ?? null,
+        provider ?? null,
+        createdBy ?? null,
         now,
         now,
     ];
@@ -173,6 +199,7 @@ export async function updateAppSecretUrlAllowlist(ref, origins) {
     const { rows } = await getDbExec().execute({
         sql: `UPDATE app_secrets SET url_allowlist = ?, updated_at = ?
       WHERE scope = ? AND scope_id = ? AND key = ?
+        AND created_by IS NULL
         AND (description IS NULL OR description NOT LIKE ?)
       RETURNING id`,
         args: [
@@ -494,7 +521,7 @@ export async function readAppSecretMeta(ref) {
     const { key, scope, scopeId } = ref;
     const client = getDbExec();
     const { rows } = await client.execute({
-        sql: `SELECT id, encrypted_value, shared_encrypted_value, description, url_allowlist, created_at, updated_at FROM app_secrets WHERE scope = ? AND scope_id = ? AND key = ? LIMIT 1`,
+        sql: `SELECT id, encrypted_value, shared_encrypted_value, description, url_allowlist, label, provider, created_by, created_at, updated_at FROM app_secrets WHERE scope = ? AND scope_id = ? AND key = ? LIMIT 1`,
         args: [scope, scopeId, key],
     });
     if (rows.length === 0)
@@ -513,12 +540,16 @@ export async function readAppSecretMeta(ref) {
         last4Value = "";
     }
     return {
+        id: String(row.id),
         key,
         scope,
         scopeId,
         last4: last4Value,
         description: row.description ?? null,
         urlAllowlist: parseAllowlist(row.url_allowlist),
+        label: row.label ?? null,
+        provider: row.provider ?? null,
+        createdBy: row.created_by ?? null,
         createdAt: Number(row.created_at ?? 0),
         updatedAt: Number(row.updated_at ?? 0),
     };
@@ -532,7 +563,7 @@ export async function listAppSecretsForScope(scope, scopeId) {
     await ensureTable();
     const client = getDbExec();
     const { rows } = await client.execute({
-        sql: `SELECT id, key, encrypted_value, shared_encrypted_value, description, url_allowlist, created_at, updated_at FROM app_secrets WHERE scope = ? AND scope_id = ? ORDER BY updated_at DESC`,
+        sql: `SELECT id, key, encrypted_value, shared_encrypted_value, description, url_allowlist, label, provider, created_by, created_at, updated_at FROM app_secrets WHERE scope = ? AND scope_id = ? ORDER BY updated_at DESC`,
         args: [scope, scopeId],
     });
     const results = [];
@@ -550,18 +581,175 @@ export async function listAppSecretsForScope(scope, scopeId) {
             last4Value = "";
         }
         results.push({
+            id: String(row.id),
             key: row.key,
             scope,
             scopeId,
             last4: last4Value,
             description: row.description ?? null,
             urlAllowlist: parseAllowlist(row.url_allowlist),
+            label: row.label ?? null,
+            provider: row.provider ?? null,
+            createdBy: row.created_by ?? null,
             createdAt: Number(row.created_at ?? 0),
             updatedAt: Number(row.updated_at ?? 0),
         });
     }
     return results;
 }
+/** The key's metadata by stored id, within one scope. Null when that scope holds no such row. */
+export async function readAppSecretMetaById(target) {
+    await ensureTable();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT key FROM app_secrets WHERE id = ? AND scope = ? AND scope_id = ? LIMIT 1`,
+        args: [target.id, target.scope, target.scopeId],
+    });
+    if (rows.length === 0)
+        return null;
+    return readAppSecretMeta({
+        key: String(rows[0].key),
+        scope: target.scope,
+        scopeId: target.scopeId,
+    });
+}
+/**
+ * Every key in one scope with nothing derived from its value, so no
+ * decryption: the cheap read for pickers, counts and lookups. Use
+ * `listAppSecretsForScope` when the masked preview is needed.
+ */
+export async function listAppSecretSummaries(scope, scopeId) {
+    await ensureTable();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT id, key, description, label, provider, created_by, created_at, updated_at FROM app_secrets WHERE scope = ? AND scope_id = ? ORDER BY updated_at DESC`,
+        args: [scope, scopeId],
+    });
+    return rows.map((row) => ({
+        id: String(row.id),
+        key: String(row.key),
+        scope,
+        scopeId,
+        description: row.description ?? null,
+        label: row.label ?? null,
+        provider: row.provider ?? null,
+        createdBy: row.created_by ?? null,
+        createdAt: Number(row.created_at ?? 0),
+        updatedAt: Number(row.updated_at ?? 0),
+    }));
+}
+/**
+ * Edit one stored key by its id within a scope, in one statement: rename,
+ * replace the value, and change the display fields together or alone. A field
+ * the patch leaves out keeps its stored value; `null` clears `label`,
+ * `provider` and `description`. Returns the key now stored and the one it
+ * replaced, or null when that scope holds no row with this id.
+ */
+export async function updateAppSecretById(target, patch) {
+    await ensureTable();
+    const client = getDbExec();
+    const { rows } = await client.execute({
+        sql: `SELECT key FROM app_secrets WHERE id = ? AND scope = ? AND scope_id = ? LIMIT 1`,
+        args: [target.id, target.scope, target.scopeId],
+    });
+    if (rows.length === 0)
+        return null;
+    const previousKey = String(rows[0].key);
+    const key = patch.key ?? previousKey;
+    if (!key)
+        throw new Error("updateAppSecretById: key cannot be empty");
+    if (patch.value !== undefined && !patch.value) {
+        throw new Error("updateAppSecretById: value cannot be empty");
+    }
+    if (key !== previousKey) {
+        const { rows: clash } = await client.execute({
+            sql: `SELECT 1 FROM app_secrets WHERE scope = ? AND scope_id = ? AND key = ? LIMIT 1`,
+            args: [target.scope, target.scopeId, key],
+        });
+        if (clash.length > 0)
+            throw new AppSecretKeyConflictError(key);
+    }
+    let encrypted = null;
+    let sharedEncrypted = null;
+    if (patch.value !== undefined) {
+        await assertWriteKeepsSecretsReadable({
+            key,
+            scope: target.scope,
+            scopeId: target.scopeId,
+        });
+        encrypted = encryptLegacyValue(patch.value);
+        sharedEncrypted = hasSharedSecretEncryptionKeyMaterial()
+            ? encryptValue(patch.value)
+            : null;
+    }
+    // Each CASE flag says whether the patch carries that field: a field left out
+    // keeps its stored value, and an explicit null clears it.
+    const { rows: updated } = await client.execute({
+        sql: `UPDATE app_secrets SET
+        key = CASE WHEN ? THEN ? ELSE key END,
+        encrypted_value = CASE WHEN ? THEN ? ELSE encrypted_value END,
+        shared_encrypted_value = CASE WHEN ? THEN ? ELSE shared_encrypted_value END,
+        label = CASE WHEN ? THEN ? ELSE label END,
+        provider = CASE WHEN ? THEN ? ELSE provider END,
+        description = CASE WHEN ? THEN ? ELSE description END,
+        created_by = COALESCE(created_by, ?),
+        updated_at = ?
+      WHERE id = ? AND scope = ? AND scope_id = ?
+      RETURNING id`,
+        args: [
+            patch.key !== undefined,
+            patch.key ?? null,
+            patch.value !== undefined,
+            encrypted,
+            patch.value !== undefined,
+            sharedEncrypted,
+            patch.label !== undefined,
+            patch.label ?? null,
+            patch.provider !== undefined,
+            patch.provider ?? null,
+            patch.description !== undefined,
+            patch.description ?? null,
+            patch.adoptedBy ?? null,
+            Date.now(),
+            target.id,
+            target.scope,
+            target.scopeId,
+        ],
+    });
+    if (updated.length === 0)
+        return null;
+    for (const staleKey of new Set([previousKey, key])) {
+        invalidateRequestSecret({
+            key: staleKey,
+            scope: target.scope,
+            scopeId: target.scopeId,
+        });
+    }
+    invalidateOptionalKeyCache();
+    invalidateAgentEngineStatusCache();
+    return { key, previousKey };
+}
+/**
+ * Delete one row by its id within a scope. Unlike `deleteAppSecret` this cannot
+ * remove a different row that took over the key name after a rename. Returns
+ * whether a row was removed.
+ */
+export async function deleteAppSecretById(target) {
+    await ensureTable();
+    const client = getDbExec();
+    const { rows } = await client.execute({
+        sql: `DELETE FROM app_secrets WHERE id = ? AND scope = ? AND scope_id = ? RETURNING key`,
+        args: [target.id, target.scope, target.scopeId],
+    });
+    if (rows.length === 0)
+        return false;
+    invalidateRequestSecret({
+        key: String(rows[0].key),
+        scope: target.scope,
+        scopeId: target.scopeId,
+    });
+    invalidateOptionalKeyCache();
+    invalidateAgentEngineStatusCache();
+    return true;
+}
 function parseAllowlist(raw) {
     if (raw === null)
         return null;

package/dist/secrets/usage.js

@@ -10,7 +10,7 @@ import { AGENT_PROVIDER_CATALOG, providerIdForEngine, } from "../client/agent-pr
 import { getRequestOrgId } from "../server/request-context.js";
 import { managedSecretUsage, resolveSecretManagedBy } from "./managed-keys.js";
 import { getRegisteredSecretUsage, getRequiredSecret, } from "./register.js";
-import { VAULT_SYNC_DESCRIPTION_PREFIX } from "./storage.js";
+import { isVaultManagedSecret } from "./vault-managed.js";
 /** App id used in effects that apply to every app. */
 export const ALL_APPS = "all";
 function providerForKey(key) {
@@ -73,9 +73,7 @@ async function resolveSharedFallback(key) {
         : null;
     return {
         status: "shared",
-        source: meta?.description?.startsWith(VAULT_SYNC_DESCRIPTION_PREFIX)
-            ? "vault"
-            : shared.source,
+        source: isVaultManagedSecret(meta) ? "vault" : shared.source,
     };
 }
 function engineDisplayLabel(entry) {

package/dist/secrets/vault-managed.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Marker on `app_secrets.description` that releases before the Vault moved
+ * onto `app_secrets` wrote on every Vault-owned row. New Vault writes mark a
+ * row with `created_by` instead: such a release deletes marked rows that its
+ * own Vault table has no entry for, and it must never find a new key that way.
+ */
+export declare const VAULT_SYNC_DESCRIPTION_PREFIX = "Synced from Dispatch vault:";
+/**
+ * True for a key the Dispatch Vault owns: created or edited through the Vault
+ * (`created_by` is set), or written by a release that marked it in the
+ * description. Rows an app registered for itself, and a person's own keys, are
+ * neither. Callers rule out `user` scope themselves.
+ */
+export declare function isVaultManagedSecret(meta: {
+    description?: string | null | undefined;
+    createdBy?: string | null | undefined;
+} | null | undefined): boolean;

package/dist/secrets/vault-managed.js

@@ -0,0 +1,19 @@
+/**
+ * Marker on `app_secrets.description` that releases before the Vault moved
+ * onto `app_secrets` wrote on every Vault-owned row. New Vault writes mark a
+ * row with `created_by` instead: such a release deletes marked rows that its
+ * own Vault table has no entry for, and it must never find a new key that way.
+ */
+export const VAULT_SYNC_DESCRIPTION_PREFIX = "Synced from Dispatch vault:";
+/**
+ * True for a key the Dispatch Vault owns: created or edited through the Vault
+ * (`created_by` is set), or written by a release that marked it in the
+ * description. Rows an app registered for itself, and a person's own keys, are
+ * neither. Callers rule out `user` scope themselves.
+ */
+export function isVaultManagedSecret(meta) {
+    if (!meta)
+        return false;
+    return (!!meta.createdBy ||
+        !!meta.description?.startsWith(VAULT_SYNC_DESCRIPTION_PREFIX));
+}

package/dist/server/agent-engine-api-key-route.d.ts

@@ -54,9 +54,9 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
     error: string;
 }>;
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    errorCode?: undefined;
     code?: undefined;
     error: string;
+    errorCode?: undefined;
 } | {
     code?: undefined;
     error: string;
@@ -66,9 +66,9 @@ export declare function createAgentEngineApiKeyHandler(): import("h3").EventHand
     error: string;
     code: ProviderKeyCheckCode;
 } | {
-    errorCode?: undefined;
     error?: undefined;
     code?: undefined;
+    errorCode?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string | undefined;

package/dist/server/builder-signup-experiment.d.ts

@@ -66,9 +66,10 @@ export declare function createBuilderSignupExperiment(dependencies: {
         status: "unavailable";
         code: string;
     } | {
-        status: "disabled";
         code?: undefined;
+        status: "disabled";
     } | {
+        code?: undefined;
         id: string;
         variant: "automatic" | "control";
         issuedAt: number;
@@ -79,7 +80,6 @@ export declare function createBuilderSignupExperiment(dependencies: {
         policy: "builder-signup-2026-11-06";
         status: "assigned";
         experimentId: string;
-        code?: undefined;
     } | {
         status: "disabled";
         code: string;
@@ -106,9 +106,10 @@ export declare function createBuilderSignupExperiment(dependencies: {
         status: "unavailable";
         code: string;
     } | {
-        status: "disabled";
         code?: undefined;
+        status: "disabled";
     } | {
+        code?: undefined;
         id: string;
         variant: "automatic" | "control";
         issuedAt: number;
@@ -119,7 +120,6 @@ export declare function createBuilderSignupExperiment(dependencies: {
         policy: "builder-signup-2026-11-06";
         status: "assigned";
         experimentId: string;
-        code?: undefined;
     } | {
         status: "disabled";
         code: string;

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.