@agent-native/core 0.149.6 → 0.151.0

package/dist/server/core-routes-plugin.js

@@ -11,7 +11,8 @@ import { mountDbAdminRoutes } from "../db-admin/routes.js";
 import { getDbExec, isProductionServerlessFunctionRuntime, } from "../db/client.js";
 import { getDatabaseRuntimeFingerprint, getRuntimeDebugFingerprint, runDatabaseSchemaHealthCheck, } from "../db/runtime-diagnostics.js";
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
-import { uploadFile, getActiveFileUploadProviderForRequest, listFileUploadProviders, } from "../file-upload/index.js";
+import { uploadFile, getActiveFileUploadProviderForRequest, listFileUploadProviders, registerFileUploadProvider, } from "../file-upload/index.js";
+import { s3FileUploadProvider } from "../file-upload/s3.js";
 import { handleMcpConnect } from "../mcp/connect-route.js";
 import { handleMcpOAuth, handleMcpOAuthAuthorizationServerMetadata, handleMcpOAuthProtectedResourceMetadata, } from "../mcp/oauth-route.js";
 import { MCP_ROUTE_PREFIXES } from "../mcp/route-paths.js";
@@ -51,7 +52,6 @@ import { createGatewayAccessCheckHandler } from "./gateway-access-check.js";
 import { getAppBasePath, getOrigin } from "./google-oauth.js";
 import { createGoogleRealtimeSessionHandler } from "./google-realtime-session.js";
 import { readBody, DEFAULT_UPLOAD_MAX_FILE_BYTES, isAllowedUploadMimeType, } from "./h3-helpers.js";
-import { isIdentitySsoEnabled } from "./identity-sso-store.js";
 import { handleIdentitySso } from "./identity-sso.js";
 import { createOpenRouteHandler } from "./open-route.js";
 import { createPollEventsHandler } from "./poll-events.js";
@@ -889,6 +889,12 @@ function wireRouteErrorCapture(nitroApp) {
         }
     });
 }
+export function ensureS3FileUploadProvider() {
+    if (listFileUploadProviders().some((provider) => provider.id === s3FileUploadProvider.id)) {
+        return;
+    }
+    registerFileUploadProvider(s3FileUploadProvider);
+}
 export function createCoreRoutesPlugin(options = {}) {
     return async (nitroApp) => {
         markDefaultPluginProvided(nitroApp, "core-routes");
@@ -905,6 +911,12 @@ export function createCoreRoutesPlugin(options = {}) {
         });
         try {
             const P = FRAMEWORK_ROUTE_PREFIX;
+            // Keep the framework-owned S3-compatible provider available even when an
+            // app does not mount the optional onboarding plugin. The settings CTA and
+            // the upload route share this registry. An app may register its own
+            // provider under the conventional `s3` id, so preserve that explicit
+            // registration instead of replacing it during core bootstrap.
+            ensureS3FileUploadProvider();
             // This response is a side-effect-free static contract used by the SSR
             // shell. Mount it before optional default-plugin/bootstrap work so a
             // browser's automatic rules fetch cannot inherit the cold-start wait.
@@ -3077,22 +3089,20 @@ export function createCoreRoutesPlugin(options = {}) {
                     }));
                 }
             }
-            // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. Mounted
-            // ONLY when `AGENT_NATIVE_IDENTITY_HUB_URL` is set, so an unset env var
-            // means the route is never even registered: zero new surface, existing
-            // auth byte-for-byte unchanged. `/login` 302s to the identity hub;
+            // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. `/login`
+            // 302s to the identity hub;
             // `/callback` verifies the hub-issued A2A-signed identity JWT and JIT-
             // links the verified email into this app's local Better Auth store. The
-            // handler 404s if disabled (defence in depth). The auth guard bypasses
-            // these two exact paths under the same env gate.
-            if (isIdentitySsoEnabled()) {
-                getH3App(nitroApp).use(`${P}/identity`, defineEventHandler(async (event) => {
-                    // Framework strips the mount prefix; what remains is the subpath
-                    // after `/identity` (e.g. `/login`, `/callback`).
-                    const subpath = event.url?.pathname || "";
-                    return handleIdentitySso(event, subpath);
-                }));
-            }
+            // handler fails closed unless direct web SSO is configured or the
+            // packaged Desktop SSO Canary requests a canonical Agent Native app.
+            // Mounting the handler unconditionally lets that request-scoped decision
+            // work.
+            getH3App(nitroApp).use(`${P}/identity`, defineEventHandler(async (event) => {
+                // Framework strips the mount prefix; what remains is the subpath
+                // after `/identity` (e.g. `/login`, `/callback`).
+                const subpath = event.url?.pathname || "";
+                return handleIdentitySso(event, subpath);
+            }));
             if (!options.disableOpenRoute) {
                 // Stable deep-link route. External agents (MCP/A2A) surface
                 // `/_agent-native/open?app=…&view=…&<recordId>=…` links; this resolves

package/dist/server/identity-sso-store.d.ts

@@ -35,6 +35,9 @@ export declare function getIdentityHubUrl(): string | undefined;
  * env-unset-no-op invariant is asserted against.
  */
 export declare function isIdentitySsoEnabled(): boolean;
+export declare function isDesktopSsoCanaryUserAgent(userAgent: string | undefined): boolean;
+export declare function isCanonicalAgentNativeAppOrigin(origin: string | undefined): boolean;
+export declare function isCanonicalAgentNativeAppRequest(host: string | undefined, forwardedProtocol: string | undefined): boolean;
 /**
  * The conditional "Sign in with Agent-Native" entry injected into the login
  * page — ONLY when the feature is enabled. Returns an empty string when

package/dist/server/identity-sso-store.js

@@ -25,6 +25,25 @@ import { randomBytes } from "node:crypto";
 import { getDbExec, isConnectionError, intType, isPostgres, } from "../db/client.js";
 import { ensureTableExists } from "../db/ddl-guard.js";
 let _initPromise;
+const DESKTOP_SSO_CANARY_USER_AGENT = /AgentNativeDesktopSsoCanary\//i;
+const CANONICAL_IDENTITY_SSO_APP_ORIGINS = new Set([
+    "https://analytics.agent-native.com",
+    "https://assets.agent-native.com",
+    "https://brain.agent-native.com",
+    "https://calendar.agent-native.com",
+    "https://chat.agent-native.com",
+    "https://clips.agent-native.com",
+    "https://content.agent-native.com",
+    "https://crm.agent-native.com",
+    "https://design.agent-native.com",
+    "https://dispatch.agent-native.com",
+    "https://forms.agent-native.com",
+    "https://macros.agent-native.com",
+    "https://mail.agent-native.com",
+    "https://plan.agent-native.com",
+    "https://slides.agent-native.com",
+    "https://tasks.agent-native.com",
+]);
 // ---------------------------------------------------------------------------
 // Feature switch — the SINGLE source of truth for whether the federated-SSO
 // client is active. Lives here (a leaf module with no dependency on auth.ts)
@@ -61,6 +80,32 @@ export function getIdentityHubUrl() {
 export function isIdentitySsoEnabled() {
     return !!getIdentityHubUrl();
 }
+export function isDesktopSsoCanaryUserAgent(userAgent) {
+    return DESKTOP_SSO_CANARY_USER_AGENT.test(userAgent ?? "");
+}
+export function isCanonicalAgentNativeAppOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const parsed = new URL(origin);
+        return (parsed.protocol === "https:" &&
+            !parsed.username &&
+            !parsed.password &&
+            parsed.pathname === "/" &&
+            !parsed.search &&
+            !parsed.hash &&
+            CANONICAL_IDENTITY_SSO_APP_ORIGINS.has(parsed.origin));
+    }
+    catch {
+        return false;
+    }
+}
+export function isCanonicalAgentNativeAppRequest(host, forwardedProtocol) {
+    if (!host || forwardedProtocol !== "https") {
+        return false;
+    }
+    return isCanonicalAgentNativeAppOrigin(`https://${host}`);
+}
 /**
  * The conditional "Sign in with Agent-Native" entry injected into the login
  * page — ONLY when the feature is enabled. Returns an empty string when

package/dist/server/identity-sso.d.ts

@@ -6,12 +6,15 @@
  * an identity authority (Dispatch) so a user logged in there can land in this
  * app without re-entering credentials.
  *
- * Opt-in, OFF by default, fully reversible. Everything here is gated on the
- * single env var `AGENT_NATIVE_IDENTITY_HUB_URL`:
+ * Opt-in, OFF by default, fully reversible. Direct web federation is gated on
+ * `AGENT_NATIVE_IDENTITY_HUB_URL`; the packaged Desktop SSO Canary may use the
+ * canonical Dispatch authority on canonical hosted apps, where Dispatch's
+ * default-off feature flag controls rollout:
  *
- *   - UNSET  → `isIdentitySsoEnabled()` is false. The route handler 404s, the
- *     auth-guard bypass does not apply, and the login page renders no SSO
- *     button. Existing auth is byte-for-byte unchanged.
+ *   - UNSET  → normal browser requests remain protected and the login page
+ *     renders no SSO button. Packaged Canary requests on canonical app origins
+ *     may reach the flow, but Dispatch refuses them unless its rollout flag
+ *     allows the user.
  *   - SET    (e.g. `https://dispatch.agent-native.com`) → two routes mount:
  *       GET /_agent-native/identity/login
  *         302 → `<HUB>/_agent-native/identity/authorize?app=<id>
@@ -59,6 +62,15 @@ export declare const IDENTITY_SSO_PROVIDER_ID = "agent-native";
  * as an identity assertion.
  */
 export declare const IDENTITY_SSO_SCOPE = "identity";
+export declare const IDENTITY_SSO_DESKTOP_COMPLETE_PATH = "/_agent-native/identity/desktop-complete";
+/**
+ * Direct web federation stays explicitly configured through
+ * `AGENT_NATIVE_IDENTITY_HUB_URL`. The packaged Desktop SSO Canary may use the
+ * canonical Dispatch authority without per-app deployment configuration, but
+ * only for canonical HTTPS Agent Native app origins. Dispatch's default-off
+ * feature flag remains the authoritative rollout gate.
+ */
+export declare function resolveIdentityHubUrl(event: H3Event): string | undefined;
 /**
  * Handle a `/_agent-native/identity/*` request. `subpath` is the part after
  * `/identity` (e.g. `/login`, `/callback`). Returns a 404 Response whenever
@@ -68,10 +80,8 @@ export declare const IDENTITY_SSO_SCOPE = "identity";
 export declare function handleIdentitySso(event: H3Event, subpath: string): Promise<Response>;
 /**
  * Whether the given (already base-path-stripped) request path is one of the
- * SSO routes that must bypass the blanket auth guard. Both routes resolve /
- * mint the browser session themselves: `/login` is the unauthenticated entry
- * point, and `/callback` is hit by a user who is (by definition) not yet
- * signed in to THIS app. Returns false when the feature is disabled, so the
- * guard's behaviour is unchanged with the env unset.
+ * two SSO routes that must bypass the blanket auth guard. The handler makes
+ * the request-scoped enablement decision and fails closed with 404; no other
+ * identity subpath bypasses authentication.
  */
 export declare function isIdentitySsoBypassPath(p: string): boolean;

package/dist/server/identity-sso.js

@@ -6,12 +6,15 @@
  * an identity authority (Dispatch) so a user logged in there can land in this
  * app without re-entering credentials.
  *
- * Opt-in, OFF by default, fully reversible. Everything here is gated on the
- * single env var `AGENT_NATIVE_IDENTITY_HUB_URL`:
+ * Opt-in, OFF by default, fully reversible. Direct web federation is gated on
+ * `AGENT_NATIVE_IDENTITY_HUB_URL`; the packaged Desktop SSO Canary may use the
+ * canonical Dispatch authority on canonical hosted apps, where Dispatch's
+ * default-off feature flag controls rollout:
  *
- *   - UNSET  → `isIdentitySsoEnabled()` is false. The route handler 404s, the
- *     auth-guard bypass does not apply, and the login page renders no SSO
- *     button. Existing auth is byte-for-byte unchanged.
+ *   - UNSET  → normal browser requests remain protected and the login page
+ *     renders no SSO button. Packaged Canary requests on canonical app origins
+ *     may reach the flow, but Dispatch refuses them unless its rollout flag
+ *     allows the user.
  *   - SET    (e.g. `https://dispatch.agent-native.com`) → two routes mount:
  *       GET /_agent-native/identity/login
  *         302 → `<HUB>/_agent-native/identity/authorize?app=<id>
@@ -41,8 +44,8 @@
  * and mint the same framework session. Removing the env returns the app to
  * its prior auth with no residue.
  */
-import { createHash } from "node:crypto";
-import { getMethod } from "h3";
+import { randomBytes } from "node:crypto";
+import { getHeader, getMethod } from "h3";
 import * as jose from "jose";
 import { GOOGLE_AUTH_REQUIRED_MESSAGE, isGoogleSignInRequiredForEmail, } from "../org/auth-policy.js";
 import { SIGN_IN_ENTRY_PATH } from "../shared/sign-in-journey.js";
@@ -50,7 +53,7 @@ import { getAppName } from "./app-name.js";
 import { getSession, safeReturnPath, isExpectedAuthFailure } from "./auth.js";
 import { getBetterAuth, getBetterAuthInternalAdapter, } from "./better-auth-instance.js";
 import { createOAuthSession, getOrigin } from "./google-oauth.js";
-import { createSsoState, consumeSsoState, isJtiReplayed, getIdentityHubUrl, isIdentitySsoEnabled, identitySsoLoginButtonHtml, } from "./identity-sso-store.js";
+import { createSsoState, consumeSsoState, isJtiReplayed, getIdentityHubUrl, isIdentitySsoEnabled, identitySsoLoginButtonHtml, isCanonicalAgentNativeAppRequest, isDesktopSsoCanaryUserAgent, } from "./identity-sso-store.js";
 export { getIdentityHubUrl, isIdentitySsoEnabled, identitySsoLoginButtonHtml };
 /**
  * The provider id recorded on the additive `account` row we link for an
@@ -67,8 +70,35 @@ export const IDENTITY_SSO_PROVIDER_ID = "agent-native";
  * as an identity assertion.
  */
 export const IDENTITY_SSO_SCOPE = "identity";
+export const IDENTITY_SSO_DESKTOP_COMPLETE_PATH = "/_agent-native/identity/desktop-complete";
+const DESKTOP_COMPLETION_NONCE = /^[A-Za-z0-9_-]{32,128}$/;
+const DESKTOP_IDENTITY_HUB_URL = "https://dispatch.agent-native.com";
 /** Identity tokens older than this are rejected even if `exp` is generous. */
 const MAX_TOKEN_AGE_SECONDS = 10 * 60;
+/**
+ * Direct web federation stays explicitly configured through
+ * `AGENT_NATIVE_IDENTITY_HUB_URL`. The packaged Desktop SSO Canary may use the
+ * canonical Dispatch authority without per-app deployment configuration, but
+ * only for canonical HTTPS Agent Native app origins. Dispatch's default-off
+ * feature flag remains the authoritative rollout gate.
+ */
+export function resolveIdentityHubUrl(event) {
+    const configured = getIdentityHubUrl();
+    if (configured)
+        return configured;
+    if (!isDesktopSsoCanaryUserAgent(getHeader(event, "user-agent"))) {
+        return undefined;
+    }
+    try {
+        if (!isCanonicalAgentNativeAppRequest(getHeader(event, "host"), getHeader(event, "x-forwarded-proto"))) {
+            return undefined;
+        }
+        return DESKTOP_IDENTITY_HUB_URL;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * A stable id for THIS app, sent to the hub as `?app=` so the authority can
  * record / display which app requested sign-in. Best-effort, non-secret,
@@ -137,23 +167,12 @@ function errorPage(message, loginPath) {
         `<p>${safe}</p><a href="${safeHref}">Back to sign in</a></div></body></html>`, 400);
 }
 /**
- * Derive a strong, deterministic, NEVER-exposed credential for a JIT-created
- * SSO user. Bound to the shared A2A secret + email so it is stable across
- * function executions but unguessable without the deployment secret. Only
- * ever used as the `password` argument to Better Auth's own
- * `signUpEmail` / `signInEmail` — never returned, logged, or sent anywhere.
+ * Create a strong, random, NEVER-exposed credential for a JIT-created SSO
+ * user. It is used once by Better Auth's signup path and is intentionally
+ * unavailable to every login surface, including later SSO retries.
  */
-function deriveSsoCredential(email) {
-    const secret = process.env.A2A_SECRET || "";
-    // A salted SHA-256 over secret + email: stable across function executions
-    // (so the same SSO user always derives the same stand-in password) but
-    // unguessable without the deployment secret. This account's only sign-in
-    // path is the signature-verified hub token, so the value is never used by
-    // anyone but Better Auth's own signUpEmail.
-    const digest = createHash("sha256")
-        .update(`${secret}:agent-native-sso:${email}`)
-        .digest("base64url");
-    return `an-sso_${digest}`;
+function createUnusableSsoCredential() {
+    return `an-sso_${randomBytes(32).toString("base64url")}`;
 }
 /**
  * JIT-link the verified hub identity into THIS app's local Better Auth
@@ -193,7 +212,7 @@ async function jitLinkIdentity(identity) {
             await auth.api.signUpEmail({
                 body: {
                     email: identity.email,
-                    password: deriveSsoCredential(identity.email),
+                    password: createUnusableSsoCredential(),
                     name: identity.name || identity.email.split("@")[0] || "User",
                 },
             });
@@ -304,7 +323,7 @@ async function verifyIdentityToken(token, expectedAudience) {
  * route somehow gets mounted.
  */
 export async function handleIdentitySso(event, subpath) {
-    const hub = getIdentityHubUrl();
+    const hub = resolveIdentityHubUrl(event);
     if (!hub) {
         return new Response("Not found", { status: 404 });
     }
@@ -413,15 +432,44 @@ export async function handleIdentitySso(event, subpath) {
         const dest = safeReturnPath(stateResult.returnPath);
         return redirect(event, dest);
     }
+    if (sub === "/desktop-complete") {
+        if (method !== "GET" && method !== "HEAD") {
+            return new Response("Method not allowed", { status: 405 });
+        }
+        let nonce = "";
+        try {
+            const url = new URL(event.node?.req?.url ?? event.path ?? "/", "http://an.invalid");
+            nonce = url.searchParams.get("nonce") || "";
+        }
+        catch {
+            return new Response("Invalid completion request", { status: 400 });
+        }
+        if (!DESKTOP_COMPLETION_NONCE.test(nonce)) {
+            return new Response("Invalid completion request", { status: 400 });
+        }
+        const current = await getSession(event).catch(() => null);
+        if (!current?.email) {
+            return new Response("Authentication required", { status: 401 });
+        }
+        return new Response('<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8">' +
+            '<meta name="viewport" content="width=device-width,initial-scale=1">' +
+            "<title>Signed in</title></head><body>Signed in. You can close this window.</body></html>", {
+            status: 200,
+            headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "no-store",
+                "Content-Security-Policy": "default-src 'none'; style-src 'none'",
+                "Referrer-Policy": "no-referrer",
+            },
+        });
+    }
     return new Response("Not found", { status: 404 });
 }
 /**
  * Whether the given (already base-path-stripped) request path is one of the
- * SSO routes that must bypass the blanket auth guard. Both routes resolve /
- * mint the browser session themselves: `/login` is the unauthenticated entry
- * point, and `/callback` is hit by a user who is (by definition) not yet
- * signed in to THIS app. Returns false when the feature is disabled, so the
- * guard's behaviour is unchanged with the env unset.
+ * two SSO routes that must bypass the blanket auth guard. The handler makes
+ * the request-scoped enablement decision and fails closed with 404; no other
+ * identity subpath bypasses authentication.
  */
 export function isIdentitySsoBypassPath(p) {
     if (!isIdentitySsoEnabled())

package/dist/server/index.d.ts

@@ -8,7 +8,7 @@ export { createEmbedStartRouteHandler, buildEmbedStartPath, type EmbedStartRoute
 export { createEmbedSessionTicket, consumeEmbedSessionTicket, normalizeEmbedTargetPath, requestHasEmbedAuthMarker, resolveEmbedSessionFromRequest, setEmbedSessionCookie, signEmbedSessionToken, verifyEmbedSessionToken, type ConsumedEmbedSessionTicket, type ConsumeEmbedSessionTicketOptions, type EmbedSessionTicket, type EmbedSessionTicketInput, type EmbedSessionTokenClaims, type ResolvedEmbedSession, type VerifyEmbedSessionTokenResult, } from "./embed-session.js";
 export { createSSEHandler, type SSEHandlerOptions } from "./sse.js";
 export { mountAuthMiddleware, autoMountAuth, getSession, COOKIE_NAME, addSession, removeSession, getSessionEmail, getFrameworkSessionCookieValues, setFrameworkSessionCookie, clearFrameworkSessionCookies, runAuthGuard, setDesktopExchange, setDesktopExchangeError, safeReturnPath, type DesktopExchangeErrorPayload, type AuthSession, type AuthOptions, } from "./auth.js";
-export { handleIdentitySso, getIdentityHubUrl, isIdentitySsoEnabled, isIdentitySsoBypassPath, identitySsoLoginButtonHtml, IDENTITY_SSO_PROVIDER_ID, IDENTITY_SSO_SCOPE, } from "./identity-sso.js";
+export { handleIdentitySso, getIdentityHubUrl, isIdentitySsoEnabled, isIdentitySsoBypassPath, identitySsoLoginButtonHtml, IDENTITY_SSO_PROVIDER_ID, IDENTITY_SSO_SCOPE, IDENTITY_SSO_DESKTOP_COMPLETE_PATH, } from "./identity-sso.js";
 export { requireEnvKey, type MissingKeyResponse } from "./missing-key.js";
 export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } from "./org-admin.js";
 export { verifyCaptcha, type CaptchaVerifyResult } from "./captcha.js";

package/dist/server/index.js

@@ -8,7 +8,7 @@ export { createEmbedStartRouteHandler, buildEmbedStartPath, } from "./embed-rout
 export { createEmbedSessionTicket, consumeEmbedSessionTicket, normalizeEmbedTargetPath, requestHasEmbedAuthMarker, resolveEmbedSessionFromRequest, setEmbedSessionCookie, signEmbedSessionToken, verifyEmbedSessionToken, } from "./embed-session.js";
 export { createSSEHandler } from "./sse.js";
 export { mountAuthMiddleware, autoMountAuth, getSession, COOKIE_NAME, addSession, removeSession, getSessionEmail, getFrameworkSessionCookieValues, setFrameworkSessionCookie, clearFrameworkSessionCookies, runAuthGuard, setDesktopExchange, setDesktopExchangeError, safeReturnPath, } from "./auth.js";
-export { handleIdentitySso, getIdentityHubUrl, isIdentitySsoEnabled, isIdentitySsoBypassPath, identitySsoLoginButtonHtml, IDENTITY_SSO_PROVIDER_ID, IDENTITY_SSO_SCOPE, } from "./identity-sso.js";
+export { handleIdentitySso, getIdentityHubUrl, isIdentitySsoEnabled, isIdentitySsoBypassPath, identitySsoLoginButtonHtml, IDENTITY_SSO_PROVIDER_ID, IDENTITY_SSO_SCOPE, IDENTITY_SSO_DESKTOP_COMPLETE_PATH, } from "./identity-sso.js";
 export { requireEnvKey } from "./missing-key.js";
 export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } from "./org-admin.js";
 export { verifyCaptcha } from "./captcha.js";

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

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

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/dist/templates/chat/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

package/dist/templates/default/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

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

@@ -168,10 +168,33 @@ Set `A2A_SECRET` (same value) on all apps that must verify each other's identity
 Each hosted `*.agent-native.com` app has its **own user store**, so "sign in once" is identity federation, not a shared cookie. **Dispatch is the identity authority.**
 
 - **Opt-in per app via one env var:** set `AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com` and the app shows a "Sign in with Agent-Native" option. **Unset = zero behavior change** — the whole path is dormant. Reversible at any time.
-- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Strict `redirect_uri` allowlist (`*.agent-native.com` + localhost). App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
+- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Canonical clients require an exact registered app ID, origin, and callback path; localhost remains available for development. App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
 - **Invariant (do not break):** identity rows are only ever **added** — never modified, renamed, or deleted. Enabling SSO logs users out, but they always log back into the **same email-matched account with data intact**. Email is the only thing that crosses the trust boundary; the app never trusts a user id, role, or org from the wire.
 - **Canary rollout:** deploy with the env unset everywhere (no-op) → set it on **one** app (mail) only → verify (logout → SSO → Dispatch → back to the same pre-existing account, data intact, direct logins still work) → expand app-by-app → rollback = unset the env on that app's deploy (instant, no data change).
 
+### Packaged Desktop workspace sign-in
+
+For canonical first-party hosted apps, the packaged Desktop SSO Canary may compose the same
+federation into one workspace sign-in. Dispatch owns the default-off
+`desktop.workspace-sso` availability flag; every app still owns its local
+session. The flag is never an auth or authorization boundary. Keep nonce,
+signature, exact origin/callback, authenticated-session, app-binding, cookie
+allowlist, revocation, and credential-custody checks unconditional. When the
+flag is Off or unreadable, Desktop must leave ordinary per-app sign-in, sign-out,
+and Settings unchanged. Never extend the broker to custom or third-party apps,
+and never expose cookies, identity tokens, or provider credentials through IPC.
+Canonical hosted apps recognize packaged Desktop requests without per-app
+identity-hub environment configuration. Ordinary browsers and self-hosted apps
+still require `AGENT_NATIVE_IDENTITY_HUB_URL`.
+Stable Desktop builds must not initialize the broker until a later release is
+separately approved.
+Treat the Canary user-agent marker only as an availability hint, never as
+remote attestation or an authentication boundary. Bind supervised acceptance
+to exact signed-artifact provenance.
+The Canary must not intercept anonymous app sign-in navigation. The user
+explicitly chooses workspace sign-in in Desktop Settings for the active
+registered app; ordinary app sign-in remains the default path.
+
 Full runbook + flow detail: [Cross-App SSO doc](/docs/cross-app-sso).
 
 ## Builder Browser Access

package/dist/templates/workspace-core/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

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

@@ -129,8 +129,12 @@ Extensions have full access to app data via helpers injected into the iframe
   in chat, record passive control/selection output at
   `inline-ui:<extensionId>:output` in application state so the agent can read it
   later with `readAppState`.
-- `agentNative.chat.send(message, opts?)` — send a visible prompt or selected
-  value back into the current agent chat.
+- `agentNative.chat.send(message, opts?)` - send a visible prompt or selected
+  value back into the current agent chat. The extension bridge keeps messages
+  draft-only unless `opts.submit === true`; pass `{ submit: true }` only from a
+  user-triggered Apply or Submit action. Never call it from polling, refresh, or
+  error handlers; use application state or `agentNative.ui.output` for passive
+  results.
 
 For transient inline generative UI, `extensionData` is host-browser
 `localStorage`: the agent cannot read it, it does not sync across devices, it

package/dist/templates/workspace-core/.agents/skills/extensions/references/api.md

@@ -137,7 +137,7 @@ await dbExec("UPDATE notes SET title = 'Updated Title' WHERE id = 'abc'");
 | `extensionData.get(collection, id, opts?)`       | Get a single item by id                                  | `extensionData.get('todos', 'todo-1')`                                                                           |
 | `extensionData.remove(collection, id, opts?)`    | Delete an item                                           | `extensionData.remove('todos', 'todo-1')`                                                                        |
 | `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state     | `agentNative.ui.output({ threshold })`                                                                           |
-| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { context: { q: 2 } })`                                                         |
+| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { submit: true, context: { q: 2 } })`                                           |
 
 ## Persisting Custom Data
 

package/dist/templates/workspace-core/.agents/skills/generative-ui/SKILL.md

@@ -76,7 +76,9 @@ The stored payload includes `value`, `updatedAt`, `extensionId`, and
 
 Use `agentNative.chat.send(message, opts?)` or `sendToAgentChat(message, opts?)`
 for a visible Apply/Submit button that should send a prompt or selected value
-into the chat.
+into the chat. Pass `{ submit: true }` explicitly for that user-triggered
+action; extension messages are draft-only otherwise. Never call these helpers
+from polling, refresh, or error handlers.
 
 ## App Data And State
 

package/docs/content/authentication.mdx

@@ -161,6 +161,33 @@ These deploys must provide `APP_NAME` or a derivable app URL (`APP_URL`,
 subdomains, set `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` alongside
 `COOKIE_DOMAIN`.
 
+## Packaged Desktop workspace SSO {#desktop-workspace-sso}
+
+The signed Agent Native Desktop SSO Canary composes hosted federation into one
+workspace sign-in for canonical first-party apps. Dispatch remains the identity
+authority, while every app mints and owns its normal local session. Electron
+keeps the authority session in a dedicated partition and copies only the target
+app's allowlisted session cookie into `persist:app-<id>`; provider credentials,
+identity tokens, and another app's cookies never enter renderer IPC.
+
+The Dispatch-owned `desktop.workspace-sso` feature flag is default-off and
+controls availability only. Missing, malformed, unreadable, and explicit-Off
+state preserve ordinary per-app sign-in and sign-out. Nonce binding, signed
+exchange validation, exact origin and callback allowlists, authenticated-session
+requirements, session isolation, and revocation remain unconditional in every
+flag state. Custom and third-party apps are excluded.
+Canonical hosted apps recognize packaged Desktop requests without per-app
+identity-hub environment configuration. Ordinary browsers and self-hosted apps
+still require `AGENT_NATIVE_IDENTITY_HUB_URL` to opt in.
+Stable Desktop builds do not initialize the broker until a later release is
+separately approved.
+The Canary user-agent marker is an availability hint rather than remote
+attestation. Authentication and authorization never trust it; supervised
+acceptance binds the client through exact signed-artifact provenance.
+The Canary does not intercept anonymous app sign-in navigation. The user must
+explicitly choose workspace sign-in in Desktop Settings for the active
+registered app; ordinary app sign-in remains the default path.
+
 ## QA Accounts {#qa-accounts}
 
 Local development and tests skip password-signup email verification by default,