@hosty-sdk/app 0.34.2 → 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-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.2",
+  "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": {