@hosty-sdk/app 0.24.0 → 0.26.0

package/README.md

@@ -69,8 +69,8 @@ After first mount, blocked content and app portals become hidden and inert while
 remains mounted. Same-user renewal restores it. A different stable user ID reloads the app document
 and refuses to replay old pending requests. `APP_SESSION_RESTORED` from `/browser-auth` is an optional
 DOM notification with `detail.userId`; it contains no credential. There is no generic draft persistence
-across reloads or cache-clearing framework. Existing identity idle/absolute lifetimes and fixed
-privileged activity windows still apply.
+across reloads or cache-clearing framework. Current user/app permissions and the authorizing principal's idle/absolute lifetime still apply.
+Core 0.130.0 advertises continuous app sessions; older servers retain their actual activity policy.
 
 Compatible SDK updates change standard presentation and recovery after a dependency update and
 rebuild, without editing this wiring. New mandatory Core capabilities can require upgrading Core.
@@ -289,13 +289,108 @@ reads or `mcp:invoke` for assistant mutations, then apply your application's use
 Do not cache validation. Keep `introspectScopedToken` on ordinary APIs: it does not opt into accepting
 MCP-only credentials. Neither token permits skipping the application's own authorization.
 
-## Privileged activity renewal
+## Continuous app access (Core 0.130.0 / SDK 0.26.0)
 
-Identity probes used by `AppIdentityBridge` pass `activeUntil` and `activityRequired` through from
-`resolveAppSession().identity`. Keep app APIs on `appFetch`; a 401 can then request a user-click
-Core popup, exchange a code on the same origin and retry once without replacing mounted content.
-For another UI framework, use `configureAppActivity` with an app-owned `exchangeCode` function,
-listen for `APP_SESSION_ENDED`, and call `renewAppActivity` directly from a click. Do not navigate
-or reload to renew access. `appActivityNeedsRenewal()` supports proactive click renewal near expiry.
-See [the activity contract](../../docs/features/app-activity-window/feature.md), including the
-separate Core-approved assistant session leases.
+Pass `continuity`, `activeUntil` and `activityRequired` from Core revalidation through custom identity
+probes. Standard SDK adapters do this automatically. `HostyOverlay` / `useAppIdentity` maintain a
+live browser parent through a Core-owned frame and refresh the app-local probe. Checks coalesce,
+run on mount/return/network recovery, and repeat at a jittered five-minute interval. App backends
+cannot keep the browser parent alive with app credentials alone.
+
+Keep protected client requests on `appFetch`. An outage returns 503 without clearing identity or
+replaying a mutation. Real expiry uses normal recovery, preserving same-user state. Optional
+`<HostyOverlay localContent={<LocalNotes />}>…</HostyOverlay>` places explicitly local/public
+content outside the protected root during an outage; do not place private actor-bound data there.
+
+For another framework, use `configureAppContinuity` / `ensureAppContinuity` from
+`@hosty-sdk/app/continuity/browser`, with validated metadata from `/continuity` and a probe that
+checks the same actor. The probe must bypass maintenance (`appFetch(path, init, false)`) to avoid
+recursion. Clean up the coordinator on unmount. `APP_CONTINUITY_UPDATED` reports silent success;
+`APP_ACTIVITY_RENEWED` continues to mean explicit recovery. Do not replay handoffs/messages on either.
+Missing continuity metadata keeps older Core's `configureAppActivity`/click renewal behavior.
+
+Server-only unattended work requires an explicit Core grant:
+
+```ts
+import { BackgroundGrantClient } from "@hosty-sdk/app/background/server";
+const background = new BackgroundGrantClient(grantId, "health"); // HOSTY_* service configuration
+const response = await background.core("/api/apps/example.target/health");
+```
+
+The client coalesces credential issuance and refreshes before expiry. It sends each operation once;
+Core enforces the immutable selected scope online. `token()` can supply the existing provider/MCP
+client's user-token input. Keep tokens server-side. See
+[Continuous App Access](../../docs/features/continuous-app-access/feature.md) for creation, logout,
+revocation, exact MCP tools and installation boundaries. Background grants do not create a scheduler.
+
+## Shared panels (Core 0.129.0 / SDK 0.25.0)
+
+`HostyOverlay` composes one UI owner per top-level browser document. Its default
+`panelLayout="auto"` adds an opened-tool rail, an **Add tool** chooser and a resizable
+workspace. In a directly embedded app it delegates presentation to the verified parent
+and renders no local rail. Use `panelLayout="slot"` with exactly one
+`HostyPanelWorkspace` inside your chrome, or `"none"` for a custom controller renderer.
+Panel hosting requires reviewed optional `apps.panels.read` (or existing `apps.read`);
+participating as a child does not require catalog access.
+
+```ts
+// app/api/hosty/ui/[...action]/route.ts — own app configuration/session only
+import { createHostyUiRouteHandler } from "@hosty-sdk/app/server";
+const handler = createHostyUiRouteHandler(config);
+export const GET = handler;
+export const POST = handler;
+```
+
+Non-Next servers use `createHostyUiResponse` from `@hosty-sdk/app/ui/server` with their
+revalidated own app-user session/token. `UiServerClient` provides only `bootstrap`,
+`listPanels` and `resolvePanel`; never expose a generic Core proxy or caller-supplied credentials.
+Both server adapters return `no-store` metadata. The React root's `uiPath` defaults to
+`/api/hosty/ui` and must be a same-origin path.
+
+Finalize a business handoff before requesting placement. Freeze the provider's app ID,
+installation ID and interface key before `ProviderClient.assistant(...)`, then read its
+current descriptor and map the completed result:
+
+```ts
+import { resolveAssistantPresentation } from "@hosty-sdk/app/assistant";
+import { buildSurfaceOpenUrl } from "@hosty-sdk/app/ui";
+const presentation = resolveAssistantPresentation(currentProvider, finalized, { expectedProvider });
+const href = buildSurfaceOpenUrl(bootstrap.coreOrigin, presentation.destination);
+// bootstrap.pinnedOpen must be true before relying on this link.
+```
+
+The pure mapper never selects an assistant or invokes it. Explicit `result.open.panelId`
+selects a matching declared panel; otherwise the unique longest endpoint/path boundary
+wins. Ties return `ambiguous_surface`, navigation-only providers return `no_panel`, and
+both retain the exact same-session destination for explicit separate opening. A changed
+provider installation is refused. Core validates pinned links again after login.
+
+```tsx
+import { useHostyUi } from "@hosty-sdk/app/ui/react";
+import { createPresentationRequestId } from "@hosty-sdk/app/ui";
+const ui = useHostyUi();
+const requestId = createPresentationRequestId(); // retain with the completed result
+const result = await ui.openSurface(presentation.target!, { placement: "side", requestId });
+// Reuse requestId and target for retries; do not repeat the business action.
+const current = await ui.getPresentation(requestId);
+const unsubscribe = ui.subscribe(event => { /* environment or presentation update */ });
+```
+
+`opened` confirms placement, with separate `loading`, `auth-required`, `ready` or
+`unreported` readiness. Providers call `ui.reportSurfaceState({ route, state: "ready" })`
+after their exact route has loaded; iframe load alone is not readiness. Deadline/abort
+returns `uncertain`, not cancellation. Query or retry the same ID. An unsupported host
+never automatically opens a tab or creates a nested workspace. **Open separately** is an
+explicit `target="_blank" rel="noopener noreferrer"` link to the pinned destination.
+
+Framework-neutral clients use `createUiHost` from `@hosty-sdk/app/ui/host`, its snapshots,
+`registerFrame`, `openSurface`, `getPresentation`, `setExpanded`, `setWidth` and `dispose`.
+React clients normally use the overlay-owned controller via `useHostyUiHost` and the shared
+`HostyAppFrame`. Core projects the target's minimal microphone/popup policy; an app message
+cannot widen it. No delegated-token responder is required.
+
+Trust is limited to exact mounted window/origin, document generation and stateless Core
+peer metadata. Matching opaque Core/user contexts prevents accidental account mixing
+between cooperating apps; it is not attestation of app code or delegated API authority.
+Every target API still authorizes its own session. Older surfaces remain `unreported`.
+See [the panel contract and verification](../../docs/features/sdk-panel-system/feature.md).

package/dist/assistant.d.ts

@@ -1,3 +1,5 @@
+import type { ProviderDescriptor } from "./providers.js";
+import { type AppSurfaceRef, type PanelTarget } from "@hosty-sdk/app/ui/types";
 /** Preserve provider refusal details through app-owned server transports. */
 export declare class AssistantError extends Error {
     readonly code: string;
@@ -12,6 +14,7 @@ export type AssistantContract = {
 export type AssistantDestination = {
     endpoint: string;
     path: string;
+    panelId?: string;
 };
 export type AssistantHandoffResult = {
     conversationId: string;
@@ -51,6 +54,18 @@ export declare function resolveAssistantDestination(destination: AssistantDestin
     path?: string | null;
     url?: string | null;
 }[]): string;
+/** Pure mapping after finalization; the presentation host separately checks current access. */
+export declare function resolveAssistantPresentation(provider: ProviderDescriptor, result: AssistantHandoffResult, options: {
+    expectedProvider: {
+        appId: string;
+        installationId: string;
+        key: string;
+    };
+}): {
+    target: PanelTarget | null;
+    destination: AppSurfaceRef;
+    reason?: "no_panel" | "ambiguous_surface";
+};
 export declare class AssistantClient {
     private readonly baseUrl;
     private readonly contract;

package/dist/assistant.js

@@ -1,3 +1,4 @@
+import { isSurfaceRoute, routeWithin } from "@hosty-sdk/app/ui/types";
 /** Preserve provider refusal details through app-owned server transports. */
 export class AssistantError extends Error {
     code;
@@ -27,7 +28,7 @@ export function createAssistantRequestId(now = Date.now()) {
 }
 /** Resolve only inside a declared UI surface on the selected app's resolved endpoint. */
 export function resolveAssistantDestination(destination, surfaces) {
-    if (!destination || typeof destination.path !== "string" || !destination.path.startsWith("/") || destination.path.startsWith("//") || /[\\\u0000-\u001f]/.test(destination.path))
+    if (!destination || !isSurfaceRoute(destination.path))
         throw new Error("Invalid assistant UI destination.");
     if (/%(?:2f|5c|25)/i.test(destination.path.split(/[?#]/, 1)[0]))
         throw new Error("Invalid assistant UI destination.");
@@ -42,6 +43,42 @@ export function resolveAssistantDestination(destination, surfaces) {
     }
     throw new Error("The assistant returned a destination outside its declared UI.");
 }
+/** Pure mapping after finalization; the presentation host separately checks current access. */
+export function resolveAssistantPresentation(provider, result, options) {
+    const expected = options.expectedProvider;
+    if (!provider.installationId)
+        throw new AssistantError("unsupported_core", "Update Core to identify assistant installations.", 409);
+    if (provider.appId !== expected.appId || provider.key !== expected.key || provider.installationId !== expected.installationId)
+        throw new AssistantError("provider_changed", "The original assistant installation is no longer available.", 409);
+    try {
+        resolveAssistantDestination(result.open, provider.uiSurfaces ?? []);
+    }
+    catch {
+        throw new AssistantError("destination_invalid", "The assistant returned an undeclared destination.", 409);
+    }
+    const destination = { appId: provider.appId, installationId: provider.installationId,
+        endpoint: result.open.endpoint, route: result.open.path };
+    const panels = (provider.uiSurfaces ?? []).filter(s => s.kind === "panel" && s.panelId && s.url
+        && s.endpoint === destination.endpoint && routeWithin(destination.route, s.path));
+    let selected;
+    if (result.open.panelId !== undefined) {
+        selected = panels.find(s => s.panelId === result.open.panelId);
+        if (!selected)
+            throw new AssistantError("destination_invalid", "The assistant panel does not match its destination.", 409);
+    }
+    else {
+        if (!panels.length)
+            return { target: null, destination, reason: "no_panel" };
+        const length = (path) => new URL(path, "https://surface.invalid").pathname.replace(/\/$/, "").length;
+        const longest = Math.max(...panels.map(s => length(s.path)));
+        const matches = panels.filter(s => length(s.path) === longest);
+        if (new Set(matches.map(s => s.panelId)).size !== 1)
+            return { target: null, destination, reason: "ambiguous_surface" };
+        selected = matches[0];
+    }
+    return { target: { panel: { appId: provider.appId, installationId: provider.installationId, panelId: selected.panelId },
+            route: destination.route }, destination };
+}
 export class AssistantClient {
     baseUrl;
     contract;

package/dist/background-server.d.ts

@@ -0,0 +1,16 @@
+import type { ProviderServerOptions } from "@hosty-sdk/app/providers/server";
+/** An explicit Core delegation reference. Keep this client and its credentials on the server. */
+export declare class BackgroundGrantClient {
+    private readonly grantId;
+    private readonly scopeId;
+    private credential?;
+    private pending?;
+    private readonly origin;
+    private readonly appId;
+    private readonly service;
+    constructor(grantId: string, scopeId: string, options?: ProviderServerOptions);
+    /** Coalesces issuance; each protected dispatch still validates the delegation online in Core. */
+    token(): Promise<string>;
+    /** Sends one operation. No automatic replay of a possibly completed mutation. */
+    core(path: string, init?: RequestInit): Promise<Response>;
+}

package/dist/background-server.js

@@ -0,0 +1,52 @@
+import { ProviderError } from "@hosty-sdk/app/providers";
+/** An explicit Core delegation reference. Keep this client and its credentials on the server. */
+export class BackgroundGrantClient {
+    grantId;
+    scopeId;
+    credential;
+    pending;
+    origin;
+    appId;
+    service;
+    constructor(grantId, scopeId, options = {}) {
+        this.grantId = grantId;
+        this.scopeId = scopeId;
+        this.origin = new URL(options.coreOrigin ?? process.env.HOSTY_CORE_ORIGIN ?? "http://127.0.0.1:7070");
+        this.appId = options.appId ?? process.env.HOSTY_APP_ID ?? "";
+        this.service = options.serviceToken ?? process.env.HOSTY_APP_SERVICE_TOKEN ?? "";
+        if (!this.appId || !this.service || !grantId || !scopeId)
+            throw new Error("An app service identity and explicit background grant/scope references are required.");
+    }
+    /** Coalesces issuance; each protected dispatch still validates the delegation online in Core. */
+    token() {
+        if (this.credential && Date.parse(this.credential.expiresAt) > Date.now() + 30_000)
+            return Promise.resolve(this.credential.accessToken);
+        if (this.pending)
+            return this.pending;
+        this.pending = (async () => {
+            const response = await fetch(new URL(`/api/internal/apps/${encodeURIComponent(this.appId)}/background/token`, this.origin), {
+                method: "POST", redirect: "error", cache: "no-store", signal: AbortSignal.timeout(10_000),
+                headers: { authorization: `Bearer ${this.service}`, "content-type": "application/json" },
+                body: JSON.stringify({ grantId: this.grantId, scopeId: this.scopeId }),
+            });
+            const body = await response.json();
+            if (!response.ok)
+                throw new ProviderError(body.code ?? "background_denied", body.message ?? "Background access is unavailable.", response.status);
+            if (typeof body.accessToken !== "string" || !Number.isFinite(Date.parse(body.expiresAt)))
+                throw new Error("Invalid background credential response.");
+            this.credential = body;
+            return body.accessToken;
+        })().finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    /** Sends one operation. No automatic replay of a possibly completed mutation. */
+    async core(path, init = {}) {
+        const url = new URL(path, this.origin);
+        if (url.origin !== this.origin.origin || !url.pathname.startsWith("/api/apps/") || url.username || url.password)
+            throw new Error("Use a Core app operation path.");
+        const headers = new Headers(init.headers);
+        headers.set("authorization", `Bearer ${this.service}`);
+        headers.set("X-Hosty-App-Identity", await this.token());
+        return fetch(url, { ...init, headers, redirect: "error", cache: "no-store" });
+    }
+}

package/dist/browser-auth.d.ts

@@ -1,3 +1,5 @@
+export { APP_CONTINUITY_UPDATED } from "@hosty-sdk/app/continuity/browser";
+export { readAppContinuity, type AppContinuity } from "@hosty-sdk/app/continuity";
 import type { AppAuthProtocol } from "./app-code.js";
 export type AppSignInResult = {
     code: string;

package/dist/browser-auth.js

@@ -1,3 +1,6 @@
+import { ensureAppContinuity } from "@hosty-sdk/app/continuity/browser";
+export { APP_CONTINUITY_UPDATED } from "@hosty-sdk/app/continuity/browser";
+export { readAppContinuity } from "@hosty-sdk/app/continuity";
 import { sha256 } from "@noble/hashes/sha2.js";
 function isValidCodeVerifier(value) {
     return typeof value === "string" && /^[A-Za-z0-9._~-]{43,128}$/.test(value);
@@ -270,6 +273,8 @@ export async function appFetch(input, init = {}, recover = true) {
     // SDK identity/protocol probes use recover=false so that validation itself can proceed.
     if (recover && renewal && activityConfig?.validateSession && !await waitForActivity(init.signal))
         return Response.json({ code: "reauth_required", message: "Hosty access has not been restored." }, { status: 401 });
+    if (recover && !await ensureAppContinuity())
+        return Response.json({ code: "session_unavailable", message: "Hosty access could not be verified." }, { status: 503 });
     const current = grant?.origin === url.origin ? grant : null;
     const headers = new Headers(init.headers);
     if (current)

package/dist/continuity-browser.d.ts

@@ -0,0 +1,11 @@
+import type { AppContinuity } from "./continuity.js";
+export declare const APP_CONTINUITY_UPDATED = "hosty:app-continuity-updated";
+type Owner = {
+    coreOrigin: string;
+    authority: AppContinuity;
+    probe: () => Promise<boolean>;
+};
+/** One coordinator per app document; probes bypass appFetch's maintenance to avoid recursion. */
+export declare function ensureAppContinuity(force?: boolean): Promise<boolean>;
+export declare function configureAppContinuity(config: Owner): () => void;
+export {};

package/dist/continuity-browser.js

@@ -0,0 +1,92 @@
+export const APP_CONTINUITY_UPDATED = "hosty:app-continuity-updated";
+let owner = null;
+let pending = null;
+let checkedAt = 0;
+let valid = true;
+/** One coordinator per app document; probes bypass appFetch's maintenance to avoid recursion. */
+export async function ensureAppContinuity(force = false) {
+    if (!owner)
+        return true;
+    if (pending)
+        return pending;
+    if (!force && Date.now() - checkedAt < Math.min(30_000, owner.authority.checkAfterSeconds * 1000))
+        return valid;
+    const current = owner;
+    pending = (async () => {
+        // Browser policy may refuse the frame. Only the app's authoritative probe decides access.
+        if (current.authority.mode === "browser")
+            await maintainParent(current);
+        const result = await current.probe().catch(() => false);
+        if (owner !== current)
+            return false;
+        valid = result;
+        checkedAt = Date.now();
+        if (result)
+            window.dispatchEvent(new Event(APP_CONTINUITY_UPDATED));
+        return result;
+    })().finally(() => { pending = null; });
+    return pending;
+}
+export function configureAppContinuity(config) {
+    owner = config;
+    checkedAt = 0;
+    valid = true;
+    let disposed = false;
+    let failures = 0;
+    let scheduleVersion = 0;
+    let timer;
+    const schedule = async (force = false) => {
+        const version = ++scheduleVersion;
+        clearTimeout(timer);
+        const ok = await ensureAppContinuity(force);
+        // Events can share one pending probe; only the latest waiter installs its next timer.
+        if (disposed || version !== scheduleVersion)
+            return;
+        failures = ok ? 0 : Math.min(4, failures + 1);
+        const seconds = ok ? config.authority.checkAfterSeconds : Math.min(300, 15 * 2 ** failures);
+        timer = setTimeout(() => { void schedule(true); }, seconds * 1000 * (0.9 + Math.random() * 0.2));
+    };
+    const wake = () => { void schedule(); };
+    const online = () => { void schedule(true); };
+    window.addEventListener("focus", wake);
+    window.addEventListener("online", online);
+    document.addEventListener("visibilitychange", wake);
+    void schedule(true);
+    return () => {
+        disposed = true;
+        clearTimeout(timer);
+        window.removeEventListener("focus", wake);
+        window.removeEventListener("online", online);
+        document.removeEventListener("visibilitychange", wake);
+        if (owner === config) {
+            owner = null;
+            checkedAt = 0;
+        }
+    };
+}
+function maintainParent(config) {
+    return new Promise(resolve => {
+        const state = Array.from(crypto.getRandomValues(new Uint8Array(32)), b => b.toString(16).padStart(2, "0")).join("");
+        const url = new URL("/api/auth/apps/continuity/frame", config.coreOrigin);
+        url.searchParams.set("grantId", config.authority.grantId);
+        url.searchParams.set("origin", window.location.origin);
+        url.searchParams.set("state", state);
+        const frame = document.createElement("iframe");
+        frame.hidden = true;
+        frame.title = "Hosty session maintenance";
+        frame.referrerPolicy = "no-referrer";
+        const done = () => { clearTimeout(timer); window.removeEventListener("message", received); frame.remove(); resolve(); };
+        const received = (event) => {
+            if (event.source === frame.contentWindow && event.origin === url.origin &&
+                event.data?.type === "hosty:continuity-result" && event.data.state === state &&
+                ["maintained", "unavailable"].includes(event.data.status))
+                done();
+        };
+        const timer = setTimeout(done, 4_000);
+        window.addEventListener("message", received);
+        frame.onload = () => frame.contentWindow?.postMessage({ type: "hosty:continuity-check", state }, url.origin);
+        frame.onerror = done;
+        frame.src = url.href;
+        document.body.append(frame);
+    });
+}

package/dist/continuity.d.ts

@@ -0,0 +1,9 @@
+/** Server-advertised authority, never inferred from embedding or a missing activity deadline. */
+export type AppContinuity = {
+    version: 1;
+    mode: "browser" | "native";
+    grantId: string;
+    expiresAt: string;
+    checkAfterSeconds: number;
+};
+export declare function readAppContinuity(value: unknown): AppContinuity | undefined;

package/dist/continuity.js

@@ -0,0 +1,9 @@
+export function readAppContinuity(value) {
+    const v = value;
+    if (v?.version !== 1 || !["browser", "native"].includes(v.mode ?? "") ||
+        typeof v.grantId !== "string" || !v.grantId || v.grantId.length > 128 ||
+        typeof v.expiresAt !== "string" || !Number.isFinite(Date.parse(v.expiresAt)) ||
+        typeof v.checkAfterSeconds !== "number" || !Number.isFinite(v.checkAfterSeconds) || v.checkAfterSeconds <= 0)
+        return;
+    return { ...v, checkAfterSeconds: Math.min(300, v.checkAfterSeconds) };
+}

package/dist/overlay-react.d.ts

@@ -1,7 +1,11 @@
 import { type ReactNode } from "react";
 /** Mount once around protected content. Presentation and recovery belong to Hosty. */
-export declare function HostyOverlay({ children, probePath, appCodePath }: {
+export declare function HostyOverlay({ children, probePath, appCodePath, uiPath, panelLayout, localContent }: {
+    /** Explicitly public/local content available during an outage; never put protected actor data here. */
+    localContent?: ReactNode;
     children: ReactNode;
     probePath?: string;
     appCodePath?: string;
+    uiPath?: string;
+    panelLayout?: "auto" | "slot" | "none";
 }): import("react").JSX.Element;

package/dist/overlay-react.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { useAppIdentity } from "./react.js";
@@ -7,6 +7,7 @@ import { useAppActivity } from "./activity-react.js";
 import { APP_SESSION_ENDED, APP_SESSION_RESTORED, APP_ACTIVITY_RENEWED, acceptAppAuthProtocol } from "./browser-auth.js";
 import { buildCoreOpenUrl, readRecoveryParams } from "./index.js";
 import { permissionReviewUrl, requestPermissionReview } from "./permissions.js";
+import { HostyUiRoot } from "./ui-react.js";
 function snapshot(body) {
     const value = body;
     if (value?.status !== "active" || typeof value.userId !== "string" || !value.userId)
@@ -29,7 +30,7 @@ function sessionReady(session) {
     return session?.setup === "ready" && (!session.activityRequired || session.recoveryReady) && !activityExpired(session);
 }
 /** Mount once around protected content. Presentation and recovery belong to Hosty. */
-export function HostyOverlay({ children, probePath = "/api/hosty/session", appCodePath = "/api/auth/app-code" }) {
+export function HostyOverlay({ children, probePath = "/api/hosty/session", appCodePath = "/api/auth/app-code", uiPath, panelLayout = "auto", localContent }) {
     const actor = useRef(null);
     const changingActor = useRef(false);
     const [session, setSession] = useState(null);
@@ -79,7 +80,7 @@ export function HostyOverlay({ children, probePath = "/api/hosty/session", appCo
             setReviewing(false);
     }, [session?.setup]);
     useEffect(() => {
-        // No keepalive polling. Focus and a pending Core review are the only readiness refreshes.
+        // Continuous sessions own their maintenance; this also observes pending permission reviews.
         let loading = false;
         const refresh = () => {
             if (loading || !actor.current || activity.pending || (activity.needed && !renewedAwaitingReadiness.current))
@@ -165,7 +166,9 @@ export function HostyOverlay({ children, probePath = "/api/hosty/session", appCo
         action = activity.renew;
         actionLabel = "Renew access";
     }
-    return _jsxs(_Fragment, { children: [_jsx("div", { "data-hosty-content": true, hidden: !ready, inert: !ready, style: ready ? { display: "contents" } : { display: "none" }, children: mounted.current ? children : null }), !ready && _jsx(OverlaySurface, { pending: pending, title: title, message: message, action: action, actionLabel: actionLabel, reviewUrl: reviewUrl })] });
+    const localOffline = (identity.ui.kind === "unavailable" || (identity.ui.kind === "active" && session?.setup === "unavailable"))
+        && localContent !== undefined;
+    return _jsxs(_Fragment, { children: [localOffline && _jsxs("div", { "data-hosty-local-content": true, children: [_jsx("p", { role: "status", children: "Hosty is unavailable. Local content remains available." }), localContent] }), _jsx("div", { "data-hosty-content": true, hidden: !ready, inert: !ready, style: ready ? { display: "contents" } : { display: "none" }, children: _jsx(HostyUiRoot, { uiPath: uiPath, panelLayout: panelLayout, active: ready, children: mounted.current ? children : null }) }), !ready && !localOffline && _jsx(OverlaySurface, { pending: pending, title: title, message: message, action: action, actionLabel: actionLabel, reviewUrl: reviewUrl })] });
 }
 function OverlaySurface({ pending, title, message, action, actionLabel, reviewUrl }) {
     const [portal, setPortal] = useState(null);

package/dist/providers-server.d.ts

@@ -24,7 +24,9 @@ export declare class ProviderClient {
         signal?: AbortSignal;
     }): Promise<SpeechResult>;
     /** User-attributed requests preserve the assistant's existing handoff and dispatch policy. */
-    assistant(provider: Pick<ProviderDescriptor, "appId" | "key">, userToken: () => Promise<string>): Promise<AssistantClient>;
+    assistant(provider: Pick<ProviderDescriptor, "appId" | "key"> & {
+        installationId?: string | null;
+    }, userToken: () => Promise<string>): Promise<AssistantClient>;
     /** Provider-side validation checks live grants on every request; never cache this result. */
     validate(token: string, kind: ProviderKind, key?: string, signal?: AbortSignal): Promise<ProviderInvocation>;
 }

package/dist/providers-server.js

@@ -31,6 +31,8 @@ export class ProviderClient {
         const issued = await this.coreRequest(`/providers/${provider.kind}/token`, { providerAppId: provider.appId, key: provider.key }, signal, userToken);
         if (issued.provider.version !== 1 || !issued.provider.url)
             throw new ProviderError("provider_incompatible", "This provider does not support interface version 1.", 409);
+        if (provider.installationId && issued.provider.installationId !== provider.installationId)
+            throw new ProviderError("provider_changed", "The selected assistant installation changed. Start a new discussion explicitly.", 409);
         const url = new URL(issued.provider.url);
         if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
             throw new ProviderError("provider_url_invalid", "Invalid provider endpoint.", 409);
@@ -58,8 +60,8 @@ export class ProviderClient {
         const binding = await this.connect(target, undefined, await userToken());
         return new AssistantClient(binding.url, { version: binding.provider.version, capabilities: binding.provider.capabilities }, async () => {
             const fresh = await this.connect(target, undefined, await userToken());
-            if (fresh.url !== binding.url)
-                throw new ProviderError("provider_changed", "The assistant endpoint changed. Reconnect explicitly.", 409);
+            if (fresh.url !== binding.url || fresh.provider.installationId !== binding.provider.installationId)
+                throw new ProviderError("provider_changed", "The assistant endpoint or installation changed. Reconnect explicitly.", 409);
             return { token: fresh.token };
         });
     }

package/dist/providers.d.ts

@@ -14,7 +14,11 @@ export type ProviderDescriptor = {
         endpoint: string | null;
         path: string;
         url: string | null;
+        kind?: "panel" | "navigation" | "entrypoint";
+        panelId?: string | null;
     }> | null;
+    /** Opaque Core installation identity; compare for equality, never parse. */
+    installationId?: string | null;
 };
 export type AppPermissionState = {
     required: string[];

package/dist/react.d.ts

@@ -1,3 +1,4 @@
+import { type AppContinuity } from "./continuity.js";
 import type { AppAuthProtocol } from "./app-code.js";
 import type { ReactNode } from "react";
 import { type AppLaunchMode, type AppSessionStatus } from "./index.js";
@@ -71,6 +72,7 @@ export declare function useAppIdentity({ probePath, appCodePath, onSession, }?:
         appAuthProtocol: AppAuthProtocol;
         activeUntil?: string | null;
         activityRequired?: boolean;
+        continuity?: AppContinuity;
     } | null;
     hasBeenActive: boolean;
     refresh: () => Promise<unknown>;

package/dist/react.js

@@ -3,6 +3,8 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 // React slice: the client identity bridge — probe, silent recovery, and the fallback
 // cards. Prop-less by design: the app id and browser-reachable Core origin arrive in the
 // probe response's `recovery` field (request-time values, never build-time props).
+import { readAppContinuity } from "./continuity.js";
+import { configureAppContinuity } from "./continuity-browser.js";
 import { AppActivityBridge } from "./activity-react.js";
 import { AuthNotice, AuthNoticeButton, authNoticeActionStyle } from "./auth-notice.js";
 import { useEffect, useRef, useState } from "react";
@@ -203,6 +205,18 @@ export function useAppIdentity({ probePath = "/api/auth/identity", appCodePath =
     const exchangeRef = useRef(null);
     const onSessionRef = useRef(onSession);
     useEffect(() => { onSessionRef.current = onSession; }, [onSession]);
+    const continuity = activity?.continuity;
+    const continuityActor = session?.userId;
+    useEffect(() => {
+        if (!continuity || !activity?.openUrl || !continuityActor)
+            return;
+        return configureAppContinuity({ coreOrigin: new URL(activity.openUrl).origin, authority: continuity,
+            probe: async () => {
+                const next = await refreshRef.current();
+                return next?.status === "active" && next.userId === continuityActor
+                    && (!next.hosty || (next.hosty.version === 1 && next.hosty.setup === "ready"));
+            } });
+    }, [continuity?.grantId, activity?.openUrl, continuityActor]);
     useEffect(() => {
         let cancelled = false;
         let probeSequence = 0;
@@ -263,7 +277,7 @@ export function useAppIdentity({ probePath = "/api/auth/identity", appCodePath =
             forgetRejectedAppGrant(rejectionCode, revision);
             if (openUrl && protocol)
                 setActivity({ openUrl, appAuthProtocol: protocol,
-                    activeUntil: activityMetadata?.activeUntil, activityRequired: activityMetadata?.activityRequired });
+                    activeUntil: activityMetadata?.activeUntil, activityRequired: activityMetadata?.activityRequired, continuity: readAppContinuity(activityMetadata?.continuity) });
             const initialLoad = firstProbe.current;
             firstProbe.current = false;
             if (silentError.current === "access_denied") {

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import "server-only";
+import { type AppContinuity } from "./continuity.js";
 import { type AppAuthProtocol } from "./app-code.js";
 export { isValidCodeVerifier } from "./app-code.js";
 import { type AppSessionFailureStatus, type AppSessionStatus, type SessionRecoveryParams } from "./index.js";
@@ -25,6 +26,7 @@ export interface HostIdentity {
     expiresAt: string | null;
     activeUntil?: string | null;
     activityRequired?: boolean;
+    continuity?: AppContinuity;
 }
 /** Structured detail for a failed resolution: the Core HTTP status (null when Core was
  * never reached) plus a machine-readable code and human-readable message. Codes pass
@@ -47,6 +49,11 @@ export declare function getAppId(config: HostyAppConfig): string;
 export declare function createHostySessionRouteHandler(config: HostyAppConfig, options?: {
     administratorOnly?: boolean;
 }): (request: Request) => Promise<Response>;
+/** Mount GET/POST at /api/hosty/ui/[...action] for the shared panel protocol. */
+export declare function createHostyUiRouteHandler(config: HostyAppConfig, options?: {
+    administratorOnly?: boolean;
+    uiPath?: string;
+}): (request: Request) => Promise<Response>;
 export declare function getCoreOrigin(): string | null;
 /** Browser-reachable Core origin. Core always injects it (falls back to its loopback
  * listen URL on localhost-only installs), so a missing value is a broken environment. */