Reference

interface PluginTool<S extends z.ZodType = z.ZodType> {
  name: string;           // lower case, digits and "_"
  title?: string;         // what the editor calls it
  description: string;    // for the model
  inputSchema: S;
  execute(input: z.infer<S>, step: PluginStepContext): unknown | Promise<unknown>;
}

interface PluginStepContext {
  runId: string;
  stepId: string;
  tenantId: string;
  space: { id: string; name: string };    // the space of the step's wizard
  project: { id: string; name: string };  // the same, by its older name
  wizard: { id: string; title: string };
  mode: "test" | "live";                  // "test": a test run from the studio
  signal: AbortSignal;                    // aborted when the run is cancelled
  emit(message: string): Promise<void>;   // tells the person what the step is doing
}

interface PluginRunner {
  id: string;                          // lower case, digits and "-", at most 24 characters
  label: { de: string; en: string };
  kind: "page" | "channel";            // an address the person opens, or a channel of its own
  capabilities: {
    input: string[];                   // field kinds asked by the runner itself
    output: { shows: string[]; pictures: string[] };
    asks: ("confirm" | "login")[];
    review: ("accept" | "regenerate" | "edit")[];
    waits: boolean;
    handoff: ("screen" | "thread" | "sms" | "push")[];
  };
  page?(request: PluginRunnerRequest): Response | Promise<Response>;
  problem?(): string | PluginRunnerProblem | null | Promise<string | PluginRunnerProblem | null>;  // why not usable in this tenant right now
  address?(wizard: { id: string; title: string; token: string }):
    | PluginRunnerAddress | null | Promise<PluginRunnerAddress | null>;  // where a person reaches the wizard
}

interface PluginRunnerProblem {
  text: string;                           // in the owner's words
  kind?: "setup" | "waiting" | "plan";    // default "setup"
  note?: { de: string; en: string };      // what the share dialog's row says instead
  plan?: string;                          // "plan": the plan that has it
}

interface PluginRunnerAddress {
  number?: string | null;   // the number people write to or call, with the country code
  keyword?: string | null;  // the word that picks this wizard on that number
  link?: string | null;     // opens the channel with the keyword written: copied, and as a QR code
}

interface PluginRunnerRequest {
  request: Request;
  tenantId: string;
  wizard: { id: string; token: string; title: string };
  path: string;                        // below /w/<token>/<id>
  query: URLSearchParams;
}

interface PluginRuns {
  start(input: ({ token: string } | { wizardId: string }) & {
    person: { channel: string; id: string };
    answers?: Record<string, unknown>;
    runner?: string;
  }): Promise<{ runId: string; ticket: string; refused: { field: string; message: string }[] | null }>;
  report(runId: string, options?: { waitSeconds?: number; draft?: Record<string, unknown> }): Promise<PluginRunReport>;
  wizards(runner: string): Promise<{ wizardId: string; token: string; title: string; lang: "de" | "en" }[]>;
  answerPage(runId: string, stepId: string, values: Record<string, unknown>): Promise<void>;
  review(runId: string, stepId: string, action: PluginReviewAction): Promise<void>;
  answerAsk(runId: string, askId: string, answer: "allow" | "skip"): Promise<void>;
  control(runId: string, action: "back" | "retry" | "cancel"): Promise<void>;
  subscribe(runId: string, listener: (signal: PluginRunSignal) => void): () => void;
  handoffUrl(runId: string): Promise<string>;
  upload(runId: string, file: { data: Uint8Array | ArrayBuffer; mime: string; name: string }): Promise<{ assetId: string }>;
  transcribe(runId: string, file: { data: Uint8Array | ArrayBuffer; mime: string }): Promise<{ text: string }>;
}

interface PluginRoute {
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  path: string;                 // "/", "/items", "/items/:id"
  role?: "member" | "admin";    // "admin": owners and admins only
  handler(request: PluginRequest): unknown | Promise<unknown>;
}

interface PluginRequest {
  request: Request;
  path: string;
  params: Record<string, string>;
  query: URLSearchParams;
  user: { id: string; tenantId: string; role: "owner" | "admin" | "member"; name: string; email: string };
  json<T = unknown>(): Promise<T>;
}

interface PluginAssistantTool<S extends z.ZodType = z.ZodType> {
  name: string;           // lower case, digits and "_"
  description: string;    // for the model
  inputSchema: S;
  card?: boolean;         // the result also goes to the chat, for the studio half's card
  execute(input: z.infer<S>, turn: PluginAssistantContext): unknown | Promise<unknown>;
}

interface PluginAssistantContext {
  tenantId: string;
  space: { id: string; name: string };
  userId: string;
  signal: AbortSignal;
  emit(message: string): void;   // the line the chat shows
  changed(): void;               // the space page draws again
}

interface PluginPublicRoute {
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  path: string;
  handler(request: PluginPublicRequest): unknown | Promise<unknown>;
}

interface PluginPublicRequest {
  request: Request;
  path: string;
  params: Record<string, string>;
  query: URLSearchParams;
  tenantId: string;    // the tenant of the address; nobody is signed in
  json<T = unknown>(): Promise<T>;
}

interface PluginStarter {
  id: string;                    // lower case, digits and "-"
  title: string;
  description: string;           // what it makes, in one or two sentences
  language?: "de" | "en";        // the language of its texts; default "en"
  definition: unknown;           // a complete wizard definition, checked when it is registered
  files?: Record<string, string | Uint8Array>;  // workspace files by path; a string is UTF-8
}

interface PluginRunEvent {
  run: { id: string; wizardId: string; mode: "test" | "live"; status: "done" | "failed" | "cancelled" };
  wizard: { id: string; title: string; projectId: string };
  values: Record<string, unknown>;   // what the person answered, by field id
}