@jini-ai/agent-plugins 0.4.7 → 0.4.8

package/dist/admin-surfaces/external-links.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Host-mediated external links: a surface declares the https origins it may link to
+ * (`linkOrigins`, parsed in `./descriptor.ts`), and asks the host page to open a URL with an `open-link` message; the host page
+ * passes that message to `openAdminSurfaceLink`, which opens it through the host's own opener only
+ * when it comes from this mount and names a declared https origin.
+ *
+ * Why the host opens links: a surface frame is sandboxed without `allow-popups` or top navigation,
+ * so it cannot open anything itself, and must not: the host decides HOW (a new tab with `noopener`
+ * on the web, the system browser on desktop). Why the gate is this strict: a link the host opens
+ * leaves the sandbox entirely, so the destination is limited to what the shipped, digest-checked
+ * surfaces file declared, and the opener receives the URL parser's normalized form so it never
+ * re-parses a string this gate judged differently.
+ */
+import { type AdminSurfaceMessageEvent, type AdminSurfaceMountRecord } from './host-validator.js';
+import { type AdminSurfaceActionResponse } from './protocol.js';
+/** Host port: opens an already-checked https URL however the host decides (new tab with `noopener`, system browser). */
+export type AdminSurfaceOpenLinkPort = (required: {
+    readonly url: string;
+}, optional?: Record<string, never>) => void | Promise<void>;
+/** `ignored`: not this mount's open-link message; drop silently. Otherwise post `response` back to the frame. */
+export type AdminSurfaceLinkVerdict = {
+    readonly ok: true;
+    readonly url: string;
+    readonly response: AdminSurfaceActionResponse;
+} | {
+    readonly ok: false;
+    readonly ignored: string;
+} | {
+    readonly ok: false;
+    readonly refused: string;
+    readonly response: AdminSurfaceActionResponse;
+};
+/**
+ * Judges one `message` event as an open-link request for one mount and, when it passes, opens it
+ * through the host's port. Pass every message event here as well as to `validateAdminSurfaceMessage`;
+ * each ignores the other's messages.
+ * @param required.openLink - The host's opener; called at most once, with the normalized URL.
+ * @complexity O(n) in the URL length, plus the opener.
+ */
+export declare function openAdminSurfaceLink(required: {
+    readonly event: AdminSurfaceMessageEvent;
+    readonly mount: AdminSurfaceMountRecord;
+    readonly openLink: AdminSurfaceOpenLinkPort;
+}, _optional?: Record<string, never>): Promise<AdminSurfaceLinkVerdict>;
+//# sourceMappingURL=external-links.d.ts.map

package/dist/admin-surfaces/external-links.js

@@ -0,0 +1,70 @@
+/**
+ * @file Host-mediated external links: a surface declares the https origins it may link to
+ * (`linkOrigins`, parsed in `./descriptor.ts`), and asks the host page to open a URL with an `open-link` message; the host page
+ * passes that message to `openAdminSurfaceLink`, which opens it through the host's own opener only
+ * when it comes from this mount and names a declared https origin.
+ *
+ * Why the host opens links: a surface frame is sandboxed without `allow-popups` or top navigation,
+ * so it cannot open anything itself, and must not: the host decides HOW (a new tab with `noopener`
+ * on the web, the system browser on desktop). Why the gate is this strict: a link the host opens
+ * leaves the sandbox entirely, so the destination is limited to what the shipped, digest-checked
+ * surfaces file declared, and the opener receives the URL parser's normalized form so it never
+ * re-parses a string this gate judged differently.
+ */
+import { frameTransportRefusal, REQUEST_ID_PATTERN } from './host-validator.js';
+import { ADMIN_SURFACE_PROTOCOL, ADMIN_SURFACE_PROTOCOL_VERSION, adminSurfaceActionResponse, } from './protocol.js';
+/** Longer URLs are refused, not cut: a truncated link would open somewhere the plugin did not mean. */
+const MAX_LINK_URL_LENGTH = 2048;
+function isOpenLinkEnvelope(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const message = data;
+    const isProtocol = message.protocol === ADMIN_SURFACE_PROTOCOL && message.version === ADMIN_SURFACE_PROTOCOL_VERSION && message.kind === 'open-link';
+    return isProtocol && typeof message.mountId === 'string' && typeof message.requestId === 'string' && REQUEST_ID_PATTERN.test(message.requestId) && typeof message.url === 'string';
+}
+/** The normalized URL when `raw` may be opened, or why not. Messages never echo the URL. @complexity O(n) in the URL length. */
+function checkLink(raw, origins) {
+    if (raw.length > MAX_LINK_URL_LENGTH)
+        return { code: 'link-too-long', message: 'The link is too long.' };
+    if (!URL.canParse(raw))
+        return { code: 'link-invalid', message: 'That link is not a valid web address.' };
+    const parsed = new URL(raw);
+    if (parsed.protocol !== 'https:')
+        return { code: 'link-not-https', message: 'Only https links can be opened.' };
+    // Credentials in a link are a phishing shape (`https://trusted@elsewhere`) and never needed to open a page.
+    if (parsed.username !== '' || parsed.password !== '')
+        return { code: 'link-invalid', message: 'That link is not a valid web address.' };
+    if (!origins.includes(parsed.origin))
+        return { code: 'link-undeclared', message: 'This surface did not declare that link destination.' };
+    return { url: parsed.href };
+}
+/**
+ * Judges one `message` event as an open-link request for one mount and, when it passes, opens it
+ * through the host's port. Pass every message event here as well as to `validateAdminSurfaceMessage`;
+ * each ignores the other's messages.
+ * @param required.openLink - The host's opener; called at most once, with the normalized URL.
+ * @complexity O(n) in the URL length, plus the opener.
+ */
+export async function openAdminSurfaceLink(required, _optional = {}) {
+    const { event, mount, openLink } = required;
+    const transport = frameTransportRefusal({ event, mount });
+    if (transport !== null)
+        return { ok: false, ignored: transport };
+    if (!isOpenLinkEnvelope(event.data))
+        return { ok: false, ignored: 'not-an-open-link' };
+    const request = event.data;
+    if (request.mountId !== mount.mountId)
+        return { ok: false, ignored: 'mount-mismatch' };
+    const refuse = (refusal, retryable = false) => ({ ok: false, refused: refusal.code, response: adminSurfaceActionResponse({ request, outcome: { ok: false, error: { ...refusal, retryable } } }) });
+    const checked = checkLink(request.url, mount.descriptor.linkOrigins ?? []);
+    if (!('url' in checked))
+        return refuse(checked);
+    try {
+        await openLink({ url: checked.url });
+    }
+    catch {
+        return refuse({ code: 'link-failed', message: 'The host could not open the link. Try again.' }, true);
+    }
+    return { ok: true, url: checked.url, response: adminSurfaceActionResponse({ request, outcome: { ok: true, result: null } }) };
+}
+//# sourceMappingURL=external-links.js.map

package/dist/admin-surfaces/host-validator.d.ts

@@ -0,0 +1,62 @@
+import type { AdminSurfaceDescriptor } from './descriptor.js';
+import { type AdminSurfaceActionRequest, type AdminSurfaceActionResponse } from './protocol.js';
+/** The fields of a `MessageEvent` the gate reads; a real event satisfies it structurally. */
+export interface AdminSurfaceMessageEvent {
+    readonly origin: string;
+    readonly source: unknown;
+    readonly data: unknown;
+}
+export interface AdminSurfaceMountRecord {
+    readonly mountId: string;
+    /** The frame's `contentWindow`; the event's `source` must be this exact object. */
+    readonly frame: unknown;
+    /** `linkOrigins` matters only to `openAdminSurfaceLink`; a record without it opens no links. */
+    readonly descriptor: Pick<AdminSurfaceDescriptor, 'actions' | 'linkOrigins'>;
+}
+/** `ignored`: not addressed to this mount; drop silently. `refused`: this mount's request was invalid;
+ * post `response` back so the surface can show why. */
+export type AdminSurfaceMessageVerdict = {
+    readonly ok: true;
+    readonly request: AdminSurfaceActionRequest;
+} | {
+    readonly ok: false;
+    readonly ignored: string;
+} | {
+    readonly ok: false;
+    readonly refused: string;
+    readonly response: AdminSurfaceActionResponse;
+};
+export declare const REQUEST_ID_PATTERN: RegExp;
+/** Character length of the payload as JSON, or Infinity when it is not JSON-serializable. */
+/** Whether `event` comes from `mount`'s frame at all (origin and window), for every inbound message kind.
+ * @returns The failed check, or `null`. @complexity O(1). */
+export declare function frameTransportRefusal(required: {
+    readonly event: AdminSurfaceMessageEvent;
+    readonly mount: Pick<AdminSurfaceMountRecord, 'frame'>;
+}, _optional?: Record<string, never>): string | null;
+/**
+ * Judges one `message` event against one mount.
+ * @complexity O(p) in the payload size (one JSON measure plus one schema walk).
+ */
+export declare function validateAdminSurfaceMessage(required: {
+    readonly event: AdminSurfaceMessageEvent;
+    readonly mount: AdminSurfaceMountRecord;
+}, _optional?: Record<string, never>): AdminSurfaceMessageVerdict;
+/** Frame heights a host accepts by default (CSS px): tall enough for a notice, short enough that a
+ *  surface cannot push the admin page out of reach. */
+export declare const ADMIN_SURFACE_MIN_HEIGHT = 96;
+export declare const ADMIN_SURFACE_MAX_HEIGHT = 4000;
+/**
+ * The frame height `event` asks for when it is `mount`'s own `resize` message (same origin, window and
+ * mount as every other inbound message), clamped to `[min, max]`; null for anything else, which the
+ * caller ignores. A size is cosmetic, so a bad one is dropped rather than answered.
+ * @complexity O(1).
+ */
+export declare function readAdminSurfaceResize(required: {
+    readonly event: AdminSurfaceMessageEvent;
+    readonly mount: Pick<AdminSurfaceMountRecord, 'mountId' | 'frame'>;
+}, optional?: {
+    readonly min?: number;
+    readonly max?: number;
+}): number | null;
+//# sourceMappingURL=host-validator.d.ts.map

package/dist/admin-surfaces/host-validator.js

@@ -0,0 +1,87 @@
+/**
+ * @file The host page's gate for messages arriving from a mounted admin surface frame.
+ *
+ * Why every check is needed: all sandboxed frames share the origin "null", so the origin check only
+ * proves "some sandboxed frame"; the window identity proves it is THIS mount's
+ * frame; the nonce proves the frame still runs the document the host initialized (a navigated frame
+ * never received it). Action and schema checks here are an early refusal for the person using the
+ * surface; the server-side dispatcher repeats them because a host route can be called directly.
+ */
+import { exceedsAdminSurfacePayloadLimit, validateAdminSurfaceActionValue } from './action-schema.js';
+import { ADMIN_SURFACE_PROTOCOL, ADMIN_SURFACE_PROTOCOL_VERSION, SANDBOXED_FRAME_ORIGIN, adminSurfaceActionResponse, } from './protocol.js';
+export const REQUEST_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+function isRequestEnvelope(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const message = data;
+    const isProtocol = message.protocol === ADMIN_SURFACE_PROTOCOL && message.version === ADMIN_SURFACE_PROTOCOL_VERSION && message.kind === 'action-request';
+    return isProtocol && hasRequestFields(message);
+}
+function hasRequestFields(message) {
+    return typeof message.mountId === 'string' && typeof message.requestId === 'string' && REQUEST_ID_PATTERN.test(message.requestId)
+        && typeof message.action === 'string' && Object.hasOwn(message, 'payload');
+}
+/** Character length of the payload as JSON, or Infinity when it is not JSON-serializable. */
+/** Whether `event` comes from `mount`'s frame at all (origin and window), for every inbound message kind.
+ * @returns The failed check, or `null`. @complexity O(1). */
+export function frameTransportRefusal(required, _optional = {}) {
+    const { event, mount } = required;
+    // "null" is the origin of every frame sandboxed with `allow-scripts` only; nothing else may speak for a mount.
+    if (event.origin !== SANDBOXED_FRAME_ORIGIN)
+        return 'origin-mismatch';
+    return event.source === mount.frame ? null : 'source-mismatch';
+}
+/** Which transport check `event` fails for `mount`, or `null` when it is this mount's well-formed request. */
+function transportRefusal(event, mount) {
+    const frame = frameTransportRefusal({ event, mount });
+    if (frame !== null)
+        return frame;
+    if (!isRequestEnvelope(event.data))
+        return 'not-an-action-request';
+    return event.data.mountId === mount.mountId ? null : 'mount-mismatch';
+}
+/**
+ * Judges one `message` event against one mount.
+ * @complexity O(p) in the payload size (one JSON measure plus one schema walk).
+ */
+export function validateAdminSurfaceMessage(required, _optional = {}) {
+    const { event, mount } = required;
+    const ignored = transportRefusal(event, mount);
+    if (ignored !== null)
+        return { ok: false, ignored };
+    const request = event.data;
+    const refuse = (code, message) => ({ ok: false, refused: code, response: adminSurfaceActionResponse({ request, outcome: { ok: false, error: { code, message, retryable: false } } }) });
+    const action = mount.descriptor.actions.find((declared) => declared.name === request.action);
+    if (action === undefined)
+        return refuse('action-undeclared', 'This surface did not declare that action.');
+    if (exceedsAdminSurfacePayloadLimit({ payload: request.payload }))
+        return refuse('invalid-payload', 'The request is too large.');
+    const violation = validateAdminSurfaceActionValue({ schema: action.input, value: request.payload });
+    if (violation !== null)
+        return refuse('invalid-payload', `The request does not match the action's input: ${violation}.`);
+    return { ok: true, request };
+}
+/** Frame heights a host accepts by default (CSS px): tall enough for a notice, short enough that a
+ *  surface cannot push the admin page out of reach. */
+export const ADMIN_SURFACE_MIN_HEIGHT = 96;
+export const ADMIN_SURFACE_MAX_HEIGHT = 4000;
+function isResizeForMount({ message, mountId }, _options = {}) {
+    const isResize = message.protocol === ADMIN_SURFACE_PROTOCOL && message.version === ADMIN_SURFACE_PROTOCOL_VERSION && message.kind === 'resize';
+    return isResize && message.mountId === mountId;
+}
+/**
+ * The frame height `event` asks for when it is `mount`'s own `resize` message (same origin, window and
+ * mount as every other inbound message), clamped to `[min, max]`; null for anything else, which the
+ * caller ignores. A size is cosmetic, so a bad one is dropped rather than answered.
+ * @complexity O(1).
+ */
+export function readAdminSurfaceResize(required, optional = {}) {
+    const { event, mount } = required;
+    if (frameTransportRefusal({ event, mount }) !== null || typeof event.data !== 'object' || event.data === null)
+        return null;
+    const message = event.data;
+    if (!isResizeForMount({ message, mountId: mount.mountId }) || typeof message.height !== 'number' || !Number.isFinite(message.height))
+        return null;
+    return Math.min(optional.max ?? ADMIN_SURFACE_MAX_HEIGHT, Math.max(optional.min ?? ADMIN_SURFACE_MIN_HEIGHT, Math.ceil(message.height)));
+}
+//# sourceMappingURL=host-validator.js.map

package/dist/admin-surfaces/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Public barrel for `@jini-ai/agent-plugins/admin-surfaces`: plugin-owned admin surfaces
+ * (sandboxed iframes) and the host-mediated action protocol. See `./README.md`.
+ *
+ * Explicit on purpose: only what a host composes is public. The parsers, checkers and message
+ * constants behind these entry points stay internal, so they can change without a host noticing.
+ */
+export { adminSurfaceInitMessage, adminSurfaceActionResponse, type AdminSurfaceBootstrap, type AdminSurfaceInitMessage, type AdminSurfaceActionRequest, type AdminSurfaceActionFailure, type AdminSurfaceActionOutcome, type AdminSurfaceActionResponse, type AdminSurfaceOpenLinkRequest, type AdminSurfaceResizeMessage, } from './protocol.js';
+export { readAdminSurfaceTheme, adminSurfaceThemeMessage, ADMIN_SURFACE_THEME_TOKENS, type AdminSurfaceTheme, type AdminSurfaceThemeToken, type AdminSurfaceColorScheme, type AdminSurfaceThemeMessage, } from './theme.js';
+export type { AdminSurfaceActionSchema } from './action-schema.js';
+export { parseAdminSurfacesFile, type AdminSurfaceCspDirective, type AdminSurfaceAction, type AdminSurfaceDescriptor } from './descriptor.js';
+export { adminSurfaceFrameAttributes, createAdminSurfaceMount, createAdminSurfaceBootstrap, adminSurfaceBootstrapHeaders } from './sandbox.js';
+export { validateAdminSurfaceMessage, readAdminSurfaceResize, ADMIN_SURFACE_MIN_HEIGHT, ADMIN_SURFACE_MAX_HEIGHT, type AdminSurfaceMessageEvent, type AdminSurfaceMountRecord, type AdminSurfaceMessageVerdict, } from './host-validator.js';
+export { createAdminSurfaceActionDispatcher, AdminSurfaceActionError, type AdminSurfaceActionHandler } from './action-dispatcher.js';
+export { defineAdminSurfaceContribution, readAdminSurfaceFile, type LoadedAdminSurface } from './contribution.js';
+export { defineAdminSurfaceHandlerContribution, createAdminSurfaceHandlerHost, type AdminSurfaceHandlerContext, type AdminSurfacePluginContext, type AdminSurfaceBootstrapCall, type AdminSurfaceHandlerCall, type AdminSurfaceHandlerModule, type LoadedAdminSurfaceHandlers, type AdminSurfaceHostKind, } from './surface-handlers.js';
+export type { AdminSurfaceConnectionDeclaration, AdminSurfaceCapabilityDeclarations } from './capability-declarations.js';
+export { ADMIN_SURFACE_ACTION_INTENTS, ADMIN_SURFACE_STATE_LIMITS, type AdminSurfaceConnectionState, type AdminSurfaceConnectionAction, type AdminSurfaceRevocationOutcome, type AdminSurfaceConnectionStatus, type AdminSurfaceSignInAttempt, type AdminSurfaceAuthorizationStart, type AdminSurfaceConnections, type AdminSurfaceStateValue, type AdminSurfaceState, type AdminSurfacePublicConfig, type AdminSurfaceForm, type AdminSurfaceForms, type AdminSurfaceCapabilities, type AdminSurfaceCapabilitiesPort, } from './surface-capabilities.js';
+export type { AdminSurfaceDeliveryBinding, AdminSurfaceDeliveryBindingDraft, AdminSurfaceDeliveryBindingForms, AdminSurfaceDeliveryBindings, } from './delivery-bindings.js';
+export { openAdminSurfaceLink, type AdminSurfaceOpenLinkPort, type AdminSurfaceLinkVerdict } from './external-links.js';
+export { createAdminSurfaceCallbackInbox, type AdminSurfaceCallbackFieldKey } from './callback-field-inbox.js';
+export { buildAdminSurfaceActionTools, type AdminSurfaceToolSource, type AdminSurfaceToolContext } from './action-tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/admin-surfaces/index.js

@@ -0,0 +1,21 @@
+/**
+ * @file Public barrel for `@jini-ai/agent-plugins/admin-surfaces`: plugin-owned admin surfaces
+ * (sandboxed iframes) and the host-mediated action protocol. See `./README.md`.
+ *
+ * Explicit on purpose: only what a host composes is public. The parsers, checkers and message
+ * constants behind these entry points stay internal, so they can change without a host noticing.
+ */
+export { adminSurfaceInitMessage, adminSurfaceActionResponse, } from './protocol.js';
+export { readAdminSurfaceTheme, adminSurfaceThemeMessage, ADMIN_SURFACE_THEME_TOKENS, } from './theme.js';
+export { parseAdminSurfacesFile } from './descriptor.js';
+export { adminSurfaceFrameAttributes, createAdminSurfaceMount, createAdminSurfaceBootstrap, adminSurfaceBootstrapHeaders } from './sandbox.js';
+export { validateAdminSurfaceMessage, readAdminSurfaceResize, ADMIN_SURFACE_MIN_HEIGHT, ADMIN_SURFACE_MAX_HEIGHT, } from './host-validator.js';
+// AdminSurfaceActionError stays public: a host's OWN handlers throw it to send a code the surface can show.
+export { createAdminSurfaceActionDispatcher, AdminSurfaceActionError } from './action-dispatcher.js';
+export { defineAdminSurfaceContribution, readAdminSurfaceFile } from './contribution.js';
+export { defineAdminSurfaceHandlerContribution, createAdminSurfaceHandlerHost, } from './surface-handlers.js';
+export { ADMIN_SURFACE_ACTION_INTENTS, ADMIN_SURFACE_STATE_LIMITS, } from './surface-capabilities.js';
+export { openAdminSurfaceLink } from './external-links.js';
+export { createAdminSurfaceCallbackInbox } from './callback-field-inbox.js';
+export { buildAdminSurfaceActionTools } from './action-tools.js';
+//# sourceMappingURL=index.js.map

package/dist/admin-surfaces/protocol.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @file The wire vocabulary shared by the host page, the host server and a plugin's admin surface:
+ * protocol constants and the message envelopes (init, action request, open-link request, response).
+ *
+ * Why a separate file: the host-side validator, the server-side dispatcher and the docs all name the
+ * same envelope, and it must stay one definition. The surface-side client (`./surface-client.ts`)
+ * deliberately repeats the constants instead of importing them so a plugin can copy that one file;
+ * the vertical-slice test proves both sides still agree.
+ */
+import type { AdminSurfaceTheme } from './theme.js';
+/** Discriminates this protocol's messages from anything else posted to the same window. */
+export declare const ADMIN_SURFACE_PROTOCOL = "jini.admin-surface";
+export declare const ADMIN_SURFACE_PROTOCOL_VERSION = 1;
+/** The ONLY sandbox token a surface frame gets. Adding `allow-same-origin` next to `allow-scripts`
+ * lets the frame remove its own sandbox, so it is never granted. */
+export declare const ADMIN_SURFACE_SANDBOX = "allow-scripts";
+/** A frame sandboxed without `allow-same-origin` has an opaque origin, which `MessageEvent.origin`
+ * serializes as the string "null". Every sandboxed frame shares it, so origin alone never identifies
+ * a mount: the per-mount nonce and the frame's window identity do. */
+export declare const SANDBOXED_FRAME_ORIGIN = "null";
+/** Short-lived data the host server issues for one surface render (e.g. a scoped access token plus
+ * public config). Never cached (see `adminSurfaceBootstrapHeaders`), refused once `expiresAt` passes. */
+export interface AdminSurfaceBootstrap<D = unknown> {
+    readonly surfaceId: string;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly data: D;
+}
+/** Host page -> surface, once per mount, after the frame loads. Carries the mount nonce and, when
+ * the host shares them, its design tokens (`./theme.ts`; later changes arrive as `theme` messages). */
+export interface AdminSurfaceInitMessage {
+    readonly protocol: typeof ADMIN_SURFACE_PROTOCOL;
+    readonly version: typeof ADMIN_SURFACE_PROTOCOL_VERSION;
+    readonly kind: 'init';
+    readonly mountId: string;
+    readonly bootstrap?: AdminSurfaceBootstrap;
+    readonly theme?: AdminSurfaceTheme;
+}
+/** Surface -> host page. `mountId` must echo the nonce from init. */
+export interface AdminSurfaceActionRequest {
+    readonly protocol: typeof ADMIN_SURFACE_PROTOCOL;
+    readonly version: typeof ADMIN_SURFACE_PROTOCOL_VERSION;
+    readonly kind: 'action-request';
+    readonly mountId: string;
+    readonly requestId: string;
+    readonly action: string;
+    readonly payload: unknown;
+}
+/** Surface -> host page: asks the host to open `url` outside the sandbox (`./external-links.ts`).
+ * Answered with an `action-response` for `requestId`, like an action. */
+export interface AdminSurfaceOpenLinkRequest {
+    readonly protocol: typeof ADMIN_SURFACE_PROTOCOL;
+    readonly version: typeof ADMIN_SURFACE_PROTOCOL_VERSION;
+    readonly kind: 'open-link';
+    readonly mountId: string;
+    readonly requestId: string;
+    readonly url: string;
+}
+/** Surface-safe failure: `message` is written for the person using the surface and never carries a
+ * handler's raw error text, a token or a submitted value. */
+/** Surface -> host: the surface's content height in CSS pixels, so the host can size the frame to fit. */
+export interface AdminSurfaceResizeMessage {
+    readonly protocol: typeof ADMIN_SURFACE_PROTOCOL;
+    readonly version: typeof ADMIN_SURFACE_PROTOCOL_VERSION;
+    readonly kind: 'resize';
+    readonly mountId: string;
+    readonly height: number;
+}
+export interface AdminSurfaceActionFailure {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+}
+export type AdminSurfaceActionOutcome = {
+    readonly ok: true;
+    readonly result: unknown;
+} | {
+    readonly ok: false;
+    readonly error: AdminSurfaceActionFailure;
+};
+/** Host page -> surface, answering exactly one request. */
+export type AdminSurfaceActionResponse = {
+    readonly protocol: typeof ADMIN_SURFACE_PROTOCOL;
+    readonly version: typeof ADMIN_SURFACE_PROTOCOL_VERSION;
+    readonly kind: 'action-response';
+    readonly mountId: string;
+    readonly requestId: string;
+} & AdminSurfaceActionOutcome;
+/** Builds the init envelope the host page posts into a freshly loaded frame.
+ * @complexity O(1). */
+export declare function adminSurfaceInitMessage(required: {
+    readonly mountId: string;
+}, optional?: {
+    readonly bootstrap?: AdminSurfaceBootstrap;
+    readonly theme?: AdminSurfaceTheme;
+}): AdminSurfaceInitMessage;
+/** Wraps a dispatcher outcome as the response to one validated request.
+ * @complexity O(1). */
+export declare function adminSurfaceActionResponse(required: {
+    readonly request: Pick<AdminSurfaceActionRequest, 'mountId' | 'requestId'>;
+    readonly outcome: AdminSurfaceActionOutcome;
+}, _optional?: Record<string, never>): AdminSurfaceActionResponse;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/admin-surfaces/protocol.js

@@ -0,0 +1,25 @@
+/** Discriminates this protocol's messages from anything else posted to the same window. */
+export const ADMIN_SURFACE_PROTOCOL = 'jini.admin-surface';
+export const ADMIN_SURFACE_PROTOCOL_VERSION = 1;
+/** The ONLY sandbox token a surface frame gets. Adding `allow-same-origin` next to `allow-scripts`
+ * lets the frame remove its own sandbox, so it is never granted. */
+export const ADMIN_SURFACE_SANDBOX = 'allow-scripts';
+/** A frame sandboxed without `allow-same-origin` has an opaque origin, which `MessageEvent.origin`
+ * serializes as the string "null". Every sandboxed frame shares it, so origin alone never identifies
+ * a mount: the per-mount nonce and the frame's window identity do. */
+export const SANDBOXED_FRAME_ORIGIN = 'null';
+/** Builds the init envelope the host page posts into a freshly loaded frame.
+ * @complexity O(1). */
+export function adminSurfaceInitMessage(required, optional = {}) {
+    return {
+        protocol: ADMIN_SURFACE_PROTOCOL, version: ADMIN_SURFACE_PROTOCOL_VERSION, kind: 'init', mountId: required.mountId,
+        ...(optional.bootstrap ? { bootstrap: optional.bootstrap } : {}), ...(optional.theme ? { theme: optional.theme } : {}),
+    };
+}
+/** Wraps a dispatcher outcome as the response to one validated request.
+ * @complexity O(1). */
+export function adminSurfaceActionResponse(required, _optional = {}) {
+    const { mountId, requestId } = required.request;
+    return { protocol: ADMIN_SURFACE_PROTOCOL, version: ADMIN_SURFACE_PROTOCOL_VERSION, kind: 'action-response', mountId, requestId, ...required.outcome };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/admin-surfaces/sandbox.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file The isolation contract a host applies when it renders and serves an admin surface: the
+ * iframe attributes, the Content-Security-Policy and headers for each served surface file, the mount
+ * nonce, and the short-lived, never-cached bootstrap envelope.
+ *
+ * Why these are pure helpers instead of host code: every host must apply the SAME strict values, and
+ * the values are the security boundary (no same-origin, no inline script, no direct network access
+ * unless the descriptor declared and validation accepted an https origin). Hosts call these and only
+ * choose routes.
+ */
+import type { AdminSurfaceDescriptor } from './descriptor.js';
+import { type AdminSurfaceBootstrap } from './protocol.js';
+/**
+ * The attributes for the `<iframe>` that renders a surface. `sandbox` is exactly `allow-scripts`:
+ * the frame gets an opaque origin, so it cannot read the host's cookies, storage or DOM.
+ * @complexity O(1).
+ */
+export declare function adminSurfaceFrameAttributes(required: {
+    readonly src: string;
+    readonly title: string;
+}, _optional?: Record<string, never>): {
+    readonly src: string;
+    readonly title: string;
+    readonly sandbox: "allow-scripts";
+    readonly referrerPolicy: "no-referrer";
+};
+/**
+ * The CSP for every file of one surface. Starts from `default-src 'none'`; scripts, styles, images
+ * and fonts may come from the surface's own files; `connect-src` and `frame-src` are closed unless the
+ * descriptor declared validated https origins. The `sandbox` directive keeps the document sandboxed
+ * even when opened directly rather than through the host's iframe.
+ * @complexity O(c) declared CSP sources.
+ */
+export declare function adminSurfaceContentSecurityPolicy(required: {
+    readonly descriptor: Pick<AdminSurfaceDescriptor, 'csp'>;
+}, _optional?: Record<string, never>): string;
+/**
+ * Response headers for one served surface file. Script files carry `Access-Control-Allow-Origin: *`
+ * because a module script requested by an opaque-origin document is a cross-origin CORS fetch; the
+ * files are static plugin code fetched without credentials, so they must never contain secrets.
+ * @complexity O(c) declared CSP sources.
+ */
+export declare function adminSurfaceFileHeaders(required: {
+    readonly descriptor: Pick<AdminSurfaceDescriptor, 'csp'>;
+    readonly path: string;
+}, _optional?: Record<string, never>): Readonly<Record<string, string>>;
+/** One rendered surface: the nonce its messages must echo (they must also come from origin "null").
+ * @complexity O(1). */
+export declare function createAdminSurfaceMount(required: {
+    readonly surfaceId: string;
+}, optional?: {
+    readonly randomBytes?: (input: {
+        readonly length: number;
+    }) => Uint8Array;
+}): {
+    surfaceId: string;
+    mountId: string;
+};
+/**
+ * The envelope a host server returns for one surface render. Its lifetime is fixed at
+ * {@link BOOTSTRAP_TTL_MS}, not caller-chosen: bootstrap data may include a short-lived access token.
+ * @complexity O(1).
+ */
+export declare function createAdminSurfaceBootstrap<D>(required: {
+    readonly surfaceId: string;
+    readonly data: D;
+    readonly nowMs: number;
+}, _optional?: Record<string, never>): AdminSurfaceBootstrap<D>;
+/** Headers for the bootstrap response: never stored by the browser or any intermediary cache.
+ * @complexity O(1). */
+export declare function adminSurfaceBootstrapHeaders(_required?: Record<string, never>, _optional?: Record<string, never>): Readonly<Record<string, string>>;
+/** True while the bootstrap may still be used.
+ * @complexity O(1). */
+export declare function isAdminSurfaceBootstrapCurrent(required: {
+    readonly bootstrap: Pick<AdminSurfaceBootstrap, 'expiresAt'>;
+    readonly nowMs: number;
+}, _optional?: Record<string, never>): boolean;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/admin-surfaces/sandbox.js

@@ -0,0 +1,92 @@
+import { ADMIN_SURFACE_SANDBOX } from './protocol.js';
+/** Bootstrap data is meant to live for one render: one minute, fixed so no host can lengthen it. */
+const BOOTSTRAP_TTL_MS = 60_000;
+const CONTENT_TYPES = {
+    html: 'text/html; charset=utf-8',
+    mjs: 'text/javascript; charset=utf-8',
+    js: 'text/javascript; charset=utf-8',
+    css: 'text/css; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+};
+/**
+ * The attributes for the `<iframe>` that renders a surface. `sandbox` is exactly `allow-scripts`:
+ * the frame gets an opaque origin, so it cannot read the host's cookies, storage or DOM.
+ * @complexity O(1).
+ */
+export function adminSurfaceFrameAttributes(required, _optional = {}) {
+    return { src: required.src, title: required.title, sandbox: ADMIN_SURFACE_SANDBOX, referrerPolicy: 'no-referrer' };
+}
+/**
+ * The CSP for every file of one surface. Starts from `default-src 'none'`; scripts, styles, images
+ * and fonts may come from the surface's own files; `connect-src` and `frame-src` are closed unless the
+ * descriptor declared validated https origins. The `sandbox` directive keeps the document sandboxed
+ * even when opened directly rather than through the host's iframe.
+ * @complexity O(c) declared CSP sources.
+ */
+export function adminSurfaceContentSecurityPolicy(required, _optional = {}) {
+    const extra = (directive) => required.descriptor.csp[directive] ?? [];
+    const own = (directive) => [`'self'`, ...extra(directive)].join(' ');
+    const closed = (directive) => (extra(directive).length ? extra(directive).join(' ') : `'none'`);
+    return [
+        `default-src 'none'`,
+        `script-src ${own('script-src')}`,
+        `style-src ${own('style-src')}`,
+        `img-src ${own('img-src')}`,
+        `font-src ${own('font-src')}`,
+        `connect-src ${closed('connect-src')}`,
+        `frame-src ${closed('frame-src')}`,
+        `form-action 'none'`,
+        `base-uri 'none'`,
+        `frame-ancestors 'self'`,
+        `sandbox ${ADMIN_SURFACE_SANDBOX}`,
+    ].join('; ');
+}
+/**
+ * Response headers for one served surface file. Script files carry `Access-Control-Allow-Origin: *`
+ * because a module script requested by an opaque-origin document is a cross-origin CORS fetch; the
+ * files are static plugin code fetched without credentials, so they must never contain secrets.
+ * @complexity O(c) declared CSP sources.
+ */
+export function adminSurfaceFileHeaders(required, _optional = {}) {
+    const extension = required.path.slice(required.path.lastIndexOf('.') + 1);
+    const script = extension === 'mjs' || extension === 'js';
+    return {
+        'Content-Type': CONTENT_TYPES[extension] ?? 'application/octet-stream',
+        'Content-Security-Policy': adminSurfaceContentSecurityPolicy({ descriptor: required.descriptor }),
+        'X-Content-Type-Options': 'nosniff',
+        'Referrer-Policy': 'no-referrer',
+        'Cache-Control': 'no-cache',
+        ...(script ? { 'Access-Control-Allow-Origin': '*' } : {}),
+    };
+}
+/** One rendered surface: the nonce its messages must echo (they must also come from origin "null").
+ * @complexity O(1). */
+export function createAdminSurfaceMount(required, optional = {}) {
+    const randomBytes = optional.randomBytes ?? (({ length }) => globalThis.crypto.getRandomValues(new Uint8Array(length)));
+    const mountId = Array.from(randomBytes({ length: 16 }), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return { surfaceId: required.surfaceId, mountId };
+}
+/**
+ * The envelope a host server returns for one surface render. Its lifetime is fixed at
+ * {@link BOOTSTRAP_TTL_MS}, not caller-chosen: bootstrap data may include a short-lived access token.
+ * @complexity O(1).
+ */
+export function createAdminSurfaceBootstrap(required, _optional = {}) {
+    return { surfaceId: required.surfaceId, issuedAt: required.nowMs, expiresAt: required.nowMs + BOOTSTRAP_TTL_MS, data: required.data };
+}
+/** Headers for the bootstrap response: never stored by the browser or any intermediary cache.
+ * @complexity O(1). */
+export function adminSurfaceBootstrapHeaders(_required = {}, _optional = {}) {
+    return {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+        Pragma: 'no-cache',
+        'X-Content-Type-Options': 'nosniff',
+    };
+}
+/** True while the bootstrap may still be used.
+ * @complexity O(1). */
+export function isAdminSurfaceBootstrapCurrent(required, _optional = {}) {
+    return required.nowMs < required.bootstrap.expiresAt;
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/admin-surfaces/settings-value.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file The one check every plugin-written settings value passes before a host stores it: plugin
+ * state (`./surface-capabilities.ts`) and a delivery binding's config (`./delivery-bindings.ts`).
+ *
+ * Why it is shared: both are plugin-chosen JSON the host persists and later hands back (to the
+ * plugin's tools, or to the delivery adapter), so both need the same guarantees — plain JSON only,
+ * bounded depth and size, and never a token the plugin obtained — and must not drift apart.
+ */
+import { type AgentPluginCapabilityGate, type AgentPluginStateValue } from '../lifecycle/tools/capabilities.js';
+export declare const ADMIN_SURFACE_STATE_LIMITS: Readonly<{
+    maxKeyLength: 128;
+    maxValueBytes: number;
+    maxDepth: 16;
+}>;
+export declare const STATE_CREDENTIAL_MESSAGE = "The plugin tried to save a connection credential in its settings; nothing was saved.";
+/**
+ * The value the host stores: serialized once, scanned and size-checked on that text, then parsed
+ * back, so what is stored is exactly what was checked (the plugin cannot change it afterwards).
+ * @param required.gate - The call's capability gate (its token memory drives the scan).
+ * @param required.value - The plugin's value, unchecked.
+ * @throws Error when the value is not plain JSON, is too large, or mentions an obtained token.
+ * @complexity O(n) in the serialized size.
+ */
+export declare function storedStateValue(required: {
+    readonly gate: AgentPluginCapabilityGate;
+    readonly value: unknown;
+}, _optional?: Record<string, never>): AgentPluginStateValue;
+//# sourceMappingURL=settings-value.d.ts.map