@jini-ai/agent-plugins 0.4.7 → 0.6.10

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/protocol.ts"],"names":[],"mappings":"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"}

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/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/admin-surfaces/protocol.ts"],"names":[],"mappings":"AAWA,2FAA2F;AAC3F,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAC3D,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAEhD;oEACoE;AACpE,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAErD;;sEAEsE;AACtE,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AA0E7C;uBACuB;AACvB,MAAM,UAAU,uBAAuB,CAAC,QAAsC,EAAE,WAA+F,EAAE;IAC/K,OAAO;QACL,QAAQ,EAAE,sBAAsB,EAAE,OAAO,EAAE,8BAA8B,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO;QAClH,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvH,CAAC;AACJ,CAAC;AAED;uBACuB;AACvB,MAAM,UAAU,0BAA0B,CAAC,QAAqI,EAAE,YAAmC,EAAE;IACrN,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC;IAChD,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,OAAO,EAAE,8BAA8B,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;AACzJ,CAAC"}

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAalF;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM;;;;;EAE5I;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,MAAM,CAiBvK;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAW9M;AAED;uBACuB;AACvB,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACxC,QAAQ,GAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,UAAU,CAAA;CAAO;;;EAK7F;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,QAAQ,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAElM;AAED;uBACuB;AACvB,wBAAgB,4BAA4B,CAAC,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAO3J;AAED;uBACuB;AACvB,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,OAAO,CAEjM"}

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/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/admin-surfaces/sandbox.ts"],"names":[],"mappings":"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"}

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"settings-value.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/settings-value.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAA+B,KAAK,yBAAyB,EAAE,KAAK,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAE7I,eAAO,MAAM,0BAA0B;;;;EAAuG,CAAC;AAC/I,eAAO,MAAM,wBAAwB,yFAAyF,CAAC;AAe/H;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,qBAAqB,CAO9K"}

package/dist/admin-surfaces/settings-value.js

@@ -0,0 +1,45 @@
+/**
+ * @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 { PLUGIN_STATE_MAX_KEY_LENGTH } from '../lifecycle/tools/capabilities.js';
+export const ADMIN_SURFACE_STATE_LIMITS = Object.freeze({ maxKeyLength: PLUGIN_STATE_MAX_KEY_LENGTH, maxValueBytes: 16 * 1024, maxDepth: 16 });
+export const STATE_CREDENTIAL_MESSAGE = 'The plugin tried to save a connection credential in its settings; nothing was saved.';
+function isStateScalar(value) {
+    return value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+}
+/** True for plain JSON data only: no undefined, functions, NaN, class instances or deep nesting. @complexity O(n) nodes. */
+function isStateValue(value, depth) {
+    if (isStateScalar(value))
+        return true;
+    if (typeof value !== 'object' || depth >= ADMIN_SURFACE_STATE_LIMITS.maxDepth)
+        return false;
+    if (Array.isArray(value))
+        return value.every((item) => isStateValue(item, depth + 1));
+    const prototype = Object.getPrototypeOf(value);
+    return (prototype === Object.prototype || prototype === null) && Object.values(value).every((item) => isStateValue(item, depth + 1));
+}
+/**
+ * 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 function storedStateValue(required, _optional = {}) {
+    const { gate, value } = required;
+    if (!isStateValue(value, 0))
+        throw new Error('A settings value must be plain JSON data (no undefined, functions, NaN or class instances).');
+    const text = JSON.stringify(value);
+    if (new TextEncoder().encode(text).byteLength > ADMIN_SURFACE_STATE_LIMITS.maxValueBytes)
+        throw new Error(`A settings value may be at most ${ADMIN_SURFACE_STATE_LIMITS.maxValueBytes} bytes of JSON.`);
+    if (gate.mentionsToken({ value: text }))
+        throw new Error(STATE_CREDENTIAL_MESSAGE);
+    return JSON.parse(text);
+}
+//# sourceMappingURL=settings-value.js.map

package/dist/admin-surfaces/settings-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-value.js","sourceRoot":"","sources":["../../src/admin-surfaces/settings-value.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,2BAA2B,EAA8D,MAAM,oCAAoC,CAAC;AAE7I,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,2BAA2B,EAAE,aAAa,EAAE,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;AAC/I,MAAM,CAAC,MAAM,wBAAwB,GAAG,sFAAsF,CAAC;AAE/H,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5I,CAAC;AAED,4HAA4H;AAC5H,SAAS,YAAY,CAAC,KAAc,EAAE,KAAa;IACjD,IAAI,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,0BAA0B,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5F,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACtF,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,CAAC,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAe,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;AACjJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA+E,EAAE,YAAmC,EAAE;IACrJ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC;IACjC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6FAA6F,CAAC,CAAC;IAC5I,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,0BAA0B,CAAC,aAAa;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,0BAA0B,CAAC,aAAa,iBAAiB,CAAC,CAAC;IACxM,IAAI,IAAI,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACnF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAA0B,CAAC;AACnD,CAAC"}

package/dist/admin-surfaces/surface-capabilities.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @file The host capability ports a plugin's admin-surface handlers receive, and the per-call
+ * session that wraps them. Jini defines the shapes and the checks; the host implements the ports
+ * (connections backed by its API-connection service, state by its own store, public config by its
+ * own settings) and Jini never names a provider.
+ *
+ * Why surfaces get more than tools: account actions (connect, reconnect, switch account, disconnect)
+ * and saving a chosen resource are admin actions a person takes on a settings screen, so they exist
+ * here and never on the executable-tool port. Why every check sits here and not only in the host:
+ * the surfaces file is the shipped, digest-checked allowlist, so the session refuses anything the
+ * surface did not declare (a connection, a start parameter, a callback field, a config name) before
+ * the host sees it, and a host that answers with more than the port promises (a connection ref, raw
+ * scopes, undeclared callback fields) is cut back to the declared shape. Like the tool session it
+ * revokes everything once the plugin is disabled and withholds results and errors that mention a
+ * token the plugin obtained (in this call, an earlier one, or one of its tools); it also refuses to persist
+ * such a token in plugin state.
+ */
+import { type AgentPluginStateReader, type AgentPluginStateValue, type AgentPluginToolCapabilities, type AgentPluginToolCapabilityScope, type IssuedTokenMemory } from '../lifecycle/tools/capabilities.js';
+import type { AdminSurfaceCapabilityDeclarations } from './capability-declarations.js';
+import { type AdminSurfaceDeliveryBindings } from './delivery-bindings.js';
+export { ADMIN_SURFACE_STATE_LIMITS, STATE_CREDENTIAL_MESSAGE } from './settings-value.js';
+/** Mirrors the API-connection lifecycle (`ApiConnectionStatus`); only `connected` serves access tokens. */
+export type AdminSurfaceConnectionState = 'connected' | 'reconnect-required' | 'revocation-pending' | 'disconnected';
+/**
+ * The API-connection start intent each account action maps to (`ApiConnectionIntent` in
+ * `@jini-ai/integrations/api-connections`, mirrored because agent-plugins does not depend on it), so a
+ * host passes `ADMIN_SURFACE_ACTION_INTENTS[action]` straight to `start`. `reconnect` and `add-scopes`
+ * are a same-account `connect` with the scope sets the handler passes (`add-scopes` re-consents for
+ * more of them); `switch` stages another account.
+ */
+export declare const ADMIN_SURFACE_ACTION_INTENTS: Readonly<{
+    readonly connect: "connect";
+    readonly reconnect: "connect";
+    readonly switch: "switch-account";
+    readonly 'add-scopes': "connect";
+}>;
+export type AdminSurfaceConnectionAction = keyof typeof ADMIN_SURFACE_ACTION_INTENTS;
+/**
+ * The honest remote outcome of a disconnect, the same values as `ApiConnectionRemoteRevocation`:
+ * never `confirmed` unless the provider confirmed it.
+ */
+export type AdminSurfaceRevocationOutcome = 'confirmed' | 'pending' | 'not-needed';
+/** Token-free status. Scope sets are the plugin's own ids, never raw provider scopes. */
+export interface AdminSurfaceConnectionStatus {
+    readonly connectionId: string;
+    readonly status: AdminSurfaceConnectionState;
+    readonly accountLabel: string | null;
+    readonly grantedScopeSetIds: readonly string[];
+    /** The account a staged switch would move to, awaiting `confirmSwitch`. */
+    readonly pendingSwitchAccountLabel: string | null;
+    /** Why the latest sign-in did not complete and what to do next, as the HOST's own lowercase
+     *  hyphenated codes (for example `access-denied` / `reconnect`), never provider text; `null` when
+     *  the latest attempt succeeded or none is recorded. A value that is not a safe code becomes `null`. */
+    readonly lastSignInAttempt: AdminSurfaceSignInAttempt | null;
+}
+/** The outcome codes of a sign-in attempt that did not complete. */
+export interface AdminSurfaceSignInAttempt {
+    readonly code: string;
+    readonly nextAction: string;
+}
+/** A sign-in the person opens (a button on hosted, the system browser on desktop). */
+export interface AdminSurfaceAuthorizationStart {
+    readonly authorizationUrl: string;
+    /** Opaque id for `takeCallbackFields` once the sign-in completed: the connection service's attempt
+     *  id, never the authorization `state`. */
+    readonly attemptId: string;
+    readonly expiresAt: string;
+}
+export interface AdminSurfaceConnections {
+    /** A fresh access token for one of the surface's declared connections; never a refresh token. */
+    getAccessToken(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<string>;
+    status(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus>;
+    begin(required: {
+        readonly connectionId: string;
+        readonly action: AdminSurfaceConnectionAction;
+    }, optional?: {
+        readonly scopeSetIds?: readonly string[];
+        readonly startParams?: Readonly<Record<string, string>>;
+    }): Promise<AdminSurfaceAuthorizationStart>;
+    confirmSwitch(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus>;
+    cancelSwitch(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus>;
+    disconnect(required: {
+        readonly connectionId: string;
+    }, optional?: Record<string, never>): Promise<AdminSurfaceConnectionStatus & {
+        readonly revocation: AdminSurfaceRevocationOutcome;
+    }>;
+    /** The declared callback fields of a completed sign-in, once; `null` when absent, taken or not completed.
+     *  Still untrusted: verify them through the provider's API before saving anything. */
+    takeCallbackFields(required: {
+        readonly connectionId: string;
+        readonly attemptId: string;
+    }, optional?: Record<string, never>): Promise<Readonly<Record<string, string>> | null>;
+}
+export type AdminSurfaceStateValue = AgentPluginStateValue;
+/** Plugin- and workspace-scoped JSON values (the host keys them by the session's scope). The plugin's
+ *  tools read the same store through the read-only `AgentPluginStateReader`; only surfaces write. */
+export interface AdminSurfaceState extends AgentPluginStateReader {
+    set(required: {
+        readonly key: string;
+        readonly value: AdminSurfaceStateValue;
+    }, optional?: Record<string, never>): Promise<void>;
+    delete(required: {
+        readonly key: string;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+/** Host-supplied public values (an app id, a browser key) for names the surface declares; `null` when unset. */
+export interface AdminSurfacePublicConfig {
+    get(required: {
+        readonly name: string;
+    }, optional?: Record<string, never>): Promise<string | null>;
+}
+/** Only form identity and display text, never fields, recipients or submission data. */
+export interface AdminSurfaceForm {
+    readonly slug: string;
+    readonly title: string;
+}
+/** Workspace-scoped discovery. The session returns at most 200 choices; titles are capped at 1024 characters. */
+export interface AdminSurfaceForms {
+    list(required: Record<string, never>, optional?: Record<string, never>): Promise<readonly AdminSurfaceForm[]>;
+}
+export type AdminSurfaceCapabilities = Pick<AgentPluginToolCapabilities, 'http' | 'limiter' | 'artifacts'> & {
+    readonly connections: AdminSurfaceConnections;
+    readonly state: AdminSurfaceState;
+    readonly publicConfig: AdminSurfacePublicConfig;
+    /** The workspace's form-delivery bindings (`./delivery-bindings.ts`). Optional for the host; a handler
+     *  gets it only when its surface declares `deliveryAdapters` and the host provides it. */
+    readonly deliveryBindings?: AdminSurfaceDeliveryBindings;
+    /** Absent unless both the host supplies it and this surface declares `forms: ["list"]`. */
+    readonly forms?: AdminSurfaceForms;
+};
+/** Host port: builds one call's capabilities for the loaded plugin, workspace and admin principal. */
+export type AdminSurfaceCapabilitiesPort = (required: AgentPluginToolCapabilityScope, optional?: Record<string, never>) => AdminSurfaceCapabilities;
+/**
+ * Opens the capability session for one admin-surface handler call.
+ * @param required.capabilities - The host's ports for this call (already scoped to plugin, workspace, principal).
+ * @param required.isLive - False once the plugin's surface handlers are revoked.
+ * @param required.declared - The surface's own capability declarations (the allowlists).
+ * @param required.issued - The plugin's token memory, shared by all its calls (tools included).
+ * @param optional.actorId - The signed-in admin; account actions are refused without one.
+ * @returns Wrapped capabilities plus the shared `release` (result) and `sanitize` (error) gates.
+ * @complexity O(1) to open; each check is bounded by the declared lists and the value caps.
+ */
+export declare function openAdminSurfaceCapabilitySession(required: {
+    readonly capabilities: AdminSurfaceCapabilities;
+    readonly isLive: () => boolean;
+    readonly declared: AdminSurfaceCapabilityDeclarations;
+    readonly issued: IssuedTokenMemory;
+}, optional?: {
+    readonly actorId?: string;
+}): {
+    capabilities: AdminSurfaceCapabilities;
+    release: <T>({ value }: {
+        readonly value: T;
+    }) => T;
+    sanitize: ({ error }: {
+        readonly error: unknown;
+    }) => unknown;
+};
+//# sourceMappingURL=surface-capabilities.d.ts.map

package/dist/admin-surfaces/surface-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-capabilities.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/surface-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAE2B,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,8BAA8B,EAC9J,KAAK,iBAAiB,EACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,kCAAkC,EAAqC,MAAM,8BAA8B,CAAC;AAC1H,OAAO,EAAyB,KAAK,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AAIlG,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,2GAA2G;AAC3G,MAAM,MAAM,2BAA2B,GAAG,WAAW,GAAG,oBAAoB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AAErH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;;;;EAE9B,CAAC;AACZ,MAAM,MAAM,4BAA4B,GAAG,MAAM,OAAO,4BAA4B,CAAC;AACrF;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;AAEnF,yFAAyF;AACzF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,2EAA2E;IAC3E,QAAQ,CAAC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD;;4GAEwG;IACxG,QAAQ,CAAC,iBAAiB,EAAE,yBAAyB,GAAG,IAAI,CAAC;CAC9D;AAED,oEAAoE;AACpE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,sFAAsF;AACtF,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;+CAC2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,iGAAiG;IACjG,cAAc,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/G,MAAM,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IAC7H,KAAK,CACH,QAAQ,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAA;KAAE,EAC1F,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;KAAE,GAC/G,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC3C,aAAa,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACpI,YAAY,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACnI,UAAU,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,4BAA4B,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAA;KAAE,CAAC,CAAC;IAC1L;0FACsF;IACtF,kBAAkB,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CACjL;AAED,MAAM,MAAM,sBAAsB,GAAG,qBAAqB,CAAC;AAE3D;qGACqG;AACrG,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,GAAG,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjI,MAAM,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7F;AAED,gHAAgH;AAChH,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpG;AAED,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,iHAAiH;AACjH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC;CAC/G;AAED,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,2BAA2B,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC,GAAG;IAC3G,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;IAChD;8FAC0F;IAC1F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,4BAA4B,CAAC;IACzD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CACpC,CAAC;AAEF,sGAAsG;AACtG,MAAM,MAAM,4BAA4B,GAAG,CAAC,QAAQ,EAAE,8BAA8B,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,wBAAwB,CAAC;AAmKpJ;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE;IACR,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,kCAAkC,CAAC;IACvI,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC,EACD,QAAQ,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO;;;;;;;;EAiB7C"}