appilot 0.0.1 → 0.1.1

package/dist/focusedSessions/pageSdk.js

@@ -0,0 +1,238 @@
+/**
+ * Focused Sessions page SDK: the surface a host app calls to run an
+ * app-initiated, mission-scoped agent conversation and receive its structured
+ * outcome (docs/agent/focused-sessions.md).
+ *
+ *   const handle = await startFocusedSession({ template_id: 'role-play', variables: { role: 'Sam' } });
+ *   handle.onOutcome(outcome => saveEvidence(outcome));
+ *
+ * Architecture mirrors the WebMCP registry: the SDK itself performs NO HTTP
+ * and holds NO credentials. It delegates to a PROVIDER the assistant surface
+ * registers on `window.__APPILOT_SESSIONS__`:
+ *   - the widget registers a direct provider (it shares the page realm and
+ *     owns the widget-key + user-token REST calls), and
+ *   - the extension's MAIN-world script registers a postMessage relay to its
+ *     isolated content script -> background -> JWT REST.
+ * A window-anchored global (not a module singleton) because the host app's
+ * bundle and the assistant surface's bundle are DIFFERENT module graphs; a
+ * module-level variable would give each its own copy.
+ *
+ * Import from `appilot` (same shipping posture as `registerTool`).
+ */
+const GLOBAL_KEY = '__APPILOT_SESSIONS__';
+const PROVIDER_WAIT_TIMEOUT_MS = 10_000;
+function getWindow() {
+    return typeof window !== 'undefined' ? window : undefined;
+}
+function getGlobal() {
+    const w = getWindow();
+    if (!w)
+        return undefined;
+    if (!w[GLOBAL_KEY])
+        w[GLOBAL_KEY] = {};
+    return w[GLOBAL_KEY];
+}
+/**
+ * Called by the assistant surface (widget boot / extension MAIN-world bridge)
+ * to expose the session transport to the page. Last registration wins: when
+ * both the widget and the extension are present on a page, the most recent
+ * surface serves new sessions (in practice hosts embed exactly one).
+ */
+export function registerFocusedSessionProvider(provider) {
+    const g = getGlobal();
+    if (!g)
+        return;
+    g.provider = provider;
+    const waiters = g.waiters ?? [];
+    g.waiters = [];
+    for (const w of waiters) {
+        try {
+            w(provider);
+        }
+        catch { /* waiter errors are the page's problem */ }
+    }
+}
+function waitForProvider(timeoutMs) {
+    const g = getGlobal();
+    if (!g)
+        return Promise.reject(new Error('Focused sessions require a browser window'));
+    if (g.provider)
+        return Promise.resolve(g.provider);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            const idx = g.waiters?.indexOf(onReady) ?? -1;
+            if (idx >= 0)
+                g.waiters?.splice(idx, 1);
+            reject(new Error('No Appilot assistant surface available (widget not loaded / extension not active)'));
+        }, timeoutMs);
+        const onReady = (provider) => {
+            clearTimeout(timer);
+            resolve(provider);
+        };
+        g.waiters = g.waiters ?? [];
+        g.waiters.push(onReady);
+    });
+}
+/**
+ * Start a focused session. Resolves once the assistant surface has created
+ * the session server-side (mission resolved + conversation bound); rejects
+ * with the surface's typed error message when the template is unknown, a
+ * required variable is missing, or no assistant surface is present.
+ */
+export async function startFocusedSession(request) {
+    // Wake the assistant surface BEFORE waiting for the provider. The widget
+    // registers its provider from the lazily-loaded panel chunk, so on a page
+    // where the user never opened the panel there is NO provider yet; without
+    // this signal, start would deadlock into the wait timeout (found in the
+    // first L3 Learn headful soak). The widget loader listens for
+    // `appilot:open` (the same event behind `window.Appilot.open()`) and
+    // mounts the panel, which binds the provider and resolves the waiter.
+    // Opening the panel is also the DESIRED UX: the session dialogue happens
+    // there. Surfaces that register eagerly (extension MAIN-world bridge)
+    // simply never hear the event.
+    try {
+        getWindow()?.dispatchEvent(new CustomEvent('appilot:open'));
+    }
+    catch { /* older browsers without CustomEvent; the eager-surface path still works */ }
+    const provider = await waitForProvider(PROVIDER_WAIT_TIMEOUT_MS);
+    const started = await provider.start(request);
+    storeSessionId(started.focused_session_id);
+    return buildHandle(provider, started);
+}
+/**
+ * The page-side handle. Shared by `startFocusedSession` and
+ * `resumeFocusedSession` so a resumed session behaves identically to a fresh
+ * one, terminal latch included.
+ */
+function buildHandle(provider, session) {
+    // Handle-level terminal latch, defence in depth on top of the provider's
+    // per-session exactly-once guarantee: the FIRST terminal event (outcome OR
+    // ended) settles the handle, later events of the other kind are ignored,
+    // so `onOutcome` and `onEnded` are mutually exclusive even against a
+    // misbehaving surface.
+    let settled = null;
+    return {
+        focusedSessionId: session.focused_session_id,
+        conversationId: session.conversation_id,
+        name: session.name,
+        onOutcome(cb) {
+            return provider.onOutcome(event => {
+                if (event.focused_session_id !== session.focused_session_id)
+                    return;
+                if (settled === 'ended')
+                    return;
+                settled = 'outcome';
+                storeSessionId(null);
+                cb(event.outcome);
+            });
+        },
+        onEnded(cb) {
+            // Older surfaces without onEnded: a never-firing subscription (the
+            // page still compiles and runs; it simply keeps the legacy behavior).
+            if (!provider.onEnded)
+                return () => { };
+            return provider.onEnded(event => {
+                if (event.focused_session_id !== session.focused_session_id)
+                    return;
+                if (settled === 'outcome')
+                    return;
+                settled = 'ended';
+                storeSessionId(null);
+                cb({ focusedSessionId: event.focused_session_id, status: event.status });
+            });
+        },
+        end() {
+            storeSessionId(null);
+            return provider.end(session.focused_session_id);
+        },
+    };
+}
+// ── Surviving a reload ───────────────────────────────────────────────────────
+//
+// A full browser reload destroys the page's handle while the session keeps
+// running on the server, which used to strand the page (learning #17). The id
+// is remembered here so the page can ask for it back.
+//
+// sessionStorage, not localStorage: a focused session belongs to the tab that
+// started it, and it must not leak into a second tab where a different mission
+// may be running. The read is NON-destructive; the entry is cleared only on a
+// terminal event or an explicit call. A destructive read looks tempting and is
+// a trap: under React StrictMode the double-invoked effect erases the value
+// before the component that needed it ever sees it.
+const RESUME_STORAGE_KEY = 'appilot.focused_session';
+function readStoredSessionId() {
+    try {
+        const raw = window.sessionStorage?.getItem(RESUME_STORAGE_KEY);
+        return raw && raw.trim() !== '' ? raw : null;
+    }
+    catch {
+        // Private mode, blocked storage, or a sandboxed frame. Resume simply is
+        // not available; nothing else degrades.
+        return null;
+    }
+}
+function storeSessionId(id) {
+    try {
+        if (id)
+            window.sessionStorage?.setItem(RESUME_STORAGE_KEY, id);
+        else
+            window.sessionStorage?.removeItem(RESUME_STORAGE_KEY);
+    }
+    catch {
+        /* storage unavailable: resume is not offered, the session still runs */
+    }
+}
+/**
+ * The id of the session this tab last started, if it has not reached a terminal
+ * state. Useful for deciding whether to offer a "continue" affordance before
+ * paying for the round-trip that `resumeFocusedSession` makes.
+ */
+export function getResumableFocusedSessionId() {
+    return getWindow() ? readStoredSessionId() : null;
+}
+/** Forget the remembered session without ending it server-side. */
+export function forgetFocusedSession() {
+    if (getWindow())
+        storeSessionId(null);
+}
+/**
+ * Re-attach to a session this tab started before a reload.
+ *
+ * Resolves to a handle when the session is still running and belongs to the
+ * current identity, and to `null` otherwise: nothing remembered, the assistant
+ * surface cannot resume, the session already ended, or it is not this user's.
+ * Ownership is checked server-side; possessing an id proves nothing.
+ *
+ * ```ts
+ * const handle = await resumeFocusedSession();
+ * if (handle) handle.onOutcome(saveEvidence);
+ * else showActivityFinishedState();
+ * ```
+ */
+export async function resumeFocusedSession(focusedSessionId) {
+    const id = focusedSessionId ?? getResumableFocusedSessionId();
+    if (!id)
+        return null;
+    try {
+        getWindow()?.dispatchEvent(new CustomEvent('appilot:open'));
+    }
+    catch { /* older browsers without CustomEvent; the eager-surface path still works */ }
+    let provider;
+    try {
+        provider = await waitForProvider(PROVIDER_WAIT_TIMEOUT_MS);
+    }
+    catch {
+        // No surface on this page. Resuming is a best-effort recovery, so it
+        // answers "no" rather than throwing at a page that is merely reloading.
+        return null;
+    }
+    if (!provider.resume)
+        return null;
+    const resumed = await provider.resume(id);
+    if (!resumed) {
+        storeSessionId(null);
+        return null;
+    }
+    storeSessionId(resumed.focused_session_id);
+    return buildHandle(provider, resumed);
+}

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,16 @@
+/**
+ * `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';
+export { isSensitiveField, isSensitiveFieldType } from './dom/sensitiveFields.js';

package/dist/runtime.js

@@ -0,0 +1,21 @@
+/**
+ * `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';
+// The one rule about credential fields. Re-exported by `appilot-shared/scanning`
+// for the surfaces that already import it from there.
+export { isSensitiveField, isSensitiveFieldType } from './dom/sensitiveFields.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 {};