wizards 0.2.25 → 0.2.27

package/apps/runtime/dist/agents/architect.js

@@ -1,4 +1,5 @@
 import { anthropic } from "@ai-sdk/anthropic";
+import { SURFACE_GUIDE } from "@engenty-wizards/shared/surface";
 import { isTextMime } from "@engenty-wizards/shared/workspace";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
@@ -27,6 +28,9 @@ ${SCHEMA_DOC}
 ${PRINCIPLES}
 ${WIDGET_GUIDE}
 
+Surface catalog (for surface steps and output.surface):
+${SURFACE_GUIDE}
+
 ${mcpServersLine(mcp)}
 
 ${connectorsLine(connectors)}${pluginToolsLine(pluginTools)}
@@ -40,6 +44,7 @@ HOW YOU WORK
 - You change the wizard ONLY through tools: edit_wizard (small ops) or replace_wizard (new or mostly rewritten). Every write returns the validator's issues — fix them before you finish.
 - Widgets and their data live in the workspace: list_files, read_file, write_file, delete_file, download_files. Then check_widget, look at the screenshot, fix, check again.
 - Order: 1. write the wizard's steps, 2. fetch only the reference data the widget truly needs (one download_files call for all of it), 3. write the widget and its sample.json, 4. check_widget and fix, 5. answer. You have about 30 tool calls — never spend them on exploring.
+- A message that starts "New step" or "Neuer Schritt" comes from the studio's step panel or diagram: add exactly that one step in the place it names – of the kind in brackets, or the kind that fits best when none is named – and build it completely: a page's fields, an AI step's instructions and output, a view's components and data, a widget with its HTML and sample.json. Read what it needs from the steps before it, and leave the other steps as they are unless the new step needs a change there. With "Only if:" / "Nur wenn:" or "AI decides:" / "KI entscheidet:" the new step is a branch that only some runs take: put it right after the step before it, and give that step a rule to the new step (a "when" condition written from the admin's words against the data known there, or an "ask" statement for AI decides) plus an "otherwise" rule (only "goto") to the step every other run went to before; the new step then goes on to that same step as the next in the list. Keep that step's other rules.
 - Call independent tools in the same step (they run together).
 - Never retype data you downloaded. Reshape it with run_script (output to a file), or let the widget read the raw files with wizard.json() and transform them when it starts.
 - Work in few, purposeful steps: every tool call costs the admin time and credits.

package/apps/runtime/dist/agents/project-assistant.js

@@ -12,7 +12,7 @@ import { brandColorSchema, ownedProject, updateProject } from "../services/proje
 import { categoryRows } from "../services/space-categories.js";
 import { currentTenant } from "../tenants/tenant.js";
 import { safeFetch } from "../tools/net-guard.js";
-import { assistantToolsOf } from "../tools/plugin.js";
+import { assistantPageOf, assistantToolsOf } from "../tools/plugin.js";
 import { readWebsite } from "./website.js";
 const MAX_STEPS = 24;
 const SYSTEM = `You help the admin of "engenty wizards" set up a SPACE: what every wizard of the space draws on — who they are (title, about), the brand (logos, colours), assets (images, graphics, videos), documents, and facts (label → value: address, VAT id, phone, opening hours — anything).
@@ -337,7 +337,16 @@ export async function runProjectAssistant(input) {
         model: resolved.model,
         tools,
     });
+    const page = input.plugin
+        ? await assistantPageOf(currentTenant(), input.plugin, { id: project.id, name: project.name })
+        : null;
     const context = [
+        page
+            ? [
+                `The admin talks to you from the page of "${page.name}" in the studio${page.description ? `: ${page.description}` : "."} They most likely want to change what that page holds: use its tools (their names begin with "${input.plugin?.replace(/-/g, "_")}_"). Space settings stay possible when they ask for them.`,
+                ...page.blocks,
+            ].join("\n\n")
+            : "",
         `The project now:\n\`\`\`json\n${JSON.stringify(await projectState(input.userId, input.projectId))}\n\`\`\``,
         input.part === "knowledge"
             ? "The admin talks to you from Wissen: they want the wizards to know something."

package/apps/runtime/dist/authoring/guide.js

@@ -1,3 +1,4 @@
+import { SURFACE_GUIDE } from "@engenty-wizards/shared/surface";
 import { sandboxGuideLine } from "../sandbox/index.js";
 import { EXAMPLE_WIZARD } from "./example.js";
 /**
@@ -50,14 +51,34 @@ type Connection =
       //           "write" that in truth only looks something up (MCP servers often leave the mark out).
 
 // Every step: { id (camelCase, unique), title, description?, next?: Branch[] }
-// Branch = { when: { field, op: "equals"|"notEquals"|"in"|"notEmpty"|"empty", value? }, goto: stepId | "end" }
-//   field is a page field id, or an output field of this or an earlier agent step as "steps.<stepId>.<fieldId>"
-//   first matching branch wins, otherwise the next step in the list.
+// Branch = { when: Condition | Condition[], goto: stepId | "end", max? }
+//        | { ask: "a statement about the run", goto: stepId | "end", max? }
+//        | { goto: stepId | "end" }   // otherwise: where the run goes when no other branch holds (one per step)
+//   ask: a decision reads the person's answers and what the steps made so far and takes the branch when the
+//   statement is true ("The person wants a refund, not an exchange"). All ask branches of a step are decided
+//   together in one cheap call, after no "when" branch matched; if none clearly holds the next step follows.
+//   Use ask where a rule on one field cannot say it; never one decision step per branch.
+//   max: how often the branch may be taken in one run. A branch BACK to an earlier step is a loop ("improve until
+//   the check passes": a decision step branches back to the writing step) — give it max (at most 10 without);
+//   the step that runs again sees what it made last time.
+// Condition = { field, op: "equals"|"notEquals"|"in"|"notEmpty"|"empty"|"gt"|"lt"|"contains", value? }
+//   field is a page field id, an output field of this or an earlier agent step as "steps.<stepId>.<fieldId>",
+//   or how many rows a stored list has as "lists.<listId>.count"
+//   gt / lt compare numbers (value is a number); contains looks into a multiselect, a list output or a text;
+//   in takes a list of values. A list of conditions holds when every one holds.
+//   first matching branch wins, otherwise the step's "otherwise" branch, else the next step in the list.
+//   A step only some runs take sits right after the step that branches to it; that step's otherwise branch
+//   leads every other run past it, and the step itself goes on as the next in the list.
 
-type PageStep = { type: "page", fields: Field[] (1–5 per page), cta?: string }
+type PageStep = { type: "page", fields: Field[] (1–5 per page), groups?: { id, instructions, optional? }[], cta?: string }
+// Decided fields: a field with ask: "statement" is shown when a decision finds the statement true of the run;
+//   fields with group: groupId are alternatives of which the decision shows one ("How should we reach the person?"),
+//   or none when the group is optional. Decided once as the run reaches the page. Such a page has up to 12 fields
+//   and shows at most 5. Use them where the earlier answers decide which question makes sense and no single field
+//   rule can say it; "when" stays the first choice.
 type Field = {
   id (camelCase, unique across the WHOLE wizard), label, kind, required?, placeholder?, help?,
-  options?: string[]            // select / multiselect
+  options?: string[]            // select / multiselect / slot
   default?: string|number|boolean|string[]
   columns?: { id, label, kind: "text"|"number"|"money" }[]   // items only; row amount = product of number/money columns
   vat?: { rate?: number, field?: fieldId }                    // items only; VAT % fixed or read from a field
@@ -74,9 +95,15 @@ type Field = {
   list?: listId                 // kind "list": the page shows that stored list for the person to check, correct and extend
   prefill?: "steps.<id>.<key>"  // what the field starts with, from an earlier step. An "items" field takes a table whose
                                 //   columns are exactly its column ids — the step proposes the positions, the person corrects them
+  when?: Condition | Condition[] // the field is shown only while this holds: it reads another field of the SAME page (decided as
+                                //   the person types) or anything known before the page (an earlier answer, steps.<id>.<field>).
+                                //   A hidden field is not required and not kept; its {{template}} is empty.
+  optionsFrom?: "steps.<id>.<key>" | "steps.<id>.<key>.<column>" | "lists.<id>.<column>"
+                                // select / multiselect / slot: the choices come from earlier data — a "list" output, one column of a
+                                //   "table" output, or a column of a stored list. "options" stand in while that data is empty.
 }
 // kinds: text textarea number select multiselect date email url toggle color image file items connection list
-//        location audio signature
+//        location audio signature slot
 //   location:  where the person is — the phone's position on a tap (with its accuracy), or an address they type.
 //              {{field}} → "Herrengasse 16, 8010 Graz (47.07071, 15.43950, ±12 m)" · {{field.lat}} {{field.lng}}
 //              {{field.accuracy}} (metres) · {{field.label}} (the address line) · {{field.map}} (a map link).
@@ -85,6 +112,10 @@ type Field = {
 //              {{field}} is what the person said, as text. {{field.seconds}} is its length.
 //   signature: drawn with the finger — a picture (dark ink, clear ground). A document step can place it:
 //              {{field}} → asset://ID, used as <img src="asset://ID">.
+//   slot:      the person picks one appointment time, shown by day. Options are ISO 8601 date-times with their offset
+//              ("2026-10-12T09:00:00+02:00"), nearly always from optionsFrom; {{field}} is the chosen one, as offered.
+//              Booking: agent step "free" with tools ["appointments.availability"] outputs a table "slots" with a "start" column;
+//              then a page { kind: "slot", optionsFrom: "steps.free.slots.start" }; then an agent step with appointments.book.
 
 type AgentStep = {
   type: "agent"
@@ -92,7 +123,12 @@ type AgentStep = {
   tools: ("web_search"|"web_fetch"|"browser"|"sandbox"|"image"|"http"|"pages")[]
   mcp?: string[]                // ids of the project's MCP servers this step may use
   connections?: string[]        // ids of wizard connections this step may read (mail → mail_search, mail_read, mail_save)
-  output: { format: "text"|"markdown"|"json", fields?: { id, kind: "text"|"number"|"list"|"table"|"yesno"|"choice", description, columns?: string[], options?: string[] }[] }
+  output: { format: "text"|"markdown"|"json", fields?: { id, kind: "text"|"number"|"list"|"table"|"yesno"|"choice"|"score", description, columns?: string[], options?: string[] }[], surface?: boolean }
+                                // "score" answers its description on the scale in options, lowest first ("low", "medium", "high")
+  each?: "steps.<id>.<key>" | "lists.<id>"
+                                // ONE RUN PER ENTRY (at most 20): the rows of a table output, the entries of a list output, or the
+                                //   rows of a stored list; the instructions read {{item.<column>}}, {{index}}, {{count}}. The output is
+                                //   one table, steps.<id>.rows: the entry's columns plus the step's output fields, a row per entry.
                                 // a table with columns gives rows as objects with exactly those keys — what widgets read
                                 // "yesno" answers the question in its description with true/false; "choice" picks one of its options
   model?: "classifier"|"standard"|"high"|"highest"  // the kind of model, see "Models"; default "high"
@@ -110,6 +146,19 @@ type AgentStep = {
 //   browser_request_user (the person solves a captcha or "continue with Google" in a picture of the page),
 //   browser_download (keeps a file from a signed-in site).
 
+type SurfaceStep = {
+  type: "surface"
+  components: SurfaceComponent[]  // a view from the surface catalog (below), written once; every run brings new data
+  data: { [key]: "fieldId" | "steps.<id>" | "steps.<id>.<key>" | "lists.<id>" | "brand.name" | "today" }
+                                // what the components read by path: {"path": "/<key>/..."}
+  // or instead of components — pieces a decision picks per run (no chart when there is nothing to chart):
+  candidates?: { id, description, components: SurfaceComponent[] (the first has the piece's id), group?, required? }[]
+  groups?: { id, instructions, optional? }[]
+}
+// A SURFACE is a native view in the runner — facts, a list of results, key figures, a chart — themed, on phones, free per run.
+//   Prefer it to a widget for such views; a widget is for what the catalog cannot show (a map, an animation).
+//   An agent step with output.format "json" can also set output.surface: true: it composes such a view of its own result.
+//   Reviews and the result show a step's view instead of its plain table.
 type GenerateStep = {
   type: "generate"
   asset: "image"|"video"|"voice"|"document"|"dashboard"
@@ -186,6 +235,7 @@ A template may only use fields asked and steps run EARLIER.`;
 export const PRINCIPLES = `
 How good wizards look:
 - For non-technical end users. Plain words, friendly titles phrased as questions ("Wofür ist der Post?").
+- A page whose fields depend on an earlier answer uses "when" on its fields, never one copy of the page per answer and a branch to each copy. Choices that depend on what an earlier step found use "optionsFrom", never one page per possible result.
 - Few pages, 1–5 fields each, one theme per page. Only ask what the result really needs; prefer selects with sensible defaults.
 - Put a review step before anything expensive (video) and before the final result, so people can correct or regenerate.
 - Money/totals: use an "items" field with vat — the runner computes totals; documents must use {{items}} verbatim. Never let a model compute totals.
@@ -277,13 +327,16 @@ ${SCHEMA_DOC}
 ${PRINCIPLES}
 ${WIDGET_GUIDE}
 
+Surface catalog (for surface steps and output.surface):
+${SURFACE_GUIDE}
+
 ${mcpServersLine(mcp)}
 
 ${connectorsLine(connectors)}${pluginToolsLine(pluginTools)}
 
 Models: a step names the KIND of model it needs, never a model. Pick the cheapest class that does the job:
 - "classifier": routing, yes/no, picking from options, pulling a few values out of text.
-  A DECISION is a "classifier" step with no tools whose json output has only "yesno" and "choice" fields: it is answered in one fast, very cheap call. Write the question into each field's description, give the step everything it must judge in its instructions via {{templates}}, and branch on the answer with "next" (e.g. { when: { field: "steps.check.refund", op: "equals", value: true }, goto: "refund" }).
+  A DECISION is a "classifier" step with no tools whose json output has only "yesno", "choice" and "score" fields: it is answered in one fast, very cheap call. A branch can also read how sure it is: "steps.<id>.<field>.p" is the probability of its answer (a number 0–1; 1 or 0 where no decision model is set up), e.g. { field: "steps.check.urgent.p", op: "gt", value: 0.8 }. Write the question into each field's description, give the step everything it must judge in its instructions via {{templates}}, and branch on the answer with "next" (e.g. { when: { field: "steps.check.refund", op: "equals", value: true }, goto: "refund" }).
 - "standard": short copy, calling an API, reformatting, simple summaries.
 - "high": research with tools, long documents, reasoning over many sources (the default).
 - "highest": hard reasoning or writing code; rare in a run, several times the cost of "high".

package/apps/runtime/dist/connectors/builtin.js

@@ -1,6 +1,7 @@
 import { createGuardedFetch } from "../engenty/connections-external/net/guarded-fetch.js";
 import { githubConnector } from "../engenty/connections-github/connector.js";
 import { googleConnectors } from "../engenty/connections-google/definitions.js";
+import { GOOGLE_OAUTH2 } from "../engenty/connections-google/shared.js";
 import { hubspotConnector } from "../engenty/connections-hubspot/connector.js";
 import { microsoftOneDriveConnector } from "../engenty/connections-microsoft/onedrive.js";
 import { microsoftOutlookConnector } from "../engenty/connections-microsoft/outlook.js";
@@ -8,9 +9,11 @@ import { s3Connector } from "../engenty/connections-s3/s3.js";
 import { hasOAuth2ClientCredentials, } from "../engenty/connections-sdk/oauth2.js";
 import { registerConnectorDefinition } from "../engenty/connections-sdk/registry.js";
 import { slackConnector } from "../engenty/connections-slack/connector.js";
+import { managed } from "../manage.js";
 import { gmailConnector as mailGmail } from "./gmail.js";
 import { imapConnector } from "./imap.js";
 import { outlookConnector as mailOutlook } from "./outlook.js";
+import { googleThroughAccount } from "./via-account.js";
 /**
  * engenty's own connectors, as engenty ships them: Gmail, Drive, Calendar, Contacts, Outlook,
  * OneDrive, Slack, GitHub, HubSpot, S3. Every project has them; an OAuth one can be connected
@@ -53,7 +56,20 @@ export async function usable(connector) {
     }
     // A connector that registers its own OAuth client needs none configured.
     return (connector.auth.oauth2.dynamicClientRegistration === true ||
-        hasOAuth2ClientCredentials(connector.auth.oauth2, resolveEnv));
+        (await hasOAuth2ClientCredentials(connector.auth.oauth2, resolveEnv)) ||
+        viaAccount(connector));
+}
+/**
+ * A Google connector on a local install without a Google client of its own: it connects through
+ * the Manage-App of the linked account, when that one offers it. Offered before an account is
+ * linked too; connecting then asks to link it first.
+ */
+export async function viaAccount(connector) {
+    return (!managed &&
+        connector.auth.kind === "oauth2" &&
+        connector.auth.oauth2 === GOOGLE_OAUTH2 &&
+        !(await hasOAuth2ClientCredentials(connector.auth.oauth2, resolveEnv)) &&
+        (await googleThroughAccount()));
 }
 /** What the server's owner has to set for an OAuth connector that is not usable yet. */
 export function missingSetup(connector) {

package/apps/runtime/dist/connectors/index.js

@@ -5,8 +5,9 @@ import { scopesForGroups, } from "../engenty/connections-sdk/types.js";
 import { env } from "../env.js";
 import { seal, unseal } from "../secrets/crypto.js";
 import { deleteSecret, getSecret, putSecret } from "../store/index.js";
-import { connectorFetch, MAIL_CONNECTORS, resolveEnv, usable } from "./builtin.js";
+import { connectorFetch, MAIL_CONNECTORS, resolveEnv, usable, viaAccount } from "./builtin.js";
 import { resolveConnector } from "./external.js";
+import { AccountConnectError, redeemTicket, refreshThroughAccount, startThroughAccount, } from "./via-account.js";
 /** The connectors a person can pick for each kind of connection. */
 const CONNECTORS = { mail: MAIL_CONNECTORS };
 const HINTS = {
@@ -95,6 +96,24 @@ export async function startOAuth(scope, projectId, runId, connection, connectorI
     if (connector.auth.kind !== "oauth2") {
         throw new Error(`${connector.name} is not connected by signing in.`);
     }
+    if (await viaAccount(connector)) {
+        // The Manage-App keeps the PKCE verifier; ours stays empty.
+        const state = {
+            scope,
+            projectId,
+            runId,
+            connectionId: connection.id,
+            connectorId,
+            verifier: "",
+            exp: Date.now() + 15 * 60_000,
+        };
+        try {
+            return await startThroughAccount(scopesFor(connection, connector), seal(state), connectRedirectUri());
+        }
+        catch (err) {
+            throw err instanceof AccountConnectError ? new ConnectError(err.message) : err;
+        }
+    }
     // Servers that hand out OAuth clients on request (most MCP servers): get one on first use.
     await connector.auth.oauth2.registerClient?.();
     const pkce = createOAuth2Pkce();
@@ -120,7 +139,11 @@ export async function startOAuth(scope, projectId, runId, connection, connectorI
 export function oauthStateRun(rawState) {
     return unseal(rawState)?.runId ?? null;
 }
-export async function finishOAuth(code, rawState) {
+/**
+ * Google came back: with a code, or — connected through the account's Manage-App — with a
+ * ticket that holds the tokens.
+ */
+export async function finishOAuth(answer, rawState) {
     const state = unseal(rawState);
     if (!state || state.exp < Date.now()) {
         throw new Error("Die Anmeldung ist abgelaufen. Bitte noch einmal verbinden.");
@@ -134,13 +157,15 @@ export async function finishOAuth(code, rawState) {
     if (connector.auth.kind !== "oauth2") {
         throw new Error("not an oauth connector");
     }
-    const tokens = await exchangeAuthorizationCode({
-        code,
-        codeVerifier: state.verifier,
-        config: connector.auth.oauth2,
-        redirectUri: connectRedirectUri(),
-        resolveEnv,
-    });
+    const tokens = "ticket" in answer
+        ? await redeemTicket(answer.ticket)
+        : await exchangeAuthorizationCode({
+            code: answer.code,
+            codeVerifier: state.verifier,
+            config: connector.auth.oauth2,
+            redirectUri: connectRedirectUri(),
+            resolveEnv,
+        });
     // A provider that will not name the account still connected it.
     const account = (await connector.auth.oauth2
         .resolveAccount?.(tokens.accessToken, fetch)
@@ -150,6 +175,7 @@ export async function finishOAuth(code, rawState) {
         refreshToken: tokens.refreshToken,
         expiresAt: tokens.expiresAt?.toISOString() ?? null,
         scopes: tokens.grantedScopes,
+        ...("ticket" in answer ? { via: "account" } : {}),
     };
     await putSecret(state.scope, slot(connection.id), connector.id, account.label, stored);
     return state;
@@ -227,12 +253,15 @@ export async function connectionContext(scope, connection, projectId) {
         data.refreshToken &&
         expires !== null &&
         expires - Date.now() < 5 * 60_000) {
-        const tokens = await refreshAccessToken({
-            config: connector.auth.oauth2,
-            refreshToken: data.refreshToken,
-            resolveEnv,
-        });
+        const tokens = data.via === "account"
+            ? await refreshThroughAccount(data.refreshToken)
+            : await refreshAccessToken({
+                config: connector.auth.oauth2,
+                refreshToken: data.refreshToken,
+                resolveEnv,
+            });
         data = {
+            ...(data.via ? { via: data.via } : {}),
             accessToken: tokens.accessToken,
             refreshToken: tokens.refreshToken ?? data.refreshToken,
             expiresAt: tokens.expiresAt?.toISOString() ?? null,

package/apps/runtime/dist/connectors/plugin-connections.js

@@ -0,0 +1,248 @@
+import { and, desc, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { db, schema } from "../db/client.js";
+import { buildAuthorizationUrl, createOAuth2Pkce, exchangeAuthorizationCode, refreshAccessToken, } from "../engenty/connections-sdk/oauth2.js";
+import { seal, unseal } from "../secrets/crypto.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { builtinConnector, connectorFetch, resolveEnv, usable, viaAccount } from "./builtin.js";
+import { connectRedirectUri as redirectUri } from "./index.js";
+import { AccountConnectError, redeemTicket, refreshThroughAccount, startThroughAccount, } from "./via-account.js";
+function oauthConnector(id) {
+    const connector = builtinConnector(id);
+    if (connector?.auth.kind !== "oauth2") {
+        throw new Error(`"${id}" is not a built-in connector that signs in.`);
+    }
+    return connector;
+}
+/** The provider rights the named actions need, and the connector's own base rights. */
+function scopesOf(connector, actions) {
+    const scopes = new Set(connector.auth.kind === "oauth2" ? connector.auth.oauth2.baseScopes : []);
+    for (const id of actions) {
+        const action = connector.actions.find((a) => a.id === id);
+        if (!action) {
+            throw new Error(`${connector.name} has no action "${id}".`);
+        }
+        for (const scope of action.providerScopes ?? []) {
+            scopes.add(scope);
+        }
+    }
+    return [...scopes];
+}
+const view = (row) => ({
+    id: row.id,
+    space: row.projectId,
+    connector: row.connector,
+    label: row.label,
+    actions: row.actions,
+    createdAt: row.createdAt.toISOString(),
+});
+/** A state the callback can tell is a plugin's: the tenant to finish it in, or null. */
+export function pluginStateTenant(rawState) {
+    const state = unseal(rawState);
+    return state && typeof state.plugin === "string" ? state.tenantId : null;
+}
+/**
+ * The provider came back for a plugin's sign-in: keeps the account. A second sign-in to the
+ * same account for the same space replaces the first one's tokens.
+ */
+export async function finishPluginOAuth(answer, rawState) {
+    const state = unseal(rawState);
+    if (!state?.plugin || state.exp < Date.now()) {
+        throw new Error("Die Anmeldung ist abgelaufen. Bitte noch einmal verbinden.");
+    }
+    const connector = oauthConnector(state.connectorId);
+    if (connector.auth.kind !== "oauth2") {
+        throw new Error("not an oauth connector");
+    }
+    const tokens = "ticket" in answer
+        ? await redeemTicket(answer.ticket)
+        : await exchangeAuthorizationCode({
+            code: answer.code,
+            codeVerifier: state.verifier,
+            config: connector.auth.oauth2,
+            redirectUri: redirectUri(),
+            resolveEnv,
+        });
+    const account = (await connector.auth.oauth2
+        .resolveAccount?.(tokens.accessToken, fetch)
+        .catch(() => null)) ?? { label: connector.name };
+    const stored = {
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        expiresAt: tokens.expiresAt?.toISOString() ?? null,
+        scopes: tokens.grantedScopes,
+        ...("ticket" in answer ? { via: "account" } : {}),
+    };
+    const same = await db.query.pluginConnection.findFirst({
+        where: and(eq(schema.pluginConnection.plugin, state.plugin), eq(schema.pluginConnection.projectId, state.projectId), eq(schema.pluginConnection.connector, connector.id), eq(schema.pluginConnection.label, account.label)),
+    });
+    if (same) {
+        await db
+            .update(schema.pluginConnection)
+            .set({ actions: state.actions, data: seal(stored), updatedAt: new Date() })
+            .where(eq(schema.pluginConnection.id, same.id));
+    }
+    else {
+        await db.insert(schema.pluginConnection).values({
+            id: nanoid(14),
+            plugin: state.plugin,
+            projectId: state.projectId,
+            connector: connector.id,
+            label: account.label,
+            actions: state.actions,
+            data: seal(stored),
+        });
+    }
+    return { plugin: state.plugin, projectId: state.projectId };
+}
+/** The tokens of a connection, refreshed when they run out within five minutes. */
+async function freshTokens(row, connector) {
+    let data = unseal(row.data);
+    if (!data) {
+        throw new Error("The connection's keys cannot be read here. Connect the account again.");
+    }
+    const expires = data.expiresAt ? Date.parse(data.expiresAt) : null;
+    if (connector.auth.kind === "oauth2" &&
+        data.refreshToken &&
+        expires !== null &&
+        expires - Date.now() < 5 * 60_000) {
+        const tokens = data.via === "account"
+            ? await refreshThroughAccount(data.refreshToken)
+            : await refreshAccessToken({
+                config: connector.auth.oauth2,
+                refreshToken: data.refreshToken,
+                resolveEnv,
+            });
+        data = {
+            ...(data.via ? { via: data.via } : {}),
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken ?? data.refreshToken,
+            expiresAt: tokens.expiresAt?.toISOString() ?? null,
+            scopes: tokens.grantedScopes.length ? tokens.grantedScopes : data.scopes,
+        };
+        await db
+            .update(schema.pluginConnection)
+            .set({ data: seal(data), updatedAt: new Date() })
+            .where(eq(schema.pluginConnection.id, row.id));
+    }
+    return data;
+}
+function contextOf(row, connector, data) {
+    const ctx = {
+        accessToken: data.accessToken,
+        fetchImpl: connectorFetch,
+        log: () => undefined,
+        connection: {
+            id: row.id,
+            connector_id: connector.id,
+            auth_kind: connector.auth.kind,
+            autonomous_mode: "read_only",
+            connected_by: row.createdBy,
+            created_at: row.createdAt.toISOString(),
+            display_name: row.label,
+            error_message: null,
+            external_account: row.label,
+            granted_scopes: data.scopes,
+            owner_user_id: null,
+            space_id: row.projectId,
+            status: "active",
+            tenant_id: currentTenant(),
+        },
+    };
+    return ctx;
+}
+/** `server.connections` of one plugin; every call runs inside the current tenant. */
+export function pluginConnections(plugin) {
+    const own = (id) => db.query.pluginConnection.findFirst({
+        where: and(eq(schema.pluginConnection.id, id), eq(schema.pluginConnection.plugin, plugin)),
+    });
+    return {
+        async available(ids) {
+            const out = [];
+            for (const id of ids) {
+                const connector = builtinConnector(id);
+                if (connector?.auth.kind === "oauth2" && (await usable(connector))) {
+                    out.push({ id, name: connector.name });
+                }
+            }
+            return out;
+        },
+        async start({ space, connector: connectorId, actions }) {
+            const connector = oauthConnector(connectorId);
+            if (connector.auth.kind !== "oauth2") {
+                throw new Error("not an oauth connector");
+            }
+            const project = await db.query.project.findFirst({
+                where: eq(schema.project.id, space),
+                columns: { id: true },
+            });
+            if (!project) {
+                throw new Error(`There is no space "${space}".`);
+            }
+            const scopes = scopesOf(connector, actions);
+            const base = {
+                plugin,
+                tenantId: currentTenant(),
+                projectId: space,
+                connectorId,
+                actions: [...new Set(actions)],
+                exp: Date.now() + 15 * 60_000,
+            };
+            if (await viaAccount(connector)) {
+                // The Manage-App keeps the PKCE verifier; ours stays empty.
+                try {
+                    const url = await startThroughAccount(scopes, seal({ ...base, verifier: "" }), redirectUri());
+                    return { url };
+                }
+                catch (err) {
+                    throw err instanceof AccountConnectError
+                        ? Object.assign(new Error(err.message), { status: 409, code: "account" })
+                        : err;
+                }
+            }
+            await connector.auth.oauth2.registerClient?.();
+            const pkce = createOAuth2Pkce();
+            const url = await buildAuthorizationUrl({
+                connector,
+                pkce,
+                redirectUri: redirectUri(),
+                scopes,
+                state: seal({ ...base, verifier: pkce.codeVerifier }),
+                resolveEnv,
+            });
+            return { url };
+        },
+        async list(space) {
+            const rows = await db.query.pluginConnection.findMany({
+                where: and(eq(schema.pluginConnection.plugin, plugin), eq(schema.pluginConnection.projectId, space)),
+                orderBy: [desc(schema.pluginConnection.createdAt)],
+            });
+            return rows.map(view);
+        },
+        async get(id) {
+            const row = await own(id);
+            return row ? view(row) : null;
+        },
+        async call(id, actionId, input) {
+            const row = await own(id);
+            if (!row) {
+                throw new Error(`There is no connection "${id}".`);
+            }
+            if (!row.actions.includes(actionId)) {
+                throw new Error(`The connection was not made for "${actionId}". Connect it again.`);
+            }
+            const connector = oauthConnector(row.connector);
+            const action = connector.actions.find((a) => a.id === actionId);
+            if (!action) {
+                throw new Error(`${connector.name} has no action "${actionId}".`);
+            }
+            const data = await freshTokens(row, connector);
+            return (await action.handler(action.inputSchema.parse(input), contextOf(row, connector, data)));
+        },
+        async remove(id) {
+            await db
+                .delete(schema.pluginConnection)
+                .where(and(eq(schema.pluginConnection.id, id), eq(schema.pluginConnection.plugin, plugin)));
+        },
+    };
+}

package/apps/runtime/dist/connectors/via-account.js

@@ -0,0 +1,63 @@
+import { accountToken } from "../auth/account.js";
+import { env } from "../env.js";
+/*
+ * Google accounts on a local install without an OAuth client of its own: the Manage-App of the
+ * linked account runs the consent at Google with its client and hands the tokens over, and
+ * refreshes them later (docs/manage-contract.md, "Google accounts through the Manage-App").
+ */
+const base = () => `${env.local.accountUrl}/v1/connect`;
+/** Something the person can mend or retry; the message is for them. */
+export class AccountConnectError extends Error {
+}
+let offered = null;
+/** Whether the Manage-App connects Google accounts; asked at most every ten minutes. */
+export async function googleThroughAccount() {
+    if (offered && Date.now() - offered.at < (offered.google ? 600_000 : 60_000)) {
+        return offered.google;
+    }
+    const google = await fetch(base(), { signal: AbortSignal.timeout(5000) })
+        .then(async (res) => res.ok ? (await res.json()).google === true : false)
+        .catch(() => false);
+    offered = { at: Date.now(), google };
+    return google;
+}
+async function call(path, body) {
+    const token = await accountToken();
+    if (!token) {
+        throw new AccountConnectError("Verbinde zuerst dein engenty-Konto (Einstellungen → Konto), dann lässt sich Google hier verbinden.");
+    }
+    const res = await fetch(`${base()}${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(20_000),
+    }).catch(() => null);
+    if (!res) {
+        throw new AccountConnectError("Dein engenty-Konto ist gerade nicht erreichbar. Bitte später noch einmal.");
+    }
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new AccountConnectError(data.code === "invalid_grant"
+            ? "Google nimmt diese Verbindung nicht mehr an. Bitte das Konto neu verbinden."
+            : data.code === "not_configured"
+                ? "Google lässt sich über dein engenty-Konto gerade nicht verbinden."
+                : `Verbinden über dein engenty-Konto hat nicht geklappt (${data.code ?? res.status}).`);
+    }
+    return data;
+}
+const tokensOf = (t) => ({
+    accessToken: t.access_token,
+    refreshToken: t.refresh_token ?? null,
+    expiresAt: t.expires_in ? new Date(Date.now() + t.expires_in * 1000) : null,
+    grantedScopes: (t.scope ?? "").split(/\s+/).filter(Boolean),
+});
+/** Google's consent page for these scopes; Google comes back to `returnUrl` with a ticket. */
+export async function startThroughAccount(scopes, state, returnUrl) {
+    return (await call("/google/start", { scopes, state, returnUrl })).url;
+}
+export async function redeemTicket(ticket) {
+    return tokensOf(await call("/google/redeem", { ticket }));
+}
+export async function refreshThroughAccount(refreshToken) {
+    return tokensOf(await call("/google/refresh", { refreshToken }));
+}