appilot 0.0.1 → 0.1.0

package/dist/httpFetch.d.ts

@@ -0,0 +1,52 @@
+/**
+ * HTTP-proxy DOM tool. Lets the backend issue a fetch from inside the page the
+ * user is on so the host-application session cookie is carried automatically
+ * (`credentials: 'include'`), without the backend ever seeing a credential.
+ *
+ * Shared between the two in-page surfaces:
+ *   - Chrome extension: invoked from the content script (relayed by the
+ *     background service worker's AgentDomBridge).
+ *   - Embeddable widget: invoked directly in-page by the widget's
+ *     AgentDomBridge (the widget already runs inside the host page).
+ *
+ * Used by customer-authored Tools whose `runtime_spec.kind === 'http_proxy'`.
+ * The backend builds the URL + headers + body from the tool's runtime_spec
+ * (NOT from agent-supplied args), then asks the client to send it. Defence
+ * in depth on this side:
+ *
+ *   1. Same-origin enforcement against `location.origin`. Even if the backend
+ *      asked us to hit `https://evil.example`, this responder rejects it.
+ *      Relative paths only.
+ *   2. Method allowlist (GET / POST / PUT / DELETE).
+ *   3. AbortController-backed timeout, capped at 15 s.
+ *   4. 401/403 surfaces as a distinct `AUTH_REQUIRED` error so the agent loop
+ *      can stop without nag-retrying.
+ *   5. No header echo: headers we forward are taken from the request payload
+ *      and `credentials: 'include'` is FORCED. We do not write `Authorization`
+ *      or `Cookie` even if the payload tries.
+ *
+ * See:
+ *   - packages/libs/shared/src/types/agent/tools.ts § HttpProxyRuntimeSpec
+ *   - docs/content-model/tools-http-proxy.md
+ */
+export interface HttpFetchArgs {
+    method?: string;
+    path?: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeout_ms?: number;
+}
+export type HttpFetchResult = {
+    ok: true;
+    status: number;
+    json: unknown;
+    duration_ms: number;
+} | {
+    ok: false;
+    error: 'BAD_REQUEST' | 'BLOCKED_ORIGIN' | 'BLOCKED_METHOD' | 'TIMEOUT' | 'NETWORK' | 'AUTH_REQUIRED' | 'STATUS' | 'PARSE';
+    detail?: string;
+    status?: number;
+    duration_ms?: number;
+};
+export declare function httpFetch(rawArgs: Record<string, unknown>): Promise<HttpFetchResult>;

package/dist/httpFetch.js

@@ -0,0 +1,137 @@
+/**
+ * HTTP-proxy DOM tool. Lets the backend issue a fetch from inside the page the
+ * user is on so the host-application session cookie is carried automatically
+ * (`credentials: 'include'`), without the backend ever seeing a credential.
+ *
+ * Shared between the two in-page surfaces:
+ *   - Chrome extension: invoked from the content script (relayed by the
+ *     background service worker's AgentDomBridge).
+ *   - Embeddable widget: invoked directly in-page by the widget's
+ *     AgentDomBridge (the widget already runs inside the host page).
+ *
+ * Used by customer-authored Tools whose `runtime_spec.kind === 'http_proxy'`.
+ * The backend builds the URL + headers + body from the tool's runtime_spec
+ * (NOT from agent-supplied args), then asks the client to send it. Defence
+ * in depth on this side:
+ *
+ *   1. Same-origin enforcement against `location.origin`. Even if the backend
+ *      asked us to hit `https://evil.example`, this responder rejects it.
+ *      Relative paths only.
+ *   2. Method allowlist (GET / POST / PUT / DELETE).
+ *   3. AbortController-backed timeout, capped at 15 s.
+ *   4. 401/403 surfaces as a distinct `AUTH_REQUIRED` error so the agent loop
+ *      can stop without nag-retrying.
+ *   5. No header echo: headers we forward are taken from the request payload
+ *      and `credentials: 'include'` is FORCED. We do not write `Authorization`
+ *      or `Cookie` even if the payload tries.
+ *
+ * See:
+ *   - packages/libs/shared/src/types/agent/tools.ts § HttpProxyRuntimeSpec
+ *   - docs/content-model/tools-http-proxy.md
+ */
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 15_000;
+const ALLOWED_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE']);
+const FORBIDDEN_HEADER_NAMES = new Set(['authorization', 'cookie']);
+export async function httpFetch(rawArgs) {
+    const args = rawArgs;
+    const method = String(args.method || 'GET').toUpperCase();
+    if (!ALLOWED_METHODS.has(method)) {
+        return { ok: false, error: 'BLOCKED_METHOD', detail: `method=${method}` };
+    }
+    const pathInput = typeof args.path === 'string' ? args.path : '';
+    if (!pathInput) {
+        return { ok: false, error: 'BAD_REQUEST', detail: 'missing path' };
+    }
+    // Same-origin enforcement. `new URL(pathInput, location.origin)` resolves a
+    // relative path against the current page origin. An absolute URL that points
+    // elsewhere will resolve with a different `.origin` and we reject it.
+    let target;
+    try {
+        target = new URL(pathInput, location.origin);
+    }
+    catch (err) {
+        return { ok: false, error: 'BAD_REQUEST', detail: `invalid path: ${String(err.message)}` };
+    }
+    if (target.origin !== location.origin) {
+        return { ok: false, error: 'BLOCKED_ORIGIN', detail: `target=${target.origin} active_tab=${location.origin}` };
+    }
+    if (args.query && typeof args.query === 'object') {
+        for (const [k, v] of Object.entries(args.query)) {
+            if (k && typeof v === 'string' && v.length > 0) {
+                target.searchParams.append(k, v);
+            }
+        }
+    }
+    const headers = new Headers();
+    if (args.headers && typeof args.headers === 'object') {
+        for (const [k, v] of Object.entries(args.headers)) {
+            if (FORBIDDEN_HEADER_NAMES.has(k.toLowerCase()))
+                continue;
+            if (typeof v === 'string')
+                headers.set(k, v);
+        }
+    }
+    if (!headers.has('Accept'))
+        headers.set('Accept', 'application/json');
+    const requestedTimeout = typeof args.timeout_ms === 'number' && Number.isFinite(args.timeout_ms)
+        ? args.timeout_ms
+        : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = Math.min(Math.max(requestedTimeout, 250), MAX_TIMEOUT_MS);
+    const init = {
+        method,
+        headers,
+        credentials: 'include',
+        redirect: 'follow',
+    };
+    if (method !== 'GET' && method !== 'DELETE' && args.body !== undefined) {
+        if (!headers.has('Content-Type'))
+            headers.set('Content-Type', 'application/json');
+        try {
+            init.body = typeof args.body === 'string' ? args.body : JSON.stringify(args.body);
+        }
+        catch (err) {
+            return { ok: false, error: 'BAD_REQUEST', detail: `body serialise: ${err.message}` };
+        }
+    }
+    const controller = new AbortController();
+    init.signal = controller.signal;
+    const timeoutHandle = window.setTimeout(() => controller.abort(), timeoutMs);
+    const startedAt = performance.now();
+    let response;
+    try {
+        response = await fetch(target.toString(), init);
+    }
+    catch (err) {
+        const elapsed = Math.round(performance.now() - startedAt);
+        if (controller.signal.aborted) {
+            return { ok: false, error: 'TIMEOUT', detail: `${timeoutMs}ms`, duration_ms: elapsed };
+        }
+        return { ok: false, error: 'NETWORK', detail: err.message, duration_ms: elapsed };
+    }
+    finally {
+        window.clearTimeout(timeoutHandle);
+    }
+    const elapsed = Math.round(performance.now() - startedAt);
+    if (response.status === 401 || response.status === 403) {
+        return { ok: false, error: 'AUTH_REQUIRED', status: response.status, duration_ms: elapsed };
+    }
+    let parsed;
+    const contentType = response.headers.get('content-type') || '';
+    const text = await response.text().catch(() => '');
+    if (contentType.includes('application/json') || (text && (text.startsWith('{') || text.startsWith('[')))) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            return { ok: false, error: 'PARSE', status: response.status, detail: err.message, duration_ms: elapsed };
+        }
+    }
+    else {
+        parsed = { _text: text.slice(0, 4000) };
+    }
+    if (!response.ok) {
+        return { ok: false, error: 'STATUS', status: response.status, detail: typeof parsed === 'object' ? JSON.stringify(parsed).slice(0, 500) : String(parsed).slice(0, 500), duration_ms: elapsed };
+    }
+    return { ok: true, status: response.status, json: parsed, duration_ms: elapsed };
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `appilot`: the single developer-facing surface for building on Appilot.
+ *
+ * Four capabilities, one package:
+ *   - Boot the assistant:   bootAppilotWidget(...)          (widget/boot)
+ *   - Register client actions: registerTool(...)            (WebMCP-aligned)
+ *   - Run Focused Sessions: startFocusedSession(...)        (mission-scoped)
+ *     and resumeFocusedSession(...) to re-attach after a page reload
+ *   - Coexist with your modals: isAppilotSurface(...)       (dom/surfaces)
+ *
+ * Browser-only, React-free, zero runtime dependencies. The internal runtime the
+ * widget/extension use to FULFILL these calls lives at `appilot/runtime`.
+ *
+ * See the docs-site "Building on Appilot" guide and
+ * docs/content-model/tools-client-actions.md.
+ */
+export { bootAppilotWidget, getWidgetAvailability, subscribeWidgetAvailability, type WidgetAvailability, type AppilotWidgetBootOptions, } from './widget/boot.js';
+export { registerTool, registerClientTool, unregisterClientTool, onClientToolsChange, hasNativeWebMcp, type ClientToolDefinition, type ClientToolHandle, } from './webmcp/sdk.js';
+export type { ClientToolContent, ClientToolResult } from './webmcp/registry.js';
+export { isAppilotSurface, markAppilotSurface, APPILOT_SURFACE_ATTR, type AppilotSurfaceKind, } from './dom/surfaces.js';
+export { startFocusedSession, resumeFocusedSession, getResumableFocusedSessionId, forgetFocusedSession, type FocusedSessionPageHandle, } from './focusedSessions/pageSdk.js';
+export type { FocusedSessionMission, FocusedSessionStartRequest, FocusedSessionStartResult, FocusedSessionOutcomeEvent, FocusedSessionPresentation, FocusedSessionEndStatus, FocusedSessionEndedEvent, } from './sessions/types.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `appilot`: the single developer-facing surface for building on Appilot.
+ *
+ * Four capabilities, one package:
+ *   - Boot the assistant:   bootAppilotWidget(...)          (widget/boot)
+ *   - Register client actions: registerTool(...)            (WebMCP-aligned)
+ *   - Run Focused Sessions: startFocusedSession(...)        (mission-scoped)
+ *     and resumeFocusedSession(...) to re-attach after a page reload
+ *   - Coexist with your modals: isAppilotSurface(...)       (dom/surfaces)
+ *
+ * Browser-only, React-free, zero runtime dependencies. The internal runtime the
+ * widget/extension use to FULFILL these calls lives at `appilot/runtime`.
+ *
+ * See the docs-site "Building on Appilot" guide and
+ * docs/content-model/tools-client-actions.md.
+ */
+// --- Boot the assistant -----------------------------------------------------
+export { bootAppilotWidget, getWidgetAvailability, subscribeWidgetAvailability, } from './widget/boot.js';
+// --- Client actions (WebMCP-aligned) ---------------------------------------
+export { registerTool, registerClientTool, unregisterClientTool, onClientToolsChange, hasNativeWebMcp, } from './webmcp/sdk.js';
+// --- Coexisting with the host app's own modal layers ------------------------
+export { isAppilotSurface, markAppilotSurface, APPILOT_SURFACE_ATTR, } from './dom/surfaces.js';
+// --- Focused Sessions -------------------------------------------------------
+export { startFocusedSession, resumeFocusedSession, getResumableFocusedSessionId, forgetFocusedSession, } from './focusedSessions/pageSdk.js';

package/dist/runtime.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `appilot/runtime`: INTERNAL runtime primitives the Appilot widget and
+ * browser-extension content scripts use to FULFILL the public SDK calls
+ * (register/collect/serialize/invoke client tools, execute the DOM tools +
+ * `http_fetch`, and back the Focused Sessions transport).
+ *
+ * This entry is NOT part of the public developer surface: host apps import from
+ * `appilot`. It is exposed as a subpath so the assistant surfaces (which
+ * DO ship this logic) import it without pulling it into the public barrel.
+ */
+export { runDomTool, resetDomToolTurn, type DomToolRequest } from './domResponder.js';
+export { httpFetch, type HttpFetchArgs, type HttpFetchResult } from './httpFetch.js';
+export { collectClientTools } from './webmcp/sdk.js';
+export { invokeClientTool, serializeClientTools, normalizeResult, __resetClientToolRegistry, type SerializedClientTool, } from './webmcp/registry.js';
+export { registerFocusedSessionProvider, type FocusedSessionProvider, } from './focusedSessions/pageSdk.js';

package/dist/runtime.js

@@ -0,0 +1,18 @@
+/**
+ * `appilot/runtime`: INTERNAL runtime primitives the Appilot widget and
+ * browser-extension content scripts use to FULFILL the public SDK calls
+ * (register/collect/serialize/invoke client tools, execute the DOM tools +
+ * `http_fetch`, and back the Focused Sessions transport).
+ *
+ * This entry is NOT part of the public developer surface: host apps import from
+ * `appilot`. It is exposed as a subpath so the assistant surfaces (which
+ * DO ship this logic) import it without pulling it into the public barrel.
+ */
+// DOM tools + HTTP-proxy executor (the agent_dom_request round-trip).
+export { runDomTool, resetDomToolTurn } from './domResponder.js';
+export { httpFetch } from './httpFetch.js';
+// WebMCP client-action collection / serialization / invocation.
+export { collectClientTools } from './webmcp/sdk.js';
+export { invokeClientTool, serializeClientTools, normalizeResult, __resetClientToolRegistry, } from './webmcp/registry.js';
+// Focused Sessions transport provider (implemented by the assistant surface).
+export { registerFocusedSessionProvider, } from './focusedSessions/pageSdk.js';

package/dist/sessions/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Focused Sessions: the public type contract for the page-facing SDK surface
+ * (`startFocusedSession` and its handle). These are the types a host app touches
+ * when it starts an app-initiated, mission-scoped agent conversation and receives
+ * its structured outcome. See docs/agent/focused-sessions.md.
+ *
+ * This file is the SINGLE SOURCE OF TRUTH for the SDK-facing session types.
+ * `appilot-shared` re-exports these (type-only) from `appilot-shared/types` so
+ * backend/repository code keeps its existing import path; the mission/template
+ * cluster that only the backend needs stays in `appilot-shared`.
+ */
+/**
+ * The RESOLVED mission frame a session runs under (the purely-runtime channel;
+ * the DB-anchored channel composes this server-side from a Session Template).
+ * Untrusted when page-supplied: sanitized + capped + gated by deployment config.
+ */
+export interface FocusedSessionMission {
+    /** Display name for the session header ("Role-play: unhappy customer"). */
+    name: string;
+    /**
+     * The mission prompt: function, persona, boundaries and completion criteria,
+     * with variable slots already substituted.
+     */
+    prompt: string;
+    /**
+     * App/client tool names the session may use, on top of a minimal internal
+     * set. Empty/absent = no app or client tools. A session can only narrow the
+     * catalog, never widen it past what the tenant already has.
+     */
+    allowed_tools?: string[];
+    /** Optional KB doc-id allowlist; absent = KB tools see the normal tenant scope. */
+    kb_doc_ids?: string[];
+    /** JSON Schema the `complete_session` outcome payload must satisfy. */
+    outcome_schema: Record<string, unknown>;
+    /** Turn budget; the session is abandoned server-side when exceeded. */
+    max_turns?: number;
+}
+/**
+ * How the assistant surface PRESENTS a focused session.
+ *
+ * A mission-scoped conversation is a different genre from ambient assistance,
+ * and the runtime has always known that (mission, closed tool scope,
+ * lifecycle, structured outcome). The UI did not: a role-play ran inside the
+ * ambient chrome plus a chip, so an end user saw a KB coverage diagnostic, an
+ * input that said "Ask anything about this page", and a one-click "New
+ * conversation" that silently orphaned the activity.
+ *
+ * THIS IS NOT A LAYOUT LANGUAGE, and keeping it that way is the point. Every
+ * field is a closed union or a plain string of COPY; none is a color, a size,
+ * a layout, a component, or markup. The rule for adding one: it must be
+ * justifiable for at least three unrelated app genres (a role-play, a support
+ * triage, a guided onboarding). A field only one app would ever set does not
+ * belong in a platform contract. A host that needs more than this renders it
+ * on its own page and lets the session drive it; an open presentation contract
+ * would just rebuild per-app bespoke UI in JSON, which is the cost Appilot
+ * exists to remove.
+ */
+export interface FocusedSessionPresentation {
+    /**
+     * `immersive` suppresses ambient-assistance furniture that is meaningless
+     * or harmful inside a mission: the KB coverage chip (an app-owner
+     * diagnostic), the welcome tip, and the "New conversation" affordance.
+     * Defaults to `ambient`, so every existing session is unchanged.
+     */
+    chrome?: 'ambient' | 'immersive';
+    /**
+     * `agent` runs one opening turn at start, so the assistant speaks first.
+     * For an activity this is the difference between a chat window and
+     * something that has begun: a learner should not have to type "hello" at a
+     * persona to make a role-play start. Defaults to `user`.
+     */
+    opening?: 'agent' | 'user';
+    /** Replaces "Ask anything about this page..." (e.g. "Reply to Mr. Weber"). */
+    input_placeholder?: string;
+    /** Relabels the session exit affordance (e.g. "End activity"). */
+    exit_label?: string;
+}
+/** Page SDK -> backend: start a focused session. Exactly one of template_id / mission. */
+export interface FocusedSessionStartRequest {
+    /** DB-anchored channel: the Session Template to instantiate. */
+    template_id?: string;
+    /** Purely-runtime channel (dev/demos; gated by deployment config). */
+    mission?: FocusedSessionMission;
+    /** Values for the template's declared variable slots. */
+    variables?: Record<string, string>;
+}
+export interface FocusedSessionStartResult {
+    focused_session_id: string;
+    /** The conversation the session is bound to (1:1, never rotates). */
+    conversation_id: number;
+    /** Resolved display name for the session header. */
+    name: string;
+    /**
+     * How the assistant surface should present this session. Resolved
+     * server-side from the template; absent means ambient defaults.
+     */
+    presentation?: FocusedSessionPresentation;
+}
+/**
+ * Payload of the `session_outcome` SSE event and of the host-page callback.
+ * Emitted once, on the turn where the agent calls `complete_session` with a
+ * schema-valid outcome. The outcome is AI output: apps must run it through their
+ * own review model, never treat it as human-validated truth.
+ */
+export interface FocusedSessionOutcomeEvent {
+    focused_session_id: string;
+    status: 'completed';
+    /** The schema-validated structured result. */
+    outcome: Record<string, unknown>;
+}
+/**
+ * How a session reached a terminal state WITHOUT delivering an outcome
+ * (the `onEnded` page callback):
+ *   - `abandoned`: the server abandoned it (turn budget exhausted, or an
+ *     out-of-band end) and the assistant surface learned it from the typed
+ *     stream error of the refused turn;
+ *   - `failed`: the mission could not be fulfilled and no outcome will ever
+ *     exist for it. Emitted server-side as the typed `SESSION_FAILED` stream
+ *     error. Distinct from `abandoned`, which means the session ran out of
+ *     room rather than out of premise;
+ *   - `expired`: reserved for a future session TTL; surfaces map unknown
+ *     terminal causes here;
+ *   - `ended`: the page itself called `handle.end()`.
+ *
+ * NOTE the asymmetry with a mission that fails its PREFLIGHT: that session is
+ * never created, so it has no terminal status at all. `startFocusedSession`
+ * rejects instead, and the page renders its own error state. See
+ * docs/agent/focused-sessions.md § Preflight.
+ */
+export type FocusedSessionEndStatus = 'abandoned' | 'expired' | 'failed' | 'ended';
+/**
+ * Payload of the page-facing `onEnded` callback: the session reached a terminal
+ * state WITHOUT having delivered an outcome. Fired exactly once per session, and
+ * NEVER for a session that delivered a `session_outcome` (`onOutcome` and
+ * `onEnded` are mutually exclusive).
+ */
+export interface FocusedSessionEndedEvent {
+    focused_session_id: string;
+    status: FocusedSessionEndStatus;
+}

package/dist/sessions/types.js

@@ -0,0 +1,12 @@
+/**
+ * Focused Sessions: the public type contract for the page-facing SDK surface
+ * (`startFocusedSession` and its handle). These are the types a host app touches
+ * when it starts an app-initiated, mission-scoped agent conversation and receives
+ * its structured outcome. See docs/agent/focused-sessions.md.
+ *
+ * This file is the SINGLE SOURCE OF TRUTH for the SDK-facing session types.
+ * `appilot-shared` re-exports these (type-only) from `appilot-shared/types` so
+ * backend/repository code keeps its existing import path; the mission/template
+ * cluster that only the backend needs stays in `appilot-shared`.
+ */
+export {};

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();
+    }
+}