@openbrf/plugin-sdk 0.0.0-stage → 1.2.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

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+
+/**
+ * An action's schemas, as the JSON Schema a caller is published.
+ *
+ * The only call to `z.toJSONSchema` in the product. Every option here is set
+ * against a failure that would otherwise be silent, so they are worth reading
+ * one at a time.
+ *
+ * `io: "input"` because output mode makes a key with a default REQUIRED, and a
+ * model reading that will dutifully supply a value for every field the platform
+ * was perfectly happy to choose itself.
+ *
+ * `cycles: "throw"` because a self-referential schema has no JSON Schema
+ * without `$ref`, and a silently emitted `$ref` to a positional name is worse
+ * than a refusal at registration.
+ *
+ * `reused: "inline"` because `$defs` invents names from the position a schema
+ * happens to hold, and those names would reach a committed artefact and a
+ * third-party client. Inlining costs bytes and keeps the document stable.
+ *
+ * The function form of `unrepresentable` because the default error names
+ * neither the action nor the path, and a build failing with "unrepresentable
+ * type" and nothing else is a half hour of searching.
+ *
+ * One property is worth stating because it is NOT what one would assume: a bare
+ * `.transform()` does not throw under input mode - it is erased and the
+ * pre-transform type is emitted. The guarantee is placed where it is real, on
+ * the output helper, which does throw. So an action whose pair is converted at
+ * registration cannot carry a transform anywhere.
+ *
+ * `.refine()`, `.check()`, `.superRefine()` and `.brand()` are erased with no
+ * marker under both modes. That is why the rule for a published schema is
+ * structural constraints first: what the document says has to be at least as
+ * strict as what the runtime enforces, or a caller is told a value is
+ * acceptable that the service will refuse.
+ */
+
+/** Refuses a schema built with a second copy of zod, whose internals differ. */
+export function isHostZodSchema(schema: unknown): schema is z.ZodType {
+  return (
+    typeof schema === "object" &&
+    schema !== null &&
+    "_zod" in schema &&
+    (schema as { _zod?: unknown })._zod !== undefined
+  );
+}
+
+function convert(
+  schema: unknown,
+  actionName: string,
+  io: "input" | "output",
+): Record<string, unknown> {
+  if (!isHostZodSchema(schema)) {
+    throw new Error(
+      `${actionName}: an action schema must be built with the host's zod.`,
+    );
+  }
+  const document = z.toJSONSchema(schema, {
+    target: "draft-2020-12",
+    io,
+    cycles: "throw",
+    reused: "inline",
+    unrepresentable: ({ path, message }) => {
+      throw new Error(
+        `${actionName}: ${message} at ${[io, ...path.map(String)].join(".")}`,
+      );
+    },
+  }) 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(
+  schema: StandardSchemaV1<unknown, unknown>,
+  actionName: string,
+): Record<string, unknown> {
+  return convert(schema, actionName, "input");
+}
+
+export function actionOutputJsonSchema(
+  schema: StandardSchemaV1<unknown, unknown>,
+  actionName: string,
+): Record<string, unknown> {
+  return convert(schema, actionName, "output");
+}

package/src/actions.ts

@@ -0,0 +1,344 @@
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+
+/**
+ * What the platform can be asked to do, declared once and dispatched through
+ * one place: an action (atgard).
+ *
+ * An action is a name, an input schema, the single capability it needs, what it
+ * does to the records, which categories of personal data it can touch, and which
+ * surfaces it may be offered on. The registry checks the calling person's
+ * capability on every call rather than trusting the caller, so registering an
+ * action is never a permission of its own - it is a way of reaching something
+ * the caller could already do.
+ *
+ * A core feature registers its own. A plugin registers the ones its manifest
+ * declared and the board consented to, and they disappear with the plugin.
+ *
+ * Swedish domain terms follow GLOSSARY.md.
+ */
+
+export const ACTION_EFFECTS = ["read", "write", "delete"] as const;
+export type ActionEffect = (typeof ACTION_EFFECTS)[number];
+
+/**
+ * Where an action may be offered.
+ *
+ * "ui" means in-process only: the platform's own screens and a plugin's own
+ * route. The other two are the ones a board switches on deliberately.
+ */
+export const ACTION_SURFACES = ["ui", "mcp", "ai"] as const;
+export type ActionSurface = (typeof ACTION_SURFACES)[number];
+
+/**
+ * What an action can touch.
+ *
+ * The first thirteen are PERSONAL_DATA_CATEGORIES from @openbrf/shared, in
+ * order, which this package deliberately does not depend on; the API side
+ * asserts the prefix equality, because it is the only place that can import
+ * both. "protected" is this list's own and marks an action that can return a
+ * field of a person carrying protected personal data (skyddade
+ * personuppgifter): it is the value the registry refuses to expose to a
+ * connected app or to the AI package at all.
+ */
+export const ACTION_PERSONAL_DATA = [
+  "name",
+  "apartment",
+  "residency",
+  "email",
+  "phone",
+  "postalAddress",
+  "personalIdentityNumber",
+  "account",
+  "financial",
+  "health",
+  "photograph",
+  "freeText",
+  "auditTrail",
+  "protected",
+] as const;
+export type ActionPersonalData = (typeof ACTION_PERSONAL_DATA)[number];
+
+/**
+ * What a public action name may look like.
+ *
+ * The intersection of three separate limits: what an MCP tools/list entry
+ * allows, what a model API allows (no dots), and what stays readable in a
+ * directory review (64 characters).
+ */
+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: ActionRetry;
+  /** The sentence a person is shown, as an i18n key. */
+  readonly messageKey: string;
+}
+
+/**
+ * The request a plugin's own route received.
+ *
+ * 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;
+
+/** The lowercase channel vocabulary. The registry maps it to the audit channel. */
+export const ACTION_CHANNELS = [
+  "web",
+  "mcp",
+  "ai",
+  "system",
+  "plugin",
+] as const;
+export type ActionChannel = (typeof ACTION_CHANNELS)[number];
+
+/**
+ * Who is acting.
+ *
+ * The person, and the capabilities the registry re-derived for this call. No
+ * email, no name, no roles: a handler that needs to decide what an audience may
+ * see reads the capability list, and a handler that does not need it is not
+ * given a person's details to leak.
+ */
+export interface ActionPrincipal {
+  readonly personId: string;
+  readonly capabilities: readonly string[];
+}
+
+/** The connected app that acted, when one did. Both hosts, never the token. */
+export interface ActionClient {
+  readonly clientId: string;
+  readonly clientHost: string | null;
+}
+
+/** What a handler is told about the call. Built by the host, never by a caller. */
+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;
+}
+
+export interface ActionDefinition<Input = unknown, Output = unknown> {
+  readonly name: string;
+  readonly titleKey: string;
+  readonly descriptionKey: string;
+  readonly group: string;
+  readonly groupTitleKey: string;
+  /** Exactly one core capability, by name. */
+  readonly capability: string;
+  readonly effect: ActionEffect;
+  readonly idempotent: boolean;
+  /**
+   * True when the act adds and overwrites nothing a person wrote.
+   *
+   * It is what separates a create from an update, and the annotation mapping
+   * reads it: MCP's destructiveHint defaults to true, so a non-read action has
+   * to say for itself that it destroys nothing.
+   */
+  readonly additive: boolean;
+  readonly needsConfirmation: boolean;
+  /** True when the handler reaches a system outside this instance. */
+  readonly openWorld: boolean;
+  /** Never empty by convention: an action that touches none says []. */
+  readonly personalData: readonly ActionPersonalData[];
+  /** Opt-in allowlist. An empty array means the action is offered nowhere. */
+  readonly surfaces: readonly ActionSurface[];
+  /** Every domain refusal the handler can raise, for the caller to act on. */
+  readonly errors: readonly ActionErrorSpec[];
+  readonly deprecatedAliases?: readonly string[];
+  /** Every object in it, at every depth, must refuse unknown keys. */
+  readonly input: StandardSchemaV1<unknown, Input>;
+  readonly output: StandardSchemaV1<unknown, Output>;
+  readonly handler: (input: Input, context: ActionContext) => Promise<Output>;
+}
+
+/**
+ * What a plugin hands the host: the id its manifest declared, and the rest.
+ *
+ * The capability, the effect, the personal-data categories and the surfaces are
+ * manifest data and are not repeated here. The loader's rule is that nothing
+ * which can refuse a plugin may run after the code that executes it, and the
+ * install consent screen renders from the catalog before anything is
+ * downloaded - so what the board consents to cannot come from the bundle.
+ */
+export interface PluginActionRegistration {
+  readonly id: string;
+  readonly definition: Omit<
+    ActionDefinition,
+    "capability" | "effect" | "personalData" | "surfaces"
+  >;
+}
+
+/** Narrows what a plugin's route offers the request it is serving. */
+export interface PluginActionFilter {
+  readonly surface?: ActionSurface;
+  readonly group?: string;
+}
+
+/** One action as a caller sees it, with its text already in the right language. */
+export interface ActionSummary {
+  readonly name: string;
+  readonly title: string;
+  readonly description: string;
+  readonly titleKey: string;
+  readonly descriptionKey: string;
+  readonly group: string;
+  readonly groupTitle: string;
+  /**
+   * The key behind `groupTitle`, alongside the two above.
+   *
+   * Both forms travel for the reason `titleKey` does: the resolved string is
+   * for a caller with no translations of its own - a connected app, a model -
+   * while a screen in this product translates the key itself. The interface's
+   * language and the language a request happens to declare are not the same
+   * thing, so a screen rendering the resolved string can show one heading in
+   * the browser's language above a page in the association's.
+   */
+  readonly groupTitleKey: string;
+  readonly capability: string;
+  readonly effect: ActionEffect;
+  readonly idempotent: boolean;
+  readonly additive: boolean;
+  readonly needsConfirmation: boolean;
+  readonly openWorld: boolean;
+  readonly personalData: readonly ActionPersonalData[];
+  readonly surfaces: readonly ActionSurface[];
+  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.
+   *
+   * Callable from the module factory onwards: a call made that early is
+   * buffered until the application is built, because the host object is not
+   * bound yet.
+   *
+   * It does not throw for a registration the host will refuse. An id the
+   * manifest never declared, or a schema that cannot be published, is found
+   * when the buffer is flushed - long after this call returned - and reaches
+   * the board as an `action-refused` finding rather than as an error the
+   * factory could have caught. A plugin that wants to know sooner validates
+   * its own manifest in its own build.
+   */
+  register: (registration: PluginActionRegistration) => void;
+
+  /**
+   * 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<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/api-version.ts

@@ -0,0 +1,28 @@
+/**
+ * The plugin API version.
+ *
+ * A single integer rather than a semver range, because the gate it guards is
+ * binary: a plugin either speaks the contract this host implements or it does
+ * not get loaded. A range would invite a plugin to claim ">=1" and then fail
+ * at the first call to a method version 2 removed, which is exactly the class
+ * of breakage the gate exists to prevent.
+ *
+ * Additive changes - a new optional manifest field, a new SDK method - keep
+ * the number. Anything a plugin built against the old contract could notice
+ * raises it, and the host may then support more than one version at a time by
+ * listing them in SUPPORTED_PLUGIN_API_VERSIONS.
+ */
+export const PLUGIN_API_VERSION = 1;
+
+/**
+ * Every version this contract can still load. Kept as a list so a host can
+ * carry an old version through a deprecation window without a plugin having
+ * to be republished on the day the new one lands.
+ */
+export const SUPPORTED_PLUGIN_API_VERSIONS: readonly number[] = [
+  PLUGIN_API_VERSION,
+];
+
+export function isSupportedApiVersion(apiVersion: number): boolean {
+  return SUPPORTED_PLUGIN_API_VERSIONS.includes(apiVersion);
+}