esoul-sdk 0.24.0 → 0.25.2

package/dist/manifest.js

@@ -115,19 +115,26 @@ export const PluginConnectionSchema = z
     .refine((c) => c.kind !== "oauth2" ||
     (!!c.authorizeUrl && !!c.tokenUrl && !!c.clientIdEnv), { message: "oauth2 connections require authorizeUrl + tokenUrl + clientIdEnv" });
 /**
- * PLATFORM ACCOUNTS — the person's Google account, used by an app without the app ever holding it.
+ * THE PERSON'S ACCOUNTS — used by an app without the app ever holding them.
  *
- * A person connects a Google account once, in Account settings, and assigns it to an app. The
- * app's server code calls Google through `credentials(ctx).slot(name).fetch(url)` in
- * `esoul-sdk/server`: the platform checks who is calling and that the URL is one the slot's
- * declared scopes reach, then adds the token itself. The token never reaches the app — the
- * platform's Google token carries every scope the platform was granted and cannot be narrowed,
- * so the declared scopes are enforced at the proxy, not at Google.
+ * A person connects an account once, at the user level (Account settings → Google for Google,
+ * Account settings → Accounts for every other service), and assigns it to an app. The app's
+ * server code calls the service through `credentials(ctx).slot(name).fetch(url)` in
+ * `esoul-sdk/server`: the platform checks who is calling and that the URL is one the slot may
+ * reach, then adds the token or key itself. The secret never reaches the app or its developer.
  *
- * A scope is written as Google's full URL or as its short name (`gmail.modify`). `openid`,
- * `email` and `profile` are implicit and may be left out.
+ * Three families:
+ *   - `google` — the platform's verified Google client. Scopes are Google's (`gmail.modify`);
+ *     the platform's token cannot be narrowed, so the declared scopes are enforced at the proxy.
+ *   - `oauth2` — any OAuth 2.0 provider (Microsoft, Dropbox, Spotify, …): the slot declares the
+ *     provider's endpoints, the scopes it asks for and the API hosts the token may be sent to.
+ *   - `apiKey` — a key the person pastes (an API key, a personal access token): the slot declares
+ *     the hosts it may be sent to and the header that carries it.
+ *
+ * For `google` a scope is written as Google's full URL or as its short name (`gmail.modify`).
+ * `openid`, `email` and `profile` are implicit and may be left out.
  */
-export const CREDENTIAL_FAMILIES = ["google"];
+export const CREDENTIAL_FAMILIES = ["google", "oauth2", "apiKey"];
 /** The Google scopes an app may declare, by short name. Everything else is refused. */
 export const GOOGLE_CREDENTIAL_SCOPES = [
     "gmail.readonly",
@@ -178,8 +185,8 @@ export function normaliseCredentialScopes(scopes) {
 }
 /** Slot names: lower-case words joined by `-` (`mailbox`, `work-calendar`). */
 export const CREDENTIAL_SLOT_RE = /^[a-z][a-z0-9-]*$/;
-/** One slot of a manifest's `credentials` block. */
-export const PluginCredentialSlotSchema = z
+/** A `google` slot of a manifest's `credentials` block. */
+export const GoogleCredentialSlotSchema = z
     .object({
     family: z.literal("google").describe('Whose accounts: "google" is the platform\'s verified Google client.'),
     scopes: z
@@ -206,6 +213,143 @@ export const PluginCredentialSlotSchema = z
     background: z.boolean().optional().describe("True when the app's own tasks use the account with nobody present (a sync on a schedule)."),
 })
     .strict();
+/**
+ * An API host an `oauth2` or `apiKey` secret may be sent to: a DNS name (`graph.microsoft.com`),
+ * lower-case, no scheme, no port, no IP address, no `localhost`.
+ */
+export const CREDENTIAL_HOST_RE = /^(?=.{4,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+const credentialHost = z
+    .string()
+    .regex(CREDENTIAL_HOST_RE, "a host is a DNS name like graph.microsoft.com — lower-case, no https://, no port, no path, no IP address");
+const credentialHosts = z
+    .array(credentialHost)
+    .min(1)
+    .max(10)
+    .describe("The API hosts the secret may be sent to. The platform refuses every other host, and the person sees this list before connecting.");
+/** Authorize parameters the platform sets itself; a slot may not override them. */
+export const RESERVED_AUTHORIZE_PARAMS = ["response_type", "client_id", "redirect_uri", "scope", "state", "code_challenge", "code_challenge_method", "nonce"];
+/** A provider scope string: printable, no spaces (`Mail.ReadWrite`, `offline_access`, `files.content.read`). */
+const providerScope = z.string().min(1).max(200).regex(/^[\x21-\x7e]+$/, "a scope is one word without spaces");
+/** The OAuth 2.0 provider an `oauth2` slot signs in with. */
+export const OAuth2ProviderSchema = z
+    .object({
+    name: z.string().min(1).max(60).describe('The service as the person knows it: "Microsoft".'),
+    authorizeUrl: oauthEndpoint.describe("The provider's authorization endpoint (authorization code + PKCE)."),
+    tokenUrl: oauthEndpoint.describe("The provider's token endpoint. Accounts of one provider are the ones that share this URL and authorizeUrl."),
+    scopes: z.array(providerScope).min(1).max(40).describe("The provider's scopes this app asks for (e.g. offline_access, User.Read, Mail.ReadWrite)."),
+    hosts: credentialHosts,
+    accountUrl: oauthEndpoint
+        .optional()
+        .describe("Optional: a GET on one of `hosts` that answers JSON naming the signed-in account (e.g. https://graph.microsoft.com/v1.0/me)."),
+    accountField: z
+        .string()
+        .regex(/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/)
+        .optional()
+        .describe('The field of that JSON to show as the account, dotted for nesting (e.g. "userPrincipalName"). Default: email, mail, userPrincipalName, login, username, name — the first present.'),
+    authorizeParams: z
+        .record(z.string().regex(/^[a-z_][a-z0-9_]*$/), z.string().max(200))
+        .optional()
+        .describe('Extra authorize parameters (e.g. { "prompt": "select_account" }). The platform sets client_id, redirect_uri, scope, state and PKCE itself.'),
+    tokenAuth: z
+        .enum(["body", "basic"])
+        .optional()
+        .describe('How the client authenticates at tokenUrl: "body" (client_id + client_secret in the form, the default) or "basic" (HTTP Basic).'),
+    clientIdEnv: envName.optional().describe("Optional: a client the PLATFORM holds for this app (operator-set env). Without it, the person registers their own client once and enters it in Account settings."),
+    clientSecretEnv: envName.optional(),
+})
+    .strict()
+    .superRefine((p, ctx) => {
+    for (const k of Object.keys(p.authorizeParams ?? {})) {
+        if (RESERVED_AUTHORIZE_PARAMS.includes(k)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["authorizeParams", k], message: `"${k}" is set by the platform` });
+        }
+    }
+    if (p.accountUrl) {
+        let host = "";
+        try {
+            host = new URL(p.accountUrl).hostname.toLowerCase();
+        }
+        catch {
+            /* the field's own check reports it */
+        }
+        if (host && !p.hosts.includes(host)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["accountUrl"], message: `accountUrl's host ${host} must be one of hosts` });
+        }
+    }
+    if (p.clientSecretEnv && !p.clientIdEnv) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["clientSecretEnv"], message: "clientSecretEnv needs clientIdEnv" });
+    }
+});
+/** Headers a key may never be sent in. */
+const FORBIDDEN_KEY_HEADERS = new Set(["cookie", "host", "content-length", "content-type", "transfer-encoding", "connection", "proxy-authorization"]);
+/** The service an `apiKey` slot sends a pasted key to. */
+export const ApiKeyProviderSchema = z
+    .object({
+    name: z.string().min(1).max(60).describe('The service as the person knows it: "Notion".'),
+    hosts: credentialHosts,
+    header: z
+        .string()
+        .regex(/^[A-Za-z][A-Za-z0-9-]{0,63}$/)
+        .refine((h) => !FORBIDDEN_KEY_HEADERS.has(h.toLowerCase()), "that header cannot carry a key")
+        .optional()
+        .describe('The header that carries the key. Default "Authorization".'),
+    prefix: z
+        .string()
+        .max(20)
+        .regex(/^[\x20-\x7e]*$/)
+        .optional()
+        .describe('Written before the key in the header: "Bearer " (the default for Authorization), "Token ", or "" for none.'),
+    keyHelp: z.string().max(300).optional().describe("Where the person finds the key, in one sentence (shown beside the field)."),
+    verifyUrl: oauthEndpoint.optional().describe("Optional: a GET on one of `hosts` that answers 2xx for a valid key — the platform checks the key there before keeping it."),
+})
+    .strict()
+    .superRefine((p, ctx) => {
+    if (p.verifyUrl) {
+        let host = "";
+        try {
+            host = new URL(p.verifyUrl).hostname.toLowerCase();
+        }
+        catch {
+            /* reported by the field */
+        }
+        if (host && !p.hosts.includes(host))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["verifyUrl"], message: `verifyUrl's host ${host} must be one of hosts` });
+    }
+});
+const slotLabel = z.string().min(1).max(60).optional().describe("The slot's name on the screen (\"Mailbox\").");
+const slotWhy = z.string().min(1).max(300).describe("One sentence the person reads before assigning an account: what the app does with it.");
+const slotBackground = z.boolean().optional().describe("True when the app's own tasks use the account with nobody present (a sync on a schedule).");
+/** An `oauth2` slot: any OAuth 2.0 provider. */
+export const OAuth2CredentialSlotSchema = z
+    .object({ family: z.literal("oauth2"), provider: OAuth2ProviderSchema, label: slotLabel, why: slotWhy, background: slotBackground })
+    .strict();
+/** An `apiKey` slot: a key the person pastes. */
+export const ApiKeyCredentialSlotSchema = z
+    .object({ family: z.literal("apiKey"), provider: ApiKeyProviderSchema, label: slotLabel, why: slotWhy, background: slotBackground })
+    .strict();
+/** One slot of a manifest's `credentials` block. */
+export const PluginCredentialSlotSchema = z.discriminatedUnion("family", [GoogleCredentialSlotSchema, OAuth2CredentialSlotSchema, ApiKeyCredentialSlotSchema]);
+/**
+ * Which accounts serve a slot: accounts of one provider are interchangeable between apps.
+ * `oauth2` — the sign-in AND token endpoints (lower-case host, path), so a slot that points either
+ * one somewhere else is another provider and never reuses a person's client or account;
+ * `apiKey` — the sorted host list. Pure, so the platform, the box and the SDK agree.
+ */
+export function credentialProviderKey(slot) {
+    if (slot.family === "oauth2" && slot.provider?.tokenUrl && slot.provider?.authorizeUrl) {
+        try {
+            const t = new URL(slot.provider.tokenUrl);
+            const a = new URL(slot.provider.authorizeUrl);
+            return `oauth2:${t.protocol}//${t.host.toLowerCase()}${t.pathname}|${a.protocol}//${a.host.toLowerCase()}${a.pathname}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (slot.family === "apiKey" && slot.provider?.hosts?.length)
+        return `apiKey:${[...slot.provider.hosts].map((h) => h.toLowerCase()).sort().join(",")}`;
+    return null;
+}
 /** The `credentials` block: slot name → slot. At most ONE slot per app for now. */
 export const PluginCredentialsSchema = z
     .record(z.string().regex(CREDENTIAL_SLOT_RE, "a slot name is lower-case words joined by - (e.g. mailbox)"), PluginCredentialSlotSchema)
@@ -478,7 +622,7 @@ export const PluginManifestSchema = z.object({
      * Parts of the app that run ON THE PERSON'S COMPUTER (plugin-device-arm.md
      * §10–§11). The declared commands are the whole authority: the owner
      * approves this list by name when they connect a machine, the app calls
-     * them with `device(ctx, linkId).run(name, params)`, and nothing else can
+     * them with `devices(ctx).run(name, params, { linkId })`, and nothing else can
      * run. Adding or changing a command in an update waits for a fresh approval.
      */
     device: z
@@ -548,10 +692,12 @@ export const PluginManifestSchema = z.object({
     /** Third-party logins surfaced in Account settings → Plugins. */
     connections: z.array(PluginConnectionSchema).optional().default([]),
     /**
-     * PLATFORM ACCOUNTS the app uses (docs/08): slot name → `{ family, scopes, why, label?, background? }`.
-     * The person assigns one of their connected Google accounts to the slot in Account settings; the
-     * app calls Google through `credentials(ctx).slot(name).fetch(url)` and never sees a token.
-     * At most one slot per app for now.
+     * THE PERSON'S ACCOUNTS the app uses (docs/08): slot name → `{ family: "google", scopes, why }`,
+     * `{ family: "oauth2", provider: { name, authorizeUrl, tokenUrl, scopes, hosts }, why }` or
+     * `{ family: "apiKey", provider: { name, hosts, header?, prefix? }, why }` (+ `label?`,
+     * `background?`). The person connects an account once in Account settings and assigns it to the
+     * app; the app calls through `credentials(ctx).slot(name).fetch(url)` and never sees a token or
+     * key. At most one slot per app for now.
      */
     credentials: PluginCredentialsSchema.optional(),
     /**
@@ -722,4 +868,16 @@ export const PluginManifestSchema = z.object({
                 ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["connections", i, field], message: problem });
         }
     });
+    for (const [slot, decl] of Object.entries(m.credentials ?? {})) {
+        if (decl.family !== "oauth2")
+            continue;
+        for (const field of ["clientIdEnv", "clientSecretEnv"]) {
+            const name = decl.provider[field];
+            if (name === undefined || !PLUGIN_ENV_NAME_RE.test(name))
+                continue;
+            const problem = pluginEnvNameProblem(m.id, name);
+            if (problem)
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["credentials", slot, "provider", field], message: problem });
+        }
+    }
 });

package/dist/react.d.ts

@@ -535,13 +535,20 @@ export interface UseCredential {
     account?: {
         email: string | null;
     };
-    /** Declared scopes (full Google URLs) the account has not granted. */
+    /** Whose account: `{ name: "Google", family: "google" }`, `{ name: "Microsoft", family: "oauth2" }`, … */
+    provider?: {
+        name: string;
+        family: "google" | "oauth2" | "apiKey";
+    };
+    /** Declared scopes the account has not granted. */
     missingScopes?: string[];
+    /** oauth2 / apiKey: declared hosts the account was not connected for. */
+    missingHosts?: string[];
     reason?: string;
     /**
-     * Take the person where the state can be fixed: the platform's Google consent for missing
-     * permissions or a reconnect, Account settings → Google to assign an account. Does nothing when
-     * only the account's owner could act.
+     * Take the person where the state can be fixed: the provider's consent for missing permissions
+     * or a reconnect, Account settings (→ Google, or → Accounts for every other service) to assign
+     * or connect an account. Does nothing when only the account's owner could act.
      */
     connect(): void;
     /** Ask again. Also done when the window regains focus. */
@@ -550,8 +557,8 @@ export interface UseCredential {
 /**
  * The state of one of your plugin.json `credentials` slots for the person looking at the app.
  *
- *   const gm = useCredential("mailbox", { nodeId: identifier.nodeId });
- *   if (gm.state !== "ready") return <button onClick={gm.connect}>Connect Google</button>;
+ *   const ms = useCredential("microsoft", { nodeId: identifier.nodeId });
+ *   if (ms.state !== "ready") return <button onClick={ms.connect}>Connect {ms.provider?.name}</button>;
  */
 export declare function useCredential(_slot: string, _where: {
     nodeId: string;

package/dist/react.js

@@ -211,8 +211,8 @@ export function YourComputers(_props) {
 /**
  * The state of one of your plugin.json `credentials` slots for the person looking at the app.
  *
- *   const gm = useCredential("mailbox", { nodeId: identifier.nodeId });
- *   if (gm.state !== "ready") return <button onClick={gm.connect}>Connect Google</button>;
+ *   const ms = useCredential("microsoft", { nodeId: identifier.nodeId });
+ *   if (ms.state !== "ready") return <button onClick={ms.connect}>Connect {ms.provider?.name}</button>;
  */
 export function useCredential(_slot, _where) {
     return hostOnly("useCredential");

package/dist/server.d.ts

@@ -234,9 +234,9 @@ export type PluginConnectionCredentials = {
 export declare function getPluginConnectionCredentials(_connectionId: string, _pluginId: string): Promise<PluginConnectionCredentials>;
 /** Why a credential call was refused. */
 export type CredentialUnavailableCode = 
-/** No account is assigned to this app's slot. The owner assigns one in Account settings. */
+/** No account is assigned to this app's slot. The owner assigns one in Account settings (→ Google, or → Accounts). */
 "not_bound"
-/** The account has not granted every scope the slot declares; `connectUrl` asks for them. */
+/** The account has not granted every scope the slot declares, or was not connected for every host it declares; `connectUrl` asks. */
  | "needs_consent"
 /** The account's grant was revoked or expired; the owner connects it again (`connectUrl`). */
  | "reconnect"
@@ -254,8 +254,15 @@ export interface CredentialStatus {
     account?: {
         email: string | null;
     };
-    /** Declared scopes (full Google URLs) the account has not granted. */
+    /** Whose account: `{ name: "Google", family: "google" }`, `{ name: "Microsoft", family: "oauth2" }`, … */
+    provider?: {
+        name: string;
+        family: "google" | "oauth2" | "apiKey";
+    };
+    /** Declared scopes the account has not granted (full Google URLs for google; the provider's own words otherwise). */
     missingScopes?: string[];
+    /** oauth2 / apiKey: declared hosts the account was not connected for (the person approves them). */
+    missingHosts?: string[];
     /** Where the person grants what is missing: a platform URL, never a provider one. */
     connectUrl?: string;
     /** One sentence for the screen or the log, when the state is not `ready`. */
@@ -295,10 +302,12 @@ export interface CredentialSlot {
     /** Is the slot usable by THIS caller right now, and if not, why. Never throws for a known slot. */
     status(): Promise<CredentialStatus>;
     /**
-     * `fetch`, with the account's token added by the platform. Only https URLs the slot's declared
-     * scopes reach are sent (e.g. `https://gmail.googleapis.com/gmail/v1/users/me/…` for Gmail);
-     * any `Authorization` or `Cookie` you pass is dropped. Answers the provider's `Response`
-     * (bodies up to 35 MB). Throws `CredentialUnavailable` when the call cannot be made.
+     * `fetch`, with the account's token or key added by the platform. Only https URLs the slot may
+     * reach are sent: for `google` the endpoints its declared scopes reach (e.g.
+     * `https://gmail.googleapis.com/gmail/v1/users/me/…`); for `oauth2` / `apiKey` the hosts its
+     * provider block declares (e.g. `https://graph.microsoft.com/v1.0/me/messages`). Any
+     * `Authorization`, `Cookie` or key header you pass is dropped. Answers the provider's
+     * `Response` (bodies up to 35 MB). Throws `CredentialUnavailable` when the call cannot be made.
      */
     fetch(url: string | URL, init?: RequestInit): Promise<Response>;
 }
@@ -315,9 +324,14 @@ export interface Credentials {
  *   const g = credentials(ctx).slot("mailbox");
  *   const r = await g.fetch("https://gmail.googleapis.com/gmail/v1/users/me/labels");
  *
+ *   const ms = credentials(ctx).slot("microsoft");          // family "oauth2"
+ *   const me = await (await ms.fetch("https://graph.microsoft.com/v1.0/me/messages?$top=10")).json();
+ *
  * Only the account's owner (or the app's own background work, when the slot declares
- * `background: true`) may use it; anyone else gets `not_allowed`. HOST-ONLY: in a Forge preview
- * it answers `not_allowed` (a box holds no credential).
+ * `background: true`) may use it; anyone else gets `not_allowed`. HOST-ONLY. In a Forge preview a
+ * `google` slot talks to a simulated Gmail; an `oauth2` / `apiKey` slot answers `not_bound`
+ * (connect real accounts to the INSTALLED app) — test that code with `fakeCredentials` from
+ * `esoul-sdk/testing`.
  */
 export declare function credentials(_ctx: object): Credentials;
 /** One turn of the conversation the model reads. */
@@ -667,6 +681,56 @@ export declare function mintRouteToken(_ctx: {
     ttlSeconds?: number;
     label?: string;
 }): Promise<RouteTokenGrant>;
+/**
+ * The headless bridge — a page opened in a headless browser ON THE PLATFORM and driven over
+ * `postMessage`, for an app whose engine only exists as a web page (a WebAssembly CAD kernel, a
+ * canvas renderer). "No computer should be required": the person's tab is one place the page
+ * can run; this is the other, on Vercel, with nobody's tab open.
+ *
+ * `url` must be https and public. The page is loaded top-level, so it is its own `parent`: a
+ * bridge written for an iframe (`?parent=<origin>` + `window.parent.postMessage`) answers
+ * unchanged when the url names the page's own origin as the parent. `boot` waits for the page's
+ * ready message; each call posts `message` to the page's window and returns the first message
+ * whose `[replyField]` (default "id") equals the call's `id`. The page stays warm on the platform
+ * between calls for the same url — the first call pays the launch, later ones only the calls.
+ * Not available in a Forge preview (the box has no browser): keep the app open there instead.
+ */
+export interface HeadlessBridgeCall {
+    id: string;
+    message: Record<string, unknown>;
+    replyField?: string;
+    timeoutMs?: number;
+}
+export interface HeadlessBridgeArgs {
+    url: string;
+    boot?: {
+        field: string;
+        oneOf: string[];
+        timeoutMs?: number;
+    };
+    calls: HeadlessBridgeCall[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+export interface HeadlessBridgeResult {
+    boot: Record<string, unknown> | null;
+    replies: (Record<string, unknown> | null)[];
+    timings: Record<string, number>;
+    warm: boolean;
+}
+/**
+ * Run a web page in the platform's headless browser and drive it over `postMessage` — see the
+ * `HeadlessBridgeArgs` note above: `url` (https, public), `boot` (the page's ready message),
+ * `calls` (each posted to the page's window, answered by the first message whose `[replyField]`
+ * equals its `id`). Warm between calls for the same url; not available in a Forge box.
+ */
+export declare function headlessBridge(_ctx: {
+    pluginId: string;
+    nodeId: string;
+    origin?: string;
+}, _args: HeadlessBridgeArgs): Promise<HeadlessBridgeResult>;
 /** A question for the person (questions(ctx).ask). */
 export interface AppQuestion {
     /** Stable per question within this app instance: asking twice with one key is one question. */

package/dist/server.js

@@ -70,9 +70,14 @@ export function isCredentialUnavailable(err) {
  *   const g = credentials(ctx).slot("mailbox");
  *   const r = await g.fetch("https://gmail.googleapis.com/gmail/v1/users/me/labels");
  *
+ *   const ms = credentials(ctx).slot("microsoft");          // family "oauth2"
+ *   const me = await (await ms.fetch("https://graph.microsoft.com/v1.0/me/messages?$top=10")).json();
+ *
  * Only the account's owner (or the app's own background work, when the slot declares
- * `background: true`) may use it; anyone else gets `not_allowed`. HOST-ONLY: in a Forge preview
- * it answers `not_allowed` (a box holds no credential).
+ * `background: true`) may use it; anyone else gets `not_allowed`. HOST-ONLY. In a Forge preview a
+ * `google` slot talks to a simulated Gmail; an `oauth2` / `apiKey` slot answers `not_bound`
+ * (connect real accounts to the INSTALLED app) — test that code with `fakeCredentials` from
+ * `esoul-sdk/testing`.
  */
 export function credentials(_ctx) {
     return hostOnly("credentials");
@@ -261,6 +266,15 @@ export function renderChartImage(_ctx, _args) {
 export function mintRouteToken(_ctx, _args) {
     return hostOnly("mintRouteToken");
 }
+/**
+ * Run a web page in the platform's headless browser and drive it over `postMessage` — see the
+ * `HeadlessBridgeArgs` note above: `url` (https, public), `boot` (the page's ready message),
+ * `calls` (each posted to the page's window, answered by the first message whose `[replyField]`
+ * equals its `id`). Warm between calls for the same url; not available in a Forge box.
+ */
+export function headlessBridge(_ctx, _args) {
+    return hostOnly("headlessBridge");
+}
 /**
  * THE PLATFORM'S QUESTIONS BELL. A question an app needs the person to answer
  * (an agent waiting on a decision) reaches them wherever they are — the bell,

package/dist/testing/credentials.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `fakeCredentials()` — a stand-in for `credentials(ctx)` (docs/08) with the platform's rules and
+ * no accounts: your test says what each slot answers, and every call is recorded.
+ *
+ *   const creds = fakeCredentials({
+ *     microsoft: {
+ *       hosts: ["graph.microsoft.com"],
+ *       fetch: (url) => Response.json(url.pathname.endsWith("/me") ? { userPrincipalName: "ann@contoso.com" } : { value: [] }),
+ *     },
+ *   });
+ *   jest.mock("esoul-sdk/server", () => ({ ...jest.requireActual("esoul-sdk/server"), credentials: (ctx: object) => creds.credentials(ctx) }));
+ *   // or, for a task: ctx.credentials = (slot) => creds.credentials(ctx).slot(slot)
+ *   creds.calls; // [{ slot, method, url, headers }] — headers as your code sent them, minus the stripped ones
+ *
+ * Like the platform: only https URLs on the slot's `hosts` are let through (when `hosts` is
+ * given), `Authorization` / `Cookie` your code sets are dropped, an undeclared slot throws
+ * `not_declared`, and a slot whose `status` is not ready throws its state as the code.
+ */
+import { type CredentialStatus, type Credentials } from "../server.js";
+export interface FakeCredentialSlot {
+    /** What `status()` answers. Default `{ state: "ready" }`; any other state makes `fetch` throw it. */
+    status?: CredentialStatus;
+    /** Hosts the slot may reach (an oauth2 / apiKey slot's `provider.hosts`). Absent = any https host. */
+    hosts?: string[];
+    /** Answers a call that passed the rules. Default: 404 with an empty JSON body. */
+    fetch?: (url: URL, init: RequestInit) => Response | Promise<Response>;
+}
+export interface FakeCredentialCall {
+    slot: string;
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+}
+export interface FakeCredentials {
+    credentials(ctx: object): Credentials;
+    calls: FakeCredentialCall[];
+}
+/**
+ * A stand-in for `credentials(ctx)` from `esoul-sdk/server`: each slot answers as the test says
+ * (`status`, `hosts`, `fetch`), the platform's refusals apply, and `calls` records every request.
+ */
+export declare function fakeCredentials(slots: Record<string, FakeCredentialSlot>): FakeCredentials;

package/dist/testing/credentials.js

@@ -0,0 +1,73 @@
+/**
+ * `fakeCredentials()` — a stand-in for `credentials(ctx)` (docs/08) with the platform's rules and
+ * no accounts: your test says what each slot answers, and every call is recorded.
+ *
+ *   const creds = fakeCredentials({
+ *     microsoft: {
+ *       hosts: ["graph.microsoft.com"],
+ *       fetch: (url) => Response.json(url.pathname.endsWith("/me") ? { userPrincipalName: "ann@contoso.com" } : { value: [] }),
+ *     },
+ *   });
+ *   jest.mock("esoul-sdk/server", () => ({ ...jest.requireActual("esoul-sdk/server"), credentials: (ctx: object) => creds.credentials(ctx) }));
+ *   // or, for a task: ctx.credentials = (slot) => creds.credentials(ctx).slot(slot)
+ *   creds.calls; // [{ slot, method, url, headers }] — headers as your code sent them, minus the stripped ones
+ *
+ * Like the platform: only https URLs on the slot's `hosts` are let through (when `hosts` is
+ * given), `Authorization` / `Cookie` your code sets are dropped, an undeclared slot throws
+ * `not_declared`, and a slot whose `status` is not ready throws its state as the code.
+ */
+import { CredentialUnavailable } from "../server.js";
+const STRIPPED = new Set(["authorization", "cookie"]);
+/**
+ * A stand-in for `credentials(ctx)` from `esoul-sdk/server`: each slot answers as the test says
+ * (`status`, `hosts`, `fetch`), the platform's refusals apply, and `calls` records every request.
+ */
+export function fakeCredentials(slots) {
+    const calls = [];
+    const slotOf = (name) => {
+        const s = slots[name];
+        if (!s)
+            throw new CredentialUnavailable("not_declared", `this app's plugin.json declares no credential slot "${name}"`);
+        return s;
+    };
+    return {
+        calls,
+        credentials(_ctx) {
+            return {
+                slot(name) {
+                    return {
+                        status: async () => slotOf(name).status ?? { state: "ready" },
+                        fetch: async (url, init = {}) => {
+                            const s = slotOf(name);
+                            const st = s.status ?? { state: "ready" };
+                            if (st.state !== "ready")
+                                throw new CredentialUnavailable(st.state, st.reason ?? st.state, { connectUrl: st.connectUrl, missingScopes: st.missingScopes });
+                            let u;
+                            try {
+                                u = new URL(typeof url === "string" ? url : url.href);
+                            }
+                            catch {
+                                throw new CredentialUnavailable("not_allowed", "refused: the URL does not parse");
+                            }
+                            if (u.protocol !== "https:" || u.username || u.password || u.port)
+                                throw new CredentialUnavailable("not_allowed", "refused: only plain https:// URLs are reachable");
+                            if (s.hosts && !s.hosts.map((h) => h.toLowerCase()).includes(u.hostname.toLowerCase())) {
+                                throw new CredentialUnavailable("not_allowed", `refused: ${u.hostname} is not a host this account may be sent to (${s.hosts.join(", ")})`);
+                            }
+                            const headers = {};
+                            new Headers(init.headers ?? undefined).forEach((v, k) => {
+                                if (!STRIPPED.has(k.toLowerCase()))
+                                    headers[k] = v;
+                            });
+                            const method = (init.method ?? "GET").toUpperCase();
+                            calls.push({ slot: name, method, url: u.href, headers });
+                            if (s.fetch)
+                                return s.fetch(u, { ...init, method, headers });
+                            return new Response("{}", { status: 404, headers: { "content-type": "application/json" } });
+                        },
+                    };
+                },
+            };
+        },
+    };
+}

package/dist/testing/index.d.ts

@@ -18,6 +18,8 @@ export { capture, fakeApps, runOp } from "./ops.js";
 export type { BoundAppFixture, EmitCall, NotifyCall, Recorder, RunOpOptions, RunOpResult } from "./ops.js";
 export { memoryFiles } from "./files.js";
 export { scriptedModel, defaultScriptedText } from "./llm.js";
+export { fakeCredentials } from "./credentials.js";
+export type { FakeCredentials, FakeCredentialSlot, FakeCredentialCall } from "./credentials.js";
 /** The failed-request banner's list, for a test that asserts a click reverted and was named (runOptimistic). */
 export { listFailedRequests, subscribeFailedRequests, __resetFailedRequests as resetFailedRequests } from "../failed-requests.js";
 export type { ScriptedLlm, ScriptedPolicy, ScriptedReply } from "./llm.js";

package/dist/testing/index.js

@@ -16,6 +16,7 @@ export { fakeViewer, memoryDb, roleForKind } from "./db.js";
 export { capture, fakeApps, runOp } from "./ops.js";
 export { memoryFiles } from "./files.js";
 export { scriptedModel, defaultScriptedText } from "./llm.js";
+export { fakeCredentials } from "./credentials.js";
 /** The failed-request banner's list, for a test that asserts a click reverted and was named (runOptimistic). */
 export { listFailedRequests, subscribeFailedRequests, __resetFailedRequests as resetFailedRequests } from "../failed-requests.js";
 export { simGmail, DEFAULT_SIM_ACCOUNT, DEFAULT_CROWD_MIX } from "./sim-gmail/index.js";

package/dist/types.d.ts

@@ -140,6 +140,21 @@ export interface EventDefinition<StateType extends ApplicationIdentifier> {
      * back to the normal conflict record. Pure. See docs/17-editing-and-merging.md.
      */
     baseMerge?: BaseMerge;
+    /**
+     * MERGE A CONCURRENT WRITE BEFORE IT BECOMES A CONFLICT. Called by the fence only when this event would be
+     * applied as a conflict — the sub-items it writes (`merge.scope`) were changed by a writer it never saw. The
+     * event knows its data: it merges what it can against the base it carries and the state it lands on, and
+     * returns the rewritten event. `detail` undefined → everything merged, no conflict marker; `detail` set → what
+     * could not be merged, stored on the marker for the resolution UI (the app's own shape); `null` → cannot reason
+     * about it (the plain conflict stands: applied and marked). Pure and deterministic — it runs in every fold.
+     * See docs/17-editing-and-merging.md §4.
+     */
+    resolveConcurrent?: (state: any, eventData: any, ctx: {
+        theirsSess: string | null;
+    }) => {
+        eventData: any;
+        detail?: unknown;
+    } | null;
 }
 export interface BaseMerge<V = any> {
     /** The value this event writes, as the state holds it right now (theirs). `undefined` → nothing to merge. */

package/docs/02-manifest.md

@@ -38,14 +38,22 @@ schema is shipped at `schemas/plugin.schema.json`.
 | `entry` | the schema module without extension (`app`) |
 | `icon` | a lucide-react name from the curated set (the workbench lists them when yours is wrong); missing → the generic glyph, never a broken tile |
 | `author` | stamped by the workbench at scaffold: `url` is `esoul:user:<id>`, and it is what the release script and the id-collision check read. No email — a manifest may become public |
-| `ops` | server operations exported by `server.ts` (docs/06) |
+| `ops` | server operations exported by `server.ts` (docs/06). A list of names (each `write`), or an object `name → { "access": "read" \| "public" \| "write" \| "roles", "roles"?, "requires"?: "account" }` (docs/13) |
+| `routes` | HTTP routes `/api/plugins/<id>/route/<name>` served by `server.ts`, same object form; `"access": "token"` makes a door for a machine (`mintRouteToken`, docs/06) |
 | `webhooks` | inbound routes `POST /api/plugins/<id>/webhook/<hook>` served by `server.ts` (docs/06) |
-| `kickableTasks` | task names the **browser** may kick (docs/07) |
+| `kickableTasks` | task names the **browser** may kick (docs/07); list or the object form |
 | `pollTasks` | tasks the platform kicks on a cadence, 5-minute granularity, minimum 5 (docs/07) |
+| `roles.vocabulary` / `roles.default` | your app's own words for people (`["staff", "customer"]`) and which word each platform role starts as (docs/13) |
 | `roles.attributes` | what a grant may say about a person, typed: `{ "customer": "int" }` — rules scope a role by `viewer.<attribute>` (docs/13) |
 | `roles.custom` | the envelope an OWNER composes roles inside at runtime — fields a role may be scoped by / denied / change, transitions, surfaces, attributes (docs/13) |
 | `workspaceTools` | the grant wall for calling OTHER apps' tools — `<applicationType>:<tool base name>`; absent = no cross-app access (docs/04, 06) |
-| `connections` | OAuth2 / API-key connections the user grants once and the platform holds sealed; **names of env vars, never values**, and only the app's own: `PLUGIN_<ID>__<NAME>`; endpoints https (docs/08) |
+| `db` | your own tables: fields, indexes, per-row `rules`, `sealed` fields — generated and scoped by the platform, additive on update (docs/14) |
+| `channel` | realtime topics and who hears each (audiences) (docs/15) |
+| `uses` / `provides` | binding slots another app fills by contract, and the contracts you provide (docs/16) |
+| `credentials` | the person's accounts the app uses, one slot for now: `family: "google"` (`scopes`), `"oauth2"` (any OAuth 2.0 provider — `provider: { name, authorizeUrl, tokenUrl, scopes, hosts }`) or `"apiKey"` (`provider: { name, hosts, header?, prefix? }`), plus `why`, `label?`, `background?`. The person connects once in Account settings and assigns the account; your code calls through `credentials(ctx).slot(name).fetch` and never sees the token, key or client secret (docs/08) |
+| `llm` | model calls billed to the owner: tiers, `dailyBudgetUsd`, `why`; called with `llm(ctx)` / `ctx.llm` — never a model SDK (docs/19) |
+| `device` | parts that run on the person's computers: `commands`, `program` (`main`, `resident`, `setup`, `selfTest`), `config`, `redact`, `onAppDeleted` (docs/18, 20) |
+| `connections` | older: OAuth2 / API-key connections whose token your code reads itself (`getPluginConnectionCredentials`); prefer a `credentials` slot. **Names of env vars, never values**, and only the app's own: `PLUGIN_<ID>__<NAME>`; endpoints https (docs/08 §9) |
 | `fileSources` / `fileProviders` | consent to read workspace files and providers; providers you contribute (docs/09) |
 | `fileProducers` | `[{ key, label }]` — your app's own bytes as a file-transfer source; implemented by `pluginServer.fileProducers[key]` (docs/09) |
 | `platformApi` | refuse install outside `[min, max]` of the platform contract version |