wizards 0.2.7 → 0.2.9

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

@@ -58,11 +58,20 @@ export interface PluginRoute {
      */
     handler(request: PluginRequest): unknown | Promise<unknown>;
 }
+/** A space: what all its wizards share. The runtime's own tables call it a project. */
+export interface PluginSpace {
+    id: string;
+    /** What the studio's switcher calls it. */
+    name: string;
+}
 /** What a tool knows about the step that calls it. */
 export interface PluginStepContext {
     runId: string;
     stepId: string;
     tenantId: string;
+    /** The space of the step's wizard. */
+    space: PluginSpace;
+    /** The same as `space`, by its older name. */
     project: {
         id: string;
         name: string;
@@ -102,10 +111,33 @@ export interface PluginRunEvent {
     /** What the person answered, by field id. */
     values: Record<string, unknown>;
 }
+/** A space was made, changed (title, about, colours, facts, systems) or deleted. */
+export interface PluginSpaceEvent {
+    space: {
+        id: string;
+    };
+}
+/** A file of a space: read and ready (a document is in the index then), or removed. */
+export interface PluginSpaceFileEvent {
+    space: {
+        id: string;
+    };
+    file: {
+        id: string;
+        name: string;
+        kind: "logo" | "asset" | "document";
+        mime: string;
+    };
+}
 export interface PluginEvents {
     "run.done": PluginRunEvent;
     "run.failed": PluginRunEvent;
     "run.cancelled": PluginRunEvent;
+    "space.created": PluginSpaceEvent;
+    "space.updated": PluginSpaceEvent;
+    "space.deleted": PluginSpaceEvent;
+    "space.file.ready": PluginSpaceFileEvent;
+    "space.file.removed": PluginSpaceFileEvent;
 }
 /** The tenant's database. A plugin reads and writes its own tables with it. */
 export type PluginDb = LibSQLDatabase<Record<string, never>>;
@@ -126,9 +158,160 @@ export interface PluginGenerateResult<T = undefined> {
     /** Set when the request had a `schema`. */
     object: T;
 }
+/** What a plugin adds to every agent step of a space's wizards. */
+export interface PluginSpaceContext {
+    /**
+     * A block of the step's instructions, after what the space says about itself and its
+     * documents: what the plugin holds for the space, and which of its tools read it. Empty or
+     * null: the step gets neither the block nor the tools.
+     */
+    block(space: PluginSpace): string | null | Promise<string | null>;
+    /** Tools the step gets with the block, named `<plugin>_<name>` for the model. */
+    tools?: PluginTool[];
+}
+/** A text a plugin puts into a space's search index, beside the space's documents. */
+export interface PluginIndexEntry {
+    /** The space's id. */
+    space: string;
+    /** The plugin's own name for it: putting the same key again replaces what it had. */
+    key: string;
+    /** What a hit is called: a page's title, a question. */
+    title: string;
+    /** Markdown, cut into passages like a document's text. */
+    text: string;
+    /** Where the studio shows it, an address of the studio: `/space#faq`. */
+    link?: string;
+}
+export interface PluginIndex {
+    /** Puts the entry in; `project_search` finds it from then on. */
+    put(entry: PluginIndexEntry): Promise<void>;
+    /** Takes one key out, or without a key every entry of the plugin in the space. */
+    remove(space: string, key?: string): Promise<void>;
+}
+/** What a tool of the space assistant knows about the turn that calls it. */
+export interface PluginAssistantContext {
+    tenantId: string;
+    space: PluginSpace;
+    /** The person talking to the assistant. */
+    userId: string;
+    /** Aborted when the person leaves or stops the turn. */
+    signal: AbortSignal;
+    /** Tells the person what the assistant is doing right now: "Liest die Sitemap …". */
+    emit(message: string): void;
+    /** Say so when the tool changed what the space page shows: the page draws it again. */
+    changed(): void;
+}
+/** A tool of the space assistant: the chat on the space page that fills the space in. */
+export interface PluginAssistantTool<S extends z.ZodType = z.ZodType> {
+    /** Lower case, digits and `_`. The model sees it as `<plugin>_<name>`. */
+    name: string;
+    /** For the model: what the tool does and when to use it. */
+    description: string;
+    inputSchema: S;
+    /**
+     * The result also goes to the chat, where the card the studio half registered for this tool
+     * (`registerAssistantCard`) draws it. It is sent as it is: keep such a result small.
+     */
+    card?: boolean;
+    execute(input: z.infer<S>, ctx: PluginAssistantContext): unknown | Promise<unknown>;
+}
+/** A page of the web, as `web.read` gives it. */
+export interface PluginWebPage {
+    /** Where it ended up, after redirects. */
+    url: string;
+    status: number;
+    /** As the server sent them, for asking later whether the page changed. */
+    etag: string | null;
+    lastModified: string | null;
+    title: string;
+    description: string;
+    /** The page's text as Markdown. */
+    text: string;
+    /** Every link of the page, absolute, each once. */
+    links: {
+        url: string;
+        text: string;
+    }[];
+}
+export interface PluginWeb {
+    /**
+     * `fetch`, behind the guard of the runtime's own requests: addresses of this machine and of
+     * the local network are refused, after a redirect too.
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * A page read the way the space assistant reads one: guarded as `fetch`, and drawn in a
+     * browser when it has hardly any text without its scripts.
+     */
+    read(url: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<PluginWebPage>;
+}
+export interface PluginDocuments {
+    /**
+     * A file as Markdown: PDF and Word by their text, scans and photos by a vision model (paid
+     * like every model call), spreadsheets as tables. Kept by content: the same bytes are read once.
+     */
+    parse(file: {
+        data: Uint8Array;
+        name: string;
+        mime: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        markdown: string;
+        pages: number | null;
+    }>;
+}
+/** One turn of a job `every` runs. */
+export interface PluginTick {
+    tenantId: string;
+    /** When it ran for this tenant before; null the first time. */
+    lastRun: Date | null;
+    /** Aborted when the plugin unloads. */
+    signal: AbortSignal;
+}
+/** What a public route's handler gets. Nobody is signed in. */
+export interface PluginPublicRequest {
+    request: Request;
+    /** The address below the plugin's public one. */
+    path: string;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    /** The tenant whose address was called; the handler runs inside it. */
+    tenantId: string;
+    json<T = unknown>(): Promise<T>;
+}
+/**
+ * A route anyone may call, below the address `publicUrl` gives: a CMS that says a page
+ * changed, a service's webhook. Check a secret of your own in it, a token or a signature.
+ */
+export interface PluginPublicRoute {
+    method: PluginHttpMethod;
+    path: string;
+    handler(request: PluginPublicRequest): unknown | Promise<unknown>;
+}
 export interface PluginServerApi {
     registerHttpRoute(route: PluginRoute): void;
     registerTool<S extends z.ZodType>(tool: PluginTool<S>): void;
+    /** A block and tools for every agent step of a space's wizards. */
+    registerSpaceContext(context: PluginSpaceContext): void;
+    /** A tool of the space assistant. */
+    registerAssistantTool<S extends z.ZodType>(tool: PluginAssistantTool<S>): 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>;
+    /**
+     * Runs `handler` for every tenant that has the plugin, at most once per `everyMs` (a minute
+     * at least), inside that tenant. When it ran is kept: a restart does not start the count again,
+     * and a runtime that was off runs it once when it starts, not once per turn it missed. One turn
+     * per tenant at a time; a turn that throws counts as run.
+     */
+    every(name: string, everyMs: number, handler: (tick: PluginTick) => void | Promise<void>): void;
+    /** The space's search index, which `project_search` asks. */
+    index: PluginIndex;
+    web: PluginWeb;
+    documents: PluginDocuments;
     /**
      * A folder of `.sql` files with the plugin's own tables. Every tenant database gets each file
      * once, in the order of the file names. Nothing is taken back when the plugin unloads.

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

@@ -1,9 +1,10 @@
 import type { ComponentType } from "react";
 /**
  * What the studio hands a plugin's studio half: the built `client.js` the studio loads after
- * sign-in. Its default export registers pages, entries of the top bar and sections of the
- * settings. React, the router and the studio's own components come from the studio
- * (docs/content/dev/plugins), so the page a plugin draws is part of the same app.
+ * sign-in. Its default export registers pages, entries of the top bar, sections of the settings
+ * and of the space page, and cards of the space assistant's chat. React, the router and the
+ * studio's own components come from the studio (docs/content/dev/plugins), so the page a plugin
+ * draws is part of the same app.
  */
 export type StudioLang = "de" | "en";
 /** A plugin's words. `de` is the source: a key missing in `en` shows the German. */
@@ -34,6 +35,43 @@ export interface StudioSettingsSection {
     /** The user menu links to it directly. */
     menu?: boolean;
 }
+/**
+ * A section of the space page, below the space's own sections. The studio draws its heading and
+ * hint above it, and its entry in the page's menu under the plugin's name; the component draws
+ * the rest, usually a `Card`.
+ */
+export interface StudioSpaceSection {
+    /** Its anchor on the page: `/space#<id>`. */
+    id: string;
+    label: () => string;
+    /** One line under the heading: what the section is for. */
+    hint?: () => string;
+    component: ComponentType;
+}
+/** What a card in the assistant's chat is handed. */
+export interface StudioAssistantCardProps<T = unknown> {
+    /** What the assistant tool returned. */
+    data: T;
+    /** Sends a message to the assistant, as if the person typed it: "Übernehmen". */
+    send(message: string): void;
+}
+/**
+ * Draws the result of a tool of the space assistant inside its chat: a tool the server half
+ * registered with `card: true`.
+ */
+export interface StudioAssistantCard {
+    /** The tool's name, as the server half registered it. */
+    tool: string;
+    component: ComponentType<StudioAssistantCardProps<any>>;
+}
+/** The space the studio shows: what all its wizards share. */
+export interface StudioSpace {
+    id: string;
+    /** What the switcher calls it. */
+    name: string;
+    /** Synced from a local install, or on a runtime where nothing is built: shown, not changed. */
+    readOnly: boolean;
+}
 export interface StudioMe {
     user: {
         id: string;
@@ -56,6 +94,13 @@ export interface StudioPluginContext {
     registerPage(page: StudioPage): void;
     registerNav(entry: StudioNavEntry): void;
     registerSettingsSection(section: StudioSettingsSection): void;
+    registerSpaceSection(section: StudioSpaceSection): void;
+    registerAssistantCard(card: StudioAssistantCard): void;
+    /**
+     * A hook: the space the studio shows, `null` while it has none. A component that calls it draws
+     * again when the person picks another space.
+     */
+    useSpace(): StudioSpace | null;
     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/projects.d.ts

@@ -65,8 +65,14 @@ export declare const PROJECT_LIMITS: {
 export declare function projectFileLimit(kind: ProjectFileKind, mime: string): number;
 /** One passage the document index found for a question. */
 export interface ProjectSearchHit {
-    fileId: string;
+    /** The document the passage is of; null for a plugin's text. */
+    fileId: string | null;
+    /** The plugin whose text it is; null for a document. */
+    plugin: string | null;
+    /** The document's name, or the title of the plugin's text. */
     name: string;
+    /** Where the studio shows a plugin's text. */
+    link: string | null;
     /** The passage's place in its document, from 0. */
     index: number;
     text: string;

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

@@ -0,0 +1,75 @@
+import type { ModelClass, TextClass } from "./definition.js";
+/**
+ * What a wizard asks models for, as a person thinks of it. Each stands for model classes; the
+ * names are the marketplace's capabilities.
+ */
+export declare const MODEL_CAPABILITIES: readonly ["text", "image", "video", "speech", "listening"];
+export type ModelCapability = (typeof MODEL_CAPABILITIES)[number];
+export declare const CAPABILITY_CLASSES: Record<ModelCapability, readonly ModelClass[]>;
+export declare function capabilityOf(cls: ModelClass): ModelCapability;
+/**
+ * A binding that sends a class to the credits of the account (or of the team in the cloud),
+ * whatever keys are there; engenty picks the model. `credits:<model>` names the model, as the
+ * gateway lists it (`fal:fal-ai/flux/schnell`, `elevenlabs:eleven_multilingual_v2`,
+ * `google/veo-3.1-fast-generate-001`).
+ */
+export declare const CREDITS = "credits";
+/** A binding to the credits: the class's model (`credits`) or a model named (`credits:<id>`). */
+export declare function isCreditsRef(ref: string | undefined): boolean;
+/** The model a credits binding names; null where engenty picks it. */
+export declare function creditsModelOf(ref: string | undefined): string | null;
+export declare function creditsRef(model: string | null): string;
+/** A media model the credits pay for, as the model-gateway lists it (`/v1/models`, `models`). */
+export interface CreditModel {
+    id: string;
+    name: string;
+    /** Who serves it: `ai-gateway`, `fal`, `elevenlabs`. */
+    source: string;
+    /** Who made it: `google`, `bfl`, `fal`, `elevenlabs` … */
+    provider: string;
+    kind: "image" | "video" | "speech" | "transcription";
+    creditsPerImage?: number;
+    creditsPerSecond?: number;
+    creditsPer1kCharacters?: number;
+    creditsPerMinute?: number;
+}
+/** The capability a credit model serves. */
+export declare function capabilityOfKind(kind: CreditModel["kind"]): ModelCapability;
+/** The providers whose API key a person can bring. */
+export declare const PROVIDER_IDS: readonly ["openai", "anthropic", "google", "fal", "elevenlabs", "replicate", "gateway"];
+export type ProviderId = (typeof PROVIDER_IDS)[number];
+interface Labels {
+    de: string;
+    en: string;
+}
+export interface ModelOption {
+    /** The binding: `<provider>:<the provider's model id>`. */
+    ref: string;
+    /** The model's own name; not translated. */
+    label: string;
+    note?: Labels;
+}
+export interface ProviderInfo {
+    id: ProviderId;
+    name: string;
+    /** One line on what it is, for someone who never heard of it. */
+    about: Labels;
+    /** Where a person makes a key. */
+    keyUrl: string;
+    /** How a key looks, for the input's placeholder. */
+    keyPlaceholder: string;
+    /** The models offered per capability, the first one is taken when the provider is picked. */
+    models: Partial<Record<ModelCapability, ModelOption[]>>;
+    /** For text: the model of each class when this provider thinks. */
+    text?: Record<TextClass, string>;
+}
+export declare const PROVIDERS: readonly ProviderInfo[];
+export declare function providerInfo(id: string): ProviderInfo | null;
+/**
+ * The provider a binding goes to: `fal:…` names it, a binding without one (`google/veo-…`) goes
+ * through the AI Gateway. Null for an installed client (`codex/…`), a local model and credits.
+ */
+export declare function providerOfRef(ref: string): ProviderId | null;
+/** The name of a bound model as a person reads it: the offered label, else the provider's id. */
+export declare function modelLabel(ref: string): string;
+export {};