@hosty-sdk/app 0.15.0 → 0.16.2

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-server.js

@@ -24,7 +24,22 @@ export function createInstallationRouteHandler(config, options = {}) {
                 return Response.json({ code: "hosty_misconfigured", message: "Installation public origin is invalid." }, { status: 503 });
             }
         }
-        if (request.method !== "GET" && (request.headers.get("origin") !== expectedOrigin ||
+        const origin = request.headers.get("origin");
+        let sameOrigin = origin === expectedOrigin;
+        // Next may reconstruct request.url with localhost while the browser uses a loopback IP.
+        // Without an explicit public origin, accept the actual Host only with the browser's
+        // unforgeable-by-page-script same-origin Fetch Metadata. Host/forwarded headers alone
+        // must never authorize a cookie-authenticated mutation.
+        if (!options.publicOrigin?.trim() && !sameOrigin && request.headers.get("sec-fetch-site") === "same-origin") {
+            try {
+                const browserOrigin = new URL(origin ?? "");
+                sameOrigin = ["http:", "https:"].includes(browserOrigin.protocol)
+                    && browserOrigin.origin === origin
+                    && browserOrigin.host === request.headers.get("host");
+            }
+            catch { /* Missing, opaque or malformed origins remain denied. */ }
+        }
+        if (request.method !== "GET" && (!sameOrigin ||
             !request.headers.get("content-type")?.startsWith("application/json")))
             return Response.json({ code: "origin_denied", message: "A same-origin JSON request is required." }, { status: 403 });
         const token = readAppIdentityToken(request.headers, config);

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.15.0",
+  "version": "0.16.2",
   "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.5",
+    "next": "^16.3.6",
     "react": "^19.2.8"
   },
   "peerDependenciesMeta": {
@@ -70,10 +74,10 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24.13.5",
+    "@types/node": "^24.19.0",
     "@types/react": "^19.3.0",
     "typescript": "^6",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.2"
   },
   "repository": {
     "type": "git",