@hosty-sdk/app 0.7.0 → 0.9.0

package/dist/embedder.d.ts

@@ -37,6 +37,33 @@ export interface DelegatedTokenRequestIntent {
  * is.
  */
 export declare function parseActiveFrameDelegatedTokenRequest(event: EmbedderMessage, activeFrameWindow: unknown, activeFrameUrl: string): DelegatedTokenRequestIntent | null;
+/** A verified ask, and the one thing its payload carries. */
+export interface AskAssistantIntent {
+    /** Trimmed and capped here, so no embedder has to remember to do it. */
+    text: string;
+}
+/**
+ * Verifies that a `message` event is an ask-the-assistant intent from the active app frame, using
+ * the same sender checks as the pair above.
+ *
+ * The text is capped in the parser rather than by the caller: a cap is part of the contract, and an
+ * embedder that forgot it would let one app's page paste itself into the operator's draft. What the
+ * embedder must still decide is *where* the text goes — this function says an app asked, never that
+ * the assistant should send anything. Nothing here may be auto-sent.
+ */
+/**
+ * Verifies an attention count posted by a frame the embedder deliberately embeds.
+ *
+ * Read from the frame rather than polled by the embedder: the page that holds the session list and
+ * its event stream is the one source, and a shell asking the same question on a timer would be a
+ * second source that disagrees with the first for the length of its interval.
+ *
+ * Sender-verified like every other message here, though the payload is only a count: a wrong badge is
+ * a small harm, and a wrong badge that any page could set is a way to make an operator stop trusting
+ * the badge that matters.
+ */
+export declare function parseActiveFrameAttention(event: EmbedderMessage, activeFrameWindow: unknown, activeFrameUrl: string): number | null;
+export declare function parseActiveFrameAskAssistant(event: EmbedderMessage, activeFrameWindow: unknown, activeFrameUrl: string): AskAssistantIntent | null;
 /**
  * Per-app reissue throttle: a frame that keeps re-posting (e.g. it never accepts the new
  * code) must not drive an unbounded reissue storm. One reissue per app per interval is

package/dist/embedder.js

@@ -12,7 +12,7 @@
 // you have decided to grant one, mint a token from Core with your own session and post it back
 // to that frame's origin. Both requests are unauthenticated by design; what makes them safe is
 // that the embedder answers from facts about its own DOM rather than from what the frame claims.
-import { AUTH_REQUIRED_INTENT_TYPE, DELEGATED_TOKEN_REQUEST_TYPE } from "./index.js";
+import { ASK_ASSISTANT_MAX_CHARS, ASK_ASSISTANT_TYPE, ATTENTION_TYPE, AUTH_REQUIRED_INTENT_TYPE, DELEGATED_TOKEN_REQUEST_TYPE, } from "./index.js";
 /**
  * Verifies that a `message` event is a genuine auth-required intent from the active app
  * frame. Every check is about facts only the embedder can know:
@@ -57,6 +57,51 @@ export function parseActiveFrameDelegatedTokenRequest(event, activeFrameWindow,
     }
     return { refresh: candidate.refresh === true };
 }
+/**
+ * Verifies that a `message` event is an ask-the-assistant intent from the active app frame, using
+ * the same sender checks as the pair above.
+ *
+ * The text is capped in the parser rather than by the caller: a cap is part of the contract, and an
+ * embedder that forgot it would let one app's page paste itself into the operator's draft. What the
+ * embedder must still decide is *where* the text goes — this function says an app asked, never that
+ * the assistant should send anything. Nothing here may be auto-sent.
+ */
+/**
+ * Verifies an attention count posted by a frame the embedder deliberately embeds.
+ *
+ * Read from the frame rather than polled by the embedder: the page that holds the session list and
+ * its event stream is the one source, and a shell asking the same question on a timer would be a
+ * second source that disagrees with the first for the length of its interval.
+ *
+ * Sender-verified like every other message here, though the payload is only a count: a wrong badge is
+ * a small harm, and a wrong badge that any page could set is a way to make an operator stop trusting
+ * the badge that matters.
+ */
+export function parseActiveFrameAttention(event, activeFrameWindow, activeFrameUrl) {
+    if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
+        return null;
+    }
+    const candidate = event.data;
+    // `typeof NaN === "number"`, and NaN survives every clamp below to arrive as a badge count no
+    // renderer can do anything with. Finiteness is the check that was actually meant.
+    if (candidate.type !== ATTENTION_TYPE || !Number.isFinite(candidate.count)) {
+        return null;
+    }
+    // Clamped rather than trusted: a negative or absurd count would render as a badge nobody can
+    // explain, and the frame has no business deciding how large a number the shell displays.
+    return Math.max(0, Math.min(99, Math.floor(candidate.count)));
+}
+export function parseActiveFrameAskAssistant(event, activeFrameWindow, activeFrameUrl) {
+    if (!isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl)) {
+        return null;
+    }
+    const candidate = event.data;
+    if (candidate.type !== ASK_ASSISTANT_TYPE || typeof candidate.text !== "string") {
+        return null;
+    }
+    const text = candidate.text.trim().slice(0, ASK_ASSISTANT_MAX_CHARS);
+    return text ? { text } : null;
+}
 /** The sender half both parsers share: right frame, right origin, object payload. */
 function isActiveFrameMessage(event, activeFrameWindow, activeFrameUrl) {
     if (!activeFrameWindow || event.source !== activeFrameWindow) {

package/dist/index.d.ts

@@ -21,6 +21,41 @@ export declare function createAuthRequiredIntent(appId: string): AuthRequiredInt
  * token is a user-scoped credential, so an embedder answers only for apps it deliberately grants
  * 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.
+ */
+export declare const ASK_ASSISTANT_TYPE = "hosty:ask-assistant";
+/**
+ * How many of an embedded assistant's sessions are waiting for the operator.
+ *
+ * Published by the page that holds them, not asked for on a timer: one source, so a shell's badge and
+ * the list behind it can never disagree.
+ */
+export declare const ATTENTION_TYPE = "hosty:assistant-attention";
+/** Longer than a prompt fragment is a page dumping itself into someone's draft. */
+export declare const ASK_ASSISTANT_MAX_CHARS = 4000;
+export interface AskAssistantMessage {
+    type: typeof ASK_ASSISTANT_TYPE;
+    /** Trimmed and capped by the embedder's parser; the app need not pre-truncate. */
+    text: string;
+}
+/**
+ * Asks the embedder to put `text` in the operator's assistant draft.
+ *
+ * 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
+ * all — never whether anyone acted on it, which is the operator's business and not the app's.
+ */
+export declare function askAssistant(text: string): boolean;
 export declare const DELEGATED_TOKEN_REQUEST_TYPE = "hosty:request-delegated-token";
 export declare const DELEGATED_TOKEN_TYPE = "hosty:delegated-token";
 export interface DelegatedTokenRequest {

package/dist/index.js

@@ -24,6 +24,53 @@ export function createAuthRequiredIntent(appId) {
  * token is a user-scoped credential, so an embedder answers only for apps it deliberately grants
  * 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.
+ */
+export const ASK_ASSISTANT_TYPE = "hosty:ask-assistant";
+/**
+ * How many of an embedded assistant's sessions are waiting for the operator.
+ *
+ * Published by the page that holds them, not asked for on a timer: one source, so a shell's badge and
+ * the list behind it can never disagree.
+ */
+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.
+ *
+ * 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
+ * all — never whether anyone acted on it, which is the operator's business and not the app's.
+ */
+export function askAssistant(text) {
+    if (typeof window === "undefined" || window.parent === window) {
+        return false;
+    }
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return false;
+    }
+    // Broadcast: the message carries no secret, and the embedder verifies the sender against its own
+    // DOM rather than trusting anything claimed here.
+    //
+    // Capped on the way out too. The parser remains where the contract is enforced — an app is not
+    // trusted to have done this — but there is no reason to structure-clone a megabyte across the
+    // boundary just to have the embedder discard it.
+    const capped = trimmed.slice(0, ASK_ASSISTANT_MAX_CHARS);
+    window.parent.postMessage({ type: ASK_ASSISTANT_TYPE, text: capped }, "*");
+    return true;
+}
 export const DELEGATED_TOKEN_REQUEST_TYPE = "hosty:request-delegated-token";
 export const DELEGATED_TOKEN_TYPE = "hosty:delegated-token";
 export function createDelegatedTokenRequest(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",