@hosty-sdk/app 0.14.0 → 0.16.1

package/README.md

@@ -180,3 +180,28 @@ an administrator browser login issued on a dedicated Core hostname, separate fro
 hosts. Existing sessions need a fresh login. Requests expire after 15 minutes and Core restart
 invalidates them. Closing your UI does not cancel a confirmed operation; status is the authority.
 Never automatically retry an execution after a lost response.
+
+## Assistant handoffs
+
+`@hosty-sdk/app/assistant` exposes the version-1 client. Discover the confirmed assistant's
+interface URL, version and capabilities through Core. Keep request and attachment identities
+until the operation is resolved; do not create a new ID after an uncertain response.
+
+```ts
+import { AssistantClient, createAssistantRequestId } from "@hosty-sdk/app/assistant";
+const client = new AssistantClient(interfaceUrl, { version: 1, capabilities: ["attachments"] }, issueToken);
+const requestId = createAssistantRequestId(); // persist with the intent before the first request
+const handoff = await client.prepare({ requestId, prompt: "Inspect this", appIds: [appId] });
+// Optional: client.upload(handoff.handoffId, stableAttachmentId, file, file.name, { signal })
+const finalized = await client.finalize(handoff.handoffId, []);
+// Validate result.open with resolveAssistantDestination against Core's declared UI surfaces.
+// Opening never submits the prompt again. client.status/cancel inspect or cancel preparations.
+```
+
+The receiver owns draft/immediate-start policy. `askAssistant(text)` remains the small embedded-app
+message helper; Shell turns that message into a handoff using its verified mounted app ID. Its boolean
+result reports message delivery to the embedder, not execution. Files use the separate `attachments`
+capability and raw upload API. See [the complete contract](../../docs/features/hosty-harness-rename/feature.md).
+
+Assistant control requests use a 60-second deadline. Uploads accept an optional caller-owned
+`AbortSignal` and have no SDK-imposed deadline, so slow valid transfers are not aborted after a minute.

package/dist/assistant.d.ts

@@ -0,0 +1,67 @@
+/** Version 1 of the manifest-discovered assistant handoff. */
+export type AssistantContract = {
+    version?: number | null;
+    capabilities?: readonly string[] | null;
+};
+export type AssistantDestination = {
+    endpoint: string;
+    path: string;
+};
+export type AssistantHandoffResult = {
+    conversationId: string;
+    disposition: "draft" | "accepted";
+    open: AssistantDestination;
+    dispatchId?: string;
+};
+export type AssistantHandoff = {
+    handoffId: string;
+    requestId: string;
+    conversationId: string;
+    state: "pending" | "finalized" | "cancelled" | "expired";
+    createdAt: string;
+    expiresAt: string;
+    replayUntil: string;
+    attachments: Array<{
+        attachmentId: string;
+        name: string;
+        mediaType: string;
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    limits?: {
+        maxFileBytes: number;
+        maxFiles: number;
+        maxTotalBytes: number;
+    };
+    result?: AssistantHandoffResult;
+    executionState?: "queued" | "running" | "completed" | "failed" | "unknown";
+};
+export declare function assistantContractError(contract: AssistantContract): string | null;
+/** Time-bearing request identities let a provider reject retries after replay records expire. */
+export declare function createAssistantRequestId(now?: number): string;
+/** Resolve only inside a declared UI surface on the selected app's resolved endpoint. */
+export declare function resolveAssistantDestination(destination: AssistantDestination, surfaces: readonly {
+    endpoint?: string | null;
+    path?: string | null;
+    url?: string | null;
+}[]): string;
+export declare class AssistantClient {
+    private readonly baseUrl;
+    private readonly contract;
+    private readonly token;
+    constructor(baseUrl: string, contract: AssistantContract, token: (refresh: boolean) => Promise<{
+        token: string;
+    }>);
+    private request;
+    prepare(input: {
+        requestId: string;
+        prompt: string;
+        appIds: string[];
+    }): Promise<AssistantHandoff>;
+    upload(handoffId: string, attachmentId: string, file: Blob, name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AssistantHandoff["attachments"][number]>;
+    finalize(handoffId: string, attachmentIds: string[]): Promise<AssistantHandoff>;
+    status(handoffId: string): Promise<AssistantHandoff>;
+    cancel(handoffId: string): Promise<AssistantHandoff>;
+}

package/dist/assistant.js

@@ -0,0 +1,79 @@
+export function assistantContractError(contract) {
+    return contract.version !== 1 || !Array.isArray(contract.capabilities)
+        ? "This assistant does not support the required assistant interface version 1." : null;
+}
+/** Time-bearing request identities let a provider reject retries after replay records expire. */
+export function createAssistantRequestId(now = Date.now()) {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    let time = now;
+    for (let i = 5; i >= 0; i--) {
+        bytes[i] = time % 256;
+        time = Math.floor(time / 256);
+    }
+    bytes[6] = (bytes[6] & 15) | 112;
+    bytes[8] = (bytes[8] & 63) | 128;
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** 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))
+        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.");
+    for (const surface of surfaces) {
+        if (surface.endpoint !== destination.endpoint || !surface.url)
+            continue;
+        const base = new URL(surface.url);
+        const url = new URL(destination.path, base.origin);
+        const root = new URL(surface.path || "/", base.origin).pathname.replace(/\/$/, "") || "/";
+        if (url.origin === base.origin && (root === "/" || url.pathname === root || url.pathname.startsWith(`${root}/`)))
+            return url.href;
+    }
+    throw new Error("The assistant returned a destination outside its declared UI.");
+}
+export class AssistantClient {
+    baseUrl;
+    contract;
+    token;
+    constructor(baseUrl, contract, token) {
+        this.baseUrl = baseUrl;
+        this.contract = contract;
+        this.token = token;
+    }
+    async request(route, init = {}, controlDeadline = true) {
+        const incompatible = assistantContractError(this.contract);
+        if (incompatible)
+            throw new Error(incompatible);
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const grant = await this.token(attempt > 0);
+            const headers = new Headers(init.headers);
+            headers.set("authorization", `Bearer ${grant.token}`);
+            if (typeof init.body === "string")
+                headers.set("content-type", "application/json");
+            const response = await fetch(`${this.baseUrl.replace(/\/$/, "")}${route}`, { ...init, headers, signal: init.signal ?? (controlDeadline ? AbortSignal.timeout(60_000) : undefined) });
+            if (response.status === 401 && attempt === 0)
+                continue;
+            const body = await response.json().catch(() => null);
+            if (!response.ok)
+                throw new Error(body?.message || `Assistant request failed (${response.status}).`);
+            return body;
+        }
+        throw new Error("Assistant authorization expired.");
+    }
+    prepare(input) {
+        return this.request("/handoffs", { method: "POST", body: JSON.stringify(input) });
+    }
+    upload(handoffId, attachmentId, file, name, options = {}) {
+        if (!this.contract.capabilities?.includes("attachments"))
+            throw new Error("This assistant does not support attachments.");
+        return this.request(`/handoffs/${encodeURIComponent(handoffId)}/attachments/${encodeURIComponent(attachmentId)}?name=${encodeURIComponent(name)}`, {
+            method: "PUT", body: file, signal: options.signal, headers: { "content-type": file.type || "application/octet-stream" },
+        }, false);
+    }
+    finalize(handoffId, attachmentIds) {
+        return this.request(`/handoffs/${encodeURIComponent(handoffId)}/finalize`, { method: "POST", body: JSON.stringify({ attachmentIds }) });
+    }
+    status(handoffId) { return this.request(`/handoffs/${encodeURIComponent(handoffId)}`); }
+    cancel(handoffId) { return this.request(`/handoffs/${encodeURIComponent(handoffId)}`, { method: "DELETE" }); }
+}

package/dist/index.d.ts

@@ -22,16 +22,10 @@ export declare function createAuthRequiredIntent(appId: string): AuthRequiredInt
  * one (Hosty Shell: the assistant gateway, which it already mints tokens for).
  */
 /**
- * An embedded app asking its embedder to put text in the assistant's draft.
- *
- * The embedder reveals its assistant surface and forwards the text there; the assistant fills the
- * **draft** and stops. Nothing is sent. That is the contract, not a UX choice: app-provided text
- * entering a model that holds host shell is the same trust boundary that keeps MCP providers off by
- * default, and an error message is exactly the shape a prompt injection arrives in. The operator
- * reads it, with its source shown, and decides.
- *
- * Plain text only, and no reply. A structured payload would invite apps to smuggle shape the
- * operator cannot read at a glance, and an answer would turn a hand-off into a channel.
+ * An embedded app handing text to the selected assistant through its embedder.
+ * The receiving assistant applies its own draft/immediate-start setting. Authentication
+ * and tool permissions still apply; the message does not prove prompt authorship.
+ * This small embedded channel carries plain text and has no execution-result reply.
  */
 export declare const ASK_ASSISTANT_TYPE = "hosty:ask-assistant";
 /**
@@ -49,7 +43,7 @@ export interface AskAssistantMessage {
     text: string;
 }
 /**
- * Asks the embedder to put `text` in the operator's assistant draft.
+ * Asks the embedder to hand `text` to the operator's selected assistant.
  *
  * Safe to call unconditionally: standalone there is no embedder to hear it, and an embedder that
  * does not offer an assistant simply ignores it. Returns whether the message could be posted at

package/dist/index.js

@@ -25,16 +25,10 @@ export function createAuthRequiredIntent(appId) {
  * one (Hosty Shell: the assistant gateway, which it already mints tokens for).
  */
 /**
- * An embedded app asking its embedder to put text in the assistant's draft.
- *
- * The embedder reveals its assistant surface and forwards the text there; the assistant fills the
- * **draft** and stops. Nothing is sent. That is the contract, not a UX choice: app-provided text
- * entering a model that holds host shell is the same trust boundary that keeps MCP providers off by
- * default, and an error message is exactly the shape a prompt injection arrives in. The operator
- * reads it, with its source shown, and decides.
- *
- * Plain text only, and no reply. A structured payload would invite apps to smuggle shape the
- * operator cannot read at a glance, and an answer would turn a hand-off into a channel.
+ * An embedded app handing text to the selected assistant through its embedder.
+ * The receiving assistant applies its own draft/immediate-start setting. Authentication
+ * and tool permissions still apply; the message does not prove prompt authorship.
+ * This small embedded channel carries plain text and has no execution-result reply.
  */
 export const ASK_ASSISTANT_TYPE = "hosty:ask-assistant";
 /**
@@ -47,7 +41,7 @@ export const ATTENTION_TYPE = "hosty:assistant-attention";
 /** Longer than a prompt fragment is a page dumping itself into someone's draft. */
 export const ASK_ASSISTANT_MAX_CHARS = 4000;
 /**
- * Asks the embedder to put `text` in the operator's assistant draft.
+ * Asks the embedder to hand `text` to the operator's selected assistant.
  *
  * Safe to call unconditionally: standalone there is no embedder to hear it, and an embedder that
  * does not offer an assistant simply ignores it. Returns whether the message could be posted at

package/dist/install-react.js

@@ -64,7 +64,7 @@ export function InstallDialog({ client, source, onClose, onInstalled }) {
         else
             popup?.close();
     };
-    return _jsxs("dialog", { ref: dialog, className: "hosty-install", "aria-labelledby": titleId, onCancel: event => { event.preventDefault(); onClose(); }, children: [_jsx("style", { children: styles }), _jsxs("header", { children: [_jsx("h2", { id: titleId, children: "Install app" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close installation", children: "\u00D7" })] }), _jsx("p", { children: "Prepare the installation here, then confirm it securely in Hosty Core." }), !source?.feedsUrl && !source?.manifestPath && _jsxs("form", { onSubmit: event => { event.preventDefault(); void review(); }, children: [_jsxs("label", { children: ["Manifest, app directory, or URL", _jsx("input", { value: manifestPath, onChange: event => { setManifestPath(event.target.value); flow.clearReview(); }, required: true, disabled: busy || frozen })] }), _jsx("button", { disabled: busy || frozen || !manifestPath.trim(), children: "Review" })] }), busy && _jsx("p", { role: "status", children: "Preparing installation\u2026" }), error && _jsxs("div", { role: "alert", children: [_jsx("p", { children: error }), !frozen && _jsx("button", { type: "button", disabled: busy, onClick: () => void review(), children: "Retry review" })] }), plan && _jsxs("form", { onSubmit: event => { event.preventDefault(); void submit(); }, children: [_jsxs("h3", { children: [plan.displayName, " ", _jsx("small", { children: plan.targetVersion })] }), plan.description && _jsx("p", { children: plan.description }), _jsxs("label", { children: ["Runtime", _jsx("select", { value: plan.targetRuntime, disabled: busy || frozen, onChange: event => void review(event.target.value), children: (plan.runtimeProfiles ?? [{ key: plan.targetRuntime, type: plan.targetRuntimeType }]).map(runtime => _jsxs("option", { value: runtime.key, children: [runtime.key, " (", runtime.type, ")"] }, runtime.key)) })] }), plan.targetRuntimeType === "localCommand" && _jsx("p", { className: "warning", children: "This runtime runs commands directly on your host, outside a container. Only install code you trust." }), plan.system && _jsx("p", { className: "warning", children: "This is a system app. Only host administrators can open it." }), !!plan.corePermissions?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested Core permissions" }), _jsx("ul", { children: plan.corePermissions.map(permission => _jsx("li", { children: permission }, permission)) })] }), plan.settings.map(setting => _jsxs("label", { children: [setting.label || setting.key, setting.required ? " (required)" : "", setting.type === "boolean" && !setting.secret
+    return _jsxs("dialog", { ref: dialog, className: "hosty-install", "aria-labelledby": titleId, onCancel: event => { event.preventDefault(); onClose(); }, children: [_jsx("style", { children: styles }), _jsxs("header", { children: [_jsx("h2", { id: titleId, children: "Install app" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close installation", children: "\u00D7" })] }), _jsx("p", { children: "Prepare the installation here, then confirm it securely in Hosty Core." }), !source?.feedsUrl && !source?.manifestPath && _jsxs("form", { onSubmit: event => { event.preventDefault(); void review(); }, children: [_jsxs("label", { children: ["Manifest, app directory, or URL", _jsx("input", { value: manifestPath, onChange: event => { setManifestPath(event.target.value); flow.clearReview(); }, required: true, disabled: busy || frozen })] }), _jsx("button", { disabled: busy || frozen || !manifestPath.trim(), children: "Review" })] }), busy && _jsx("p", { role: "status", children: "Preparing installation\u2026" }), error && _jsxs("div", { role: "alert", children: [_jsx("p", { children: error }), !frozen && _jsx("button", { type: "button", disabled: busy, onClick: () => void review(), children: "Retry review" })] }), plan && _jsxs("form", { onSubmit: event => { event.preventDefault(); void submit(); }, children: [_jsxs("h3", { children: [plan.displayName, " ", _jsx("small", { children: plan.targetVersion })] }), plan.description && _jsx("p", { children: plan.description }), _jsxs("label", { children: ["Runtime", _jsx("select", { value: plan.targetRuntime, disabled: busy || frozen, onChange: event => void review(event.target.value), children: (plan.runtimeProfiles ?? [{ key: plan.targetRuntime, type: plan.targetRuntimeType }]).map(runtime => _jsxs("option", { value: runtime.key, children: [runtime.key, " (", runtime.type, ")"] }, runtime.key)) })] }), plan.targetRuntimeType === "localCommand" && _jsx("p", { className: "warning", children: "This runtime runs commands directly on your host, outside a container. Only install code you trust." }), plan.system && _jsx("p", { className: "warning", children: "This is a system app. Only host administrators can open it." }), !!plan.requestedRoles?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested provider roles" }), _jsx("ul", { children: plan.requestedRoles.map(role => _jsx("li", { children: plan.roleDescriptions?.[role] ?? role }, role)) })] }), !!plan.corePermissions?.length && _jsxs("section", { children: [_jsx("h3", { children: "Requested Core permissions" }), _jsx("ul", { children: plan.corePermissions.map(permission => _jsx("li", { children: plan.permissionDescriptions?.[permission] ?? permission }, permission)) })] }), plan.settings.map(setting => _jsxs("label", { children: [setting.label || setting.key, setting.required ? " (required)" : "", setting.type === "boolean" && !setting.secret
                                 ? _jsx("input", { type: "checkbox", checked: ["true", "1", "yes", "on", "enabled"].includes((settings[setting.key] ?? "").toLowerCase()), disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: String(event.target.checked) })) })
                                 : setting.type === "select" && setting.options?.length && !setting.secret
                                     ? _jsxs("select", { value: settings[setting.key] ?? "", disabled: busy || frozen, onChange: event => setSettings(current => ({ ...current, [setting.key]: event.target.value })), children: [_jsx("option", { value: "", children: "Select a value" }), setting.options.map(option => _jsx("option", { value: option.value, children: option.label }, option.value))] })

package/dist/install.d.ts

@@ -26,6 +26,9 @@ export interface InstallPlan {
     defaultAutostart?: boolean;
     system?: boolean;
     corePermissions?: string[];
+    requestedRoles?: string[];
+    permissionDescriptions?: Record<string, string>;
+    roleDescriptions?: Record<string, string>;
     runtimeProfiles?: {
         key: string;
         type: string;

package/dist/server.js

@@ -552,6 +552,6 @@ async function readJsonOrThrow(response) {
     }
 }
 // Delegated tokens live in their own entry ("./delegated") because that module must stay
-// importable from plain Node services (the ai-gateway system app) — this file's "server-only"
+// importable from plain Node services (the Harness system app) — this file's "server-only"
 // import would throw there. Re-exported here so Next apps keep one import surface.
 export { validateDelegatedToken, } from "./delegated.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.14.0",
+  "version": "0.16.1",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -48,6 +48,10 @@
     "./install/server": {
       "types": "./dist/install-server.d.ts",
       "default": "./dist/install-server.js"
+    },
+    "./assistant": {
+      "types": "./dist/assistant.d.ts",
+      "default": "./dist/assistant.js"
     }
   },
   "scripts": {
@@ -58,7 +62,7 @@
     "server-only": "^0.0.1"
   },
   "peerDependencies": {
-    "next": "^16.3.4",
+    "next": "^16.3.5",
     "react": "^19.2.8"
   },
   "peerDependenciesMeta": {
@@ -70,10 +74,10 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24.13.4",
+    "@types/node": "^24.13.5",
     "@types/react": "^19.3.0",
     "typescript": "^6",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "repository": {
     "type": "git",