@agent-native/core 0.149.6 → 0.151.1

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/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,

package/docs/content/cross-app-sso.mdx

@@ -35,6 +35,11 @@ cookie**. Each separately hosted app still creates and owns its own local
 session. Dispatch proves the user's identity at the app's front door, and the
 app then continues with its normal local auth and access checks.
 
+The packaged Desktop Canary is deliberately more explicit: it never intercepts
+anonymous app sign-in navigation. The user chooses workspace sign-in in Desktop
+Settings for the active registered app; ordinary app sign-in remains the
+default path when that action is not chosen or the flag is unavailable.
+
 For a product walkthrough, record this exact sequence: sign in once in
 Dispatch, open two other hosted apps, show that neither asks for credentials,
 then sign out of one app and show that the other app's session is independent.
@@ -140,7 +145,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
     "in": "query",
     "type": "string",
     "required": true,
-    "description": "App callback URL. Validated against a strict allowlist (`*.agent-native.com` or localhost by default)."
+    "description": "App callback URL. Canonical apps must match an exact registered app ID, origin, and callback path; localhost is allowed for development."
   },
   {
     "name": "state",
@@ -156,7 +161,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
   },
   {
     "status": "400",
-    "description": "`redirect_uri` failed allowlist validation (cross-origin, scheme-relative `//host`, or unlisted suffix)."
+    "description": "`app` and `redirect_uri` failed allowlist validation (mismatched app, cross-origin, scheme-relative `//host`, or unlisted host)."
   }
 ]}>
 
@@ -183,7 +188,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
 
 ### Opting in {#opt-in}
 
-An app participates **only** when this environment variable is set on its deployment:
+An app's ordinary web sign-in participates **only** when this environment variable is set on its deployment:
 
 ```bash
 AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
@@ -197,10 +202,10 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 The whole model rests on a few deliberately small guarantees:
 
 - **Short-lived signed token.** The identity assertion is an `A2A_SECRET`-signed JWT with a **≤ 2-minute** expiry and `scope: "identity"`. It authorizes a single sign-in and cannot be replayed for long or repurposed for API/A2A access.
-- **Strict `redirect_uri` allowlist.** Dispatch only ever redirects to `*.agent-native.com` or localhost by default. Arbitrary, scheme-relative (`//host`), and cross-origin redirect targets are rejected, so the authority can't be turned into an open-redirect or token-exfiltration oracle.
+- **Strict app-bound `redirect_uri` allowlist.** Every canonical app ID maps to one exact production origin and callback path; localhost remains available for development. Unknown subdomains, mismatched app IDs, arbitrary paths, scheme-relative (`//host`), and cross-origin targets are rejected, so the authority can't become a token-exfiltration oracle.
 - **Email-only join from a verified token.** The _only_ thing that crosses the trust boundary is the verified email in a signed token. The app does not accept a user id, role, org membership, or any privileged state from the wire — it derives everything locally from the matched account.
 - **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path.
-- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert.
+- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset, ordinary browser federation is inert. The separately gated packaged Desktop path is described below.
 
 <Callout id="doc-block-18qhl3m" tone="success">
 
@@ -265,6 +270,31 @@ The just-in-time link is a single decision keyed entirely on the verified email:
 
 </Diagram>
 
+## Packaged Desktop workspace {#desktop-workspace}
+
+The signed Agent Native Desktop SSO Canary uses this same federation flow as the
+ordinary sign-in front door for canonical first-party apps. A dedicated
+Electron partition holds the Dispatch authority session; each target app still
+mints its own local session, and Desktop transfers only that app's allowlisted
+session cookie into its isolated `persist:app-<id>` partition. Custom,
+user-added, and third-party apps are excluded.
+
+Dispatch registers the default-off `desktop.workspace-sso` rollout flag. The
+flag controls whether Desktop may begin the ceremony; it does not authorize a
+user or weaken nonce, signature, origin, callback, app-binding, cookie,
+revocation, or credential-custody checks. With the flag Off or unavailable,
+Desktop leaves ordinary per-app sign-in, sign-out, and Settings unchanged.
+Canonical hosted apps recognize the packaged Desktop request without requiring
+`AGENT_NATIVE_IDENTITY_HUB_URL` on every deployment; ordinary web browsers and
+self-hosted apps still require that explicit configuration.
+Stable Desktop builds do not initialize the broker until a later release is
+separately approved.
+The Canary user-agent marker is an availability hint, not remote attestation;
+the server cannot infer code signature from HTTP. No authentication or
+authorization decision trusts it. Supervised acceptance therefore binds the
+tested client through the signed artifact's exact commit, manifest, hashes, and
+notarization evidence.
+
 ## Self-hosting {#self-hosting}
 
 Any Dispatch deployment can serve as the identity hub — you are not limited to `dispatch.agent-native.com`. Set `AGENT_NATIVE_IDENTITY_HUB_URL` on each client app to point at your Dispatch instance:
@@ -275,7 +305,7 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
 
 **Redirect allowlist.** The hub (Dispatch) validates `redirect_uri` on the authorize endpoint before issuing a token. The allowlist is configured in `templates/dispatch/server/lib/identity-sso.ts`:
 
-- **Default:** `*.agent-native.com` and localhost only (the `DEFAULT_ALLOWED_HOST_SUFFIXES` constant).
+- **Default:** exact registered Agent Native app ID/origin pairs and localhost only (`CANONICAL_IDENTITY_SSO_APP_ORIGINS`).
 - **Extending it:** set the `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` environment variable on the Dispatch deployment with a comma-separated list of additional host suffixes:
 
   ```bash
@@ -283,11 +313,11 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
   IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
   ```
 
-  Each entry is normalized to a dot-prefixed suffix (`.yourcompany.com`), so a suffix check is both sufficient and the least footgun-prone — no per-app list to keep in sync. Entries that would match everything (empty or just `.`) are filtered out.
+  Each entry is normalized to a dot-prefixed suffix (`.yourcompany.com`). Entries that would match everything (empty or just `.`) are filtered out. The request must still provide a valid app ID and the exact `/_agent-native/identity/callback` path.
 
 - **Localhost** is always allowed for local development of client-side apps regardless of `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
 
-Without `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, a self-hosted Dispatch can only issue tokens to apps on `*.agent-native.com`. Set the env var on your Dispatch deployment to unlock other domains.
+Without `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, a self-hosted Dispatch can only issue tokens to the exact registered Agent Native app origins. Set the env var on your Dispatch deployment to unlock other domains.
 
 ## Canary rollout runbook {#canary-rollout}