appilot 0.0.1 → 0.1.0

package/dist/webmcp/sdk.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `appilot` client actions: the WebMCP-aligned surface a host app calls to
+ * expose its actions to the Appilot agent.
+ *
+ * Two postures, one call site:
+ *   - POLYFILL (provider): for the 99% of apps with no native WebMCP, our
+ *     in-page registry IS the tool surface (see registry.ts).
+ *   - CONSUMER (native): when the browser exposes `navigator.modelContext` /
+ *     `document.modelContext`, we also delegate registration to it (so the page
+ *     is a real WebMCP page for any agent), and the collector prefers native
+ *     tools. Namespace is detect-only because the spec is in flux; we bind to
+ *     the stable descriptor (name/description/inputSchema/execute).
+ *
+ * Import from `appilot`. See docs/content-model/tools-client-actions.md.
+ */
+import { type ClientToolDefinition, type ClientToolHandle, type SerializedClientTool } from './registry.js';
+/** True when the browser natively implements a WebMCP `modelContext`. */
+export declare function hasNativeWebMcp(): boolean;
+/**
+ * Register a tool with Appilot, WebMCP-style. The descriptor is the stable
+ * WebMCP shape: `{ name, description, inputSchema?, annotations?, execute }`.
+ *
+ * If the browser exposes a native `modelContext`, we ALSO register there so a
+ * native browser agent sees the same tool: "re-emission, not rewrite". We
+ * always mirror into Appilot's registry so collection does not depend on the
+ * still-unspecified native `getTools()`/`executeTool()` discovery API.
+ */
+export declare function registerTool(def: ClientToolDefinition): ClientToolHandle;
+/**
+ * The per-turn collector the extension/widget call to gather the descriptors
+ * to send to the backend. Returns Appilot-registry tools today; when only
+ * native tools exist (a page that used `navigator.modelContext` directly), the
+ * extension's main-world bridge supplies them instead. Kept here so both
+ * surfaces share one serialization shape.
+ */
+export declare function collectClientTools(): SerializedClientTool[];
+export { registerClientTool, unregisterClientTool, onClientToolsChange } from './registry.js';
+export type { ClientToolDefinition, ClientToolHandle, SerializedClientTool } from './registry.js';

package/dist/webmcp/sdk.js

@@ -0,0 +1,81 @@
+/**
+ * `appilot` client actions: the WebMCP-aligned surface a host app calls to
+ * expose its actions to the Appilot agent.
+ *
+ * Two postures, one call site:
+ *   - POLYFILL (provider): for the 99% of apps with no native WebMCP, our
+ *     in-page registry IS the tool surface (see registry.ts).
+ *   - CONSUMER (native): when the browser exposes `navigator.modelContext` /
+ *     `document.modelContext`, we also delegate registration to it (so the page
+ *     is a real WebMCP page for any agent), and the collector prefers native
+ *     tools. Namespace is detect-only because the spec is in flux; we bind to
+ *     the stable descriptor (name/description/inputSchema/execute).
+ *
+ * Import from `appilot`. See docs/content-model/tools-client-actions.md.
+ */
+import { registerClientTool, serializeClientTools, } from './registry.js';
+function nativeModelContext() {
+    if (typeof navigator !== 'undefined' && navigator.modelContext) {
+        return navigator.modelContext;
+    }
+    if (typeof document !== 'undefined' && document.modelContext) {
+        return document.modelContext;
+    }
+    return undefined;
+}
+/** True when the browser natively implements a WebMCP `modelContext`. */
+export function hasNativeWebMcp() {
+    return nativeModelContext() !== undefined;
+}
+/**
+ * Register a tool with Appilot, WebMCP-style. The descriptor is the stable
+ * WebMCP shape: `{ name, description, inputSchema?, annotations?, execute }`.
+ *
+ * If the browser exposes a native `modelContext`, we ALSO register there so a
+ * native browser agent sees the same tool: "re-emission, not rewrite". We
+ * always mirror into Appilot's registry so collection does not depend on the
+ * still-unspecified native `getTools()`/`executeTool()` discovery API.
+ */
+export function registerTool(def) {
+    const appilotHandle = registerClientTool(def);
+    let nativeAbort;
+    const native = nativeModelContext();
+    if (native?.registerTool) {
+        try {
+            // Both the spec-draft (returns Promise + AbortController option) and
+            // the Chrome-shipped surface accept this descriptor shape.
+            const controller = typeof AbortController !== 'undefined' ? new AbortController() : undefined;
+            native.registerTool({
+                name: def.name,
+                description: def.description,
+                inputSchema: def.inputSchema,
+                annotations: def.annotations,
+                execute: def.execute,
+            }, controller ? { signal: controller.signal } : undefined);
+            nativeAbort = controller;
+        }
+        catch {
+            // Native registration is best-effort; Appilot's registry still works.
+        }
+    }
+    return {
+        unregister() {
+            appilotHandle.unregister();
+            try {
+                nativeAbort?.abort?.();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}
+/**
+ * The per-turn collector the extension/widget call to gather the descriptors
+ * to send to the backend. Returns Appilot-registry tools today; when only
+ * native tools exist (a page that used `navigator.modelContext` directly), the
+ * extension's main-world bridge supplies them instead. Kept here so both
+ * surfaces share one serialization shape.
+ */
+export function collectClientTools() {
+    return serializeClientTools();
+}
+export { registerClientTool, unregisterClientTool, onClientToolsChange } from './registry.js';

package/dist/widget/boot.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Appilot widget boot: load the embeddable assistant into a host app with an
+ * identified user token, and keep it authenticated for the life of the page.
+ *
+ * The host app owns identity: it exposes a backend RELAY endpoint that mints an
+ * identified widget token (so the widget key never sees the end user's
+ * credentials), and this boot loader POSTs to it, then loads the widget bundle
+ * with the returned token.
+ *
+ * Design guarantees:
+ * - Boot does not latch on failure: a failed relay or bundle load returns
+ *   availability to 'unavailable' and a later bootAppilotWidget() call retries
+ *   from scratch (one hiccup never permanently disables the assistant).
+ * - The widget token (TTL ~3600s) is re-relayed at ~80% of its TTL. The fresh
+ *   token is written back to the loader script tag (data-user-token) so every
+ *   subsequent (re)boot stays authenticated past the hour, AND handed to the
+ *   live instance through `window.Appilot.setUserToken` so a long-lived tab
+ *   never starts 401ing on a healthy host session.
+ * - The widget can request an out-of-band refresh by dispatching
+ *   'appilot:identity-refresh-requested' on window (it does so when its
+ *   federated identity is rejected); the loader re-relays immediately.
+ * - When the host supplies `getBearer` and it returns null (the host session
+ *   is gone), the scheduled refresh does NOT call the relay: relaying without
+ *   a bearer would mint whatever fallback identity the endpoint assigns,
+ *   silently swapping the signed-in user for a default persona. The loader
+ *   retries until the host session is back.
+ * - The relay call carries a bearer supplied by the host (`getBearer`) when one
+ *   exists, so a logged-in user federates as themselves; without it the relay
+ *   falls back to whatever identity the endpoint assigns.
+ * - Availability is observable (getWidgetAvailability / subscribeWidgetAvailability)
+ *   so pages can render an honest "assistant unavailable" state. Pairs with
+ *   React useSyncExternalStore(subscribeWidgetAvailability, getWidgetAvailability).
+ */
+export type WidgetAvailability = 'unknown' | 'booting' | 'ready' | 'unavailable';
+export interface AppilotWidgetBootOptions {
+    /** Widget bundle URL. Missing = no assistant. */
+    widgetScriptUrl: string | undefined;
+    /** Publishable widget key. */
+    widgetKey?: string;
+    /** Appilot backend base URL. */
+    appilotApiUrl?: string;
+    /** Identity relay endpoint on the host app's own backend. */
+    tokenEndpoint?: string;
+    /** JSON body for the relay, e.g. { persona: 'learner' }. Omitted = relay default. */
+    tokenBody?: Record<string, unknown>;
+    /**
+     * Supplies the host session bearer attached to the relay call so the relay
+     * can federate the LOGGED-IN user instead of a default identity. Return null
+     * when no user session exists. Host-specific; keeps this loader app-agnostic.
+     */
+    getBearer?: () => string | null | undefined;
+    /** How the app names its assistant in console diagnostics ('assistant', 'Appilot'). */
+    surfaceLabel?: string;
+    /**
+     * Header brand text and assistant label inside the panel (`data-brand-name`).
+     * Omitted, the widget falls back to the organization name from `/widget/init`,
+     * which white-labels the panel with the HOST's brand. An app that wants the
+     * assistant to carry its own name passes it here.
+     */
+    brandName?: string;
+    /** Maximum time for token relay + bundle readiness. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    position?: 'bottom-right' | 'bottom-left';
+    theme?: string;
+    language?: string;
+}
+export declare function getWidgetAvailability(): WidgetAvailability;
+/** Subscribe to availability changes. Returns the unsubscribe function. */
+export declare function subscribeWidgetAvailability(listener: (state: WidgetAvailability) => void): () => void;
+export declare function bootAppilotWidget(options: AppilotWidgetBootOptions): Promise<void>;
+/** Test-only: reset module state between tests. Never call from app code. */
+export declare function __resetAppilotWidgetForTests(): void;

package/dist/widget/boot.js

@@ -0,0 +1,264 @@
+/**
+ * Appilot widget boot: load the embeddable assistant into a host app with an
+ * identified user token, and keep it authenticated for the life of the page.
+ *
+ * The host app owns identity: it exposes a backend RELAY endpoint that mints an
+ * identified widget token (so the widget key never sees the end user's
+ * credentials), and this boot loader POSTs to it, then loads the widget bundle
+ * with the returned token.
+ *
+ * Design guarantees:
+ * - Boot does not latch on failure: a failed relay or bundle load returns
+ *   availability to 'unavailable' and a later bootAppilotWidget() call retries
+ *   from scratch (one hiccup never permanently disables the assistant).
+ * - The widget token (TTL ~3600s) is re-relayed at ~80% of its TTL. The fresh
+ *   token is written back to the loader script tag (data-user-token) so every
+ *   subsequent (re)boot stays authenticated past the hour, AND handed to the
+ *   live instance through `window.Appilot.setUserToken` so a long-lived tab
+ *   never starts 401ing on a healthy host session.
+ * - The widget can request an out-of-band refresh by dispatching
+ *   'appilot:identity-refresh-requested' on window (it does so when its
+ *   federated identity is rejected); the loader re-relays immediately.
+ * - When the host supplies `getBearer` and it returns null (the host session
+ *   is gone), the scheduled refresh does NOT call the relay: relaying without
+ *   a bearer would mint whatever fallback identity the endpoint assigns,
+ *   silently swapping the signed-in user for a default persona. The loader
+ *   retries until the host session is back.
+ * - The relay call carries a bearer supplied by the host (`getBearer`) when one
+ *   exists, so a logged-in user federates as themselves; without it the relay
+ *   falls back to whatever identity the endpoint assigns.
+ * - Availability is observable (getWidgetAvailability / subscribeWidgetAvailability)
+ *   so pages can render an honest "assistant unavailable" state. Pairs with
+ *   React useSyncExternalStore(subscribeWidgetAvailability, getWidgetAvailability).
+ */
+const DEFAULT_APPILOT_API_URL = 'http://localhost:6001';
+/** Dispatched by the widget when its federated identity is rejected (401),
+ *  asking the loader for an immediate re-relay instead of waiting for the
+ *  scheduled ~80%-TTL refresh. Mirror of the widget's WidgetSDK constant. */
+const IDENTITY_REFRESH_REQUESTED_EVENT = 'appilot:identity-refresh-requested';
+const DEFAULT_TOKEN_ENDPOINT = '/api/widget/token';
+const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+const TOKEN_REFRESH_FRACTION = 0.8;
+const REFRESH_RETRY_MS = 60_000;
+const DEFAULT_BOOT_TIMEOUT_MS = 10_000;
+let availability = 'unknown';
+const listeners = new Set();
+let scriptEl = null;
+let refreshTimer = null;
+let bootTimer = null;
+let bootAbortController = null;
+let activeAttempt = 0;
+let warnedMissingConfig = false;
+let refreshRequestListener = null;
+function detachRefreshRequestListener() {
+    if (refreshRequestListener) {
+        window.removeEventListener(IDENTITY_REFRESH_REQUESTED_EVENT, refreshRequestListener);
+        refreshRequestListener = null;
+    }
+}
+function attachRefreshRequestListener(options) {
+    detachRefreshRequestListener();
+    refreshRequestListener = () => {
+        clearRefreshTimer();
+        void refreshWidgetToken(options);
+    };
+    window.addEventListener(IDENTITY_REFRESH_REQUESTED_EVENT, refreshRequestListener);
+}
+function setAvailability(next) {
+    if (availability === next)
+        return;
+    availability = next;
+    for (const listener of listeners)
+        listener(next);
+}
+export function getWidgetAvailability() {
+    return availability;
+}
+/** Subscribe to availability changes. Returns the unsubscribe function. */
+export function subscribeWidgetAvailability(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+async function relayWidgetToken(options, signal) {
+    const endpoint = options.tokenEndpoint ?? DEFAULT_TOKEN_ENDPOINT;
+    // The host bearer lets the relay federate the LOGGED-IN user instead of a
+    // default identity; without it the relay assigns whatever identity it wants.
+    const bearer = options.getBearer?.() ?? null;
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        signal,
+        headers: {
+            ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),
+            ...(options.tokenBody !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        ...(options.tokenBody !== undefined ? { body: JSON.stringify(options.tokenBody) } : {}),
+    });
+    if (!response.ok) {
+        throw new Error(`widget token relay responded ${response.status}`);
+    }
+    return (await response.json());
+}
+function clearRefreshTimer() {
+    if (refreshTimer !== null) {
+        clearTimeout(refreshTimer);
+        refreshTimer = null;
+    }
+}
+function clearBootTimer() {
+    if (bootTimer !== null) {
+        clearTimeout(bootTimer);
+        bootTimer = null;
+    }
+}
+function hasRequiredWidgetApi() {
+    return typeof window.Appilot?.open === 'function';
+}
+function cleanFailedAttempt(attempt, script) {
+    if (attempt !== activeAttempt) {
+        script?.remove();
+        return;
+    }
+    activeAttempt += 1;
+    clearBootTimer();
+    clearRefreshTimer();
+    detachRefreshRequestListener();
+    bootAbortController?.abort();
+    bootAbortController = null;
+    const target = script ?? scriptEl;
+    target?.remove();
+    if (!target || scriptEl === target)
+        scriptEl = null;
+    setAvailability('unavailable');
+}
+function scheduleTokenRefresh(expiresIn, options) {
+    clearRefreshTimer();
+    const ttl = expiresIn && expiresIn > 0 ? expiresIn : DEFAULT_TOKEN_TTL_SECONDS;
+    refreshTimer = setTimeout(() => {
+        void refreshWidgetToken(options);
+    }, ttl * TOKEN_REFRESH_FRACTION * 1000);
+}
+async function refreshWidgetToken(options) {
+    // Host session gone: do NOT hit the relay bearerless. The relay would fall
+    // back to its default identity (dev personas in development), silently
+    // swapping the federated user on the next token. Wait for the session to
+    // come back (login) and retry; the widget shows its own identity-expired
+    // state in the meantime.
+    if (options.getBearer && !options.getBearer()) {
+        clearRefreshTimer();
+        refreshTimer = setTimeout(() => {
+            void refreshWidgetToken(options);
+        }, REFRESH_RETRY_MS);
+        return;
+    }
+    try {
+        const relayed = await relayWidgetToken(options);
+        // Keep the loader tag fresh so any widget (re)boot past the original TTL
+        // stays authenticated.
+        scriptEl?.setAttribute('data-user-token', relayed.token);
+        // Feed the live instance so an open tab adopts the fresh token without
+        // a reload (`window.Appilot.setUserToken`, widget >= 2026-08-25).
+        const appilot = window.Appilot;
+        appilot?.setUserToken?.(relayed.token);
+        scheduleTokenRefresh(relayed.expiresIn, options);
+    }
+    catch (error) {
+        console.warn('[appilot] widget token refresh failed; retrying shortly', error);
+        clearRefreshTimer();
+        refreshTimer = setTimeout(() => {
+            void refreshWidgetToken(options);
+        }, REFRESH_RETRY_MS);
+    }
+}
+export async function bootAppilotWidget(options) {
+    // Idempotent while healthy; 'unavailable' deliberately falls through so a
+    // later call retries after a failure.
+    if (availability === 'booting' || availability === 'ready')
+        return;
+    const label = options.surfaceLabel ?? 'assistant';
+    if (!options.widgetScriptUrl) {
+        if (!warnedMissingConfig) {
+            warnedMissingConfig = true;
+            console.warn(`[appilot] widget script URL is not configured; ${label} disabled`);
+        }
+        setAvailability('unavailable');
+        return;
+    }
+    setAvailability('booting');
+    const attempt = ++activeAttempt;
+    bootAbortController?.abort();
+    bootAbortController = new AbortController();
+    clearBootTimer();
+    bootTimer = setTimeout(() => {
+        if (attempt !== activeAttempt)
+            return;
+        console.warn(`[appilot] widget boot timed out; ${label} disabled`);
+        cleanFailedAttempt(attempt);
+    }, options.timeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS);
+    let relayed;
+    try {
+        relayed = await relayWidgetToken(options, bootAbortController.signal);
+    }
+    catch (error) {
+        if (attempt !== activeAttempt)
+            return;
+        console.warn(`[appilot] widget token relay unavailable; ${label} disabled`, error);
+        cleanFailedAttempt(attempt);
+        return;
+    }
+    if (attempt !== activeAttempt)
+        return;
+    const script = document.createElement('script');
+    script.src = options.widgetScriptUrl;
+    script.async = true;
+    if (options.widgetKey)
+        script.dataset.apiKey = options.widgetKey;
+    script.dataset.apiUrl = options.appilotApiUrl || DEFAULT_APPILOT_API_URL;
+    script.dataset.userToken = relayed.token;
+    if (options.brandName)
+        script.dataset.brandName = options.brandName;
+    script.dataset.position = options.position ?? 'bottom-right';
+    script.dataset.theme = options.theme ?? 'host';
+    script.dataset.language = options.language ?? 'en';
+    script.addEventListener('load', () => {
+        if (attempt !== activeAttempt) {
+            script.remove();
+            return;
+        }
+        if (!hasRequiredWidgetApi()) {
+            console.warn(`[appilot] widget bundle loaded without its panel API; ${label} disabled`);
+            cleanFailedAttempt(attempt, script);
+            return;
+        }
+        clearBootTimer();
+        bootAbortController = null;
+        setAvailability('ready');
+        scheduleTokenRefresh(relayed.expiresIn, options);
+        attachRefreshRequestListener(options);
+    });
+    script.addEventListener('error', () => {
+        if (attempt !== activeAttempt) {
+            script.remove();
+            return;
+        }
+        console.warn(`[appilot] widget bundle failed to load; ${label} disabled`);
+        cleanFailedAttempt(attempt, script);
+    });
+    document.head.appendChild(script);
+    scriptEl = script;
+}
+/** Test-only: reset module state between tests. Never call from app code. */
+export function __resetAppilotWidgetForTests() {
+    activeAttempt += 1;
+    clearBootTimer();
+    bootAbortController?.abort();
+    bootAbortController = null;
+    clearRefreshTimer();
+    detachRefreshRequestListener();
+    scriptEl?.remove();
+    scriptEl = null;
+    listeners.clear();
+    availability = 'unknown';
+    warnedMissingConfig = false;
+}

package/package.json

@@ -1,17 +1,52 @@
 {
-	"name": "appilot",
-	"version": "0.0.1",
-	"description": "Name reservation for the Appilot SDK. The published SDK will land here.",
-	"keywords": ["appilot", "webmcp", "agent", "assistant", "widget"],
-	"homepage": "https://appilot.space",
-	"license": "ISC",
-	"author": "BetterKnow GmbH",
-	"files": ["README.md"],
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	},
-	"engines": {
-		"node": ">=18"
-	}
-}
+  "name": "appilot",
+  "version": "0.1.0",
+  "description": "Appilot SDK: the single developer-facing surface for building on Appilot. Boot the assistant (bootAppilotWidget), register client actions (registerTool, WebMCP-aligned), and run Focused Sessions (startFocusedSession). Browser-only, React-free, zero runtime dependencies.",
+  "homepage": "https://appilot.space",
+  "author": "BetterKnow GmbH",
+  "keywords": [
+    "appilot",
+    "webmcp",
+    "agent",
+    "assistant",
+    "widget",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "jsdom": "^26.1.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "ISC",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}