appilot-mcp 0.1.0 → 0.2.1

package/dist/remote/oauth.d.ts

@@ -21,15 +21,33 @@ import type { OAuthServerProvider, AuthorizationParams } from '@modelcontextprot
 import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
 import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
-/** Scopes this authorization server can grant, mirroring the service-token scopes. */
-export declare const SUPPORTED_SCOPES: readonly ["config:read", "config:write"];
+import { type ConsentLocale } from './consentMessages.js';
+/**
+ * Scopes this authorization server can grant, mirroring the service-token scopes.
+ *
+ * `provision:write` belongs here even though the service never mints it: the
+ * sealed service token carries whatever scopes it was minted with, so leaving
+ * provisioning off this list did not remove the power, it only stopped the
+ * consent screen from disclosing it. The grant is now enforced per tool
+ * (see `server.ts`), which is what makes the screen's promise real.
+ *
+ * `feedback:write` is the one scope that governs sending data OUT of the
+ * tenant, which is why it is separate from the config scopes rather than folded
+ * into them.
+ */
+export declare const SUPPORTED_SCOPES: readonly ["config:read", "config:write", "provision:write", "feedback:write"];
 /** What the instance says a credential reaches. Absent on instances without /config/whoami. */
 export interface TokenIdentity {
+    organizationName?: string | null;
+    appName?: string | null;
     organizationId: number | null;
     appId: number | null;
     scopes: string[];
 }
 export interface AppilotOAuthOptions {
+    handoffSecret?: string;
+    /** Trusted Backoffice origin configured by the operator, never a request parameter. */
+    backofficeUrl?: string;
     /** Public origin of this service, used to build the consent form action. */
     publicUrl: URL;
     /** The Appilot backend this deployment serves. */
@@ -44,6 +62,7 @@ export declare class AppilotOAuthProvider implements OAuthServerProvider {
     private readonly sealer;
     private readonly consentPath;
     private readonly verifyServiceToken;
+    private readonly redeemed;
     constructor(options: AppilotOAuthOptions);
     /**
      * Client registrations are sealed into the client_id itself, so dynamic
@@ -52,19 +71,33 @@ export declare class AppilotOAuthProvider implements OAuthServerProvider {
      */
     get clientsStore(): OAuthRegisteredClientsStore;
     authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
+    /** Complete only in the browser that initiated this OAuth request. */
+    finishConnection(id: string, code: string, cookieHeader: string, res: Response): Promise<string>;
     /** The authorization request travels through the consent form, so it is sealed too. */
     private sealAuthRequest;
     /**
-     * Handle the consent form post: verify the pasted service token, then either
-     * redirect back with an authorization code or re-render with the reason it
-     * failed. Returns the HTML to render, or the redirect to follow.
+     * Handle the consent form post.
+     *
+     * Two stages, because the first screen cannot yet say what it is granting.
+     * The service only learns which organization a token reaches, and which
+     * scopes it really carries, by asking the instance about the token the person
+     * just pasted. Redirecting straight from there would mean the one screen a
+     * person sees never names the org the connection will reach or the
+     * provisioning power the token may carry. So a verified token renders a
+     * confirmation naming both, and only that confirmation issues a code.
+     *
+     * `stage=request`  the pasted-token form (sealed by `authorize`)
+     * `stage=confirm`  what the token actually reaches, awaiting approval
+     * `stage=code`     the authorization code itself
      */
-    handleConsent(form: Record<string, unknown>): Promise<{
+    handleConsent(form: Record<string, unknown>, fallbackLocale?: ConsentLocale): Promise<{
         redirect: string;
     } | {
         html: string;
         status: number;
     }>;
+    /** Seal the authorization code and hang it off the client's redirect. */
+    private issueCode;
     private openCode;
     challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;
     exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string, _codeVerifier?: string, redirectUri?: string): Promise<OAuthTokens>;

package/dist/remote/oauth.js

@@ -17,15 +17,81 @@
  * Spec: docs/architecture/appilot-mcp.md, section "Remote deployment".
  */
 import { InvalidGrantError, InvalidTokenError, InvalidClientError, ServerError, } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { consentLocale, message } from './consentMessages.js';
+import { cookieName, connectionRequest, startConnection } from './handoff.js';
+import { randomUUID } from 'node:crypto';
+import { SERVICE_TOKEN_PREFIX } from 'appilot-shared/types';
 import { TokenSealer, SealError } from './tokens.js';
-import { renderConsentPage, renderErrorPage } from './consent.js';
-/** Scopes this authorization server can grant, mirroring the service-token scopes. */
-export const SUPPORTED_SCOPES = ['config:read', 'config:write'];
+import { renderConsentPage, renderConfirmPage, renderErrorPage } from './consent.js';
+/**
+ * Scopes this authorization server can grant, mirroring the service-token scopes.
+ *
+ * `provision:write` belongs here even though the service never mints it: the
+ * sealed service token carries whatever scopes it was minted with, so leaving
+ * provisioning off this list did not remove the power, it only stopped the
+ * consent screen from disclosing it. The grant is now enforced per tool
+ * (see `server.ts`), which is what makes the screen's promise real.
+ *
+ * `feedback:write` is the one scope that governs sending data OUT of the
+ * tenant, which is why it is separate from the config scopes rather than folded
+ * into them.
+ */
+export const SUPPORTED_SCOPES = [
+    'config:read',
+    'config:write',
+    'provision:write',
+    'feedback:write',
+];
+/**
+ * What to ask for when the client asks for nothing.
+ *
+ * Most clients send a `scope` parameter and get exactly what they asked for.
+ * Some send none, and the previous default of `config:read` alone meant that a
+ * connection made by such a client came out read-only however wide the pasted
+ * token was. That was survivable while the surface was mostly reads. It is not
+ * now: an agent would meet a refusal on nearly every authoring call, mid-task,
+ * with no way to widen the grant except reconnecting.
+ *
+ * Requesting everything is safe here because of where the grant is actually
+ * decided. It is capped by the token (`granted = requested ∩ token.scopes`),
+ * and the confirm screen names the exact set before any code is issued, so the
+ * person still approves the real thing. A client that deliberately sends a
+ * narrow scope keeps getting exactly that scope, and its refusals stay legible.
+ */
+const DEFAULT_REQUESTED_SCOPES = SUPPORTED_SCOPES;
 const AUTH_REQUEST_TTL = 10 * 60;
+const CONFIRM_TTL = 5 * 60;
 const CODE_TTL = 60;
 const ACCESS_TTL = 60 * 60;
 const REFRESH_TTL = 90 * 24 * 60 * 60;
-const SERVICE_TOKEN_PREFIX = 'appilot_pat_';
+/**
+ * Replay guard for authorization codes.
+ *
+ * OAuth 2.1 requires a code to be single-use, and a sealed artifact cannot be
+ * deleted server-side, so the only thing that can be remembered is that it was
+ * already redeemed. Entries expire with the code itself, which bounds the set to
+ * the codes issued in the last minute. This is per-instance: a replay routed to
+ * a second container is not caught by it, and stays bounded by the 60-second TTL
+ * and by PKCE, which is where the guarantee sat before. Cheap, correct for the
+ * common case, and it keeps the service free of a database.
+ */
+class RedeemedCodes {
+    seen = new Map();
+    /** True when this id had already been redeemed. Records it either way. */
+    check(id) {
+        const now = Date.now();
+        if (this.seen.size > 512) {
+            for (const [k, expiry] of this.seen)
+                if (expiry <= now)
+                    this.seen.delete(k);
+        }
+        const previous = this.seen.get(id);
+        if (previous !== undefined && previous > now)
+            return true;
+        this.seen.set(id, now + CODE_TTL * 1000);
+        return false;
+    }
+}
 /**
  * Ask the instance what a pasted service token actually reaches. Returns null
  * when the instance rejects it. Returns an empty identity when the instance
@@ -37,10 +103,11 @@ async function defaultVerifyServiceToken(baseUrl, pat) {
     try {
         res = await fetch(`${baseUrl}/config/whoami`, {
             headers: { Authorization: `Bearer ${pat}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(10_000),
         });
     }
-    catch (err) {
-        throw new ServerError(`Could not reach the Appilot instance at ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    catch {
+        throw new ServerError('Appilot could not be reached. Please try again.');
     }
     if (res.status === 401 || res.status === 403)
         return null;
@@ -53,6 +120,8 @@ async function defaultVerifyServiceToken(baseUrl, pat) {
     }
     const body = (await res.json());
     return {
+        organizationName: typeof body.organizationName === 'string' ? body.organizationName : null,
+        appName: typeof body.appName === 'string' ? body.appName : null,
         organizationId: body.organizationId ?? null,
         appId: body.appId ?? null,
         scopes: Array.isArray(body.scopes) && body.scopes.length ? body.scopes : ['config:read'],
@@ -63,12 +132,13 @@ export class AppilotOAuthProvider {
     sealer;
     consentPath;
     verifyServiceToken;
+    redeemed = new RedeemedCodes();
     constructor(options) {
         this.options = options;
         this.sealer = new TokenSealer(options.secret);
         this.consentPath = new URL('/consent', options.publicUrl).toString();
         this.verifyServiceToken =
-            options.verifyServiceToken ?? (pat => defaultVerifyServiceToken(options.baseUrl, pat));
+            options.verifyServiceToken ?? ((pat) => defaultVerifyServiceToken(options.baseUrl, pat));
     }
     /**
      * Client registrations are sealed into the client_id itself, so dynamic
@@ -85,7 +155,9 @@ export class AppilotOAuthProvider {
                 // the registration handler generated rather than seal it.
                 const { client_secret: _secret, client_secret_expires_at: _expires, ...meta } = client;
                 const publicMeta = { ...meta, token_endpoint_auth_method: 'none' };
-                const client_id = await this.sealer.seal('client', { meta: publicMeta });
+                const client_id = await this.sealer.seal('client', {
+                    meta: publicMeta,
+                });
                 return {
                     ...publicMeta,
                     client_id,
@@ -109,33 +181,121 @@ export class AppilotOAuthProvider {
         };
     }
     async authorize(client, params, res) {
-        const requested = (params.scopes?.length ? params.scopes : ['config:read']).filter(s => SUPPORTED_SCOPES.includes(s));
+        const language = consentLocale(typeof res.req?.query?.lang === 'string'
+            ? res.req.query.lang
+            : res.req?.get('Accept-Language'));
+        const requested = (params.scopes?.length ? params.scopes : DEFAULT_REQUESTED_SCOPES).filter((s) => SUPPORTED_SCOPES.includes(s));
         const sealedRequest = await this.sealAuthRequest({
+            language,
             client_id: client.client_id,
+            client_name: client.client_name || 'your assistant',
             redirect_uri: params.redirectUri,
             code_challenge: params.codeChallenge,
             state: params.state,
-            scopes: requested.length ? requested : ['config:read'],
+            scopes: requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES],
             resource: params.resource?.toString(),
         });
+        if (this.options.handoffSecret &&
+            this.options.backofficeUrl &&
+            res.req?.query?.manual !== '1') {
+            try {
+                await startConnection({
+                    baseUrl: this.options.baseUrl,
+                    secret: this.options.handoffSecret,
+                    backofficeUrl: this.options.backofficeUrl,
+                    secure: this.options.publicUrl.protocol === 'https:',
+                }, sealedRequest, client.client_id, client.client_name || 'AI assistant', requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES], language, res);
+                return;
+            }
+            catch {
+                res
+                    .status(503)
+                    .set('Content-Type', 'text/html; charset=utf-8')
+                    .send(renderConsentPage({
+                    locale: language,
+                    request: sealedRequest,
+                    action: this.consentPath,
+                    clientName: client.client_name || 'AI assistant',
+                    baseUrl: this.options.baseUrl,
+                    backofficeUrl: this.options.backofficeUrl,
+                    scopes: requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES],
+                    error: message('sessionUnavailable', language),
+                }));
+                return;
+            }
+        }
         res.set('Content-Type', 'text/html; charset=utf-8').send(renderConsentPage({
+            locale: language,
             request: sealedRequest,
             action: this.consentPath,
             clientName: client.client_name || 'an MCP client',
             baseUrl: this.options.baseUrl,
-            scopes: requested.length ? requested : ['config:read'],
+            backofficeUrl: this.options.backofficeUrl,
+            scopes: requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES],
         }));
     }
+    /** Complete only in the browser that initiated this OAuth request. */
+    async finishConnection(id, code, cookieHeader, res) {
+        if (!this.options.handoffSecret ||
+            !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id))
+            throw new InvalidGrantError('Connection expired');
+        const name = cookieName(id);
+        const proof = cookieHeader
+            .split(';')
+            .map((s) => s.trim())
+            .find((s) => s.startsWith(`${name}=`))
+            ?.slice(name.length + 1);
+        if (!proof || !/^[a-f0-9]{64}$/.test(proof))
+            throw new InvalidGrantError('Use the browser where you started the connection');
+        const grant = await connectionRequest(this.options.baseUrl, this.options.handoffSecret, 'redeem', { id, code, browserProof: proof });
+        const request = await this.sealer.open('code', grant.requestState);
+        if (request.stage !== 'request')
+            throw new InvalidGrantError('Invalid connection request');
+        res.clearCookie(name, {
+            path: '/connect/callback',
+            httpOnly: true,
+            sameSite: 'lax',
+            secure: this.options.publicUrl.protocol === 'https:',
+        });
+        const redirect = new URL(request.redirect_uri);
+        if (grant.denied) {
+            redirect.searchParams.set('error', 'access_denied');
+            if (request.state)
+                redirect.searchParams.set('state', request.state);
+            return redirect.toString();
+        }
+        if (typeof grant.rawToken !== 'string' ||
+            !Array.isArray(grant.scopes) ||
+            !grant.scopes.length ||
+            grant.scopes.some((s) => !request.scopes.includes(s)))
+            throw new InvalidGrantError('Invalid approval');
+        return this.issueCode(redirect, request, {
+            pat: grant.rawToken,
+            scopes: grant.scopes,
+            appId: grant.appId ?? undefined,
+            organizationId: grant.organizationId,
+        });
+    }
     /** The authorization request travels through the consent form, so it is sealed too. */
     sealAuthRequest(request) {
         return this.sealer.seal('code', { ...request, stage: 'request' }, AUTH_REQUEST_TTL);
     }
     /**
-     * Handle the consent form post: verify the pasted service token, then either
-     * redirect back with an authorization code or re-render with the reason it
-     * failed. Returns the HTML to render, or the redirect to follow.
+     * Handle the consent form post.
+     *
+     * Two stages, because the first screen cannot yet say what it is granting.
+     * The service only learns which organization a token reaches, and which
+     * scopes it really carries, by asking the instance about the token the person
+     * just pasted. Redirecting straight from there would mean the one screen a
+     * person sees never names the org the connection will reach or the
+     * provisioning power the token may carry. So a verified token renders a
+     * confirmation naming both, and only that confirmation issues a code.
+     *
+     * `stage=request`  the pasted-token form (sealed by `authorize`)
+     * `stage=confirm`  what the token actually reaches, awaiting approval
+     * `stage=code`     the authorization code itself
      */
-    async handleConsent(form) {
+    async handleConsent(form, fallbackLocale = 'en') {
         const rawRequest = typeof form.request === 'string' ? form.request : '';
         let request;
         try {
@@ -144,85 +304,168 @@ export class AppilotOAuthProvider {
         catch {
             return {
                 status: 400,
-                html: renderErrorPage('This sign-in link expired', 'Start the connection again from the client that sent you here. A consent link is valid for ten minutes.'),
+                html: renderErrorPage('This sign-in link expired', 'Start the connection again from the client that sent you here. A consent link is valid for ten minutes.', fallbackLocale),
             };
         }
-        if (request.stage !== 'request') {
-            return { status: 400, html: renderErrorPage('Invalid request', 'That token is not a consent request.') };
+        const locale = request.language ?? fallbackLocale;
+        if (request.stage !== 'request' && request.stage !== 'confirm') {
+            return {
+                status: 400,
+                html: renderErrorPage('Invalid request', 'That confirmation is incomplete. Start again.', locale),
+            };
         }
         const redirect = new URL(request.redirect_uri);
-        if (form.action === 'deny') {
+        const deny = () => {
             redirect.searchParams.set('error', 'access_denied');
             redirect.searchParams.set('error_description', 'The person declined the request.');
             if (request.state)
                 redirect.searchParams.set('state', request.state);
             return { redirect: redirect.toString() };
+        };
+        if (form.action === 'deny')
+            return deny();
+        // Stage 2: the person has seen what the token reaches and approved it.
+        if (request.stage === 'confirm') {
+            if (form.action === 'back') {
+                const { pat: _pat, identity: _identity, app_id: _app, ...original } = request;
+                const scopes = request.requested_scopes ?? request.scopes;
+                return {
+                    status: 200,
+                    html: renderConsentPage({
+                        locale,
+                        request: await this.sealAuthRequest({ ...original, scopes }),
+                        action: this.consentPath,
+                        clientName: request.client_name || 'your assistant',
+                        baseUrl: this.options.baseUrl,
+                        backofficeUrl: this.options.backofficeUrl,
+                        scopes,
+                    }),
+                };
+            }
+            if (form.action !== 'confirm' || !request.pat || !request.identity) {
+                return {
+                    status: 400,
+                    html: renderErrorPage('Invalid request', 'That confirmation is incomplete. Start again.', locale),
+                };
+            }
+            return {
+                redirect: await this.issueCode(redirect, request, {
+                    pat: request.pat,
+                    scopes: request.scopes,
+                    appId: request.app_id,
+                    organizationId: request.identity.organizationId ?? undefined,
+                }),
+            };
         }
         const pat = typeof form.pat === 'string' ? form.pat.trim() : '';
         const reRender = (error) => ({
             status: 400,
             html: renderConsentPage({
+                locale,
                 request: rawRequest,
                 action: this.consentPath,
-                clientName: 'an MCP client',
+                clientName: request.client_name || 'your assistant',
                 baseUrl: this.options.baseUrl,
+                backofficeUrl: this.options.backofficeUrl,
                 scopes: request.scopes,
                 error,
             }),
         });
         if (!pat.startsWith(SERVICE_TOKEN_PREFIX)) {
-            return reRender(`That does not look like a service token. A service token starts with ${SERVICE_TOKEN_PREFIX} and is created in the Backoffice under Settings, Service Tokens.`);
+            return reRender(message('wrongToken', locale));
         }
         let identity;
         try {
             identity = await this.verifyServiceToken(pat);
         }
-        catch (err) {
-            return reRender(err instanceof Error ? err.message : String(err));
+        catch {
+            return reRender(message('verifyError', locale));
         }
         if (!identity) {
-            return reRender('The instance rejected that service token. It may have been revoked or have expired.');
+            return reRender(message('rejected', locale));
         }
         // Never grant more than the token itself carries.
-        const granted = request.scopes.filter(s => identity.scopes.includes(s));
+        const granted = request.scopes.filter((s) => identity.scopes.includes(s));
         if (granted.length === 0) {
-            return reRender(`That token grants ${identity.scopes.join(', ')}, which does not cover the requested ${request.scopes.join(', ')}. Create a token with the needed scope.`);
+            return reRender(message('noScopes', locale));
         }
         // An app-scoped token dictates its own app; a form value cannot widen it.
         const formAppId = Number(form.app_id);
         const appId = identity.appId ?? (Number.isInteger(formAppId) && formAppId > 0 ? formAppId : undefined);
-        const code = await this.sealer.seal('code', {
+        const confirmRequest = await this.sealer.seal('code', {
             ...request,
-            stage: 'code',
+            requested_scopes: request.scopes,
+            stage: 'confirm',
             scopes: granted,
             pat,
             app_id: appId,
-            organization_id: identity.organizationId ?? undefined,
+            identity,
+        }, CONFIRM_TTL);
+        return {
+            status: 200,
+            html: renderConfirmPage({
+                locale,
+                request: confirmRequest,
+                action: this.consentPath,
+                baseUrl: this.options.baseUrl,
+                backofficeUrl: this.options.backofficeUrl,
+                scopes: granted,
+                withheldScopes: identity.scopes.filter((s) => !granted.includes(s)),
+                unavailableScopes: request.scopes.filter((s) => !granted.includes(s)),
+                clientName: request.client_name,
+                organizationName: identity.organizationName,
+                appName: identity.appName,
+                organizationId: identity.organizationId,
+                appId: appId ?? null,
+                appScoped: identity.appId != null,
+            }),
+        };
+    }
+    /** Seal the authorization code and hang it off the client's redirect. */
+    async issueCode(redirect, request, grant) {
+        const code = await this.sealer.seal('code', {
+            ...request,
+            stage: 'code',
+            // A per-code id, so redeeming one can be remembered. A sealed artifact
+            // carries no server-side handle otherwise.
+            jti: randomUUID(),
+            scopes: grant.scopes,
+            pat: grant.pat,
+            app_id: grant.appId,
+            organization_id: grant.organizationId,
         }, CODE_TTL);
         redirect.searchParams.set('code', code);
         if (request.state)
             redirect.searchParams.set('state', request.state);
-        return { redirect: redirect.toString() };
+        return redirect.toString();
     }
-    async openCode(client, authorizationCode) {
+    async openCode(client, authorizationCode, redeem) {
         let code;
         try {
             code = await this.sealer.open('code', authorizationCode);
         }
         catch (err) {
-            throw new InvalidGrantError(err instanceof SealError ? 'The authorization code is invalid or has expired.' : String(err));
+            throw new InvalidGrantError(err instanceof SealError
+                ? 'The authorization code is invalid or has expired.'
+                : String(err));
         }
         if (code.stage !== 'code')
             throw new InvalidGrantError('That token is not an authorization code.');
         if (code.client_id !== client.client_id)
             throw new InvalidClientError('The authorization code was issued to a different client.');
+        // Single use, and only on the exchange: the SDK reads the PKCE challenge
+        // from the same code first, and burning it there would reject every
+        // legitimate exchange.
+        if (redeem && code.jti && this.redeemed.check(code.jti)) {
+            throw new InvalidGrantError('That authorization code has already been used.');
+        }
         return code;
     }
     async challengeForAuthorizationCode(client, authorizationCode) {
-        return (await this.openCode(client, authorizationCode)).code_challenge;
+        return (await this.openCode(client, authorizationCode, false)).code_challenge;
     }
     async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri) {
-        const code = await this.openCode(client, authorizationCode);
+        const code = await this.openCode(client, authorizationCode, true);
         if (redirectUri !== undefined && redirectUri !== code.redirect_uri) {
             throw new InvalidGrantError('redirect_uri does not match the one the code was issued for.');
         }
@@ -240,7 +483,9 @@ export class AppilotOAuthProvider {
             throw new InvalidClientError('The refresh token was issued to a different client.');
         }
         // A refresh may narrow the grant, never widen it.
-        const narrowed = scopes?.length ? sealed.scopes.filter(s => scopes.includes(s)) : sealed.scopes;
+        const narrowed = scopes?.length
+            ? sealed.scopes.filter((s) => scopes.includes(s))
+            : sealed.scopes;
         if (narrowed.length === 0)
             throw new InvalidGrantError('The requested scopes are not covered by this grant.');
         return this.issue({ ...sealed, scopes: narrowed });

package/dist/scaffold.d.ts

@@ -34,4 +34,51 @@ interface ScaffoldOptions {
     idNamespace?: string;
 }
 export declare function scaffoldIntegration(options: ScaffoldOptions): ScaffoldResult;
+/**
+ * `scaffold_agent_first`: the four pieces one capability needs, together.
+ *
+ * `scaffoldIntegration` above returns the integration. It does not return the
+ * shape of an agent-first application, and the two are not the same thing. A
+ * capability that a user can complete through the assistant alone is four
+ * artifacts that have to agree with each other: the way the agent calls the
+ * backend, the way the page acts in the user's own session, the procedure the
+ * agent follows in the interface, and the meaning behind it.
+ *
+ * The split between the last two is the rule that is easiest to state and
+ * easiest to break. The Action Plan is the procedure. Knowledge carries meaning.
+ * A step-by-step knowledge article is a procedure in the wrong place, and it
+ * teaches the agent to author steps instead of adopting the plan that already
+ * exists. Emitting both halves correctly is how a scaffold teaches that once.
+ */
+export interface AgentFirstScaffold {
+    capability: string;
+    /** Ready for `create_tool`, minus the credential. */
+    tool: Record<string, unknown>;
+    /** Ready for `create_action_plan` once the control ids exist. */
+    actionPlan: Record<string, unknown>;
+    /** Ready for `create_knowledge`. */
+    knowledge: Record<string, unknown>;
+    files: ScaffoldFile[];
+    order: string[];
+    notes: string[];
+}
+interface AgentFirstOptions {
+    /** What the user is trying to do, in their words. */
+    capability: string;
+    /** Short English slug, used for the tool name and the plan id. */
+    slug: string;
+    appId: number | null;
+    /**
+     * The host endpoint the agent should reach, as a PATH on the host origin.
+     * The executor rejects an absolute URL: a server-side tool call is proxied
+     * to the app's own origin, never to an arbitrary host.
+     */
+    endpoint?: {
+        method: string;
+        path: string;
+    } | null;
+    /** True when the operation is UI-coupled and belongs in the page instead. */
+    clientSide?: boolean;
+}
+export declare function scaffoldAgentFirst(options: AgentFirstOptions): AgentFirstScaffold;
 export {};