appilot 0.0.1 → 0.1.0

package/README.md

@@ -1,12 +1,106 @@
 # appilot
 
-This version is a name reservation, not a working package. It contains no code.
+The Appilot browser SDK. Boot the assistant, let the agent act through your own
+UI, and run mission-scoped sessions.
 
-Appilot adds intelligence to any web app: its AI helps people operate the app and
-act on their behalf, shipping as a browser extension or an embeddable widget.
-The developer SDK (widget boot, client-registered actions aligned with WebMCP,
-focused sessions) will publish here.
+Browser-only, React-free, zero runtime dependencies.
 
-See https://appilot.space.
+```bash
+npm install appilot
+```
 
-Maintained by BetterKnow GmbH.
+Pair it with [`appilot-server`](https://www.npmjs.com/package/appilot-server),
+which runs the identity relay in your backend. The assistant serves identified
+users only, and the credential that mints that identity must never reach a
+browser.
+
+## Boot the assistant
+
+```ts
+import { bootAppilotWidget } from 'appilot';
+
+bootAppilotWidget({
+  widgetScriptUrl: 'https://cdn.appilot.space/widget/v1/appilot.esm.js',
+  widgetKey: 'wk_live_…',            // publishable; optional on a registered domain
+  tokenEndpoint: '/api/widget/token', // your relay
+  brandName: 'Acme',                  // names the assistant, not your app
+});
+```
+
+On a registered production domain the tenant is resolved from the page's domain,
+so the key is optional. It is required on localhost, where no domain resolves.
+
+## Let the agent act in your app
+
+`registerTool` declares a capability your page performs, in the user's own
+session: navigate the SPA, open a modal, or a mutation your page already knows
+how to do safely. It is WebMCP-aligned, so where the browser exposes a native
+`navigator.modelContext` the same call registers there too.
+
+```ts
+import { registerTool } from 'appilot';
+
+const handle = registerTool({
+  name: 'open_booking',
+  description: 'Open a booking by id so the user can see it.',
+  inputSchema: {
+    type: 'object',
+    properties: { booking_id: { type: 'string' } },
+    required: ['booking_id'],
+  },
+  annotations: { readOnlyHint: true },   // absent or false means mutating,
+                                         // and the agent confirms first
+  async execute({ booking_id }) {
+    navigate(`/bookings/${booking_id}`);
+    return { content: [{ type: 'text', text: `Opened booking ${booking_id}.` }] };
+  },
+});
+
+handle.unregister();   // on route change
+```
+
+Backend operations belong in an HTTP-proxy tool configured server-side instead,
+where the credential stays out of the page.
+
+## Mission-scoped conversations
+
+When the conversation *is* the unit of work (a role-play, a tutoring dialogue, an
+assessment), your app opens a Focused Session against a template you authored and
+receives a structured outcome.
+
+```ts
+import { startFocusedSession, resumeFocusedSession } from 'appilot';
+
+const handle = await startFocusedSession({
+  template_id: 'role-play-activity',
+  variables: { role: 'unhappy customer' },
+});
+
+handle.onOutcome(outcome => saveEvidence(outcome));
+handle.onEnded(({ status }) => showEndedState(status));  // no outcome is coming
+```
+
+`startFocusedSession` **rejects** when the template's mandatory grounding is
+unavailable, and no session is created. That is the contract, not an edge case:
+your page renders its own error state instead of a model narrating a backend
+problem at your user.
+
+After a full page reload, `resumeFocusedSession()` re-attaches to the session
+this tab started, or resolves to `null` when there is nothing running. Ownership
+is checked server-side.
+
+Outcomes reach your page through the user's browser, so they are client-trusted.
+Before treating one as evidence, re-read it server to server.
+
+## Also exported
+
+`isAppilotSurface(element)` lets your own modal or focus trap recognize Appilot's
+chrome and not dismiss itself when the user interacts with the assistant.
+
+## Docs
+
+<https://docs.appilot.space>
+
+## License
+
+ISC

package/dist/dom/surfaces.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The Appilot surface contract: one attribute that identifies every piece of
+ * Appilot chrome living in the host page's top-level DOM.
+ *
+ * ## Why this exists
+ *
+ * `docs/architecture/in-page-overlays.md` settled WHERE our chrome mounts
+ * (always under `document.documentElement`). It says nothing about what happens
+ * when the host app opens a modal layer, and that is where a co-resident
+ * assistant breaks.
+ *
+ * Every modal library (Radix, Headless UI, MUI, Ant, Vaadin, the native
+ * `<dialog>`) implements two behaviours that are hostile to us, because to them
+ * we are indistinguishable from the page underneath:
+ *
+ *   1. Dismiss-on-outside-interaction. A `pointerdown` or `focusin` outside the
+ *      modal's own subtree closes it. Our chrome is ALWAYS outside, so clicking
+ *      the Appilot launcher closes the user's half-filled form.
+ *   2. Focus trapping. Focus that lands outside the modal is yanked back. Even
+ *      with (1) fixed, the user cannot type in our composer.
+ *
+ * A host app can opt out of both, but only if it can answer "is this element
+ * Appilot's?" cheaply and stably. Before this contract it had to guess between
+ * `#appilot-panel-container`, `#appilot-toggle`, `<appilot-assistant>` and
+ * `[data-appilot-widget]` (which is stamped on `<html>` itself, so a naive
+ * `closest()` matches the whole document). That is a trap, and hosts fell into
+ * it. Now there is one selector: `[data-appilot-surface]`.
+ *
+ * See `docs/architecture/host-modal-coexistence.md` for the host-side recipes.
+ */
+/** The attribute every Appilot-injected top-level element carries. */
+export declare const APPILOT_SURFACE_ATTR = "data-appilot-surface";
+/**
+ * What a given piece of chrome is. Hosts may branch on the value (for example,
+ * allowing interaction with the panel but still dismissing on a stray click on
+ * a transient gesture shield), but the common case only tests for presence.
+ */
+export type AppilotSurfaceKind = 
+/** The floating launcher button (extension and widget bubble layout). */
+'launcher'
+/** The assistant panel itself, including its Shadow DOM host. */
+ | 'panel'
+/** Transient drag/resize gesture shields. */
+ | 'shield'
+/** The coach-mark bubble and its dim layer. */
+ | 'coach'
+/** The cyan control-locate comet and impact ring. */
+ | 'locate'
+/** The in-context editor's element-picker capture surface. */
+ | 'picker';
+/**
+ * Stamp an element as Appilot chrome. Call this on EVERY element mounted into
+ * the host page's top-level DOM, at creation time, before it is appended.
+ *
+ * Internal to Appilot's own runtimes (widget, extension, shared overlays).
+ * Host apps consume the contract through {@link isAppilotSurface}.
+ */
+export declare function markAppilotSurface<T extends Element>(element: T, kind: AppilotSurfaceKind): T;
+/**
+ * Does this node belong to Appilot's chrome?
+ *
+ * Pass the target of a pointer or focus event. Returns true for the chrome
+ * element itself and for anything nested inside it, including across a Shadow
+ * DOM boundary: our panel lives in a shadow root, so a real click inside the
+ * composer retargets at the document level to the shadow HOST, which is the
+ * element that carries the attribute.
+ *
+ * Deliberately tolerant about its input (`EventTarget | null`, text nodes,
+ * detached nodes) because callers pass `event.target` straight through and a
+ * dismissal guard must never throw.
+ *
+ * @example Radix / shadcn dialog
+ * ```tsx
+ * <DialogContent
+ *   onInteractOutside={(event) => {
+ *     if (isAppilotSurface(event.target)) event.preventDefault();
+ *   }}
+ * >
+ * ```
+ */
+export declare function isAppilotSurface(target: EventTarget | Node | null | undefined): boolean;

package/dist/dom/surfaces.js

@@ -0,0 +1,91 @@
+/**
+ * The Appilot surface contract: one attribute that identifies every piece of
+ * Appilot chrome living in the host page's top-level DOM.
+ *
+ * ## Why this exists
+ *
+ * `docs/architecture/in-page-overlays.md` settled WHERE our chrome mounts
+ * (always under `document.documentElement`). It says nothing about what happens
+ * when the host app opens a modal layer, and that is where a co-resident
+ * assistant breaks.
+ *
+ * Every modal library (Radix, Headless UI, MUI, Ant, Vaadin, the native
+ * `<dialog>`) implements two behaviours that are hostile to us, because to them
+ * we are indistinguishable from the page underneath:
+ *
+ *   1. Dismiss-on-outside-interaction. A `pointerdown` or `focusin` outside the
+ *      modal's own subtree closes it. Our chrome is ALWAYS outside, so clicking
+ *      the Appilot launcher closes the user's half-filled form.
+ *   2. Focus trapping. Focus that lands outside the modal is yanked back. Even
+ *      with (1) fixed, the user cannot type in our composer.
+ *
+ * A host app can opt out of both, but only if it can answer "is this element
+ * Appilot's?" cheaply and stably. Before this contract it had to guess between
+ * `#appilot-panel-container`, `#appilot-toggle`, `<appilot-assistant>` and
+ * `[data-appilot-widget]` (which is stamped on `<html>` itself, so a naive
+ * `closest()` matches the whole document). That is a trap, and hosts fell into
+ * it. Now there is one selector: `[data-appilot-surface]`.
+ *
+ * See `docs/architecture/host-modal-coexistence.md` for the host-side recipes.
+ */
+/** The attribute every Appilot-injected top-level element carries. */
+export const APPILOT_SURFACE_ATTR = 'data-appilot-surface';
+/**
+ * Stamp an element as Appilot chrome. Call this on EVERY element mounted into
+ * the host page's top-level DOM, at creation time, before it is appended.
+ *
+ * Internal to Appilot's own runtimes (widget, extension, shared overlays).
+ * Host apps consume the contract through {@link isAppilotSurface}.
+ */
+export function markAppilotSurface(element, kind) {
+    element.setAttribute(APPILOT_SURFACE_ATTR, kind);
+    return element;
+}
+/**
+ * Does this node belong to Appilot's chrome?
+ *
+ * Pass the target of a pointer or focus event. Returns true for the chrome
+ * element itself and for anything nested inside it, including across a Shadow
+ * DOM boundary: our panel lives in a shadow root, so a real click inside the
+ * composer retargets at the document level to the shadow HOST, which is the
+ * element that carries the attribute.
+ *
+ * Deliberately tolerant about its input (`EventTarget | null`, text nodes,
+ * detached nodes) because callers pass `event.target` straight through and a
+ * dismissal guard must never throw.
+ *
+ * @example Radix / shadcn dialog
+ * ```tsx
+ * <DialogContent
+ *   onInteractOutside={(event) => {
+ *     if (isAppilotSurface(event.target)) event.preventDefault();
+ *   }}
+ * >
+ * ```
+ */
+export function isAppilotSurface(target) {
+    const element = toElement(target);
+    if (!element)
+        return false;
+    // Walk the composed tree by hand rather than trusting `closest()`: `closest()`
+    // stops at a shadow root, and an element inside a nested shadow tree would
+    // report no match even though its host is ours.
+    let node = element;
+    while (node) {
+        if (node instanceof Element && node.hasAttribute(APPILOT_SURFACE_ATTR))
+            return true;
+        const parent = node.parentNode;
+        node = parent instanceof ShadowRoot ? parent.host : parent;
+    }
+    return false;
+}
+function toElement(target) {
+    if (!target)
+        return null;
+    if (target instanceof Element)
+        return target;
+    // Text nodes are legitimate event targets in some engines; climb to the element.
+    if (target instanceof Node)
+        return target.parentElement;
+    return null;
+}

package/dist/dom/uniqueSelector.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compute a unique-enough CSS selector for a live element.
+ *
+ * Shared by:
+ *   - the in-page DOM responder (`agents/domResponder.ts`), which stamps a
+ *     `selector` onto every element hit at observe time so the backend can mint
+ *     a server-trusted `element_ref` -> `dom_target` (Universal Mode Stage 1);
+ *   - the action-plan runtime's DOM-target resolver
+ *     (`components/actionPlans/utils/resolveDomTarget.ts`), which re-derives a
+ *     fresh selector when a page step's original selector goes stale after a
+ *     re-render (Stage 2 fallback).
+ *
+ * Strategy, cheapest-first:
+ *   1. A stable `#id` when the id is unique and CSS-safe.
+ *   2. Otherwise walk up to the nearest id-anchored ancestor (or the root),
+ *      appending `tag:nth-of-type(k)` segments, stopping as soon as the partial
+ *      selector matches exactly one element.
+ * Returns '' when no selector can be derived (the element is then
+ * unreferenceable; callers fall back to role/name or pause).
+ *
+ * This NEVER trusts model input: it reads only the live DOM.
+ */
+export declare function computeUniqueSelector(el: Element): string;

package/dist/dom/uniqueSelector.js

@@ -0,0 +1,104 @@
+/**
+ * Compute a unique-enough CSS selector for a live element.
+ *
+ * Shared by:
+ *   - the in-page DOM responder (`agents/domResponder.ts`), which stamps a
+ *     `selector` onto every element hit at observe time so the backend can mint
+ *     a server-trusted `element_ref` -> `dom_target` (Universal Mode Stage 1);
+ *   - the action-plan runtime's DOM-target resolver
+ *     (`components/actionPlans/utils/resolveDomTarget.ts`), which re-derives a
+ *     fresh selector when a page step's original selector goes stale after a
+ *     re-render (Stage 2 fallback).
+ *
+ * Strategy, cheapest-first:
+ *   1. A stable `#id` when the id is unique and CSS-safe.
+ *   2. Otherwise walk up to the nearest id-anchored ancestor (or the root),
+ *      appending `tag:nth-of-type(k)` segments, stopping as soon as the partial
+ *      selector matches exactly one element.
+ * Returns '' when no selector can be derived (the element is then
+ * unreferenceable; callers fall back to role/name or pause).
+ *
+ * This NEVER trusts model input: it reads only the live DOM.
+ */
+function cssEscape(value) {
+    const esc = window.CSS?.escape;
+    if (typeof esc === 'function')
+        return esc(value);
+    // Minimal fallback: escape characters that break attribute/id selectors.
+    return value.replace(/([^a-zA-Z0-9_-])/g, '\\$1');
+}
+function isUniqueSelector(selector) {
+    try {
+        return document.querySelectorAll(selector).length === 1;
+    }
+    catch {
+        return false;
+    }
+}
+function nthOfTypeSegment(el) {
+    const tag = el.tagName.toLowerCase();
+    const parent = el.parentElement;
+    if (!parent)
+        return tag;
+    const sameTag = Array.from(parent.children).filter(c => c.tagName === el.tagName);
+    if (sameTag.length === 1)
+        return tag;
+    const index = sameTag.indexOf(el) + 1;
+    return `${tag}:nth-of-type(${index})`;
+}
+// Per-element selector cache. The walk below issues up to 12
+// `querySelectorAll(candidate)` uniqueness probes per element; the action-plan
+// DOM-target heal re-derives a selector for the same live element on repeated
+// ticks, so caching collapses that to a SINGLE validating `querySelector` on
+// the cache hit. The cache is invalidated structurally: a cached selector is
+// only returned when it still resolves to the SAME element (a re-render that
+// moves the element produces a miss and a fresh compute). A WeakMap keyed by
+// the element never leaks across detached nodes.
+const selectorCache = new WeakMap();
+export function computeUniqueSelector(el) {
+    if (!(el instanceof Element))
+        return '';
+    const cached = selectorCache.get(el);
+    if (cached) {
+        try {
+            if (document.querySelector(cached) === el)
+                return cached;
+        }
+        catch {
+            /* cached selector went malformed against a changed DOM: recompute */
+        }
+    }
+    const result = computeUniqueSelectorUncached(el);
+    if (result)
+        selectorCache.set(el, result);
+    return result;
+}
+function computeUniqueSelectorUncached(el) {
+    const id = el.getAttribute('id');
+    if (id && /^[A-Za-z][\w-]*$/.test(id)) {
+        const byId = `#${cssEscape(id)}`;
+        if (isUniqueSelector(byId))
+            return byId;
+    }
+    const segments = [];
+    let node = el;
+    let depth = 0;
+    while (node && node.nodeType === 1 && depth < 12) {
+        const nodeId = node.getAttribute('id');
+        if (nodeId && /^[A-Za-z][\w-]*$/.test(nodeId) && isUniqueSelector(`#${cssEscape(nodeId)}`)) {
+            segments.unshift(`#${cssEscape(nodeId)}`);
+            const candidate = segments.join(' > ');
+            if (isUniqueSelector(candidate))
+                return candidate;
+            break;
+        }
+        segments.unshift(nthOfTypeSegment(node));
+        const candidate = segments.join(' > ');
+        if (isUniqueSelector(candidate))
+            return candidate;
+        node = node.parentElement;
+        depth++;
+    }
+    const full = segments.join(' > ');
+    return isUniqueSelector(full) ? full : '';
+}

package/dist/domResponder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * In-page DOM responder for the agent runtime.
+ *
+ * Implements the six Web-MCP-aligned DOM tools (plus the `http_fetch`
+ * HTTP-proxy tool) the agent calls via the agent_dom_request SSE round-trip.
+ * See docs/agent/dom-tools.md for the wire format.
+ *
+ * This module is the in-page side of the contract, shared by both surfaces:
+ *   - Chrome extension: invoked from the content-script message listener
+ *     (content.ts) when the background relays an agent_dom_request to the
+ *     active tab.
+ *   - Embeddable widget: invoked directly by the widget's AgentDomBridge
+ *     (services/AgentDomBridge.ts), which intercepts agent_dom_request on the
+ *     widget SSE stream and POSTs the result to /widget/agent/dom-response.
+ *
+ * Element-id correlation: each call to get_page_outline / find_elements /
+ * inspect_element returns ephemeral ids that subsequent calls (inspect /
+ * wait_for) can dereference. Ids are kept in `currentTurnElementMap`; the
+ * map is cleared on each NEW turn (`resetTurn` on the request, or
+ * `resetDomToolTurn()`).
+ *
+ * Authoring controls bridge: when find_elements / inspect_element hit an
+ * element matched by an authored Control's locator, the `matches_authored_control`
+ * field returns the Control's semantic_id. The Controls registry is provided
+ * per turn (controlsForTurn).
+ */
+/** Clear the per-turn element-id map. Call at the start of every new turn. */
+export declare function resetDomToolTurn(): void;
+export interface DomToolRequest {
+    tool: string;
+    args: Record<string, unknown>;
+    controlsForTurn?: Array<{
+        semantic_id: string;
+        locator: string;
+    }>;
+    resetTurn?: boolean;
+}
+export declare function runDomTool(req: DomToolRequest): Promise<unknown>;