@hosty-sdk/app 0.34.1 → 0.35.1

package/dist/tool-activity-server.d.ts

@@ -0,0 +1,35 @@
+import type { ProviderServerOptions } from "./providers-server.js";
+import type { ToolActivity, ToolActivityState } from "./ui-types.js";
+export type ToolActivityValue = {
+    state: ToolActivityState;
+    count?: number;
+    label?: string;
+    ttlSeconds?: number;
+};
+export type ToolActivityReporterOptions = ProviderServerOptions & {
+    installationId?: string;
+    onError?: (error: Error) => void;
+    /** Acknowledges the current value; rejection keeps it queued for retry. */
+    onReported?: (userId: string, panelId: string, value: ToolActivityValue) => void | Promise<void>;
+};
+/** Server-only, current-state reporting. No transcript data or browser frame is required. */
+export declare class ToolActivityReporter {
+    private readonly options;
+    private readonly appId;
+    private readonly installation;
+    private readonly core;
+    private readonly service;
+    private readonly entries;
+    private readonly controller;
+    private readonly timer;
+    private pending?;
+    private disposed;
+    constructor(options?: ToolActivityReporterOptions);
+    set(userId: string, panelId: string, value: ToolActivityValue): void;
+    /** Serializes changes, retries failures and renews presence. After Core restarts every retained
+     * state is re-reported within 20 seconds, without rebinding to another installation. */
+    flush(): Promise<void>;
+    private sendDue;
+    dispose(): Promise<void>;
+}
+export type { ToolActivity };

package/dist/tool-activity-server.js

@@ -0,0 +1,93 @@
+/** Server-only, current-state reporting. No transcript data or browser frame is required. */
+export class ToolActivityReporter {
+    options;
+    appId;
+    installation;
+    core;
+    service;
+    entries = new Map();
+    controller = new AbortController();
+    timer;
+    pending;
+    disposed = false;
+    constructor(options = {}) {
+        this.options = options;
+        this.appId = options.appId ?? process.env.HOSTY_APP_ID ?? "";
+        this.installation = options.installationId ?? process.env.HOSTY_APP_INSTALLATION_ID ?? "";
+        this.core = new URL(options.coreOrigin ?? process.env.HOSTY_CORE_ORIGIN ?? "http://127.0.0.1:7070");
+        this.service = options.serviceToken ?? process.env.HOSTY_APP_SERVICE_TOKEN ?? "";
+        if (!this.appId || !this.installation || !this.service)
+            throw new Error("Tool activity requires a Core-managed installation and app service identity.");
+        this.timer = setInterval(() => { void this.flush(); }, 250);
+        this.timer.unref?.();
+    }
+    set(userId, panelId, value) {
+        if (this.disposed)
+            return;
+        if (!userId || !panelId || !["idle", "working", "needs-you", "failed"].includes(value.state)
+            || value.count !== undefined && (!Number.isInteger(value.count) || value.count < 0 || value.count > 9999)
+            || value.label !== undefined && (value.label.length > 120 || /[\x00-\x1f\x7f]/.test(value.label))
+            || value.ttlSeconds !== undefined && (!Number.isInteger(value.ttlSeconds) || value.ttlSeconds < 1 || value.ttlSeconds > 300))
+            throw new Error("Invalid tool activity.");
+        const key = JSON.stringify([userId, panelId]), previous = this.entries.get(key);
+        if (!previous && this.entries.size >= 10_000)
+            throw new Error("Tool activity reporter capacity reached.");
+        if (previous && JSON.stringify(previous.value) === JSON.stringify(value))
+            return;
+        this.entries.set(key, { userId, panelId, value: { ...value }, due: 0 });
+        void this.flush();
+    }
+    /** Serializes changes, retries failures and renews presence. After Core restarts every retained
+     * state is re-reported within 20 seconds, without rebinding to another installation. */
+    flush() {
+        if (this.pending)
+            return this.pending;
+        if (this.disposed)
+            return Promise.resolve();
+        this.pending = this.sendDue().finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    async sendDue() {
+        for (const [key, entry] of this.entries) {
+            if (this.disposed || entry.due > Date.now())
+                continue;
+            try {
+                const response = await fetch(new URL(`/api/internal/apps/${encodeURIComponent(this.appId)}/ui/activity`, this.core), {
+                    method: "POST", redirect: "error", cache: "no-store",
+                    signal: AbortSignal.any([this.controller.signal, AbortSignal.timeout(10_000)]),
+                    headers: { authorization: `Bearer ${this.service}`, "content-type": "application/json" },
+                    body: JSON.stringify({ userId: entry.userId, installationId: this.installation, panelId: entry.panelId, ...entry.value }),
+                });
+                await response.body?.cancel();
+                if (!response.ok)
+                    throw new Error(`Tool activity report failed (${response.status}).`);
+                // A newer value may have arrived during this request; never acknowledge or delete it.
+                if (this.entries.get(key) !== entry)
+                    continue;
+                await this.options.onReported?.(entry.userId, entry.panelId, { ...entry.value });
+                if (this.entries.get(key) !== entry)
+                    continue;
+                if (entry.value.state === "idle")
+                    this.entries.delete(key);
+                else
+                    entry.due = Date.now() + Math.min(20_000, (entry.value.ttlSeconds ?? 60) * 1000 / 3);
+            }
+            catch (error) {
+                if (this.disposed)
+                    return;
+                entry.due = Date.now() + 5000;
+                try {
+                    this.options.onError?.(error instanceof Error ? error : new Error("Tool activity unavailable."));
+                }
+                catch { /* Observers cannot stop reporting. */ }
+            }
+        }
+    }
+    async dispose() {
+        this.disposed = true;
+        clearInterval(this.timer);
+        this.controller.abort();
+        await this.pending;
+        this.entries.clear();
+    }
+}

package/dist/ui-host.d.ts

@@ -112,7 +112,8 @@ export declare class UiHost implements UiClient {
         signal?: AbortSignal;
     }) => Promise<PresentationResult>;
     private status;
-    selectPanel: (ref: PanelRef, workspaceId?: string) => Promise<PresentationResult>;
+    selectPanel: (ref: PanelRef, workspaceId?: string, signal?: AbortSignal) => Promise<PresentationResult>;
+    private selectPanelWithSignal;
     setExpanded: (expanded: boolean, workspaceId?: string) => void;
     setWidth: (width: number, workspaceId?: string) => void;
     setAttention: (panel: PanelRef | string, attention: number) => void;

package/dist/ui-host.js

@@ -449,8 +449,10 @@ export class UiHost {
         return operation;
     };
     openSurface = (target, options) => waitForPresentation(this.open(target, options, "local"), options.requestId, options.signal);
-    open(target, options, source, frame, sourceWorkspace) {
+    open(target, options, source, frame, sourceWorkspace, selectionSignal) {
         const id = options.requestId;
+        if (selectionSignal?.aborted)
+            return Promise.resolve({ status: "blocked", requestId: id, code: "presentation_cancelled" });
         if (!this.active || !this.activityReady || this.disposed)
             return Promise.resolve({ status: "blocked", requestId: id, code: "activity_required" });
         if (!validId(id) || !validTarget(target) || options.placement !== "side" || options.reuse !== undefined && !["exact", "new"].includes(options.reuse))
@@ -503,6 +505,8 @@ export class UiHost {
             try {
                 const own = await this.bootstrap(generation);
                 const check = () => {
+                    if (selectionSignal?.aborted)
+                        throw new UiError("presentation_cancelled", "This selection was cancelled.");
                     this.checkActivity(generation);
                     this.requireTools(frame);
                     if (!own.canHost)
@@ -763,7 +767,21 @@ export class UiHost {
             return failure(id, error);
         }
     }
-    selectPanel = async (ref, workspaceId = DEFAULT_WORKSPACE) => {
+    // Host-owned selections may cancel before presentation without superseding another selection.
+    // PresentationOptions.signal still cancels only a protocol caller's wait.
+    selectPanel = async (ref, workspaceId = DEFAULT_WORKSPACE, signal) => {
+        const cancel = () => this.invalidateRendererWork();
+        signal?.addEventListener("abort", cancel);
+        try {
+            return await this.selectPanelWithSignal(ref, workspaceId, signal);
+        }
+        finally {
+            signal?.removeEventListener("abort", cancel);
+        }
+    };
+    selectPanelWithSignal = async (ref, workspaceId, signal) => {
+        if (signal?.aborted)
+            return { status: "blocked", requestId: createPresentationRequestId(), code: "presentation_cancelled" };
         const opened = this.snapshot.tools.filter(t => t.workspaceId === workspaceId && t.key === panelKey(ref)).sort((a, b) => b.focusedAt - a.focusedAt)[0];
         if (opened?.resolved.surface) {
             const requestId = createPresentationRequestId();
@@ -778,6 +796,8 @@ export class UiHost {
                 const resolved = await uiRequest(this.path, "panels/resolve", opened.target);
                 this.checkActivity(generation);
                 this.requireTools();
+                if (signal?.aborted)
+                    throw new UiError("presentation_cancelled", "This selection was cancelled.");
                 if (selection !== state.generation)
                     throw new UiError("presentation_superseded", "A newer action replaced this opening.");
                 if (!resolved.available || !resolved.surface)
@@ -802,7 +822,8 @@ export class UiHost {
         else if (opened)
             this.closePresentation(opened.presentationId);
         const requestId = createPresentationRequestId();
-        return waitForPresentation(this.open({ panel: ref }, { placement: "side", requestId }, "local", undefined, workspaceId), requestId);
+        const opening = this.open({ panel: ref }, { placement: "side", requestId }, "local", undefined, workspaceId, signal);
+        return signal ? opening : waitForPresentation(opening, requestId);
     };
     setExpanded = (expanded, workspaceId = DEFAULT_WORKSPACE) => {
         if (!expanded)

package/dist/ui-server.d.ts

@@ -1,6 +1,6 @@
 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";
+import { type ToolActivity, 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. */
 export declare class UiServerClient {
     private readonly appId;
@@ -12,6 +12,7 @@ export declare class UiServerClient {
         parentOrigin?: string;
     }, token: string, signal?: AbortSignal): Promise<UiBootstrap>;
     listPanels(token: string, signal?: AbortSignal): Promise<UiPanel[]>;
+    activity(token: string, signal?: AbortSignal): Promise<ToolActivity[]>;
     navigation(token: string, signal?: AbortSignal): Promise<UiNavigationCatalog>;
     resolveNavigation(target: UiNavigationTarget, token: string, signal?: AbortSignal): Promise<UiResolvedNavigation>;
     resolvePanel(target: PanelTarget, token: string, signal?: AbortSignal): Promise<UiResolvedPanel>;

package/dist/ui-server.js

@@ -35,6 +35,9 @@ export class UiServerClient {
     async listPanels(token, signal) {
         return (await this.request("panels", token, undefined, signal)).panels;
     }
+    async activity(token, signal) {
+        return (await this.request("activity", token, undefined, signal)).activities;
+    }
     navigation(token, signal) {
         return this.request("navigation", token, undefined, signal);
     }
@@ -70,6 +73,11 @@ export async function createHostyUiResponse(request, context, options = {}) {
         else if (request.method === "GET" && route === "panels") {
             result = { panels: await client.listPanels(context.token, request.signal) };
         }
+        else if (request.method === "GET" && route === "activity") {
+            if (url.search)
+                throw new UiError("ui_request_invalid", "Unexpected activity parameters.", 400);
+            result = { activities: await client.activity(context.token, request.signal) };
+        }
         else if (request.method === "GET" && route === "navigation") {
             if (url.search)
                 throw new UiError("ui_request_invalid", "Unexpected navigation parameters.", 400);

package/dist/ui-types.d.ts

@@ -192,3 +192,13 @@ export type UiRouterAdapter = {
     subscribe(listener: () => void): () => void;
     navigate(route: string): void | Promise<void>;
 };
+/** Activity is owned by Core, independently of mounted tool frames. */
+export type ToolActivityState = "idle" | "working" | "needs-you" | "failed";
+export type ToolActivity = {
+    panel: PanelRef;
+    state: ToolActivityState | "no-connection";
+    count: number | null;
+    label: string | null;
+    reportedAt: string | null;
+    expiresAt: string | null;
+};

package/package.json

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