wizards 0.2.25 → 0.2.27

package/node_modules/@engenty-wizards/plugin-sdk/dist/index.d.ts

@@ -77,8 +77,11 @@ export interface PluginStepContext {
         name: string;
     };
     wizard: {
+        id: string;
         title: string;
     };
+    /** "test": a test run from the studio. Keep what it makes apart from what real runs make. */
+    mode: "test" | "live";
     /** Aborted when the run is cancelled. */
     signal: AbortSignal;
     /** Tells the person what the step is doing right now. */
@@ -453,6 +456,82 @@ export interface PluginPublicRoute {
     path: string;
     handler(request: PluginPublicRequest): unknown | Promise<unknown>;
 }
+/** An account a plugin connected for a space: a calendar, a mailbox. */
+export interface PluginConnection {
+    id: string;
+    /** The space it was connected for. */
+    space: string;
+    /** The built-in connector behind it: `google-calendar`, `microsoft-outlook`. */
+    connector: string;
+    /** The account, as the provider names it: an e-mail address. */
+    label: string;
+    /** The actions it was connected for; the provider granted what they need. */
+    actions: string[];
+    createdAt: string;
+}
+/**
+ * Accounts a plugin connects on its own, for a space rather than for a wizard's run: the
+ * runtime's built-in connectors (Google, Microsoft, …), signed in with OAuth. The runtime keeps
+ * the tokens sealed, refreshes them, and on a local install connects Google through the linked
+ * account's Manage-App, as it does for wizards.
+ */
+export interface PluginConnections {
+    /** Of these connector ids, the ones a person can connect on this runtime now, with their names. */
+    available(connectors: string[]): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    /**
+     * The provider's sign-in page. Open it in a window: when the person is done, the window posts
+     * `{ type: "wizards:connected", ok }` to the studio and closes. `actions` are the connector's
+     * actions the plugin will call; only the rights they need are asked for.
+     */
+    start(input: {
+        space: string;
+        connector: string;
+        actions: string[];
+    }): Promise<{
+        url: string;
+    }>;
+    /** What is connected for the space, the newest first. */
+    list(space: string): Promise<PluginConnection[]>;
+    /** One connection by its id, or null. */
+    get(connectionId: string): Promise<PluginConnection | null>;
+    /**
+     * Runs one of the connector's actions with the connection's account. Throws when the action
+     * is not one the connection was made for, or when the provider refuses (the account was
+     * disconnected there: connect again).
+     */
+    call<T = unknown>(connectionId: string, action: string, input: Record<string, unknown>): Promise<T>;
+    /** Forgets the connection and its tokens. */
+    remove(connectionId: string): Promise<void>;
+}
+/**
+ * A wizard a plugin brings as a template: offered beside the marketplace's starters when a
+ * wizard is made, and to the assistant and AI apps as an example to copy.
+ */
+export interface PluginStarter {
+    /** Lower case, digits and `-`; the starter is known as `<plugin id>.<id>`. */
+    id: string;
+    title: string;
+    /** What it makes, in one or two sentences. */
+    description: string;
+    /** The language its texts are in. Default: German. */
+    language?: "de" | "en";
+    /** A complete wizard definition. Checked when it is registered. */
+    definition: unknown;
+    /** Workspace files it needs (widgets, sample data), by path. */
+    files?: Record<string, string | Uint8Array>;
+}
+/**
+ * What the space assistant is told when the admin talks to it from the plugin's own page (the
+ * studio half's `studio.Assistant`): what the page holds now, so it can change it with the
+ * plugin's assistant tools.
+ */
+export interface PluginAssistantPage {
+    /** Text for the assistant: the state of the page, in a few lines. Cut at 8,000 characters. */
+    block(space: PluginSpace): string | null | Promise<string | null>;
+}
 export interface PluginServerApi {
     registerHttpRoute(route: PluginRoute): void;
     registerTool<S extends z.ZodType>(tool: PluginTool<S>): void;
@@ -460,6 +539,8 @@ export interface PluginServerApi {
     registerSpaceContext(context: PluginSpaceContext): void;
     /** A tool of the space assistant. */
     registerAssistantTool<S extends z.ZodType>(tool: PluginAssistantTool<S>): void;
+    /** What the space assistant is told when the admin talks to it from the plugin's own page. */
+    registerAssistantContext(context: PluginAssistantPage): void;
     registerPublicRoute(route: PluginPublicRoute): void;
     /** The full address of a public route for the current tenant: what to hand to whoever calls it. */
     publicUrl(path: string): Promise<string>;
@@ -491,6 +572,10 @@ export interface PluginServerApi {
      * status 503 and the code `no_model`, which a route passes on as it is.
      */
     generate<T = undefined>(request: PluginGenerateRequest<T>): Promise<PluginGenerateResult<T>>;
+    /** Accounts the plugin connects for a space, through the runtime's built-in connectors. */
+    connections: PluginConnections;
+    /** A wizard the plugin brings as a template. */
+    registerStarter(starter: PluginStarter): void;
     /** Something to undo when the plugin unloads or reloads: a timer, a socket. */
     onUnload(dispose: () => void | Promise<void>): void;
 }

package/node_modules/@engenty-wizards/plugin-sdk/dist/studio.d.ts

@@ -80,6 +80,15 @@ export interface StudioSpace {
     /** Synced from a local install, or on a runtime where nothing is built: shown, not changed. */
     readOnly: boolean;
 }
+/** The space assistant on a plugin's page: what it says before the first message. */
+export interface StudioAssistantProps {
+    title?: string;
+    hello?: string;
+    /** The input's placeholder: an example of what to ask. */
+    placeholder?: string;
+    /** The assistant changed something: read the page's data again. */
+    onChanged?: () => void;
+}
 export interface StudioMe {
     user: {
         id: string;
@@ -109,6 +118,20 @@ export interface StudioPluginContext {
      * again when the person picks another space.
      */
     useSpace(): StudioSpace | null;
+    /**
+     * A hook: where the page stands, as the trail after the logo in the top bar ("Termine /
+     * Kalender"), said there instead of a heading of the page's own. Set while the page is shown.
+     */
+    useCrumbs(items: {
+        label: string;
+        to?: string;
+    }[]): void;
+    /**
+     * The space assistant, docked at the lower edge of a page of the plugin, as on the space page.
+     * It talks from the plugin's page: it gets what the server half's `registerAssistantContext`
+     * says and uses the plugin's assistant tools first. Place it once, anywhere in the page.
+     */
+    Assistant: ComponentType<StudioAssistantProps>;
     i18n: {
         /** Takes the plugin's words and gives the function that reads them in the language in effect. */
         register<M extends StudioMessages>(messages: M): (key: keyof M["de"] & string, vars?: Record<string, string | number>) => string;

package/node_modules/@engenty-wizards/shared/dist/decision.d.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+/**
+ * Decisions: typed questions over a state, answered by a decision model (System One: TypeSafe's
+ * Jev and models of its kind) or, where there is none, by a language model asked for the same
+ * answers as structured output. Both ways give the same shapes; only a decision model gives
+ * probabilities that mean something.
+ */
+/** Yes or no: P(yes). */
+export interface NoulQuestion {
+    type: "noul";
+    instructions: string;
+    criteria?: {
+        true: string;
+        false: string;
+    };
+}
+/** One of named options, each with what it covers (null: the name says it). */
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string | null>;
+}
+/** A level on an ordered scale, lowest first. */
+export interface ScoreQuestion {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+}
+export type DecisionQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+export interface NoulAnswer {
+    type: "noul";
+    /** P(yes), 0–1. A language model's answer is 1 or 0. */
+    noul: number;
+}
+export interface ChoiceAnswer {
+    type: "choice";
+    choice: string;
+    /** Per option; only from a decision model. */
+    probabilities?: Record<string, number>;
+    confidence?: number;
+}
+export interface ScoreAnswer {
+    type: "score";
+    /** Index of the level, lowest = 0. */
+    level: number;
+    /** The level's description, as the question lists it. */
+    label: string;
+    /** Per level index; only from a decision model. */
+    probabilities?: Record<string, number>;
+    confidence?: number;
+}
+export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export type DecisionSource = "systemone" | "llm";
+export interface Decision {
+    answers: Record<string, DecisionAnswer>;
+    /** Which way answered; with both, the language model filled what the decision model left open. */
+    source: DecisionSource;
+}
+/**
+ * The answers a System One response gives that fit their questions; a question whose answer is
+ * missing or does not fit is left out, for the language model to answer.
+ */
+export declare function readSystemOne(questions: Record<string, DecisionQuestion>, response: unknown): Record<string, DecisionAnswer>;
+/** The questions as one structured-output object a language model fills. */
+export declare function decisionSchema(questions: Record<string, DecisionQuestion>): z.ZodObject<{
+    [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>;
+/** What a language model filled in, as answers; null when it does not fit. */
+export declare function readObject(questions: Record<string, DecisionQuestion>, object: unknown): Record<string, DecisionAnswer> | null;
+/**
+ * How sure the answer is that it picked rightly, as the margin between the winner and the
+ * runner-up; null where there are no probabilities (a language model's answer).
+ */
+export declare function marginOf(answer: DecisionAnswer): number | null;
+/** The probability of what was answered: P(yes) for a yes/no, P(pick) otherwise; 1 without. */
+export declare function pOf(answer: DecisionAnswer): number;

package/node_modules/@engenty-wizards/shared/dist/decision.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+/** Probabilities sum to one within rounding. */
+const SUM_TOLERANCE = 0.02;
+function unit(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+}
+/**
+ * A distribution over exactly the offered keys that sums to one, with `pick` on top — so a
+ * malformed or cut-off answer never counts. Engenty-pro's validateChoiceAnswer.
+ */
+function validDistribution(probabilities, offered, pick) {
+    if (!probabilities || typeof probabilities !== "object") {
+        return false;
+    }
+    const p = probabilities;
+    const keys = Object.keys(p);
+    if (keys.length !== offered.length || !offered.every((k) => k in p)) {
+        return false;
+    }
+    let sum = 0;
+    let max = 0;
+    for (const k of keys) {
+        if (!unit(p[k])) {
+            return false;
+        }
+        sum += p[k];
+        max = Math.max(max, p[k]);
+    }
+    return Math.abs(sum - 1) < SUM_TOLERANCE && p[pick] >= max - 1e-6;
+}
+/**
+ * The answers a System One response gives that fit their questions; a question whose answer is
+ * missing or does not fit is left out, for the language model to answer.
+ */
+export function readSystemOne(questions, response) {
+    const raw = response?.answers ?? {};
+    const out = {};
+    for (const [name, q] of Object.entries(questions)) {
+        const a = raw[name];
+        if (!a || typeof a !== "object") {
+            continue;
+        }
+        if (q.type === "noul" && a.type === "noul" && unit(a.noul)) {
+            out[name] = { type: "noul", noul: a.noul };
+        }
+        else if (q.type === "choice" && a.type === "choice") {
+            const offered = Object.keys(q.criteria);
+            if (typeof a.choice === "string" &&
+                offered.includes(a.choice) &&
+                validDistribution(a.probabilities, offered, a.choice)) {
+                out[name] = {
+                    type: "choice",
+                    choice: a.choice,
+                    probabilities: a.probabilities,
+                    ...(unit(a.confidence) ? { confidence: a.confidence } : {}),
+                };
+            }
+        }
+        else if (q.type === "score" && a.type === "score") {
+            const offered = q.criteria.map((_, i) => String(i));
+            const probabilities = a.probabilities;
+            const top = probabilities
+                ? Object.entries(probabilities).sort((x, y) => y[1] - x[1])[0]?.[0]
+                : undefined;
+            if (top !== undefined && validDistribution(probabilities, offered, top)) {
+                const level = Number(top);
+                out[name] = {
+                    type: "score",
+                    level,
+                    label: q.criteria[level],
+                    probabilities,
+                    ...(unit(a.confidence) ? { confidence: a.confidence } : {}),
+                };
+            }
+        }
+    }
+    return out;
+}
+/** The questions as one structured-output object a language model fills. */
+export function decisionSchema(questions) {
+    const shape = {};
+    for (const [name, q] of Object.entries(questions)) {
+        if (q.type === "noul") {
+            const hint = q.criteria ? ` (true: ${q.criteria.true}; false: ${q.criteria.false})` : "";
+            shape[name] = z.boolean().describe(`${q.instructions}${hint}`);
+        }
+        else if (q.type === "choice") {
+            const options = Object.keys(q.criteria);
+            const hints = Object.entries(q.criteria)
+                .filter(([, d]) => d)
+                .map(([k, d]) => `${k}: ${d}`)
+                .join("; ");
+            shape[name] = z
+                .enum(options)
+                .describe(hints ? `${q.instructions} (${hints})` : q.instructions);
+        }
+        else {
+            shape[name] = z
+                .enum(q.criteria)
+                .describe(`${q.instructions} (lowest to highest)`);
+        }
+    }
+    return z.object(shape);
+}
+/** What a language model filled in, as answers; null when it does not fit. */
+export function readObject(questions, object) {
+    if (!object || typeof object !== "object") {
+        return null;
+    }
+    const o = object;
+    const out = {};
+    for (const [name, q] of Object.entries(questions)) {
+        const v = o[name];
+        if (q.type === "noul" && typeof v === "boolean") {
+            out[name] = { type: "noul", noul: v ? 1 : 0 };
+        }
+        else if (q.type === "choice" && typeof v === "string" && v in q.criteria) {
+            out[name] = { type: "choice", choice: v };
+        }
+        else if (q.type === "score" && typeof v === "string" && q.criteria.includes(v)) {
+            out[name] = { type: "score", level: q.criteria.indexOf(v), label: v };
+        }
+        else {
+            return null;
+        }
+    }
+    return out;
+}
+/**
+ * How sure the answer is that it picked rightly, as the margin between the winner and the
+ * runner-up; null where there are no probabilities (a language model's answer).
+ */
+export function marginOf(answer) {
+    if (answer.type === "noul") {
+        return null;
+    }
+    const p = Object.values(answer.probabilities ?? {}).sort((a, b) => b - a);
+    return p.length >= 2 ? p[0] - p[1] : null;
+}
+/** The probability of what was answered: P(yes) for a yes/no, P(pick) otherwise; 1 without. */
+export function pOf(answer) {
+    if (answer.type === "noul") {
+        return answer.noul;
+    }
+    const key = answer.type === "choice" ? answer.choice : String(answer.level);
+    return answer.probabilities?.[key] ?? 1;
+}