appilot-mcp 0.2.1 → 0.4.0

package/dist/server.js

@@ -19,7 +19,7 @@ import { inspectPage } from './inspect.js';
 import { runHealthContract } from './contract/healthContract.js';
 import { soakSelectors } from './soak.js';
 import { applyManifest, parseManifest, planManifest } from './manifest.js';
-import { scaffoldIntegration, scaffoldAgentFirst } from './scaffold.js';
+import { SCAFFOLD_FRAMEWORKS, scaffoldIntegration, scaffoldAgentFirst, integrationSnippet } from './scaffold.js';
 import { verifyIntegration } from './verify.js';
 import { redactForTransport, refuseSecretOverRemote } from './redaction.js';
 /**
@@ -43,7 +43,9 @@ const DEFAULT_WIDGET_SCRIPT_URL = 'https://cdn.appilot.space/widget/v1/appilot.e
  */
 const SERVER_INSTRUCTIONS = `Audit, extend and fix an Appilot app's content-model configuration, and build a new capability so the agent can operate it.
 
-Work in this order: capabilities (what this instance supports, and the closed vocabularies its entities accept; on-premise trails cloud), read_config, validate_config, then report the findings to the user in plain language, ranked critical to low, each with its concrete fix. Do not paste raw tool output at them.
+For a new app, work in this order: whoami, then create_app (on bare localhost pass isTest, which mints a wk_test_ key), then scaffold_integration for the host's framework, then verify_integration against the running page, then configure the content model.
+
+To audit an existing one, work in this order: capabilities (what this instance supports, and the closed vocabularies its entities accept; on-premise trails cloud), read_config, validate_config, then report the findings to the user in plain language, ranked critical to low, each with its concrete fix. Do not paste raw tool output at them.
 
 If read_config returns a gaps array, an entity could not be read. Say so and stop treating that entity as empty: every lint over it silently passed.
 
@@ -58,6 +60,20 @@ Three things to get right. A widget secret belongs in the server environment and
 If something is missing or broken in Appilot itself, report_feedback records it. Say plainly what it does: the report is read, and a reply is part of a support plan rather than something promised here. Never put configuration contents, knowledge bodies or secrets in a report, and show the user the exact text first.
 
 Writing needs a config:write service token, reading needs config:read, provisioning needs provision:write, reporting needs feedback:write. A scope refusal means the user should reconnect with a token carrying that scope, not that you should find another route.`;
+/**
+ * Where each scope comes from, appended to the refusal.
+ *
+ * A refusal that names the missing scope and stops leaves the reader one
+ * question short of acting: who can widen it. For provisioning the answer is
+ * not "you", which is exactly the case the configurator meets, so the refusal
+ * says who to ask and what the preset is called on the screen they will open.
+ */
+const HOW_TO_GRANT = {
+    'config:read': 'config:read is on every Service tokens preset in the Backoffice, "Inspect only" included.',
+    'config:write': 'config:write comes from the Backoffice Service tokens preset "Edit configuration".',
+    'provision:write': 'provision:write is granted by an organization administrator in the Backoffice, under Service tokens with the "Set up integrations" preset, or through the account approval screen. A configurator who is not an administrator cannot mint it and has to ask one.',
+    'feedback:write': 'feedback:write is a Backoffice Service tokens option, and it is the only scope that sends anything out of the organization.',
+};
 export function createAppilotServer(conn) {
     const client = new AppilotClient(conn);
     function text(value) {
@@ -85,7 +101,8 @@ export function createAppilotServer(conn) {
         if (!granted || granted.includes(scope))
             return null;
         return errorText(new Error(`This connection was granted ${granted.length ? granted.join(', ') : 'no scopes'}, which does not include ${scope}. ` +
-            'Reconnect and approve that scope, using a service token that carries it.'));
+            'Reconnect and approve that scope, using a service token that carries it. ' +
+            HOW_TO_GRANT[scope]));
     }
     function resolveAppId(appId) {
         const id = appId ?? conn.defaultAppId;
@@ -365,16 +382,17 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('create_app', {
         title: 'Create an app, its domains, and a widget key',
-        description: 'Provision an Appilot app in one call: the app, the domains it runs on, and optionally a widget key, plus the exact script tag and boot snippet to paste into the host application. Idempotent: re-running converges on the existing app rather than creating a second one. Pass dryRun to preview. The widget key and its secret are returned EXACTLY ONCE, at creation; store the secret in the host backend only. Requires a provision:write service token.',
+        description: 'Provision an Appilot app in one call: the app, the domains it runs on, and optionally a widget key, plus the exact script tag and boot snippet to paste into the host application. Idempotent: re-running converges on the existing app rather than creating a second one. Pass dryRun to preview. The widget key and its secret are returned EXACTLY ONCE, at creation; store the secret in the host backend only. Working on your own machine: do NOT pass localhost or 127.0.0.1 as a domain, because they name every developer\'s machine and are refused. Either run the app on a hostname that resolves to 127.0.0.1 (myapp.lvh.me) and register THAT, which gives the turn full app context and needs no key, or pass isTest true with no domains for a loopback-bound wk_test_ key, which gives the tenant and the user and no app context. Requires a provision:write service token.',
         inputSchema: {
             name: z.string().min(1),
             description: z.string().optional(),
             domains: z.array(z.string()).optional(),
             widgetKeyName: z.string().optional(),
-            isTestKey: z.boolean().optional(),
+            isTest: z.boolean().optional(),
+            allowedDomains: z.array(z.string()).optional(),
             dryRun: z.boolean().optional(),
         },
-    }, async ({ name, description, domains, widgetKeyName, isTestKey, dryRun }) => {
+    }, async ({ name, description, domains, widgetKeyName, isTest, allowedDomains, dryRun }) => {
         const refusal = scopeRefusal('provision:write');
         if (refusal)
             return refusal;
@@ -382,8 +400,8 @@ export function createAppilotServer(conn) {
             const result = await client.provisionApp({
                 app: { name, description },
                 domains: (domains ?? []).map(domain => ({ domain })),
-                widgetKey: widgetKeyName || isTestKey !== undefined
-                    ? { name: widgetKeyName, isTest: isTestKey }
+                widgetKey: widgetKeyName || isTest !== undefined || allowedDomains
+                    ? { name: widgetKeyName, isTest, allowedDomains }
                     : undefined,
                 dryRun: dryRun === true,
             });
@@ -393,9 +411,135 @@ export function createAppilotServer(conn) {
             return errorText(err);
         }
     });
+    server.registerTool('list_apps', {
+        title: 'List the apps this organization has provisioned',
+        description: 'The apps this credential reaches, with each app\'s registered domains and their verification status. Call it before create_app so "which apps do I have" has an answer, and to find the app id and the domain id every other provisioning tool takes. Carries no secret. Reads the provisioning surface, so it needs a provision:write service token even though it writes nothing.',
+        inputSchema: {},
+    }, async () => {
+        const refusal = scopeRefusal('provision:write');
+        if (refusal)
+            return refusal;
+        try {
+            return text(await client.listProvisioned());
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('list_widget_keys', {
+        title: 'List the widget keys this organization holds',
+        description: 'The organization\'s widget keys by label, prefix, allowed domains and active state. No raw key and no secret: both are shown exactly once, at creation. Call it before create_app so a re-run recognises the key it already minted instead of asking for another, because every extra key is another live credential. Requires a provision:write service token.',
+        inputSchema: {},
+    }, async () => {
+        const refusal = scopeRefusal('provision:write');
+        if (refusal)
+            return refusal;
+        try {
+            return text(await client.listWidgetKeys());
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('verify_domain', {
+        title: 'Check or trigger a domain\'s DNS verification',
+        description: 'Where a domain\'s verification stands, and the exact TXT record it needs. Pass trigger to ask Appilot to look for the record now. A live widget key needs a verified domain, and this is what closes that loop: create_app reports the key as blocked and names the record, and this reports whether the record is visible yet. Requires a provision:write service token.',
+        inputSchema: {
+            domain: z.string().min(1),
+            appId: z.number().int().optional(),
+            trigger: z.boolean().optional(),
+        },
+    }, async ({ domain, appId, trigger }) => {
+        const refusal = scopeRefusal('provision:write');
+        if (refusal)
+            return refusal;
+        try {
+            const wanted = domain.trim().toLowerCase().replace(/^https?:\/\//, '').replace(/[/:].*$/, '');
+            const provisioned = await client.listProvisioned();
+            const scoped = appId != null ? provisioned.filter(a => Number(a.id) === appId) : provisioned;
+            const owner = scoped.find(a => a.domains.some(d => String(d.domain).toLowerCase() === wanted));
+            const row = owner?.domains.find(d => String(d.domain).toLowerCase() === wanted);
+            if (!owner || !row) {
+                return errorText(new Error(`${wanted} is not a registered domain of ${appId != null ? `app ${appId}` : 'any app in this organization'}. ` +
+                    'list_apps shows what is registered, and create_app adds a domain. A loopback name (localhost, 127.0.0.1) is never registrable: run the app on a hostname that resolves to 127.0.0.1 instead.'));
+            }
+            const result = {
+                app: { id: owner.id, name: owner.name },
+                domain: row.domain,
+                domainId: row.id,
+                verificationStatus: row.verification_status,
+            };
+            // The TXT record lives on the apps router, which authenticates an
+            // organization session rather than a service token. When that is
+            // refused, the provisioning dry run answers the same question, so the
+            // tool degrades to a second source instead of to nothing.
+            try {
+                result.record = await client.domainVerification(Number(row.id));
+            }
+            catch {
+                try {
+                    const preview = await client.provisionApp({
+                        app: { name: owner.name },
+                        domains: [{ domain: row.domain }],
+                        dryRun: true,
+                    });
+                    const previewed = preview.domains.find(d => d.domain.toLowerCase() === wanted);
+                    if (previewed?.dns_record_name) {
+                        result.record = {
+                            dns_record_name: previewed.dns_record_name,
+                            dns_record_value: previewed.dns_record_value,
+                            verification_status: previewed.verification_status,
+                        };
+                    }
+                }
+                catch (err) {
+                    result.recordUnavailable = err instanceof Error ? err.message : String(err);
+                }
+            }
+            if (trigger && row.verification_status !== 'verified') {
+                try {
+                    result.checked = await client.triggerDomainVerification(Number(row.id));
+                }
+                catch (err) {
+                    result.triggerRefused =
+                        `${err instanceof Error ? err.message : String(err)} ` +
+                            'Triggering the check authenticates an organization session rather than a service token today, so run it from the Backoffice under Domains once the TXT record is published.';
+                }
+            }
+            return text(result);
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('integration_snippet', {
+        title: 'Get the script tag and boot call for an app that already exists',
+        description: 'The two forms of the widget boot for an app you already provisioned: the no-build script tag, and the bundled bootAppilotWidget call reading the key from the framework\'s public variable. Use it instead of re-running create_app, which is a provisioning write, when all you lost was the snippet. It composes the answer locally, writes nothing, and needs no scope. Pass the publishable widget key to have it appear in the script tag; the widget SECRET never belongs here.',
+        inputSchema: {
+            appId: z.number().int().optional(),
+            widgetKey: z.string().optional(),
+            widgetScriptUrl: z.string().optional(),
+            framework: z.enum(SCAFFOLD_FRAMEWORKS).optional(),
+        },
+    }, async ({ appId, widgetKey, widgetScriptUrl, framework }) => {
+        try {
+            return text({
+                appId: appId ?? conn.defaultAppId ?? null,
+                ...integrationSnippet({
+                    widgetScriptUrl: widgetScriptUrl ?? DEFAULT_WIDGET_SCRIPT_URL,
+                    apiUrl: conn.baseUrl || null,
+                    widgetKey: widgetKey ?? null,
+                    framework,
+                }),
+            });
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
     server.registerTool('plan_manifest', {
         title: 'Preview an app manifest (writes nothing)',
-        description: 'Diff an appilot.app-manifest against the live instance and return what would change: provisioning actions per app/domain/key, the config-bundle import diff, and the health findings over the resulting state. Writes nothing. Returns a planToken that apply_manifest requires, so an apply always follows a preview of the exact same manifest. Keep the manifest in the repository under version control.',
+        description: 'Diff an appilot.app-manifest against the live instance and return what would change: provisioning actions per app/domain/key, the config-bundle import diff, and the health findings over the resulting state. Writes nothing. Returns a planToken that apply_manifest requires, so an apply always follows a preview of the exact same manifest. Keep the manifest in the repository under version control. A complete example ships with this package at examples/app.appilot.json and is also in the docs. Which half is revisioned: the CONFIG half gets a pre_restore revision on every commit, so a wrong import is undone by restoring it; the PROVISIONING half is not revisioned, so a domain or a key it creates is undone by hand.',
         inputSchema: { manifest: z.union([z.record(z.any()), z.string()]) },
     }, async ({ manifest }) => {
         const refusal = scopeRefusal('config:read');
@@ -415,7 +559,7 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('apply_manifest', {
         title: 'Apply a previously planned app manifest',
-        description: 'Provision and configure an app from an appilot.app-manifest. Requires the planToken returned by plan_manifest for the SAME manifest: a mismatch means the manifest changed after it was previewed, and the apply is refused. Pass expectedCurrentHash from the plan so a concurrent config edit is a 409 rather than a silent overwrite. mode=replace makes the config match the bundle exactly, including deletions. Requires provision:write, and config:write when the manifest carries a config bundle.',
+        description: 'Provision and configure an app from an appilot.app-manifest. Requires the planToken returned by plan_manifest for the SAME manifest: a mismatch means the manifest changed after it was previewed, and the apply is refused. Pass expectedCurrentHash from the plan so a concurrent config edit is a 409 rather than a silent overwrite. mode=replace makes the config match the bundle exactly, including deletions. Needs config:write when the manifest carries a config bundle, and provision:write only when the provisioning half would actually change something: a manifest whose app, domains and keys already exist applies with config:write alone.',
         inputSchema: {
             manifest: z.union([z.record(z.any()), z.string()]),
             planToken: z.string(),
@@ -424,17 +568,26 @@ export function createAppilotServer(conn) {
             allowUnhealthy: z.boolean().optional(),
         },
     }, async ({ manifest, planToken, mode, expectedCurrentHash, allowUnhealthy }) => {
-        // A manifest apply provisions AND writes configuration, so it needs both.
-        const refusal = scopeRefusal('provision:write') ?? scopeRefusal('config:write');
-        if (refusal)
-            return refusal;
         try {
             const parsed = parseManifest(manifest);
+            // The config half always writes when the manifest carries one. The
+            // provisioning half is decided by the manifest rather than by the
+            // tool: applyManifest previews it and refuses only when it would
+            // actually change an app, a domain or a key. A CI token holding
+            // config:write alone keeps content in sync on an app a person
+            // already provisioned, which is the reason the scopes are separate.
+            if (parsed.config) {
+                const configRefusal = scopeRefusal('config:write');
+                if (configRefusal)
+                    return configRefusal;
+            }
+            const provisionRefusal = scopeRefusal('provision:write');
             const result = await applyManifest(client, parsed, {
                 planToken,
                 mode,
                 expectedCurrentHash,
                 allowUnhealthy,
+                provisionRefusal: provisionRefusal ? provisionRefusal.content[0].text : null,
             });
             return text({ ...result, provisioning: redactForTransport(result.provisioning, conn.transport) });
         }
@@ -444,9 +597,9 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('scaffold_integration', {
         title: 'Generate the host application integration code',
-        description: 'Return the source a host application needs: the identity relay for its backend (the one security-critical piece, built on appilot-server), the widget boot call, and a client-action example. Returns file CONTENTS for you to write into the repository; this server never touches the filesystem. Pick the framework that matches the host.',
+        description: 'Return the source a host application needs: the identity relay for its backend (the one security-critical piece, built on appilot-server), the widget boot call, and a client-action example. Returns file CONTENTS for you to write into the repository; this server never touches the filesystem. Pick the framework that matches the host, or `other` when the backend is not Node (Django, Rails, PHP), which returns the raw exchange as curl plus a Python and a Ruby handler. The notes carry what local development needs, and the answer differs between a hostname you registered and bare localhost.',
         inputSchema: {
-            framework: z.enum(['next', 'express', 'fastify', 'hono', 'remix', 'sveltekit']),
+            framework: z.enum(SCAFFOLD_FRAMEWORKS),
             widgetKey: z.string().optional(),
             widgetScriptUrl: z.string().optional(),
             idNamespace: z.string().optional(),
@@ -522,15 +675,17 @@ export function createAppilotServer(conn) {
     });
     server.registerTool('scaffold_agent_first', {
         title: 'Scaffold one capability so the agent can operate it',
-        description: 'Return the four artifacts a capability needs to be agent-operable, agreeing with each other: the HTTP-proxy tool, the client action when the operation belongs in the page, the Action Plan that is the procedure, and the knowledge article that carries the meaning and not the steps. Also returns the order to create them in, which matters because a form cannot name controls that do not exist yet. `endpoint.path` is a path on the host origin, not an absolute URL. Use it when building a new agent-first app or making an existing feature reachable through the assistant.',
+        description: 'Return the four artifacts a capability needs to be agent-operable, agreeing with each other: the HTTP-proxy tool, the client action when the operation belongs in the page, the Action Plan that is the procedure, and the knowledge article that carries the meaning and not the steps. Also returns the order to create them in, which matters because a form cannot name controls that do not exist yet. `endpoint.path` is a path on the host origin, not an absolute URL. Pass `shape`: `create` is the open, fill and submit plan, `navigate` is one step to a screen, and `read` gets NO plan at all, because a plan whose only step opens a screen does nothing. Pass `clientSide` when the operation belongs in the page, and no HTTP-proxy tool is emitted. Use it when building a new agent-first app or making an existing feature reachable through the assistant.',
         inputSchema: {
             capability: z.string().min(1),
             slug: z.string().min(1),
             appId: z.number().int().optional(),
             endpoint: z.object({ method: z.string(), path: z.string() }).optional(),
             clientSide: z.boolean().optional(),
+            shape: z.enum(['create', 'navigate', 'read']).optional(),
+            viewPath: z.string().optional(),
         },
-    }, async ({ capability, slug, appId, endpoint, clientSide }) => {
+    }, async ({ capability, slug, appId, endpoint, clientSide, shape, viewPath }) => {
         try {
             return text(scaffoldAgentFirst({
                 capability,
@@ -538,6 +693,8 @@ export function createAppilotServer(conn) {
                 appId: appId ?? conn.defaultAppId ?? null,
                 endpoint: endpoint ?? null,
                 clientSide,
+                shape,
+                viewPath,
             }));
         }
         catch (err) {

package/dist/userClient.d.ts

@@ -0,0 +1,213 @@
+/**
+ * HTTP client over the Appilot runtime routes (`/agent/runtime/*`), used by the
+ * Appilot connector: the surface an end user operates their own app through,
+ * from whatever assistant they already pay for.
+ *
+ * The credential is a user session, not a service token. It authenticates the
+ * way the extension does, so the connector can never exceed what the person
+ * themselves can do, and it can never write configuration: that is Studio, on a
+ * different mount with a different scope (see `client.ts`).
+ *
+ * Two rules about what this client does with an answer.
+ *
+ * Page-derived content passes through VERBATIM. `page/read` and `page/find`
+ * answer with one `page_content` string: the DOM tool's result serialized and
+ * wrapped in the backend's delimited untrusted-content block. Nothing here opens
+ * that block. The delimiters are a prompt-injection defence that works only
+ * while they are still around the content, the model reads the JSON inside them
+ * perfectly well, and a client that reassembled structure out of the block would
+ * be a second parser of a hostile string.
+ *
+ * Everything that is NOT page-derived is read field by field, and never invented.
+ * A missing field does not throw: an answer the connector cannot parse must not
+ * take the conversation down. A failed read never becomes an empty success:
+ * `configured` stays null when the instance did not say, an absent plan list is
+ * not an empty one, and a refusal comes back as a refusal carrying the guidance
+ * the backend wrote for the person.
+ *
+ * Contract: docs/architecture/appilot-runtime-connector.md.
+ * Routes:   packages/services/backend/src/routes/agentRuntime.ts.
+ * Channel:  docs/architecture/agent-bridge.md.
+ */
+import type { AppilotConnection } from './config.js';
+/**
+ * What to say when a refusal arrives without guidance of its own.
+ *
+ * The routes send `error.guidance` from the bridge's failure vocabulary and
+ * that is what the assistant repeats, so this map is the fallback for a body
+ * that carries none. `NO_BRIDGE` is the one that matters most: a caller that
+ * turns it into a guess about the page is the failure the vocabulary exists to
+ * prevent.
+ */
+export declare const BRIDGE_REFUSALS: Record<string, string>;
+/** A typed refusal from the runtime routes. Never a value a caller can mistake for data. */
+export declare class RuntimeRefusalError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+/**
+ * The steer that keeps an assistant from narrating a plan the person is already
+ * watching. `runtimeEnvelope` puts it on every response; see the connector spec,
+ * "Every result says whether it was shown".
+ */
+export interface Presentation {
+    shown_in_page: boolean;
+    instruction?: string;
+}
+/** What a visible result should have said, repeated when a result forgets to. */
+export declare const SHOWN_IN_PAGE_INSTRUCTION = "This ran in the page the person is watching. Confirm in one sentence. Do not list the steps.";
+/** Mode and its reason, exactly as the server derived them. Never inflated here. */
+export interface ModeStamp {
+    mode: string | null;
+    mode_reason: string | null;
+}
+export interface RuntimeContextResult extends ModeStamp {
+    bridge_live: boolean | null;
+    surface: string | null;
+    url: string | null;
+    app: {
+        id: number | null;
+        name: string | null;
+    } | null;
+    view: {
+        view_path: string | null;
+        view_name: string | null;
+    } | null;
+    /** Null when the instance did not say. Never defaulted, in either direction. */
+    configured: boolean | null;
+    configured_reason: string | null;
+    /** Null when the instance did not answer with a plan list at all. */
+    plans: Record<string, unknown>[] | null;
+    presentation: Presentation | null;
+    notes: string[];
+}
+/**
+ * A page read or find. `page_content` is the backend's delimited untrusted block
+ * and travels exactly as it arrived.
+ */
+export interface RuntimePageResult extends ModeStamp {
+    what?: string;
+    page_content: string | null;
+    elapsed_ms: number | null;
+    presentation: Presentation | null;
+    notes: string[];
+}
+export interface RuntimeHighlightResult extends ModeStamp {
+    target: Record<string, unknown> | null;
+    elapsed_ms: number | null;
+    presentation: Presentation | null;
+    notes: string[];
+}
+export interface RuntimeKnowledgeResult extends ModeStamp {
+    /** Null when the instance did not answer with passages. Empty means it found none. */
+    passages: Record<string, unknown>[] | null;
+    citations: Record<string, unknown>[] | null;
+    configured: boolean | null;
+    configured_reason: string | null;
+    /** The server's own line for the person, on an app with no curated knowledge. */
+    guidance: string | null;
+    presentation: Presentation | null;
+    notes: string[];
+}
+export interface RuntimePlansResult extends ModeStamp {
+    plans: Record<string, unknown>[] | null;
+    configured: boolean | null;
+    view_path: string | null;
+    presentation: Presentation | null;
+    notes: string[];
+}
+export interface RuntimePlanRunResult extends ModeStamp {
+    plan_handle: string | null;
+    plan_id: string | null;
+    plan_name: string | null;
+    interaction_id: number | null;
+    pace: string | null;
+    state: string | null;
+    /** Above zero means the assembler refused part of what was asked. */
+    steps_dropped: number | null;
+    presentation: Presentation | null;
+    notes: string[];
+}
+export interface RuntimePlanStatusResult extends ModeStamp {
+    plan_handle: string | null;
+    plan_id: string | null;
+    plan_name: string | null;
+    pace: string | null;
+    state: string | null;
+    step_index: number | null;
+    total_steps: number | null;
+    detail: string | null;
+    updated_at: number | null;
+    /** True when the call held for a transition rather than reading the current state. */
+    waited: boolean;
+    presentation: Presentation | null;
+    notes: string[];
+}
+/** The three paces the dock implements. There is no fourth, and a connector may not invent timings. */
+export declare const PACES: readonly ["teach", "walk", "do"];
+export type Pace = (typeof PACES)[number];
+/** The three ways `POST /page/read` can look at the page, in the route's own words. */
+export declare const PAGE_READS: readonly ["outline", "text", "form_state"];
+export type PageRead = (typeof PAGE_READS)[number];
+/** One field of a plan's form step, by the control's semantic id. */
+export interface PlanFormValue {
+    control: string;
+    value: string;
+}
+export declare class AppilotRuntimeClient {
+    private readonly conn;
+    constructor(conn: AppilotConnection);
+    private request;
+    /** Where the person is, and what applies here. Carries no mode by design. */
+    context(): Promise<RuntimeContextResult>;
+    /**
+     * Outline, visible text in a region, or form state with validation errors.
+     *
+     * The answer's `page_content` is passed on untouched, delimiters and all.
+     */
+    readPage(args: {
+        what: PageRead;
+        region_id?: string;
+        selector?: string;
+        form_id?: string;
+        max_chars?: number;
+    }): Promise<RuntimePageResult>;
+    /** Elements by role and accessible name, inside the same untrusted block. */
+    findOnPage(args: {
+        role?: string;
+        name?: string;
+        limit?: number;
+    }): Promise<RuntimePageResult>;
+    private pageResult;
+    /** Draw the locate overlay on a control, a zone or a ref. Visible work. */
+    highlight(args: {
+        control?: string;
+        zone?: string;
+        ref?: string;
+    }): Promise<RuntimeHighlightResult>;
+    /** Curated knowledge with resolved citations. Answers without a shared tab. */
+    searchKnowledge(args: {
+        query: string;
+    }): Promise<RuntimeKnowledgeResult>;
+    /** The curated procedures that apply to the current view. */
+    listPlans(): Promise<RuntimePlansResult>;
+    /**
+     * Assemble a curated plan and publish it to the page at a pace.
+     *
+     * `plan_id` is the authored id `list_plans` returns; there is no free-form
+     * goal, because an app with no curated plan for the task is refused rather
+     * than served an assembled guess.
+     */
+    runPlan(args: {
+        plan_id: string;
+        pace?: Pace;
+        form_values?: PlanFormValue[];
+    }): Promise<RuntimePlanRunResult>;
+    /**
+     * State of a running plan. With `wait` the route holds up to 50 seconds for
+     * the next transition, which is how an assistant that cannot see the screen
+     * follows a plan without polling.
+     */
+    planStatus(handle: string, wait?: boolean): Promise<RuntimePlanStatusResult>;
+}