@hosty-sdk/app 0.27.24 → 0.29.0

package/README.md

@@ -544,3 +544,17 @@ Keep launch/auth exports for older hosts and native transport. Native clients se
 navigation/launcher and disabled tools until they provide a panel host. `panelLayout="none"` is a
 rendering choice, not a disable policy: explicitly disable local tools or register a renderer.
 See [UI composition and browser acceptance](../../docs/features/sdk-ui-composition/feature.md).
+
+## Child Core sandbox controls
+
+`@hosty-sdk/app/sandbox/react` exports `CoreEnvironmentPanel` for operator-facing child Core
+management. Supply an authenticated `EnvironmentRequest` transport, a tab-local replay storage key
+and optionally a workspace with its active worktrees. Shell and Workspaces use this shared panel
+for create/start, current/source Core selection, normal test-account setup, app status, preview and
+confirmed deletion. The component does not grant authority: Core independently checks the optional
+`core.environments.inspect/operate` grants, administrator identity and workspace source access.
+
+`@hosty-sdk/app/sandbox/server` provides the server-side clients for independent app sandboxes and
+child Core environments. Caller-owned `core.environments.read/manage` authority remains distinct
+from the operator panel's cross-caller permissions. See the
+[sandbox contract](../../docs/features/app-sandbox-runtimes/feature.md) for lifecycle and cleanup rules.

package/dist/index.d.ts

@@ -206,3 +206,8 @@ export declare function decideRecoveryAction(input: {
 }): RecoveryAction;
 /** Paint-time navigation policy. Kept in the pure entry point for Node and edge consumers. */
 export declare function chromeBootstrapScript(defaults?: import("./ui-types").UiChromeOverrides): string;
+/** Execution scope is independent of the principal's role. Never infer it from an app ID. */
+import type { SandboxTarget, SandboxIdentityContext } from "./sandbox-identity.js";
+export type { SandboxTarget, SandboxIdentityContext } from "./sandbox-identity.js";
+export declare function readSandboxTarget(environment: Record<string, string | undefined>): SandboxTarget | null;
+export declare function readSandboxIdentity(payload: Record<string, unknown>, expected: SandboxTarget | null): SandboxIdentityContext | null;

package/dist/index.js

@@ -269,3 +269,24 @@ export function chromeBootstrapScript(defaults = {}) {
         throw new Error("Invalid navigation default.");
     return `(()=>{try{const d=${JSON.stringify({ navigation })},p=new URLSearchParams(location.search),h=new URLSearchParams();for(const k of ["hosty_navigation","hosty_tools","hosty_tool_launcher","hosty_launch"])for(const v of p.getAll(k))h.append(k,v);document.documentElement.setAttribute('data-hosty-chrome-hints',h.toString());const one=k=>p.getAll(k).length===1?p.get(k):null,n=one('hosty_navigation'),l=one('hosty_launch');document.documentElement.setAttribute('data-hosty-navigation',n==='show'||n==='hide'?n:d.navigation??(l==='native'||l==='embedded'?'hide':'show'));}catch{}})();`;
 }
+export function readSandboxTarget(environment) {
+    const fields = [environment.HOSTY_SANDBOX_INSTANCE_ID, environment.HOSTY_SANDBOX_GENERATION, environment.HOSTY_SANDBOX_DATA_REVISION];
+    if (!environment.HOSTY_SANDBOX_PROTOCOL && fields.every(value => !value))
+        return null;
+    if (environment.HOSTY_SANDBOX_PROTOCOL !== "hosty-sandbox-v1" || fields.some(value => !/^[a-f0-9]{32}$/.test(value ?? "")))
+        throw new Error("The sandbox execution target is missing or unsupported.");
+    return { runtimeInstanceId: fields[0], generation: fields[1], dataRevision: fields[2] };
+}
+export function readSandboxIdentity(payload, expected) {
+    if (!expected) {
+        if (payload.identityRealm === "sandbox" || payload.runtimeInstanceId != null || payload.generation != null || payload.dataRevision != null)
+            throw new Error("An installed app cannot accept a sandbox identity.");
+        return null;
+    }
+    if (payload.runtimeInstanceId !== expected.runtimeInstanceId || payload.generation !== expected.generation || payload.dataRevision !== expected.dataRevision
+        || (payload.identityRealm !== "sandbox" && payload.identityRealm !== "core") || typeof payload.appRole !== "string"
+        || !Array.isArray(payload.permissions) || !payload.permissions.every(value => typeof value === "string")
+        || (payload.identityRealm === "sandbox" && payload.hostRole != null))
+        throw new Error("The identity belongs to a different or unsupported sandbox target.");
+    return { ...expected, identityRealm: payload.identityRealm, appRole: payload.appRole, permissions: payload.permissions };
+}

package/dist/sandbox-identity.d.ts

@@ -0,0 +1,10 @@
+export interface SandboxTarget {
+    runtimeInstanceId: string;
+    generation: string;
+    dataRevision: string;
+}
+export interface SandboxIdentityContext extends SandboxTarget {
+    identityRealm: "sandbox" | "core";
+    appRole: string;
+    permissions: string[];
+}

package/dist/sandbox-identity.js

@@ -0,0 +1 @@
+export {};

package/dist/sandbox-react.d.ts

@@ -0,0 +1,28 @@
+export type EnvironmentRequest = <T>(path: string, body?: unknown, signal?: AbortSignal) => Promise<T>;
+export interface EnvironmentWorkspace {
+    id: string;
+    worktrees: {
+        id: string;
+        label: string;
+        state: string;
+    }[];
+}
+export interface EnvironmentApps {
+    state: string;
+    apps: {
+        id: string;
+        displayName: string;
+        version?: string;
+        runtimeState: string;
+        health?: string;
+        previewUrl?: string;
+    }[];
+    error?: string;
+}
+/** Shared operator panel; each host supplies its authenticated same-origin Core transport. */
+export declare function CoreEnvironmentPanel({ request, storageKey, workspace, workspaceHref }: {
+    request: EnvironmentRequest;
+    storageKey: string;
+    workspace?: EnvironmentWorkspace;
+    workspaceHref?: (id: string) => string;
+}): import("react").JSX.Element;

package/dist/sandbox-react.js

@@ -0,0 +1,208 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+const button = "inline-flex items-center justify-center gap-2 rounded-md border bg-background px-3 py-2 text-sm font-medium hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed";
+const field = "w-full rounded-md border bg-background px-3 py-2 text-sm";
+function message(error) { return error instanceof Error ? error.message : "Sandbox request failed."; }
+function link(value) {
+    try {
+        const url = new URL(value ?? "");
+        return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Shared operator panel; each host supplies its authenticated same-origin Core transport. */
+export function CoreEnvironmentPanel({ request, storageKey, workspace, workspaceHref }) {
+    const [environments, setEnvironments] = useState([]);
+    const [apps, setApps] = useState({});
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState("");
+    const [readError, setReadError] = useState("");
+    const [notice, setNotice] = useState("");
+    const [busy, setBusy] = useState(false);
+    const [pending, setPending] = useState(null);
+    const pendingRef = useRef(null);
+    const active = useRef(true);
+    const refreshSequence = useRef(0);
+    const [removing, setRemoving] = useState(null);
+    const [creating, setCreating] = useState(false);
+    const savePending = useCallback((value) => {
+        // Do not send a mutation if its replay identity cannot be persisted.
+        if (value)
+            sessionStorage.setItem(storageKey, JSON.stringify(value));
+        else
+            sessionStorage.removeItem(storageKey);
+        pendingRef.current = value;
+        if (active.current)
+            setPending(value);
+    }, [storageKey]);
+    const refresh = useCallback(async (signal) => {
+        const sequence = ++refreshSequence.current;
+        try {
+            const result = await request("", undefined, signal);
+            if (signal?.aborted || !active.current || sequence !== refreshSequence.current)
+                return;
+            const selected = result.environments.filter(e => !workspace || e.context?.workspaceId === workspace.id);
+            setEnvironments(selected.filter(e => e.state !== "finished"));
+            setLoading(false);
+            setReadError("");
+            const saved = pendingRef.current;
+            if (saved?.id) {
+                const item = selected.find(e => e.id === saved.id);
+                const operation = item?.operations.find(o => o.id.replaceAll("-", "") === String(saved.body.requestId).replaceAll("-", ""));
+                if (operation && ["succeeded", "failed"].includes(operation.state)) {
+                    const superseded = operation !== item?.operations.at(-1);
+                    if (operation.state === "succeeded" || saved.kind !== "finish" || superseded)
+                        savePending(null);
+                    setError(operation.state === "failed" ? item?.error ?? "Sandbox operation failed." : "");
+                    if (item?.state === "finished")
+                        setNotice("Sandbox deleted. Workspace source is preserved.");
+                    else if (superseded)
+                        setNotice("A newer operation replaced the previous request. Review the current sandbox status.");
+                }
+            }
+            const results = await Promise.all(selected.filter(e => e.state === "running").map(async (e) => {
+                try {
+                    return [e.id, await request(`/${e.id}/apps`, undefined, signal)];
+                }
+                catch (cause) {
+                    return [e.id, { state: "unavailable", apps: [], error: message(cause) }];
+                }
+            }));
+            if (!signal?.aborted && active.current && sequence === refreshSequence.current)
+                setApps(Object.fromEntries(results));
+        }
+        catch (cause) {
+            if (!signal?.aborted && active.current && sequence === refreshSequence.current) {
+                setEnvironments([]);
+                setApps({});
+                setLoading(false);
+                setReadError(message(cause));
+            }
+        }
+    }, [request, workspace, savePending]);
+    useEffect(() => {
+        active.current = true;
+        const controller = new AbortController();
+        try {
+            const saved = JSON.parse(sessionStorage.getItem(storageKey) ?? "null");
+            if (saved && /^\/(?:from-workspace|[a-f0-9]{32}\/operations\/(?:start|stop|restart|finish))$/.test(saved.path)
+                && typeof saved.body?.requestId === "string") {
+                pendingRef.current = saved;
+                setPending(saved);
+                setNotice("A previous request needs confirmation. Refresh or retry the same request.");
+            }
+        }
+        catch {
+            setError("Cannot read the saved sandbox request.");
+        }
+        let polling = false;
+        async function poll() {
+            if (polling)
+                return;
+            polling = true;
+            try {
+                await refresh(controller.signal);
+            }
+            finally {
+                polling = false;
+            }
+        }
+        void poll();
+        const timer = setInterval(() => { if (document.visibilityState === "visible")
+            void poll(); }, 5000);
+        return () => { active.current = false; controller.abort(); clearInterval(timer); };
+    }, [refresh, storageKey]);
+    async function run(value) {
+        setBusy(true);
+        setError("");
+        try {
+            savePending(value);
+            const result = await request(value.path, value.body);
+            if (value.kind !== "finish" || result.state === "finished")
+                savePending(null);
+            if (result.error)
+                throw new Error(result.error);
+            if (result.state === "finished")
+                setNotice("Sandbox deleted. Workspace source is preserved.");
+            else
+                setNotice("");
+            await refresh();
+            return result;
+        }
+        catch (cause) {
+            const status = cause.status;
+            if (status && status >= 400 && status < 500)
+                savePending(null);
+            if (active.current)
+                setError(message(cause));
+            return null;
+        }
+        finally {
+            if (active.current)
+                setBusy(false);
+        }
+    }
+    async function command(item, kind) {
+        return run({ path: `/${item.id}/operations/${kind}`, body: { requestId: crypto.randomUUID(), expectedRevision: item.revision }, id: item.id, kind });
+    }
+    async function create(body) {
+        const created = await run({ path: "/from-workspace", body: { ...body, requestId: crypto.randomUUID() }, kind: "create" });
+        if (created) {
+            if (active.current) {
+                setCreating(false);
+                await command(created, "start");
+            }
+        }
+    }
+    const disabled = busy || pending !== null;
+    return _jsxs("section", { className: "space-y-4 rounded-lg border bg-card p-4", "aria-label": "Sandbox environments", children: [_jsxs("header", { className: "flex flex-wrap items-center justify-between gap-3", children: [_jsxs("div", { children: [_jsx("h3", { className: "font-semibold", children: "Sandbox environments" }), _jsx("p", { className: "text-sm text-muted-foreground", children: "Separate Core instances with their own apps, users and temporary data." })] }), _jsxs("div", { className: "flex gap-2", children: [_jsx("button", { className: button, onClick: () => { setError(""); void refresh(); }, children: "Refresh sandboxes" }), workspace && _jsx("button", { className: button, disabled: disabled || !workspace.worktrees.some(t => t.state === "active"), onClick: () => setCreating(!creating), children: "Create sandbox" })] })] }), creating && workspace && _jsx(CreateEnvironment, { workspace: workspace, disabled: disabled, onCreate: create, onCancel: () => setCreating(false) }), notice && _jsx("p", { role: "status", className: "text-sm text-muted-foreground", children: notice }), (error || readError) && _jsx("p", { role: "alert", className: "text-sm text-destructive", children: error || readError }), pending && _jsxs("div", { className: "flex items-center gap-3 text-sm", children: [_jsx("span", { children: busy ? `Sandbox ${pending.kind} is in progress…` : "The request outcome is not confirmed." }), _jsx("button", { className: button, disabled: busy, onClick: () => void run(pending), children: "Retry same request" })] }), loading ? _jsx("p", { role: "status", className: "text-sm text-muted-foreground", children: "Loading sandboxes\u2026" }) : !environments.length && !error && !readError && _jsx("p", { className: "text-sm text-muted-foreground", children: "No active sandbox environments." }), environments.map(item => _jsxs("article", { className: "space-y-3 rounded-md border p-3", "aria-label": `Sandbox ${item.label}`, children: [_jsxs("header", { className: "flex flex-wrap items-start justify-between gap-3", children: [_jsxs("div", { children: [_jsxs("h4", { className: "font-medium", children: [item.label, " ", _jsx("span", { className: "ml-2 rounded border px-2 py-0.5 text-xs font-normal", children: item.state })] }), _jsxs("p", { className: "mt-1 text-xs text-muted-foreground", children: [item.mode === "source" ? "Core built from workspace source" : item.mode === "release" ? "Installed Core release" : "Current Core build", item.context?.workspaceId && workspaceHref && _jsxs(_Fragment, { children: [" \u00B7 ", _jsx("a", { className: "underline", href: workspaceHref(item.context.workspaceId), children: "Open workspace" })] })] })] }), _jsxs("div", { className: "flex flex-wrap gap-2", children: [item.state === "running" && link(item.previewUrl) && _jsx("a", { className: button, href: item.previewUrl + "/login", target: "_blank", rel: "noreferrer", children: "Open Core" }), _jsx("button", { className: button, disabled: disabled || ["building", "starting", "stopping", "finishing", "cleanup-failed"].includes(item.state), onClick: () => void command(item, item.state === "running" ? "stop" : "start"), children: item.state === "running" ? "Stop" : "Start" }), _jsx("button", { className: button + " text-destructive", disabled: disabled || item.state === "finishing", onClick: () => setRemoving(item.id), children: item.state === "cleanup-failed" ? "Retry deletion" : "Delete sandbox" })] })] }), item.limits && _jsxs("p", { className: "text-xs text-muted-foreground", children: ["Reserved: ", (item.limits.memoryBytes / 1073741824).toFixed(1), " GiB container memory \u00B7 ", item.limits.cpus, " CPUs \u00B7 ", item.limits.pids, " PIDs \u00B7 ", (item.limits.diskBytes / 1073741824).toFixed(1), " GiB soft disk limit. Released after deletion."] }), item.usage && _jsx("p", { className: "text-xs text-muted-foreground", children: item.usage.state === "unknown" ? "Resource usage unavailable; the reservation remains active." : `Observed: ${(item.usage.containerMemoryBytes / 1048576).toFixed(0)} MiB containers · ${(item.usage.coreMemoryBytes / 1048576).toFixed(0)} MiB Core process · ${(item.usage.ownedDiskBytes / 1073741824).toFixed(2)} GiB owned data.` }), item.error && _jsx("p", { role: "alert", className: "text-sm text-destructive", children: item.error }), item.state === "running" && _jsxs(_Fragment, { children: [_jsx(EnvironmentApplications, { value: apps[item.id] }), apps[item.id] && ["setup-required", "sign-in-required"].includes(apps[item.id].state) && _jsx(SetupAccount, { request: request, id: item.id, disabled: disabled, onDone: () => refresh() })] }), removing === item.id && _jsxs("div", { role: "alertdialog", "aria-label": `Delete ${item.label}`, className: "space-y-3 rounded-md border border-destructive p-3", children: [_jsx("p", { className: "text-sm", children: "Permanently delete this sandbox, all its apps, test users, data and caches? Workspace source and shared folders are preserved." }), _jsxs("div", { className: "flex gap-2", children: [_jsx("button", { className: button + " text-destructive", disabled: disabled, onClick: () => { setRemoving(null); void command(item, "finish"); }, children: "Delete permanently" }), _jsx("button", { className: button, onClick: () => setRemoving(null), children: "Cancel" })] })] })] }, item.id))] });
+}
+function EnvironmentApplications({ value }) {
+    if (!value)
+        return _jsx("p", { role: "status", className: "text-sm text-muted-foreground", children: "Reading application status\u2026" });
+    if (value.state !== "ready")
+        return _jsx("p", { role: "status", className: "text-sm text-muted-foreground", children: value.error ?? (value.state === "setup-required" ? "Set up a test administrator for this fresh Core." : "Application status is unavailable.") });
+    if (!value.apps.length)
+        return _jsx("p", { className: "text-sm text-muted-foreground", children: "No apps installed in this sandbox yet." });
+    return _jsx("ul", { className: "divide-y", "aria-label": "Sandbox applications", children: value.apps.map(app => _jsxs("li", { className: "flex flex-wrap items-center justify-between gap-3 py-2 text-sm", children: [_jsxs("div", { children: [_jsx("span", { className: "font-medium", children: app.displayName }), _jsxs("span", { className: "ml-2 text-muted-foreground", children: [app.runtimeState, " \u00B7 ", app.health ?? "Health unknown"] })] }), app.runtimeState === "running" && link(app.previewUrl) && _jsxs("a", { className: button, href: app.previewUrl, target: "_blank", rel: "noreferrer", children: ["Open preview", _jsxs("span", { className: "sr-only", children: [" for ", app.displayName] })] })] }, app.id)) });
+}
+function CreateEnvironment({ workspace, disabled, onCreate, onCancel }) {
+    const trees = workspace.worktrees.filter(t => t.state === "active");
+    const [selected, setSelected] = useState(trees.slice(0, 16).map(t => t.id));
+    const [source, setSource] = useState(false);
+    function submit(event) {
+        event.preventDefault();
+        const form = new FormData(event.currentTarget);
+        void onCreate({ label: form.get("label"), workspaceId: workspace.id, worktreeIds: selected,
+            ...(source ? { coreWorktreeId: form.get("coreWorktreeId"), coreProject: form.get("coreProject") } : {}) });
+    }
+    return _jsxs("form", { onSubmit: submit, className: "space-y-3 rounded-md border bg-muted/30 p-3", "aria-label": "Create workspace sandbox", children: [_jsxs("label", { className: "block space-y-1 text-sm", children: ["Sandbox name", _jsx("input", { className: field, name: "label", required: true, maxLength: 120, defaultValue: "Workspace sandbox" })] }), _jsxs("fieldset", { className: "space-y-2", children: [_jsx("legend", { className: "text-sm font-medium", children: "Attached worktrees" }), trees.map(t => _jsxs("label", { className: "flex gap-2 text-sm", children: [_jsx("input", { type: "checkbox", checked: selected.includes(t.id), onChange: e => setSelected(old => e.target.checked ? [...old, t.id] : old.filter(id => id !== t.id)) }), t.label] }, t.id))] }), _jsxs("label", { className: "flex gap-2 text-sm", children: [_jsx("input", { type: "checkbox", checked: source, onChange: e => setSource(e.target.checked) }), "Build Core from a worktree"] }), source && _jsxs("div", { className: "grid gap-3 sm:grid-cols-2", children: [_jsxs("label", { className: "space-y-1 text-sm", children: ["Core worktree", _jsx("select", { className: field, name: "coreWorktreeId", required: true, children: trees.filter(t => selected.includes(t.id)).map(t => _jsx("option", { value: t.id, children: t.label }, t.id)) })] }), _jsxs("label", { className: "space-y-1 text-sm", children: ["Core project, relative to worktree", _jsx("input", { className: field, name: "coreProject", required: true, defaultValue: "apps/core/src/Haas.Hosty.Core/Haas.Hosty.Core.csproj" })] })] }), _jsx("p", { className: "text-xs text-muted-foreground", children: "Starts a fresh Core with separate users and data. Attached worktrees stay available until the sandbox is deleted." }), _jsxs("div", { className: "flex gap-2", children: [_jsx("button", { className: button, type: "submit", disabled: disabled || selected.length === 0 || selected.length > 16, children: "Create and start" }), _jsx("button", { className: button, type: "button", onClick: onCancel, children: "Cancel" })] })] });
+}
+function SetupAccount({ request, id, disabled, onDone }) {
+    const [error, setError] = useState("");
+    const [busy, setBusy] = useState(false);
+    async function submit(event) {
+        event.preventDefault();
+        const form = event.currentTarget;
+        const data = new FormData(form);
+        setBusy(true);
+        setError("");
+        try {
+            const result = await request(`/${id}/setup`, { email: data.get("email"), displayName: data.get("displayName"), password: data.get("password") });
+            if (result.status !== 200)
+                throw new Error(result.body?.message ?? "Sandbox account setup failed.");
+            await onDone();
+        }
+        catch (cause) {
+            setError(message(cause));
+        }
+        finally {
+            form.elements.namedItem("password").value = "";
+            setBusy(false);
+        }
+    }
+    return _jsxs("form", { onSubmit: submit, "aria-label": "Sandbox administrator", className: "space-y-3 rounded-md border p-3", children: [_jsx("p", { className: "text-sm", children: "Use a separate sandbox administrator. For an existing Core, enter its current account. Parent credentials are not copied." }), _jsxs("div", { className: "grid gap-3 sm:grid-cols-3", children: [_jsxs("label", { className: "text-sm", children: ["Display name", _jsx("input", { className: field, name: "displayName", required: true, autoComplete: "off" })] }), _jsxs("label", { className: "text-sm", children: ["Test email", _jsx("input", { className: field, type: "email", name: "email", required: true, autoComplete: "off" })] }), _jsxs("label", { className: "text-sm", children: ["Test password", _jsx("input", { className: field, type: "password", name: "password", minLength: 12, required: true, autoComplete: "new-password" })] })] }), error && _jsx("p", { role: "alert", className: "text-sm text-destructive", children: error }), _jsx("button", { className: button, disabled: disabled || busy, children: busy ? "Connecting…" : "Connect test account" })] });
+}

package/dist/sandbox-server.d.ts

@@ -0,0 +1,180 @@
+import type { ProviderServerOptions } from "./providers-server.js";
+export type SandboxSource = {
+    kind: "worktree";
+    worktreeId: string;
+} | {
+    kind: "appArtifact";
+    artifactDigest?: string;
+};
+export interface SandboxLimits {
+    memoryBytes?: number;
+    cpus?: number;
+    pids?: number;
+    dataBytes?: number;
+    cacheBytes?: number;
+    startupSeconds?: number;
+}
+export interface SandboxContext {
+    workspaceId?: string;
+    sessionId?: string;
+    jobId?: string;
+}
+export interface SandboxPlanInput {
+    appId: string;
+    profile: string;
+    source: SandboxSource;
+    limits?: SandboxLimits;
+    context?: SandboxContext;
+}
+export interface SandboxPlan {
+    id: string;
+    digest: string;
+    inputDigest: string;
+    request: SandboxPlanInput;
+    blockers: string[];
+    expiresAt: string;
+}
+export interface SandboxOperation {
+    id: string;
+    kind: string;
+    state: string;
+    errorCode?: string;
+    message?: string;
+}
+export interface SandboxUser {
+    id: string;
+    fixtureKey: string;
+    displayName: string;
+    role: string;
+    permissions: string[];
+    enabled: boolean;
+    revision: number;
+}
+export interface SandboxInstance {
+    id: string;
+    appId: string;
+    source: SandboxSource;
+    context?: SandboxContext;
+    revision: number;
+    generation: string;
+    dataRevision: string;
+    state: string;
+    previewUrl?: string;
+    errorCode?: string;
+    operations: SandboxOperation[];
+    users: SandboxUser[];
+    viewers?: string[];
+    endpoints?: {
+        key: string;
+        url: string;
+    }[];
+    metrics?: {
+        at: string;
+        memoryBytes: number | null;
+        sampledPeakMemoryBytes: number | null;
+        services: {
+            service: string;
+            memoryBytes: number | null;
+            cpuPercent: number | null;
+        }[];
+    };
+    storage?: {
+        at: string;
+        dataBytes: number;
+        seedBytes: number;
+        cacheBytes: number;
+        evidenceBytes: number;
+        totalBytes: number;
+        warning: boolean;
+        errorCode?: string;
+    };
+}
+export interface SandboxDiagnostics {
+    instanceId: string;
+    state: string;
+    errorCode?: string;
+    services: {
+        service: string;
+        state: string;
+        text: string;
+    }[];
+}
+export declare const sandboxActions: readonly ["sandbox-logs", "sandbox-plan", "sandbox-prepare", "sandbox-list", "sandbox-status", "sandbox-users", "sandbox-seed", "sandbox-start", "sandbox-restart", "sandbox-stop", "sandbox-reset", "sandbox-dispose", "sandbox-browser", "sandbox-export", "sandbox-user-delete", "sandbox-viewers", "sandbox-evidence-clear", "sandbox-preview", "sandbox-browser-cancel"];
+export type SandboxAction = typeof sandboxActions[number];
+export declare class SandboxError extends Error {
+    readonly code: string;
+    readonly status: number | null;
+    constructor(code: string, message: string, status: number | null);
+}
+/** Server-only transport. The authority callback can supply an interactive grant or an explicitly
+ * approved BackgroundGrantClient.token(); neither workspaces nor assistant roles are required. */
+export declare class SandboxClient {
+    private readonly authority;
+    private readonly origin;
+    private readonly appId;
+    private readonly service;
+    constructor(authority: () => Promise<string>, options?: ProviderServerOptions);
+    plan(input: SandboxPlanInput): Promise<SandboxPlan>;
+    prepare(input: {
+        requestId: string;
+        planId: string;
+        digest: string;
+    }): Promise<SandboxInstance>;
+    list(): Promise<{
+        instances: SandboxInstance[];
+    }>;
+    status(runtimeInstanceId: string): Promise<SandboxInstance>;
+    command(runtimeInstanceId: string, action: "start" | "restart" | "stop" | "reset" | "dispose", input: {
+        requestId: string;
+        expectedRevision: number;
+        seedRevision?: string;
+    }): Promise<SandboxInstance>;
+    call<T = unknown>(action: SandboxAction, input: Record<string, unknown>): Promise<T>;
+}
+export declare const coreEnvironmentActions: readonly ["environment-create", "environment-list", "environment-status", "environment-start", "environment-stop", "environment-restart", "environment-finish", "environment-setup", "environment-api"];
+export type CoreEnvironmentAction = typeof coreEnvironmentActions[number];
+export interface CoreEnvironment {
+    id: string;
+    label: string;
+    mode: string;
+    projectPath?: string;
+    context?: SandboxContext;
+    state: string;
+    revision: number;
+    port: number;
+    dataRoot?: string;
+    previewUrl: string;
+    process?: {
+        pid: number;
+        startedAt: string;
+    };
+    error?: string;
+    operations: SandboxOperation[];
+    limits?: {
+        memoryBytes: number;
+        cpus: number;
+        pids: number;
+        diskBytes: number;
+        applicationMemoryBytes: number;
+        applicationCpus: number;
+        applicationPids: number;
+    };
+    usage?: {
+        ownedDiskBytes: number;
+        containerMemoryBytes: number;
+        coreMemoryBytes: number;
+        state: string;
+        observedAt: string;
+        error?: string;
+    };
+}
+/** Full child Core transport. Requires core.environments permissions and live administrator authority.
+ * Setup uses ordinary password authentication. Parent credentials are never forwarded to the child. */
+export declare class CoreEnvironmentClient {
+    private readonly authority;
+    private readonly origin;
+    private readonly appId;
+    private readonly service;
+    constructor(authority: () => Promise<string>, options?: ProviderServerOptions);
+    call<T = unknown>(action: CoreEnvironmentAction, input: Record<string, unknown>): Promise<T>;
+}

package/dist/sandbox-server.js

@@ -0,0 +1,147 @@
+export const sandboxActions = ["sandbox-logs", "sandbox-plan", "sandbox-prepare", "sandbox-list", "sandbox-status", "sandbox-users", "sandbox-seed",
+    "sandbox-start", "sandbox-restart", "sandbox-stop", "sandbox-reset", "sandbox-dispose", "sandbox-browser", "sandbox-export", "sandbox-user-delete", "sandbox-viewers", "sandbox-evidence-clear", "sandbox-preview", "sandbox-browser-cancel"];
+export class SandboxError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "SandboxError";
+    }
+}
+/** Server-only transport. The authority callback can supply an interactive grant or an explicitly
+ * approved BackgroundGrantClient.token(); neither workspaces nor assistant roles are required. */
+export class SandboxClient {
+    authority;
+    origin;
+    appId;
+    service;
+    constructor(authority, options = {}) {
+        this.authority = authority;
+        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 || !["http:", "https:"].includes(this.origin.protocol) || this.origin.username || this.origin.password
+            || this.origin.pathname !== "/" || this.origin.search || this.origin.hash)
+            throw new Error("A valid Core origin and calling app service identity are required.");
+    }
+    plan(input) { return this.call("sandbox-plan", input); }
+    prepare(input) { return this.call("sandbox-prepare", input); }
+    list() { return this.call("sandbox-list", {}); }
+    status(runtimeInstanceId) { return this.call("sandbox-status", { runtimeInstanceId }); }
+    command(runtimeInstanceId, action, input) {
+        return this.call(`sandbox-${action}`, { runtimeInstanceId, ...input });
+    }
+    async call(action, input) {
+        if (!sandboxActions.includes(action))
+            throw new SandboxError("sandbox_operation_invalid", "Unknown sandbox operation.", 400);
+        const { runtimeInstanceId, ...body } = input;
+        const jobId = body.jobId;
+        const root = `/api/internal/apps/${encodeURIComponent(this.appId)}/sandbox-instances`;
+        const read = action === "sandbox-logs" || action === "sandbox-list" || action === "sandbox-status" || action === "sandbox-export" || action === "sandbox-preview";
+        let suffix = "";
+        if (action === "sandbox-plan")
+            suffix = "/plans";
+        else if (action !== "sandbox-list" && action !== "sandbox-prepare") {
+            if (typeof runtimeInstanceId !== "string" || !/^[a-f0-9]{32}$/.test(runtimeInstanceId))
+                throw new SandboxError("sandbox_id_invalid", "Use the Core-issued runtime instance ID.", 400);
+            suffix = `/${runtimeInstanceId}`;
+            if (action === "sandbox-logs")
+                suffix += "/diagnostics";
+            else if (action === "sandbox-users")
+                suffix += "/users";
+            else if (action === "sandbox-user-delete")
+                suffix += "/users/delete";
+            else if (action === "sandbox-viewers")
+                suffix += "/viewers";
+            else if (action === "sandbox-evidence-clear")
+                suffix += "/evidence/clear";
+            else if (action === "sandbox-seed")
+                suffix += "/seeds";
+            else if (action === "sandbox-browser")
+                suffix += "/browser-runs";
+            else if (action === "sandbox-browser-cancel")
+                suffix += "/browser-runs/cancel";
+            else if (action === "sandbox-preview")
+                suffix += "/preview" + (typeof body.userId === "string" ? "?userId=" + encodeURIComponent(body.userId) : "");
+            else if (action === "sandbox-export") {
+                if (typeof jobId !== "string" || !/^[a-f0-9]{32}$/.test(jobId))
+                    throw new SandboxError("sandbox_job_invalid", "Select a recorded browser run.", 400);
+                suffix += `/browser-runs/${jobId}`;
+            }
+            else if (!read)
+                suffix += `/operations/${action.slice("sandbox-".length)}`;
+        }
+        if (!read && action !== "sandbox-plan" && (typeof body.requestId !== "string" || !/^[a-f0-9-]{32,36}$/i.test(body.requestId)))
+            throw new SandboxError("sandbox_request_required", "Persist a request UUID before sending a mutation. Replay the same UUID and arguments after an uncertain result.", 400);
+        const credential = await this.authority();
+        let response;
+        try {
+            response = await fetch(new URL(root + suffix, this.origin), { method: read ? "GET" : "POST", redirect: "error", cache: "no-store",
+                headers: { authorization: `Bearer ${this.service}`, "X-Hosty-User-Token": credential, "content-type": "application/json" },
+                body: read ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(action === "sandbox-browser" ? 330_000 : 180_000) });
+        }
+        catch {
+            throw new SandboxError("sandbox_outcome_unknown", "Core could not confirm the outcome. Read the operation or replay its original request UUID and arguments.", null);
+        }
+        const result = await response.json().catch(() => null);
+        if (!result)
+            throw new SandboxError("sandbox_outcome_unknown", "Core returned no readable outcome; keep the original operation identity.", response.status);
+        if (!response.ok)
+            throw new SandboxError(result.code ?? "sandbox_failed", result.message ?? "Sandbox request failed.", response.status);
+        return result;
+    }
+}
+export const coreEnvironmentActions = ["environment-create", "environment-list", "environment-status", "environment-start",
+    "environment-stop", "environment-restart", "environment-finish", "environment-setup", "environment-api"];
+/** Full child Core transport. Requires core.environments permissions and live administrator authority.
+ * Setup uses ordinary password authentication. Parent credentials are never forwarded to the child. */
+export class CoreEnvironmentClient {
+    authority;
+    origin;
+    appId;
+    service;
+    constructor(authority, options = {}) {
+        this.authority = authority;
+        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 || !["http:", "https:"].includes(this.origin.protocol) || this.origin.username || this.origin.password
+            || this.origin.pathname !== "/" || this.origin.search || this.origin.hash)
+            throw new Error("Core origin and app service identity are required.");
+    }
+    async call(action, input) {
+        if (!coreEnvironmentActions.includes(action))
+            throw new SandboxError("environment_operation_invalid", "Unknown environment operation.", 400);
+        const { environmentId, ...body } = input;
+        const read = action === "environment-list" || action === "environment-status";
+        let suffix = "";
+        if (action !== "environment-list" && action !== "environment-create") {
+            if (typeof environmentId !== "string" || !/^[a-f0-9]{32}$/.test(environmentId))
+                throw new SandboxError("environment_id_invalid", "Select a Core-issued environment ID.", 400);
+            suffix = `/${environmentId}` + (action === "environment-status" ? "" : action === "environment-api" ? "/api"
+                : action === "environment-setup" ? "/setup" : `/operations/${action.slice("environment-".length)}`);
+        }
+        const replayable = !read && action !== "environment-api" && action !== "environment-setup";
+        if (replayable && (typeof body.requestId !== "string" || !/^[a-f0-9-]{32,36}$/i.test(body.requestId)))
+            throw new SandboxError("environment_request_required", "Persist a request UUID before sending lifecycle operations.", 400);
+        let response;
+        try {
+            response = await fetch(new URL(`/api/internal/apps/${encodeURIComponent(this.appId)}/core-environments${suffix}`, this.origin), {
+                method: read ? "GET" : "POST", redirect: "error", cache: "no-store",
+                headers: { authorization: `Bearer ${this.service}`, "X-Hosty-User-Token": await this.authority(), "content-type": "application/json" },
+                body: read ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(490_000),
+            });
+        }
+        catch {
+            throw new SandboxError("environment_outcome_unknown", "Core did not confirm the outcome. Observe state; replay lifecycle UUIDs unchanged. Child API mutations follow their own recovery contract.", null);
+        }
+        const result = await response.json().catch(() => null);
+        if (!result)
+            throw new SandboxError("environment_outcome_unknown", "Core returned no readable outcome.", response.status);
+        if (!response.ok)
+            throw new SandboxError(result.code ?? "environment_failed", result.message ?? "Environment request failed.", response.status);
+        return result;
+    }
+}

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import "server-only";
+import { type SandboxIdentityContext } from "./index.js";
 import { type AppContinuity } from "./continuity.js";
 import { type AppAuthProtocol } from "./app-code.js";
 export { isValidCodeVerifier } from "./app-code.js";
@@ -27,6 +28,8 @@ export interface HostIdentity {
     activeUntil?: string | null;
     activityRequired?: boolean;
     continuity?: AppContinuity;
+    /** Present for every identity (including real viewers) acting inside a sandbox. */
+    sandbox?: SandboxIdentityContext;
 }
 /** 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

package/dist/server.js

@@ -1,6 +1,7 @@
 // Server slice: Next route-handler factories and Core revalidation. Never reaches a client
 // bundle — the service token lives here.
 import "server-only";
+import { readSandboxTarget, readSandboxIdentity } from "./index.js";
 import { readAppContinuity } from "./continuity.js";
 import { createHostySessionResponse } from "./session-server.js";
 import { createHostyUiResponse } from "./ui-server.js";
@@ -67,6 +68,8 @@ export function readAppIdentityToken(headers, config) {
             return token;
         }
     }
+    if (process.env.HOSTY_SANDBOX_PROTOCOL)
+        return headers.get(HOSTY_APP_IDENTITY_HEADER)?.trim() || readCookie(headers.get("cookie"), config.identityCookieName) || null;
     return readCookie(headers.get("cookie"), config.identityCookieName) || headers.get(HOSTY_APP_IDENTITY_HEADER)?.trim() || null;
 }
 /** True when the effective request protocol is https (honouring the forwarded proto). */
@@ -119,7 +122,8 @@ export async function resolveAppSession(token, config) {
         };
     }
     const now = Date.now();
-    const cached = revalidationCache.get(token);
+    // Synthetic subject changes and instance revocation are checked online on every request.
+    const cached = process.env.HOSTY_SANDBOX_PROTOCOL ? undefined : revalidationCache.get(token);
     if (cached) {
         if (now - cached.cachedAt < REVALIDATION_CACHE_TTL_MS && now < cached.expiresAtMs) {
             return { status: "active", identity: cached.identity };
@@ -211,6 +215,13 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
     if (!payload || payload.active !== true || !userId) {
         return { status: "expired" };
     }
+    let sandbox;
+    try {
+        sandbox = readSandboxIdentity(payload, readSandboxTarget(process.env));
+    }
+    catch {
+        return { status: "forbidden", error: { status: 403, code: "sandbox_identity_mismatch", message: "The identity does not match this execution target." } };
+    }
     const hostRole = readString(payload.hostRole);
     const expiresAt = readString(payload.expiresAt);
     const identity = {
@@ -218,14 +229,15 @@ async function revalidateWithCore(token, coreOrigin, serviceToken, config) {
         email: readString(payload.email),
         displayName: readString(payload.displayName),
         hostRole,
-        appRole: config.mapHostRole ? config.mapHostRole(hostRole) : hostRole,
+        appRole: sandbox?.identityRealm === "sandbox" ? sandbox.appRole : config.mapHostRole ? config.mapHostRole(hostRole) : hostRole,
         expiresAt,
         activeUntil: readString(payload.activeUntil),
         activityRequired: payload.activityRequired === true,
         continuity: readAppContinuity(payload.continuity),
+        ...(sandbox ? { sandbox } : {}),
     };
     const expiresAtMs = expiresAt ? Date.parse(expiresAt) : Number.NaN;
-    if (Number.isFinite(expiresAtMs) && expiresAtMs > Date.now()) {
+    if (!sandbox && Number.isFinite(expiresAtMs) && expiresAtMs > Date.now()) {
         pruneRevalidationCache();
         revalidationCache.set(token, { identity, expiresAtMs, cachedAt: Date.now() });
     }

package/dist/session-server.d.ts

@@ -1,5 +1,6 @@
 import { type ProviderServerOptions } from "@hosty-sdk/app/providers/server";
 import type { AppSessionStatus, SessionRecoveryParams } from "./session-types.js";
+import type { SandboxIdentityContext } from "./sandbox-identity.js";
 import type { AppContinuity } from "./continuity.js";
 /** Framework-neutral server adapter. Call with an already authenticated app session, never request data. */
 export type HostySessionInput = {
@@ -10,6 +11,7 @@ export type HostySessionInput = {
         activeUntil?: string | null;
         activityRequired?: boolean;
         continuity?: AppContinuity;
+        sandbox?: SandboxIdentityContext;
     };
     error?: {
         code: string;

package/dist/session-server.js

@@ -7,6 +7,12 @@ export async function createHostySessionResponse(session, recovery, options = {}
     const identity = session.identity;
     if (options.administratorOnly && identity.hostRole !== "host.admin")
         return Response.json({ status: "forbidden", recovery }, { headers });
+    if (identity.sandbox) {
+        // Core admits only recipes without required global permissions in this offline profile.
+        // The revalidated execution identity is authoritative; never query the installed app's
+        // permission state or advertise a global permission-review action from a test realm.
+        return Response.json({ status: "active", ...identity, recovery, hosty: { version: 1, setup: "ready" } }, { headers });
+    }
     let setup = "unavailable";
     let notice;
     try {

package/dist/ui-server.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxIdentityContext } from "./sandbox-identity.js";
 import type { ProviderServerOptions } from "@hosty-sdk/app/providers/server";
 import { type PanelTarget, type UiBootstrap, type UiPanel, type UiResolvedPanel, type UiNavigationCatalog, type UiNavigationTarget, type UiResolvedNavigation } from "@hosty-sdk/app/ui/types";
 /** Server transport for generic UI metadata. Credentials never appear in returned metadata. */
@@ -20,6 +21,7 @@ type UiAuthenticatedContext = {
         status: "active";
         identity: {
             hostRole: string | null;
+            sandbox?: SandboxIdentityContext;
         };
     } | {
         status: "not-present" | "expired" | "forbidden" | "unavailable" | "misconfigured";

package/dist/ui-server.js

@@ -55,6 +55,8 @@ export async function createHostyUiResponse(request, context, options = {}) {
         }
         if (options.administratorOnly && context.session.identity.hostRole !== "host.admin")
             throw new UiError("admin_required", "This application requires administrator access.", 403);
+        if (context.session.identity.sandbox)
+            throw new UiError("unsupported_sandbox_ui", "Global application panels are unavailable inside this sandbox profile.", 409);
         const url = new URL(request.url);
         const prefix = (options.uiPath ?? "/api/hosty/ui").replace(/\/$/, "");
         const route = url.pathname.startsWith(prefix + "/") ? url.pathname.slice(prefix.length + 1) : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.27.24",
+  "version": "0.29.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -120,6 +120,14 @@
     "./next": {
       "types": "./dist/next.d.ts",
       "default": "./dist/next.js"
+    },
+    "./sandbox/server": {
+      "types": "./dist/sandbox-server.d.ts",
+      "default": "./dist/sandbox-server.js"
+    },
+    "./sandbox/react": {
+      "types": "./dist/sandbox-react.d.ts",
+      "default": "./dist/sandbox-react.js"
     }
   },
   "scripts": {