@openbrf/plugin-sdk 1.0.0 → 1.4.0

package/src/action-refusal.ts

@@ -0,0 +1,178 @@
+import type { ActionRetry } from "./actions.ts";
+
+/**
+ * Why the registry refused a call, in a form a caller can act on.
+ *
+ * A caller here is often a model rather than a person, which changes what a
+ * refusal has to carry. A person reads a sentence and decides what to do; a
+ * model needs to know whether trying again could ever work, and what to change
+ * if it could. So every refusal has a code, a status, and a published rule for
+ * how a connector should render it.
+ *
+ * The vocabulary lives here rather than in the API because a plugin dispatching
+ * through `host.actions.invoke` has no other way to read it: the catalogue
+ * endpoint serves the same table over HTTP, and a plugin in the same process
+ * has no route to that. The API imports it back, so there is one list.
+ */
+
+export const ACTION_ERROR_REASONS = [
+  "unknown-action",
+  "forbidden-capability",
+  "forbidden-surface",
+  "insufficient-scope",
+  "not-serving",
+  "read-only",
+  "confirmation-required",
+  "output-invalid",
+  "rate-limited",
+  "internal",
+] as const;
+
+export type ActionErrorReason = (typeof ACTION_ERROR_REASONS)[number];
+
+/**
+ * How a connector should tell its caller about a refusal.
+ *
+ * A protocol error means the call never happened; a tool result means it
+ * happened and was refused, and only the second is something to tell the
+ * person about.
+ */
+export type ActionRefusalTransport = "protocol" | "tool-result";
+
+/**
+ * How a connector should render each refusal, published as data.
+ *
+ * Served on the catalogue endpoint as well, so that two connectors - one
+ * reading it over HTTP, one in process - cannot disagree about whether a 403
+ * is worth retrying. Keyed by the registry's reasons and by the two refusals
+ * that are not the registry's own: a body the action's input schema refuses,
+ * and a refusal raised by the service behind the action.
+ */
+export const ACTION_ERROR_MCP: Readonly<
+  Record<
+    ActionErrorReason | "invalid-body" | "domain",
+    {
+      readonly transport: ActionRefusalTransport;
+      readonly retry: ActionRetry;
+    }
+  >
+> = {
+  "unknown-action": { transport: "protocol", retry: "never" },
+  "invalid-body": { transport: "tool-result", retry: "after-edit" },
+  "forbidden-capability": { transport: "tool-result", retry: "never" },
+  "forbidden-surface": { transport: "tool-result", retry: "never" },
+  "insufficient-scope": { transport: "tool-result", retry: "never" },
+  "not-serving": { transport: "tool-result", retry: "never" },
+  "read-only": { transport: "tool-result", retry: "after-backoff" },
+  "confirmation-required": { transport: "tool-result", retry: "never" },
+  "output-invalid": { transport: "protocol", retry: "never" },
+  "rate-limited": { transport: "tool-result", retry: "after-backoff" },
+  internal: { transport: "protocol", retry: "after-backoff" },
+  domain: { transport: "tool-result", retry: "never" },
+};
+
+/**
+ * Which of the three ways a call was refused.
+ *
+ * "registry" is the registry's own refusal, and `reason` is then one of
+ * ACTION_ERROR_REASONS. "invalid-body" is an input the action's schema
+ * refused, and `reason` is "invalid-body". "domain" is the service behind the
+ * action refusing on the merits, and `reason` is one the action declared in
+ * its `errors`.
+ */
+export type ActionRefusalKind = "registry" | "invalid-body" | "domain";
+
+/**
+ * What `host.actions.invoke` rejects with when the call was refused.
+ *
+ * One shape for all three kinds, so that a connector renders a refusal from
+ * the fields it carries rather than by recognising the host's classes, which a
+ * plugin cannot import. Recognise one with `isActionRefusal`, not with
+ * `instanceof`: the host builds it, and a plugin's bundled copy of this
+ * package is not the host's.
+ *
+ * A plugin route that rethrows one answers its caller with the same status,
+ * body and headers the registry would have.
+ */
+export interface ActionRefusal extends Error {
+  readonly name: "ActionRefusal";
+  readonly kind: ActionRefusalKind;
+  readonly reason: string;
+  /** The HTTP status the refusal answers with. */
+  readonly status: number;
+  readonly transport: ActionRefusalTransport;
+  /**
+   * From ACTION_ERROR_MCP for the registry's refusals and an invalid body. For
+   * a domain refusal, the verdict the action declared for that reason in its
+   * `errors`, or "never" for a reason it did not declare.
+   */
+  readonly retry: ActionRetry;
+  /**
+   * The particulars the refusal publishes, keyed by the field they travel in.
+   *
+   * `scopes` on an insufficient-scope refusal names the scope the call needed.
+   * `issues` on an invalid body lists `{ path, message }` for each failing
+   * field, and never the submitted value.
+   */
+  details(): Record<string, readonly unknown[]>;
+  /**
+   * The bearer challenge to answer a connected app with, as the value of a
+   * `WWW-Authenticate` header (RFC 6750, ADR 0009).
+   *
+   * Set on an insufficient-scope refusal, where it names every scope the
+   * instance issues so the client can ask for what it is missing in one round
+   * trip. Absent wherever no challenge would help.
+   */
+  readonly challenge?: string;
+}
+
+const KINDS: readonly unknown[] = [
+  "registry",
+  "invalid-body",
+  "domain",
+] satisfies ActionRefusalKind[];
+const TRANSPORTS: readonly unknown[] = [
+  "protocol",
+  "tool-result",
+] satisfies ActionRefusalTransport[];
+const RETRIES: readonly unknown[] = [
+  "never",
+  "after-edit",
+  "after-backoff",
+] satisfies ActionRetry[];
+const REGISTRY_REASONS: readonly unknown[] = ACTION_ERROR_REASONS;
+
+/**
+ * Whether a value `host.actions.invoke` rejected with is a refusal.
+ *
+ * Structural rather than `instanceof`, for the reason on ActionRefusal. False
+ * means the call failed rather than being refused - the host could not be
+ * reached, or something broke - and a connector answers that as an internal
+ * error without inspecting it.
+ */
+export function isActionRefusal(value: unknown): value is ActionRefusal {
+  if (!(value instanceof Error) || value.name !== "ActionRefusal") {
+    return false;
+  }
+  const refusal = value as Error &
+    Partial<Record<keyof ActionRefusal, unknown>>;
+  if (
+    typeof refusal.reason !== "string" ||
+    typeof refusal.status !== "number" ||
+    typeof refusal.details !== "function" ||
+    !KINDS.includes(refusal.kind) ||
+    !TRANSPORTS.includes(refusal.transport) ||
+    !RETRIES.includes(refusal.retry) ||
+    (refusal.challenge !== undefined && typeof refusal.challenge !== "string")
+  ) {
+    return false;
+  }
+  switch (refusal.kind) {
+    case "registry":
+      return REGISTRY_REASONS.includes(refusal.reason);
+    case "invalid-body":
+      return refusal.reason === "invalid-body";
+    default:
+      return true;
+  }
+}

package/src/action-schema.ts

@@ -58,7 +58,7 @@ function convert(
       `${actionName}: an action schema must be built with the host's zod.`,
     );
   }
-  return z.toJSONSchema(schema, {
+  const document = z.toJSONSchema(schema, {
     target: "draft-2020-12",
     io,
     cycles: "throw",
@@ -69,6 +69,9 @@ function convert(
       );
     },
   }) as Record<string, unknown>;
+  // zod hangs a non-enumerable `~standard` on the root. A shallow copy leaves
+  // it behind, so what a caller is handed is a plain JSON document.
+  return { ...document };
 }
 
 export function actionInputJsonSchema(

package/src/actions.ts

@@ -67,12 +67,15 @@ export type ActionPersonalData = (typeof ACTION_PERSONAL_DATA)[number];
  */
 export const ACTION_NAME_PATTERN = /^[a-z][a-z0-9_]{2,63}$/;
 
+/** Whether trying again could ever work, and after what. */
+export type ActionRetry = "never" | "after-edit" | "after-backoff";
+
 /** What a refusal means for a caller that is a model rather than a person. */
 export interface ActionErrorSpec {
   /** The machine-readable reason the handler raises. */
   readonly reason: string;
   /** Whether trying again could ever work, and after what. */
-  readonly retry: "never" | "after-edit" | "after-backoff";
+  readonly retry: ActionRetry;
   /** The sentence a person is shown, as an i18n key. */
   readonly messageKey: string;
 }
@@ -80,9 +83,14 @@ export interface ActionErrorSpec {
 /**
  * The request a plugin's own route received.
  *
- * Opaque on purpose: the host reads a symbol on it that only the host writes,
- * so a plugin passes the request it was handed straight through and cannot
- * construct one. That is what stops a plugin naming a person it was not given.
+ * Opaque on purpose: the host recognises the request it authenticated by its
+ * identity, which nothing on it can copy, so a plugin passes the request it was
+ * handed straight through and cannot construct one. That is what stops a plugin
+ * naming a person it was not given.
+ *
+ * It speaks for its person only while the route is serving it. Once the
+ * response is sent the host refuses it, so a request kept for later names
+ * nobody.
  */
 export type ActionRequest = object;
 
@@ -120,6 +128,19 @@ export interface ActionContext {
   readonly principal: ActionPrincipal;
   readonly channel: ActionChannel;
   readonly client?: ActionClient;
+  /**
+   * The plugin whose route dispatched the call, when one did, by its manifest
+   * id. Set by the host from the plugin it serves, whatever the channel.
+   */
+  readonly pluginId?: string;
+  /**
+   * The pending change this call confirms, when it confirms one.
+   *
+   * A confirmed call is the confirming person's own, on `web`; this is what
+   * ties its audit entry back to the proposal, and to the channel and the app
+   * the proposal came through.
+   */
+  readonly pendingChangeId?: string;
   readonly requestId: string;
   readonly now: Date;
 }
@@ -212,6 +233,35 @@ export interface ActionSummary {
   readonly errors: readonly ActionErrorSpec[];
 }
 
+/**
+ * What proposing a change answers with.
+ *
+ * Nothing has run. The change waits, for a week at most, until the person whose
+ * request proposed it confirms or rejects it on the platform's own screen at
+ * `path`, which a plugin's view links to. A plugin cannot confirm one.
+ */
+export interface PendingChangeReceipt {
+  readonly id: string;
+  readonly expiresAt: Date;
+  /** The preview, on the platform's own screen, relative to the origin. */
+  readonly path: string;
+}
+
+/**
+ * One action as a plugin is offered it: the summary, and the JSON Schema
+ * (draft 2020-12) of what it takes and what it returns.
+ *
+ * What an MCP connector puts in `tools/list` and what a model is told a tool
+ * accepts. The input schema is the one `invoke` validates against, converted
+ * as the HTTP catalogue converts it, so a tool is described by the rule it is
+ * held to. Each listing builds both afresh: changing one changes nothing the
+ * host holds or hands anybody else.
+ */
+export interface ActionWithSchemas extends ActionSummary {
+  readonly inputSchema: Record<string, unknown>;
+  readonly outputSchema: Record<string, unknown>;
+}
+
 export interface PluginActions {
   /**
    * Registers an action the manifest declared.
@@ -229,19 +279,66 @@ export interface PluginActions {
    */
   register: (registration: PluginActionRegistration) => void;
 
-  /** What this plugin's route may offer the request it is serving. */
+  /**
+   * What this plugin's route may offer the request it is serving, each with
+   * its schemas.
+   *
+   * Filtered by channel, surface, capability, liveness and arming, as `invoke`
+   * is, and the schemas are of the actions listed and no others. Token scope
+   * (`mcp:read`, `mcp:write`) and read-only mode are decided at `invoke`, which
+   * may still refuse a listed action.
+   */
   list: (
     request: ActionRequest,
     filter?: PluginActionFilter,
-  ) => Promise<ActionSummary[]>;
+  ) => Promise<ActionWithSchemas[]>;
 
   /**
    * Dispatch. The person, the channel and the connected app all come from the
    * request the host authenticated, never from an argument.
+   *
+   * A refused call rejects with an `ActionRefusal`, whichever of the three
+   * ways it was refused - by the registry, over its input or by the service
+   * behind it - and `isActionRefusal` recognises one. Anything else it
+   * rejects with is a fault rather than an answer.
    */
   invoke: <Output>(
     request: ActionRequest,
     name: string,
     input: unknown,
   ) => Promise<Output>;
+
+  /**
+   * Holds a write as a pending change instead of running it (ADR 0039).
+   *
+   * The call is checked as `invoke` would check it before running anything -
+   * the action exists and is offered, the person holds its capability, the
+   * input fits its schema - and refused the same way. A read cannot be
+   * proposed, and nor can an action the platform's own screens are not offered.
+   * The person whose request this is then sees the change as a preview and
+   * confirms it, and it runs as them at that moment, with every check made
+   * again; or rejects it, and nothing runs.
+   *
+   * Added after `invoke`, so a plugin installed on an older host has to check
+   * that it is there before calling it, for the reason `host.actions` gives.
+   */
+  propose: (
+    request: ActionRequest,
+    name: string,
+    input: unknown,
+  ) => Promise<PendingChangeReceipt>;
+
+  /**
+   * The connected app the request was authenticated with, or null when it
+   * arrived on a signed-in session.
+   *
+   * The app a dispatch on this request is recorded as, read from what the host
+   * established when it authenticated the request rather than from the
+   * request's own properties, which the plugin can write. A connector asks it
+   * before answering on a route that serves connected apps only.
+   *
+   * Added after `list` and `invoke`, so a plugin must feature-detect it
+   * (`host.actions?.client === undefined`) before calling it.
+   */
+  client: (request: ActionRequest) => ActionClient | null;
 }

package/src/blocks.ts

@@ -0,0 +1,289 @@
+import { z } from "zod";
+
+import type { PluginAbortSignal } from "./abort-signal.ts";
+import type { PluginSettingsValues } from "./settings-schema.ts";
+import { pluginSettingsSchema } from "./settings-schema.ts";
+
+/**
+ * Blocks a plugin adds to the association's website.
+ *
+ * A page on the website is a list of blocks, never markup (ADR 0006), and a
+ * plugin's block is one more type in that list. The manifest declares it - its
+ * name, how the page editor offers it and the settings the board fills in - and
+ * the server bundle registers the function that renders it. The host does the
+ * rest: it offers the block in the editor, validates the settings on every
+ * save, calls the render function while it renders the page, and decides what
+ * of the answer reaches the visitor's browser.
+ *
+ * What the render function returns is a small tree of elements rather than a
+ * string of HTML. The host reads it against a short list of elements and
+ * attributes and prints what passes through the same renderer as the rest of
+ * the page, so a script, a stylesheet, an event handler or a picture from
+ * another host has no way into the markup however the tree was built. The
+ * website's content security policy refuses all four as well; the list is what
+ * keeps the page from carrying them at all.
+ */
+
+/**
+ * The name of one block, unique within its plugin.
+ *
+ * The block's type id is composed by the host as `<plugin id>/<name>`, which is
+ * what a page stores, so two plugins cannot claim one type and no plugin can
+ * claim one of the core's. The name has a core block's own shape: a
+ * lowerCamelCase word of at most 32 characters.
+ */
+export const PLUGIN_BLOCK_NAME_PATTERN = /^[a-z][a-zA-Z0-9]{0,31}$/;
+
+/** The type id a page stores a plugin's block under. */
+export function pluginBlockType(pluginId: string, name: string): string {
+  return `${pluginId}/${name}`;
+}
+
+/**
+ * The pictures the page editor can show beside a plugin's block.
+ *
+ * A name rather than an image, as for the core's blocks: the editor draws each
+ * one in the theme's own colours, and a manifest carries no markup. `plugin` is
+ * the one to choose when none of the others says what the block is.
+ */
+export const PLUGIN_BLOCK_ICONS = [
+  "plugin",
+  "paragraph",
+  "heading",
+  "image",
+  "form",
+  "news",
+  "calendar",
+  "documents",
+  "people",
+  "facts",
+  "contact",
+  "questions",
+] as const;
+export type PluginBlockIcon = (typeof PLUGIN_BLOCK_ICONS)[number];
+
+/**
+ * Where the page editor files a plugin's block.
+ *
+ * The core's categories, less `layout`: a layout block arranges other blocks,
+ * and a plugin's block holds none.
+ */
+export const PLUGIN_BLOCK_CATEGORIES = [
+  "text",
+  "media",
+  "association",
+] as const;
+export type PluginBlockCategory = (typeof PLUGIN_BLOCK_CATEGORIES)[number];
+
+/**
+ * One block a plugin declares, as the manifest carries it.
+ *
+ * `labelKey` is an i18n key in the plugin's own namespace, like every other
+ * label a manifest names. The settings are the same declaration the plugin's
+ * own settings form is made of, and the page editor renders them as a form on
+ * the block: one set of values per block on a page, validated by the host on
+ * every save.
+ */
+export const pluginBlockSchema = z.strictObject({
+  name: z
+    .string()
+    .regex(
+      PLUGIN_BLOCK_NAME_PATTERN,
+      "must be a lowerCamelCase word of at most 32 characters",
+    ),
+  labelKey: z.string().min(1).max(200),
+  icon: z.enum(PLUGIN_BLOCK_ICONS).default("plugin"),
+  category: z.enum(PLUGIN_BLOCK_CATEGORIES).default("association"),
+  /*
+   * No secret field. A block's values are stored in the page that holds it
+   * and are read by whoever renders the page, so a credential there would be
+   * published with it.
+   */
+  settingsSchema: pluginSettingsSchema
+    .refine(
+      (schema) => schema.fields.every((field) => field.type !== "secret"),
+      {
+        message:
+          "a block's settings may not declare a secret field: they are published with the page",
+      },
+    )
+    .default({ fields: [] }),
+});
+
+export type PluginBlockDeclaration = z.infer<typeof pluginBlockSchema>;
+
+/**
+ * The blocks a manifest declares. At most sixteen, each name once.
+ *
+ * A name appearing twice would be one type id with two renderers, and a page
+ * that holds it would render with whichever registered last.
+ */
+export const pluginBlocksSchema = z
+  .array(pluginBlockSchema)
+  .max(16)
+  .superRefine((blocks, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, block] of blocks.entries()) {
+      if (seen.has(block.name)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [index, "name"],
+          message: `two blocks are declared with the name "${block.name}"`,
+        });
+      }
+      seen.add(block.name);
+    }
+  });
+
+/**
+ * The elements a rendered block may contain.
+ *
+ * Text and its structure, and nothing that loads, runs or styles anything. An
+ * element outside this list is left out together with everything inside it,
+ * because what an unknown element holds is not text the plugin meant a reader
+ * to see: the body of a script, a stylesheet, a template.
+ *
+ * Headings start at the second level, as a page's own blocks do: the page's
+ * title is its first-level heading.
+ */
+export const PLUGIN_BLOCK_ELEMENTS = [
+  "p",
+  "h2",
+  "h3",
+  "h4",
+  "ul",
+  "ol",
+  "li",
+  "dl",
+  "dt",
+  "dd",
+  "strong",
+  "em",
+  "small",
+  "code",
+  "blockquote",
+  "a",
+  "br",
+  "span",
+  "div",
+  "section",
+  "table",
+  "caption",
+  "thead",
+  "tbody",
+  "tfoot",
+  "tr",
+  "th",
+  "td",
+  "time",
+] as const;
+export type PluginBlockElementName = (typeof PLUGIN_BLOCK_ELEMENTS)[number];
+
+/**
+ * The attributes an element may carry, by element. Every other one is left out.
+ *
+ *   href      on `a`: http, https, mailto or a path on this instance. Any other
+ *             address - `javascript:` above all - leaves the link out and keeps
+ *             its text. A link to another host is given noopener and
+ *             noreferrer by the host.
+ *   dateTime  on `time`: the machine-readable date beside the one shown.
+ *   scope     on `th`: `row`, `col`, `rowgroup` or `colgroup`.
+ *
+ * No `class`, no `style` and no `id`: the theme decides how the website looks,
+ * and the host wraps every plugin's block in one element the theme can style.
+ */
+export const PLUGIN_BLOCK_ATTRIBUTES: Readonly<
+  Partial<Record<PluginBlockElementName, readonly string[]>>
+> = {
+  a: ["href"],
+  time: ["dateTime"],
+  th: ["scope"],
+};
+
+/** One element of a rendered block. */
+export interface PluginBlockElement {
+  readonly tag: PluginBlockElementName;
+  readonly attributes?: Readonly<Record<string, string>>;
+  readonly children?: readonly PluginBlockNode[];
+}
+
+/**
+ * A piece of a rendered block: text, or an element.
+ *
+ * Text is text. It is escaped as it is printed, so `"<b>"` reads as the three
+ * characters and is never an element.
+ */
+export type PluginBlockNode = string | PluginBlockElement;
+
+/** What a render function answers with. Null, or nothing, renders nothing. */
+export type PluginBlockContent =
+  PluginBlockNode | readonly PluginBlockNode[] | null | undefined;
+
+/**
+ * What a block's render function is told.
+ *
+ * The block's own settings, already validated against its declaration with
+ * the declared defaults applied, and the reader's language with a translation
+ * function in the plugin's own namespace. Nothing about the reader: the same
+ * page is rendered for a visitor with no account and for a member, and what a
+ * block may say must not depend on who is reading it.
+ */
+export interface PluginBlockRenderContext {
+  /** The block's type id, `<plugin id>/<name>`. */
+  readonly type: string;
+  readonly settings: PluginSettingsValues;
+  /** The language the page is being rendered in: `sv` or `en`. */
+  readonly locale: string;
+  /** Translates a key from the plugin's own locale files. */
+  readonly t: (
+    key: string,
+    values?: Readonly<Record<string, string | number>>,
+  ) => string;
+  /**
+   * Aborted when the host stops waiting for this block.
+   *
+   * A render that has not answered within PLUGIN_BLOCK_RENDER_TIMEOUT_MS is
+   * left off the page, and the page is sent without it. The host cannot stop
+   * the plugin's code, so a render doing slow work of its own should hand this
+   * on to whatever it is waiting for.
+   */
+  readonly signal: PluginBlockAbortSignal;
+}
+
+/**
+ * The `AbortSignal` a render function is given. See {@link PluginAbortSignal}.
+ */
+export type PluginBlockAbortSignal = PluginAbortSignal;
+
+/**
+ * How long the host waits for one block to render, in milliseconds.
+ *
+ * Every block on a page renders at the same time, so this is also about the
+ * longest a plugin can add to a page's answer. A website's front page has to
+ * answer quickly for a visitor with no account, and a block that cannot is
+ * left off rather than waited for.
+ */
+export const PLUGIN_BLOCK_RENDER_TIMEOUT_MS = 2000;
+
+/** What a plugin hands the host for one block its manifest declared. */
+export interface PluginBlockRegistration {
+  /** The block's name as the manifest declares it, not its type id. */
+  readonly name: string;
+  readonly render: (
+    context: PluginBlockRenderContext,
+  ) => PluginBlockContent | Promise<PluginBlockContent>;
+}
+
+export interface PluginBlocks {
+  /**
+   * Registers the render function of a block the manifest declared.
+   *
+   * Callable from the module factory onwards, as `host.actions.register` is: a
+   * call made before the application exists is kept until it does. A name the
+   * manifest does not declare stops the plugin serving and is reported as
+   * `block-refused`. A declared block with no render function registered is
+   * not offered in the page editor, and a page that already holds one shows
+   * nothing in its place.
+   */
+  register: (registration: PluginBlockRegistration) => void;
+}