appilot 0.0.1 → 0.1.1

package/dist/webmcp/registry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * In-page client-action registry: the WebMCP-aligned tool surface a host page
+ * declares at runtime so the Appilot agent can call its actions.
+ *
+ * WHY a window-anchored global (not a module singleton): the registry must be
+ * reachable from code that does NOT share this module instance.
+ *   - Widget: the embedding page and the widget bundle are separate bundles in
+ *     the same realm; a module-level singleton in one is invisible to the other.
+ *   - Extension: the content-script runs in an isolated world; the page's tools
+ *     live in the main world. A main-world bridge collects/invokes via this
+ *     global. See packages/apps/extension/.../mainWorldWebmcp.ts.
+ * Anchoring on `window.__APPILOT_WEBMCP__` (mirroring `navigator.modelContext`)
+ * gives every party one stable handle. This file is the only place that reads
+ * or writes that global.
+ *
+ * Standard alignment: we bind to the stable WebMCP descriptor
+ * (name/description/inputSchema/execute → {content:[{type,text}]}) and treat the
+ * namespace (`navigator.modelContext` vs `document.modelContext`) as detect-only.
+ * See docs/content-model/tools-client-actions.md and webmcp-alignment.md.
+ */
+export interface ClientToolContent {
+    type: 'text';
+    text: string;
+}
+export interface ClientToolResult {
+    content?: ClientToolContent[];
+    /** Loose escape hatch: handlers that return raw JSON are normalized too. */
+    [k: string]: unknown;
+}
+export interface ClientToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema for the args. Mirrors WebMCP `inputSchema`. */
+    inputSchema?: Record<string, unknown>;
+    /** Mirrors WebMCP `annotations.readOnlyHint`. Absent ⇒ treated as mutating. */
+    annotations?: {
+        readOnlyHint?: boolean;
+    };
+    execute: (input: Record<string, unknown>) => Promise<ClientToolResult | unknown> | ClientToolResult | unknown;
+}
+/** The agent-facing descriptor (no handler) shipped to the backend per turn. */
+export interface SerializedClientTool {
+    name: string;
+    description: string;
+    input_schema?: Record<string, unknown>;
+    read_only: boolean;
+    title?: string;
+}
+export interface ClientToolHandle {
+    unregister(): void;
+}
+/**
+ * Register a client tool/action. Idempotent per name (re-registering replaces).
+ * Returns a handle whose `unregister()` removes it (use on route change).
+ *
+ * Secure-context only (HTTPS / localhost / *.lvh.me), matching the standard.
+ * On a non-secure context the call is a no-op and returns an inert handle.
+ */
+export declare function registerClientTool(def: ClientToolDefinition): ClientToolHandle;
+/** Remove a registered tool by name. */
+export declare function unregisterClientTool(name: string): void;
+/** Subscribe to registry changes (WebMCP `toolchange` analogue). */
+export declare function onClientToolsChange(listener: () => void): () => void;
+/** Serialize the current registry to the agent-facing descriptors (no handlers). */
+export declare function serializeClientTools(): SerializedClientTool[];
+/**
+ * Invoke a registered handler by name and normalize the result to a plain
+ * value the agent loop can serialize. Returns a structured error object when
+ * the action is unknown or throws (never rejects).
+ */
+export declare function invokeClientTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+/** Collapse a WebMCP `{content:[{type,text}]}` result or raw JSON to a value. */
+export declare function normalizeResult(raw: unknown): unknown;
+/** Test/inspection helper: clear the global registry. */
+export declare function __resetClientToolRegistry(): void;

package/dist/webmcp/registry.js

@@ -0,0 +1,152 @@
+/**
+ * In-page client-action registry: the WebMCP-aligned tool surface a host page
+ * declares at runtime so the Appilot agent can call its actions.
+ *
+ * WHY a window-anchored global (not a module singleton): the registry must be
+ * reachable from code that does NOT share this module instance.
+ *   - Widget: the embedding page and the widget bundle are separate bundles in
+ *     the same realm; a module-level singleton in one is invisible to the other.
+ *   - Extension: the content-script runs in an isolated world; the page's tools
+ *     live in the main world. A main-world bridge collects/invokes via this
+ *     global. See packages/apps/extension/.../mainWorldWebmcp.ts.
+ * Anchoring on `window.__APPILOT_WEBMCP__` (mirroring `navigator.modelContext`)
+ * gives every party one stable handle. This file is the only place that reads
+ * or writes that global.
+ *
+ * Standard alignment: we bind to the stable WebMCP descriptor
+ * (name/description/inputSchema/execute → {content:[{type,text}]}) and treat the
+ * namespace (`navigator.modelContext` vs `document.modelContext`) as detect-only.
+ * See docs/content-model/tools-client-actions.md and webmcp-alignment.md.
+ */
+const GLOBAL_KEY = '__APPILOT_WEBMCP__';
+function getWindow() {
+    return typeof window !== 'undefined' ? window : undefined;
+}
+function getRegistry() {
+    const w = getWindow();
+    if (!w)
+        return undefined;
+    const holder = w;
+    if (!holder[GLOBAL_KEY]) {
+        holder[GLOBAL_KEY] = { version: 1, tools: new Map(), listeners: new Set() };
+    }
+    return holder[GLOBAL_KEY];
+}
+function isSecureContextOk() {
+    const w = getWindow();
+    if (!w)
+        return false;
+    // Mirror WebMCP's [SecureContext]. Allow localhost/127.* for dev + playground.
+    if (w.isSecureContext)
+        return true;
+    const host = w.location?.hostname ?? '';
+    return host === 'localhost' || host === '127.0.0.1' || host.endsWith('.localhost') || host.endsWith('.lvh.me');
+}
+function notify(reg) {
+    for (const fn of reg.listeners) {
+        try {
+            fn();
+        }
+        catch { /* listener errors are non-fatal */ }
+    }
+}
+/**
+ * Register a client tool/action. Idempotent per name (re-registering replaces).
+ * Returns a handle whose `unregister()` removes it (use on route change).
+ *
+ * Secure-context only (HTTPS / localhost / *.lvh.me), matching the standard.
+ * On a non-secure context the call is a no-op and returns an inert handle.
+ */
+export function registerClientTool(def) {
+    const reg = getRegistry();
+    if (!reg || !isSecureContextOk()) {
+        return { unregister() { } };
+    }
+    if (!def || typeof def.name !== 'string' || typeof def.execute !== 'function') {
+        throw new Error('registerClientTool: { name, execute } are required');
+    }
+    reg.tools.set(def.name, def);
+    notify(reg);
+    let active = true;
+    return {
+        unregister() {
+            if (!active)
+                return;
+            active = false;
+            if (reg.tools.get(def.name) === def) {
+                reg.tools.delete(def.name);
+                notify(reg);
+            }
+        },
+    };
+}
+/** Remove a registered tool by name. */
+export function unregisterClientTool(name) {
+    const reg = getRegistry();
+    if (!reg)
+        return;
+    if (reg.tools.delete(name))
+        notify(reg);
+}
+/** Subscribe to registry changes (WebMCP `toolchange` analogue). */
+export function onClientToolsChange(listener) {
+    const reg = getRegistry();
+    if (!reg)
+        return () => { };
+    reg.listeners.add(listener);
+    return () => { reg.listeners.delete(listener); };
+}
+/** Serialize the current registry to the agent-facing descriptors (no handlers). */
+export function serializeClientTools() {
+    const reg = getRegistry();
+    if (!reg)
+        return [];
+    const out = [];
+    for (const def of reg.tools.values()) {
+        out.push({
+            name: def.name,
+            description: def.description ?? '',
+            input_schema: def.inputSchema,
+            read_only: def.annotations?.readOnlyHint === true,
+            title: def.name,
+        });
+    }
+    return out;
+}
+/**
+ * Invoke a registered handler by name and normalize the result to a plain
+ * value the agent loop can serialize. Returns a structured error object when
+ * the action is unknown or throws (never rejects).
+ */
+export async function invokeClientTool(name, args) {
+    const reg = getRegistry();
+    const def = reg?.tools.get(name);
+    if (!def) {
+        return { ok: false, error: 'ACTION_NOT_REGISTERED', detail: `no client action registered as "${name}"` };
+    }
+    try {
+        const raw = await def.execute(args ?? {});
+        return { ok: true, data: normalizeResult(raw) };
+    }
+    catch (err) {
+        return { ok: false, error: 'ACTION_FAILED', detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Collapse a WebMCP `{content:[{type,text}]}` result or raw JSON to a value. */
+export function normalizeResult(raw) {
+    if (raw && typeof raw === 'object' && Array.isArray(raw.content)) {
+        const parts = raw.content;
+        const text = parts.filter(p => p && p.type === 'text').map(p => p.text).join('\n').trim();
+        if (text)
+            return text;
+    }
+    return raw;
+}
+/** Test/inspection helper: clear the global registry. */
+export function __resetClientToolRegistry() {
+    const reg = getRegistry();
+    if (reg) {
+        reg.tools.clear();
+        reg.listeners.clear();
+    }
+}

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,91 @@
+/**
+ * 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 and handed
+ *   to the live instance through `window.Appilot.setUserToken`, so a long-lived
+ *   tab never starts 401ing on a healthy host session. The refreshed token is
+ *   NOT written back to the DOM (see "The token and the DOM" below).
+ * - 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).
+ *
+ * ## The token and the DOM
+ *
+ * `data-user-token` is a bearer token for the end user. Anything that can read
+ * the host page's DOM can read it and act as that person against the Appilot
+ * backend, so it must not live there.
+ *
+ * Two changes follow. The refresh no longer writes the rotated token back to
+ * the tag: `window.Appilot.setUserToken` already feeds the live instance, and a
+ * later re-boot re-relays a fresh token anyway, so the DOM write bought a
+ * hypothetical reboot path at the price of a token sitting in the page for the
+ * life of the tab, being renewed there every ~48 minutes.
+ *
+ * The boot token still passes through the attribute, because that is the only
+ * channel the shipped widget bundle reads its configuration from, and it is
+ * removed as soon as the bundle has consumed it (`releaseBootToken`). That
+ * shrinks the exposure from the lifetime of the page to the interval between
+ * appending the script and the bundle parsing its config. Closing it entirely
+ * needs the widget to accept a non-DOM handoff; until then, treat the boot
+ * token as short-lived and keep the relay's TTL short.
+ */
+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;