wizards 0.3.7 → 0.4.0

package/README.md

@@ -44,37 +44,50 @@ A wizard in use: it asks on one page, then on the next, and ends with the result
   <img src="docs/assets/wizard.png" alt="A wizard in use on a phone, three pictures: which week and how many children, what is on the table, and the finished weekly plan with PDF, PNG and sharing">
 </p>
 
-## Install
+## Get started
 
-On macOS or Linux, in a terminal:
+Create an account at [engenty.ai](https://engenty.ai): it is in a closed beta, so "Get started"
+takes your e-mail for an invitation, or your invitation code. Signed in, the studio asks who
+your team is, reads your website into your space, takes first documents, and you build your
+first wizard in the browser. Links run day and night on the team's credits.
+
+## Install it on your computer
+
+The same account on your own machine: it thinks with your Claude, ChatGPT, Gemini or Cursor
+subscription, reads your local files and browses for you, and what you publish keeps running in
+the cloud behind the same links. On macOS or Linux, in a terminal:
 
 ```bash
 curl -fsSL https://engenty.ai/install.sh | bash
 ```
 
-It needs nothing but `curl` and asks for no password. It brings its own Node.js (a Node you
-already have is left alone), installs engenty wizards into `~/.engenty/wizards` and then walks
-you through the rest:
+It needs nothing but `curl` and `tar` and asks for no password. It brings its own Node.js (a
+Node you already have is left alone), installs engenty wizards into `~/.engenty/wizards` and
+then walks you through the rest:
 
+- **Your engenty account.** A code and the browser for the sign-in; your team's space comes
+  down to this computer. "Later" skips it, `wizards account sign-in` does it any time.
+  `--local` leaves the account out: nothing leaves the computer, links answer on it only
+  ([local only](https://engenty.ai/docs/user/local-only)).
 - **Something to think with.** It looks for Codex, Claude Code, Gemini CLI and Cursor Agent and
   offers to install one if there is none — first the one whose app (Claude, ChatGPT, Cursor) is
   on your Mac, as its subscription is most likely yours already. The first page of the studio
-  installs them too. Or use an API key or [Ollama](https://ollama.com).
+  installs them too. Or use your account's credits, an API key or [Ollama](https://ollama.com).
 - **Google Chrome and ffmpeg** (optional): Chrome for PDF and PNG exports and for steps that use
   a browser, ffmpeg for MP4 videos of animated widgets.
 - **Start at login** (optional): engenty wizards starts in the background when you log in (a
   LaunchAgent on a Mac, a systemd user service on Linux). Links and AI clients then always
   reach it. `wizards autostart on` or `off` switches it later.
 
-Then it starts and the studio opens in your browser. Later, start it with:
+It starts nothing. Afterwards:
 
 ```bash
-wizards
+wizards start
 ```
 
-It runs while that terminal is open; Ctrl-C stops it. `wizards status` says what is
-installed and what runs, `wizards setup` runs the guided setup again, and
-`wizards --help` lists the rest.
+starts it and opens the studio; it runs while that terminal is open, Ctrl-C stops it.
+`wizards` opens a menu with all of it, `wizards status` says what is installed and what runs,
+`wizards setup` runs the guided setup again, and `wizards --help` lists the rest.
 
 **Install it as an app.** In Chrome or Edge the studio installs as an app: its own window, its
 own icon in the Dock or taskbar. The studio offers it in a banner at the top; or click the install
@@ -99,9 +112,10 @@ machine; a checkout brings its own sandbox, the installed version has none yet.
 
 ## First start
 
-The setup asks what engenty should think with. Pick an AI client that is installed on your
-computer — engenty uses your existing subscription and signs it in for you in a terminal right
-on the page — or enter your own keys. It stays until a test call works, then the studio opens.
+The setup shows your account at the top and asks what engenty should think with. Pick an AI
+client that is installed on your computer — engenty uses your existing subscription and signs
+it in for you in a terminal right on the page — your account's credits, or enter your own keys.
+It stays until a test call works, then the studio opens.
 
 Change it later under Settings.
 

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

@@ -6,7 +6,7 @@ import { nanoid } from "nanoid";
 import { z } from "zod";
 import { knowsTools } from "../assistant/knows.js";
 import { PRIMER } from "../assistant/primer.js";
-import { attachTools, costOf, gatewayTools, textModel } from "../models.js";
+import { attachTools, contextWindowOf, costOf, gatewayTools, textModel, usageOf, } from "../models.js";
 import { ServiceError } from "../services/errors.js";
 import { knowledgeCounts } from "../services/knowledge.js";
 import { addProjectFileFromUrl, projectFileContent, projectFiles, updateProjectFile, } from "../services/project-files.js";
@@ -16,8 +16,12 @@ import { categoryRows } from "../services/space-categories.js";
 import { currentTenant } from "../tenants/tenant.js";
 import { assistantPageOf, assistantToolsOf } from "../tools/plugin.js";
 import { readWebsite } from "./website.js";
+/** How a message written meanwhile reaches the model. */
+export function signalText(taken) {
+    return `The person wrote this while you were working. What they asked before still stands unless this changes it:\n\n${taken.map((s) => s.message).join("\n\n")}`;
+}
 const MAX_STEPS = 24;
-const SYSTEM = `You are the assistant of the engenty wizards studio. You stand on every page of the studio except the wizard editor, which has a chat of its own: the space's pages, the settings, the plugins' pages. You help the person who works here understand the app, set it up and find their way.
+const SYSTEM = `You are Goose, the assistant of the engenty wizards studio. You stand on every page of the studio except the wizard editor, which has a chat of its own: the space's pages, the settings, the plugins' pages. You help the person who works here understand the app, set it up and find their way.
 
 You talk to the person. Answer in their language, briefly and warmly: a few sentences, a short list where it helps. Never mention JSON, ids, keys or tool names. Call it a space (German „Space“), never a project: the tools say project, the app says space.
 
@@ -641,12 +645,29 @@ function partOf(route) {
     const m = route.match(/^\/space\/(info|knowledge|data|results)/);
     return m ? m[1] : route === "/space" ? "info" : null;
 }
+/** How large each tool is in the prompt: its description and its schema, in characters. */
+function toolSizes(tools) {
+    return Object.entries(tools)
+        .map(([name, tool]) => {
+        let schema = "";
+        try {
+            schema = JSON.stringify(tool?.inputSchema ? z.toJSONSchema(tool.inputSchema, { unrepresentable: "any" }) : {});
+        }
+        catch {
+            // A provider's own tool (web search) has no schema of ours.
+        }
+        return { name, chars: String(tool?.description ?? "").length + schema.length };
+    })
+        .sort((a, b) => b.chars - a.chars);
+}
 /** One turn of the studio assistant. */
 export async function runStudioAssistant(input) {
-    let changed = false;
+    // How often the space or a plugin's data changed: a part of the answer changed something when
+    // this grew during it.
+    let changes = 0;
     const resolved = await textModel("high");
     const wrote = () => {
-        changed = true;
+        changes++;
         input.onChanged?.();
     };
     const cards = [];
@@ -746,6 +767,31 @@ export async function runStudioAssistant(input) {
     ]
         .filter(Boolean)
         .join("\n\n");
+    input.onPrompt?.({
+        model: resolved.ref,
+        system: SYSTEM,
+        context,
+        history: history.messages.map((m) => ({ role: m.role, chars: m.content.length })),
+        tools: toolSizes(tools),
+    });
+    let reply = "";
+    // Where the part the result holds begins: a message written meanwhile cuts the answer there.
+    const from = { reply: 0, cards: 0, toolCalls: 0, changes: 0 };
+    const cut = () => {
+        const part = {
+            reply: reply.slice(from.reply).trim(),
+            changed: changes > from.changes,
+            cards: cards.slice(from.cards),
+            toolCalls: toolCalls.slice(from.toolCalls),
+        };
+        Object.assign(from, {
+            reply: reply.length,
+            cards: cards.length,
+            toolCalls: toolCalls.length,
+            changes,
+        });
+        return part;
+    };
     const stream = await agent.stream([
         ...history.messages.map((m) => m.role === "user"
             ? { role: "user", content: m.content }
@@ -755,11 +801,37 @@ export async function runStudioAssistant(input) {
         maxSteps: MAX_STEPS,
         abortSignal: input.signal,
         modelSettings: { maxOutputTokens: 8000 },
+        // What the person wrote meanwhile comes before the next step, after the tools' results.
+        prepareStep: async ({ stepNumber, messageList }) => {
+            const taken = stepNumber > 0 ? (input.takeSignals?.() ?? []) : [];
+            if (!taken.length) {
+                return;
+            }
+            await input.onSignal?.(taken, cut());
+            messageList.add({ role: "user", content: signalText(taken) }, "input");
+            return { messageList };
+        },
     });
-    let reply = "";
+    const window = contextWindowOf(resolved.ref);
+    // A step lasts from the end of the one before – its tools' work included – to its own end.
+    let stepStarted = Date.now();
     for await (const chunk of stream.fullStream) {
         const payload = chunk.payload ?? chunk;
-        if (chunk.type === "text-delta") {
+        if (chunk.type === "step-finish" && input.onStep) {
+            const usage = usageOf(payload.output?.usage);
+            input.onStep({
+                model: resolved.ref,
+                inputTokens: usage.inputTokens ?? 0,
+                outputTokens: usage.outputTokens ?? 0,
+                cachedInputTokens: usage.cachedInputTokens ?? 0,
+                ms: Date.now() - stepStarted,
+                costUsd: costOf(resolved, payload.output?.usage),
+                tools: (payload.output?.toolCalls ?? []).map((c) => c.payload?.toolName ?? c.toolName ?? ""),
+                window,
+            });
+            stepStarted = Date.now();
+        }
+        else if (chunk.type === "text-delta") {
             const text = payload.text ?? payload.delta ?? "";
             reply += text;
             input.onText?.(text);
@@ -780,5 +852,5 @@ export async function runStudioAssistant(input) {
         }
     }
     const usage = (await stream.totalUsage) ?? (await stream.usage);
-    return { reply: reply.trim(), changed, cards, toolCalls, costUsd: costOf(resolved, usage) };
+    return { ...cut(), costUsd: costOf(resolved, usage) };
 }

package/apps/runtime/dist/assistant/runs.js

@@ -0,0 +1,24 @@
+const running = new Map();
+export function startRun(runId, userId) {
+    running.set(runId, { userId, inbox: [] });
+}
+export function endRun(runId) {
+    running.delete(runId);
+}
+/** Puts a message into the person's running turn; false when that turn is over. */
+export function signalRun(userId, runId, signal) {
+    const run = running.get(runId);
+    if (!run || run.userId !== userId) {
+        return false;
+    }
+    run.inbox.push(signal);
+    return true;
+}
+/** The messages that came in since the turn last looked, oldest first. */
+export function takeSignals(runId) {
+    const run = running.get(runId);
+    if (!run?.inbox.length) {
+        return [];
+    }
+    return run.inbox.splice(0);
+}

package/apps/runtime/dist/auth/account.js

@@ -9,9 +9,11 @@ import { deleteSetting, readSetting, writeSetting } from "../settings.js";
  * browser at the Manage-App, the code comes back to this server on the loopback interface. The
  * account is optional; it unlocks credits through the gateway and publishing to the cloud.
  */
-const CLIENT = { id: "wizards-desktop" };
+export const CLIENT = { id: "wizards-desktop" };
 const REFRESH = "account.refresh";
-const SCOPE = "openid profile email offline_access wizards:read wizards:write wizards:publish";
+export const SCOPE = "openid profile email offline_access wizards:read wizards:write wizards:publish";
+/** The team of the linked account as the Manage-App last named it, for lines that must not wait on it. */
+const TEAM = "account.team";
 /** Loopback redirect on the port this server listens on (RFC 8252). */
 function redirectUri() {
     return `http://127.0.0.1:${env.port}/api/auth/callback`;
@@ -48,7 +50,11 @@ export async function startLink(options = {}) {
     return signUp.toString();
 }
 let cached = null;
-async function keep(tokens) {
+/**
+ * Keeps what the token endpoint handed out: the refresh token in the vault, the account in the
+ * settings. The browser flow (finishLink) and the device flow (device.ts) end here alike.
+ */
+export async function keep(tokens) {
     const claims = unverifiedClaims(tokens.access_token);
     if (!claims) {
         throw new Error("The account's token names no tenant.");
@@ -128,6 +134,25 @@ export async function unlink() {
     cached = null;
     await vaultDelete(REFRESH);
     await deleteSetting("account");
+    await deleteSetting(TEAM);
+}
+/** The team as the Manage-App last named it: `wizards status` and the menu show it without a round trip. */
+export function knownTeam() {
+    return readSetting(TEAM);
+}
+let rememberedTeam = null;
+async function rememberTeam(tenant) {
+    const same = `${tenant.id}\n${tenant.name}\n${tenant.balanceCredits}`;
+    if (same === rememberedTeam) {
+        return;
+    }
+    rememberedTeam = same;
+    await writeSetting(TEAM, {
+        tenantId: tenant.id,
+        name: tenant.name,
+        balanceCredits: tenant.balanceCredits,
+        at: new Date().toISOString(),
+    });
 }
 /** Balance and tenants of the linked account, straight from the Manage-App. */
 export async function accountOverview() {
@@ -139,5 +164,12 @@ export async function accountOverview() {
         headers: { authorization: `Bearer ${token}` },
         signal: AbortSignal.timeout(10_000),
     }).catch(() => null);
-    return res?.ok ? (await res.json()) : null;
+    if (!res?.ok) {
+        return null;
+    }
+    const overview = (await res.json());
+    if (overview?.tenant) {
+        await rememberTeam(overview.tenant).catch(() => undefined);
+    }
+    return overview;
 }

package/apps/runtime/dist/auth/device.js

@@ -0,0 +1,101 @@
+import { env } from "../env.js";
+import { discovery, ManageError, tokenRequest } from "../manage.js";
+import { CLIENT, keep, SCOPE } from "./account.js";
+/**
+ * Signing in from a terminal (RFC 8628): the Manage-App hands out a code, the person types it
+ * on any browser at the account's /device page and allows it, and this process asks the token
+ * endpoint until they did. For `wizards setup` and `wizards account sign-in`; the studio keeps
+ * the browser flow of account.ts. Both end in the same keep(): the refresh token in the vault,
+ * the account in the settings, so the runtime picks it up wherever it runs.
+ *
+ *   POST <account>/api/auth/device/code      client_id, scope, resource → the codes
+ *   POST <token endpoint of the discovery>   grant_type device_code, every `interval` seconds,
+ *                                            until tokens come, or the code expired or was refused
+ */
+const GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+/** Why a sign-in ended without an account; the message is for the person. */
+export class DeviceSignInError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** Asks the Manage-App for a code to sign this install in with. */
+export async function requestDeviceCode() {
+    const base = env.local.accountUrl;
+    // The discovery names the endpoint when the Manage-App advertises it.
+    const d = (await discovery(base).catch(() => null));
+    const res = await fetch(d?.device_authorization_endpoint ?? `${base}/api/auth/device/code`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            client_id: CLIENT.id,
+            scope: SCOPE,
+            resource: env.local.cloudUrl,
+        }),
+        signal: AbortSignal.timeout(15_000),
+    }).catch(() => null);
+    if (!res) {
+        throw new DeviceSignInError("unreachable", `${base} is not reachable right now.`);
+    }
+    const data = (await res.json().catch(() => ({})));
+    if (!(res.ok && data.device_code && data.user_code && data.verification_uri)) {
+        throw new DeviceSignInError("refused", data.error_description ||
+            (data.error
+                ? `The account refused the sign-in (${data.error}).`
+                : `The account did not hand out a code (${res.status}).`));
+    }
+    return {
+        deviceCode: data.device_code,
+        userCode: data.user_code,
+        verificationUri: data.verification_uri,
+        verificationUriComplete: data.verification_uri_complete ?? null,
+        expiresAt: Date.now() + (data.expires_in ?? 1800) * 1000,
+        interval: Math.max(1, data.interval ?? 5),
+    };
+}
+const pause = (ms) => new Promise((done) => setTimeout(done, ms));
+/**
+ * Asks the token endpoint until the person allowed the code in the browser, and keeps the
+ * tokens as the browser flow does. `authorization_pending` asks again after `interval`;
+ * `slow_down` asks five seconds later each time (RFC 8628 §3.5); a network error is tried
+ * again a few times. `expired_token` and `access_denied` end it.
+ */
+export async function waitForDeviceSignIn(code, options = {}) {
+    const wait = options.wait ?? pause;
+    let interval = code.interval;
+    let failures = 0;
+    for (;;) {
+        await wait(interval * 1000);
+        if (Date.now() >= code.expiresAt) {
+            throw new DeviceSignInError("expired", "The code has expired. Start the sign-in again.");
+        }
+        try {
+            const tokens = await tokenRequest({ grant_type: GRANT, device_code: code.deviceCode, resource: env.local.cloudUrl }, CLIENT, env.local.accountUrl);
+            return await keep(tokens);
+        }
+        catch (err) {
+            if (!(err instanceof ManageError)) {
+                if (++failures >= 5) {
+                    throw new DeviceSignInError("unreachable", `${env.local.accountUrl} stopped answering. Start the sign-in again.`);
+                }
+                continue;
+            }
+            failures = 0;
+            switch (err.code) {
+                case "authorization_pending":
+                    continue;
+                case "slow_down":
+                    interval += 5;
+                    continue;
+                case "expired_token":
+                    throw new DeviceSignInError("expired", "The code has expired. Start the sign-in again.");
+                case "access_denied":
+                    throw new DeviceSignInError("denied", "The sign-in was refused in the browser.");
+                default:
+                    throw new DeviceSignInError("refused", `The account refused the sign-in (${err.code}).`);
+            }
+        }
+    }
+}

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

@@ -273,7 +273,7 @@ export const authRoutes = new Hono()
     if (!managed) {
         // The linked account of a runtime that runs alone: the system browser lands here.
         if (!code) {
-            return c.html(closePage("Anmeldung abgebrochen. Du kannst dieses Fenster schließen."), 400);
+            return c.html(closePage("Sign-in cancelled. You can close this window."), 400);
         }
         try {
             await finishLink(code, rawState);
@@ -281,11 +281,11 @@ export const authRoutes = new Hono()
             void firstSync();
             // The Pro modules the account's plan includes.
             void refreshPro();
-            return c.html(closePage("Angemeldet. Du kannst dieses Fenster schließen."));
+            return c.html(closePage("Signed in. You can close this window."));
         }
         catch (err) {
             console.error("[account]", err);
-            return c.html(closePage("Anmeldung hat nicht geklappt. Bitte noch einmal versuchen."), 400);
+            return c.html(closePage("The sign-in did not work. Please try again."), 400);
         }
     }
     const state = unseal(getCookie(c, STATE_COOKIE) ?? "");
@@ -322,7 +322,7 @@ export const authRoutes = new Hono()
                 exp: Date.now() + 2 * 60_000,
             });
             const link = `engenty-wizards://signin?code=${encodeURIComponent(code)}`;
-            return c.html(`${closePage("Angemeldet. Kehre jetzt zu engenty wizards zurück.")}
+            return c.html(`${closePage("Signed in. Go back to engenty wizards now.")}
 <script>location.href = ${JSON.stringify(link)};</script>`);
         }
         setSessionCookie(c, id);