@jini-ai/agent-plugins 0.4.7 → 0.6.10

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.6.10
+
+## 0.4.8 — 2026-10-22
+
+- 2026-10-22: Provider contributions refuse failures by default (core peer floor ^0.4.9), durable update transaction for operator-installed plugins, coverage.
+
+- `./lifecycle`: `defineProviderContribution()` wraps `defineExecutablePluginContribution` so a bundled plugin can contribute a provider for `@jini-ai/core/provider-registry` (id checked before import), and `contributeProviders()` merges loader and registry refusals. Needs `@jini-ai/core` with `./provider-registry`: the peer range is raised to `^0.4.9` (the first core release carrying that subpath), so release core 0.4.9 before this. Without recovery policies, an unreadable manifest, a throwing module/validator/parser or a hostile descriptor is now a refusal line (never a throw), so one broken plugin no longer discards the healthy contributions loaded with it.
+
+## Unreleased — compatibility and advisory requirements
+
+- Uses `semver`, the same library as site plugins (`@jini-ai/plugins` checks `sdkRange` with
+  `semver.satisfies`), for `hostRange` and update ordering. Declared the way site plugins declare it
+  (optional peer + dev dependency, as `pnpm guard`'s subpath isolation requires): hosts that parse
+  manifests or use `./lifecycle` must install `semver@^7.6.2`.
+- `extensions.<ns>.hostRange` is checked against `AGENT_PLUGIN_CONTRACT_VERSION` (the host's Agent
+  Plugin contract, not an app version). A malformed range is listable with a parse warning but is
+  incompatible: `setAgentPluginEnabled({ enabled: true })` throws `AgentPluginHostIncompatibleError`
+  (`PLUGIN_HOST_INCOMPATIBLE`). Disabling is never refused.
+- `extensions.<ns>.requires` (capability ids) is advisory and computed live from other active
+  plugins: enabling returns `warnings: ['Needs <cap>']`; disabling a provider returns
+  `'<dependent> needs <cap>'`. Never blocks.
+- `setAgentPluginEnabled` now runs under the per-plugin state lock shared with install/update/uninstall.
+- `planAgentPluginUpdate()`: manifest semver orders releases, the digest identifies bytes.
+
 ## 0.4.7 — 2026-10-15 — folder uploads share one ZIP encoder
 
 - New `./folder-zip` (universal): `zipFolderFiles()`, the binary-safe stored-mode folder encoder,
@@ -66,7 +90,6 @@
   rationale alongside the canonical implementations; move the URL-install real-HTTP/ZIP
   integration suite into the package and add paired metadata-translation regression cases.
 
-
 ## Unreleased — lifecycle test compilation
 
 - Preserve copied test timeouts and conditional skips through Vitest registration.
@@ -94,7 +117,6 @@
 - Native liveness treats only ESRCH as death; unknown probe failures never authorize stale-owner eviction.
 - Archive-error specification now matches safe generic transport/body causes and redacted URL diagnostics.
 
-
 ## Unreleased
 
 - Add the host-injected plugin lifecycle on `./lifecycle`: archive installation, activation and locks, bundled digests and seeding/retirement, trusted files, reference resolution and local ranking.

package/README.md

@@ -108,11 +108,40 @@ Catalog format) that this package does not implement.
 | `./lifecycle/yauzl` | node | `createYauzlAgentPluginArchiveReader({ yauzl })`; the host supplies the optional peer library. |
 | `./folder-zip` | universal | `zipFolderFiles({ files, maxBytes })`: packs picked folder `File`s into one stored-mode, binary-safe `.zip` `File` (the admin "Upload a folder" encoder). |
 | `./folder-zip/node` | node | `zipLocalFolder({ path, maxBytes })`: the same encoder over a local folder; refuses symlinks/special files, bounds entries and bytes. |
+| `./admin-surfaces` | universal | Plugin-owned admin surfaces: the contribution definition (host-named file), sandboxed-iframe/CSP/bootstrap helpers, the host-page message gate and the server-side action dispatcher. See "Admin surfaces" below. |
+| `./admin-surfaces/client` | universal | `createAdminSurfaceClient(...)`: the self-contained surface-side protocol client a plugin's UI imports or copies. |
 | `./ui-ux-design/*` | — | Raw files of the bundled `ui-ux-design` plugin — static JSON/Markdown, not run through the TS build. |
 
 The universal root handles structural validation. The separate Node lifecycle entry implements
 local archive installation and host-owned activation policy; it does not implement remote catalog discovery.
 
+## Admin surfaces
+
+A plugin can ship its own admin UI as static files the host renders in an
+`<iframe sandbox="allow-scripts">` (never `allow-same-origin`). The surface has no server access:
+it posts `action-request` messages, the host page checks origin (`"null"` for a sandboxed frame),
+frame window, per-mount nonce, declared action and input schema, and forwards the request to a host
+route whose dispatcher runs a host-provided handler. Full format, protocol and API:
+[`src/admin-surfaces/README.md`](src/admin-surfaces/README.md).
+
+Contribution file (the host names it, e.g. `<product>-admin-surfaces.json`, and passes it to
+`defineAdminSurfaceContribution({ filename })`):
+
+```json
+{ "schemaVersion": 1, "surfaces": [ {
+  "id": "connection-settings", "title": "Connection settings",
+  "entry": "surface/index.html", "files": ["surface/app.mjs"],
+  "actions": [ { "name": "save-selection", "input": { "type": "object", "properties": { "resourceId": { "type": "string" } }, "required": ["resourceId"] } } ],
+  "csp": { "connect-src": ["https://api.example.com"] }
+} ] }
+```
+
+Messages (all carry `protocol: "jini.admin-surface", version: 1`):
+`init { mountId, bootstrap? }` host → frame once; `action-request { mountId, requestId, action, payload }`
+frame → host; `action-response { mountId, requestId, ok, result | error: { code, message, retryable } }`
+host → frame. Bootstrap data is short-lived (`expiresAt`, one minute) and served with
+`Cache-Control: no-store`.
+
 ## Not this package: `@jini-ai/plugins` (`./host`)
 
 `@jini-ai/plugins` is a **different, sibling package** — Jini's own host-extension plugin format
@@ -280,3 +309,20 @@ as plugin ids so package state cannot overlap migration inputs or installation s
 
 The `dev.tovu.memory` proposal is consumer policy and is not implemented by this neutral entry.
 No version bump or publishing accompanies this workspace implementation.
+
+Admin-screen actions can also be assistant tools. Declare `effect: "read" | "write" |
+"destructive"` on each action in the host-named admin-surfaces contribution file;
+omitting it means `write`. `buildAdminSurfaceActionTools` projects every declared
+action as `<surface>_<action>` (hyphens become underscores); pass the returned
+`additionalTools` to `createAgentPluginToolProjection.sync` alongside executable
+tools. The host's existing plugin registry supplies the `p_<plugin>__` namespace.
+Calls accept `{ payload: <declared input> }`, so object and scalar actions share
+one tool envelope. The existing screen dispatcher validates input/results and
+calls the same admitted handler host with the same scoped capabilities.
+
+Bind the adapter's authorization port to the screen action permission and a fresh
+active/trusted surface lookup, then use the host's existing confirmation policy
+for writes and destructive actions. Set discovery `readOnly`/`sideEffects` from
+the effect. Sync after activation changes: absent actions are withdrawn and held
+handlers are revoked. A host may collect its issued sign-in URLs around dispatch;
+return those URLs for the assistant to show. This adapter never opens a browser.

package/dist/admin-surfaces/action-dispatcher.d.ts

@@ -0,0 +1,37 @@
+import type { AdminSurfaceDescriptor } from './descriptor.js';
+import type { AdminSurfaceActionOutcome } from './protocol.js';
+/** Thrown by a handler to send a specific, surface-safe failure. Any other throw becomes `action-failed`. */
+export declare class AdminSurfaceActionError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(required: {
+        readonly code: string;
+        readonly message: string;
+    }, optional?: {
+        readonly retryable?: boolean;
+        readonly cause?: unknown;
+    });
+}
+/** A host-provided implementation of one declared action. `context` is whatever the host route
+ * established (workspace, signed-in user); the surface never supplies it. */
+export type AdminSurfaceActionHandler<C> = (required: {
+    readonly payload: unknown;
+    readonly context: C;
+}) => Promise<unknown>;
+export declare function createAdminSurfaceActionDispatcher<C>(required: {
+    readonly descriptor: Pick<AdminSurfaceDescriptor, 'id' | 'actions'>;
+    readonly handlers: Readonly<Record<string, AdminSurfaceActionHandler<C>>>;
+}, optional?: {
+    readonly onHandlerError?: (input: {
+        readonly surfaceId: string;
+        readonly action: string;
+        readonly error: unknown;
+    }) => void;
+}): {
+    dispatch: (input: {
+        readonly action: string;
+        readonly payload: unknown;
+        readonly context: C;
+    }) => Promise<AdminSurfaceActionOutcome>;
+};
+//# sourceMappingURL=action-dispatcher.d.ts.map

package/dist/admin-surfaces/action-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-dispatcher.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/action-dispatcher.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAA6B,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1F,6GAA6G;AAC7G,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAChB,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,GAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMrJ;AAED;6EAC6E;AAC7E,MAAM,MAAM,yBAAyB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;CAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAuB9H,wBAAgB,kCAAkC,CAAC,CAAC,EAClD,QAAQ,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,sBAAsB,EAAE,IAAI,GAAG,SAAS,CAAC,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;CAAE,EAC5J,QAAQ,GAAE;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;CAAO;sBAI/G;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,KAAG,OAAO,CAAC,yBAAyB,CAAC;EAmBhJ"}

package/dist/admin-surfaces/action-dispatcher.js

@@ -0,0 +1,69 @@
+/**
+ * @file The server-side mediator between a surface's action requests and the host's handlers.
+ *
+ * Why it exists: a plugin surface never talks to the server directly; the host page forwards each
+ * validated request to a host route, and that route calls this dispatcher. It is the authoritative
+ * check (the browser-side gate can be bypassed by calling the route directly): only declared actions
+ * run, only with schema-valid input, and a handler's raw error never reaches the surface.
+ */
+import { exceedsAdminSurfacePayloadLimit, validateAdminSurfaceActionValue } from './action-schema.js';
+/** Thrown by a handler to send a specific, surface-safe failure. Any other throw becomes `action-failed`. */
+export class AdminSurfaceActionError extends Error {
+    code;
+    retryable;
+    constructor(required, optional = {}) {
+        super(required.message, optional.cause === undefined ? undefined : { cause: optional.cause });
+        this.name = 'AdminSurfaceActionError';
+        this.code = required.code;
+        this.retryable = optional.retryable ?? false;
+    }
+}
+const failure = (code, message, retryable = false) => ({ ok: false, error: { code, message, retryable } });
+/** Maps a handler throw to a surface-safe failure. @complexity O(1). */
+function handlerFailure(error) {
+    if (error instanceof AdminSurfaceActionError)
+        return { code: error.code, message: error.message, retryable: error.retryable };
+    return { code: 'action-failed', message: 'The action failed. Try again; if it keeps failing, check the server log.', retryable: true };
+}
+/**
+ * Binds one surface's declared actions to host handlers.
+ * @param required.handlers - Keyed by action name; a declared action without a handler answers `action-unavailable`.
+ * @param optional.onHandlerError - Hears every handler throw (with its cause) for server-side logging.
+ * @complexity O(p) per dispatch in the payload and result sizes, plus the handler's own cost.
+ */
+/** Why `payload` cannot reach the handler (too large, or outside the action's input), or null. @complexity O(payload size). */
+function payloadRefusal(schema, payload) {
+    if (exceedsAdminSurfacePayloadLimit({ payload }))
+        return failure('invalid-payload', 'The request is too large.');
+    const violation = validateAdminSurfaceActionValue({ schema, value: payload });
+    return violation === null ? null : failure('invalid-payload', `The request does not match the action's input: ${violation}.`);
+}
+export function createAdminSurfaceActionDispatcher(required, optional = {}) {
+    const { descriptor, handlers } = required;
+    /** Runs one request. Never throws for a handler fault. */
+    async function dispatch(input) {
+        const action = descriptor.actions.find((declared) => declared.name === input.action);
+        if (action === undefined)
+            return failure('action-undeclared', 'This surface did not declare that action.');
+        const handler = Object.hasOwn(handlers, action.name) ? handlers[action.name] : undefined;
+        if (handler === undefined)
+            return failure('action-unavailable', 'This action is not available on this host.');
+        const refused = payloadRefusal(action.input, input.payload);
+        if (refused !== null)
+            return refused;
+        let result;
+        try {
+            result = await handler({ payload: input.payload, context: input.context });
+        }
+        catch (error) {
+            optional.onHandlerError?.({ surfaceId: descriptor.id, action: action.name, error });
+            return { ok: false, error: handlerFailure(error) };
+        }
+        if (action.result !== undefined && validateAdminSurfaceActionValue({ schema: action.result, value: result }) !== null) {
+            return failure('invalid-result', 'The host returned a result this surface did not declare.');
+        }
+        return { ok: true, result };
+    }
+    return { dispatch };
+}
+//# sourceMappingURL=action-dispatcher.js.map

package/dist/admin-surfaces/action-dispatcher.js.map

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

package/dist/admin-surfaces/action-schema.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file A deliberately small, closed subset of JSON Schema for admin-surface action inputs and
+ * results: checked once when the descriptor is parsed, then used to validate every payload.
+ *
+ * Why not full JSON Schema: a surface's payload crosses a trust boundary (plugin UI -> host
+ * handler), so the schema language is fail-closed. An unknown keyword refuses the descriptor
+ * instead of being ignored (a plugin cannot rely on `pattern` or `format` that would silently pass),
+ * objects are closed (no undeclared keys reach a handler), and every node must name its `type`.
+ * Violation messages name the path only, never the value, so a rejected payload cannot echo a secret.
+ */
+export type AdminSurfaceActionSchema = {
+    readonly type: 'object';
+    readonly properties?: Readonly<Record<string, AdminSurfaceActionSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: false;
+} | {
+    readonly type: 'array';
+    readonly items: AdminSurfaceActionSchema;
+    readonly maxItems?: number;
+} | {
+    readonly type: 'string';
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly enum?: readonly string[];
+} | {
+    readonly type: 'number' | 'integer';
+    readonly minimum?: number;
+    readonly maximum?: number;
+} | {
+    readonly type: 'boolean' | 'null';
+};
+/**
+ * Why a declared schema is unusable, or `null` when it is a valid member of the subset.
+ * @complexity O(n) schema nodes; recursion bounded by {@link MAX_DEPTH}.
+ */
+export declare function checkAdminSurfaceActionSchema(required: {
+    readonly schema: unknown;
+}, optional?: {
+    readonly depth?: number;
+}): string | null;
+/**
+ * The first place `value` violates a schema that passed {@link checkAdminSurfaceActionSchema}, or
+ * `null` when it conforms. The message names a path such as `$.rows[2]`, never the offending value.
+ * @complexity O(v) values visited.
+ */
+export declare function validateAdminSurfaceActionValue(required: {
+    readonly schema: AdminSurfaceActionSchema;
+    readonly value: unknown;
+}, optional?: {
+    readonly path?: string;
+}): string | null;
+/** True when `payload` serializes to more than 64 KiB of JSON text, or cannot be serialized. @complexity O(payload size). */
+export declare function exceedsAdminSurfacePayloadLimit(required: {
+    readonly payload: unknown;
+}, _optional?: Record<string, never>): boolean;
+//# sourceMappingURL=action-schema.d.ts.map

package/dist/admin-surfaces/action-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-schema.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/action-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,KAAK,CAAA;CAAE,GACnL;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAChG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACxH;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7F;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC;AA0B1C;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,GAAG,IAAI,CAU/I;AAsCD;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,GAAG,IAAI,CAG1L;AAuDD,6HAA6H;AAC7H,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,OAAO,CAEvI"}

package/dist/admin-surfaces/action-schema.js

@@ -0,0 +1,167 @@
+/**
+ * @file A deliberately small, closed subset of JSON Schema for admin-surface action inputs and
+ * results: checked once when the descriptor is parsed, then used to validate every payload.
+ *
+ * Why not full JSON Schema: a surface's payload crosses a trust boundary (plugin UI -> host
+ * handler), so the schema language is fail-closed. An unknown keyword refuses the descriptor
+ * instead of being ignored (a plugin cannot rely on `pattern` or `format` that would silently pass),
+ * objects are closed (no undeclared keys reach a handler), and every node must name its `type`.
+ * Violation messages name the path only, never the value, so a rejected payload cannot echo a secret.
+ */
+const MAX_DEPTH = 8;
+/** Applies when an array schema declares no `maxItems`, so no payload is unbounded. */
+const DEFAULT_MAX_ITEMS = 1000;
+const ANNOTATIONS = ['type', 'title', 'description'];
+const KEYWORDS = {
+    object: ['properties', 'required', 'additionalProperties'],
+    array: ['items', 'maxItems'],
+    string: ['minLength', 'maxLength', 'enum'],
+    number: ['minimum', 'maximum'],
+    integer: ['minimum', 'maximum'],
+    boolean: [],
+    null: [],
+};
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+const isCount = (value) => value === undefined || (Number.isInteger(value) && value >= 0);
+const isBound = (value) => value === undefined || (typeof value === 'number' && Number.isFinite(value));
+/**
+ * Why a declared schema is unusable, or `null` when it is a valid member of the subset.
+ * @complexity O(n) schema nodes; recursion bounded by {@link MAX_DEPTH}.
+ */
+export function checkAdminSurfaceActionSchema(required, optional = {}) {
+    const { schema } = required;
+    const depth = optional.depth ?? 0;
+    if (!isPlainObject(schema))
+        return 'must be an object';
+    if (depth > MAX_DEPTH)
+        return `nests deeper than ${MAX_DEPTH} levels`;
+    const type = schema.type;
+    if (typeof type !== 'string' || !Object.hasOwn(KEYWORDS, type))
+        return 'must declare a supported type';
+    const unknown = Object.keys(schema).find((key) => !ANNOTATIONS.includes(key) && !KEYWORDS[type].includes(key));
+    if (unknown !== undefined)
+        return `uses unsupported keyword '${unknown}'`;
+    return checkKeywords(schema, type, depth);
+}
+/** @complexity O(n) child schema nodes. */
+function checkKeywords(schema, type, depth) {
+    if (type === 'object')
+        return checkObject(schema, depth);
+    if (type === 'array')
+        return checkArray(schema, depth);
+    if (type === 'string')
+        return checkString(schema);
+    if (type === 'number' || type === 'integer')
+        return isBound(schema.minimum) && isBound(schema.maximum) ? null : 'minimum/maximum must be finite numbers';
+    return null;
+}
+function checkObject(schema, depth) {
+    const properties = schema.properties ?? {};
+    if (!isPlainObject(properties))
+        return 'properties must be an object';
+    if (schema.additionalProperties !== undefined && schema.additionalProperties !== false)
+        return 'additionalProperties may only be false (objects are closed)';
+    if (!listsDeclaredKeys(schema.required ?? [], properties))
+        return 'required must list declared properties';
+    for (const [key, child] of Object.entries(properties)) {
+        const reason = checkAdminSurfaceActionSchema({ schema: child }, { depth: depth + 1 });
+        if (reason !== null)
+            return `property '${key}' ${reason}`;
+    }
+    return null;
+}
+const listsDeclaredKeys = (required, properties) => Array.isArray(required) && required.every((key) => typeof key === 'string' && Object.hasOwn(properties, key));
+function checkArray(schema, depth) {
+    if (!isCount(schema.maxItems))
+        return 'maxItems must be a non-negative integer';
+    const reason = checkAdminSurfaceActionSchema({ schema: schema.items }, { depth: depth + 1 });
+    return reason === null ? null : `items ${reason}`;
+}
+function checkString(schema) {
+    if (!isCount(schema.minLength) || !isCount(schema.maxLength))
+        return 'minLength/maxLength must be non-negative integers';
+    const values = schema.enum;
+    if (values === undefined)
+        return null;
+    return Array.isArray(values) && values.length > 0 && values.every((value) => typeof value === 'string') ? null : 'enum must be a non-empty list of strings';
+}
+/**
+ * The first place `value` violates a schema that passed {@link checkAdminSurfaceActionSchema}, or
+ * `null` when it conforms. The message names a path such as `$.rows[2]`, never the offending value.
+ * @complexity O(v) values visited.
+ */
+export function validateAdminSurfaceActionValue(required, optional = {}) {
+    const validate = VALIDATORS[required.schema.type];
+    return validate(required.schema, required.value, optional.path ?? '$');
+}
+function validateObject(schema, value, path) {
+    if (!isPlainObject(value))
+        return `${path} must be an object`;
+    const properties = schema.properties ?? {};
+    const extra = Object.keys(value).find((key) => !Object.hasOwn(properties, key));
+    if (extra !== undefined)
+        return `${path} has an undeclared property ${JSON.stringify(extra.slice(0, 64))}`;
+    const missing = (schema.required ?? []).find((key) => !Object.hasOwn(value, key));
+    if (missing !== undefined)
+        return `${path}.${missing} is required`;
+    for (const [key, child] of Object.entries(value)) {
+        const reason = validateAdminSurfaceActionValue({ schema: properties[key], value: child }, { path: `${path}.${key}` });
+        if (reason !== null)
+            return reason;
+    }
+    return null;
+}
+function validateArray(schema, value, path) {
+    if (!Array.isArray(value))
+        return `${path} must be an array`;
+    if (value.length > (schema.maxItems ?? DEFAULT_MAX_ITEMS))
+        return `${path} has too many items`;
+    for (const [index, item] of value.entries()) {
+        const reason = validateAdminSurfaceActionValue({ schema: schema.items, value: item }, { path: `${path}[${index}]` });
+        if (reason !== null)
+            return reason;
+    }
+    return null;
+}
+function validateString(schema, value, path) {
+    if (typeof value !== 'string')
+        return `${path} must be a string`;
+    if (value.length < (schema.minLength ?? 0) || value.length > (schema.maxLength ?? Infinity))
+        return `${path} has the wrong length`;
+    return schema.enum === undefined || schema.enum.includes(value) ? null : `${path} is not one of the allowed values`;
+}
+function validateNumber(schema, value, path) {
+    const ok = typeof value === 'number' && Number.isFinite(value) && (schema.type === 'number' || Number.isInteger(value));
+    if (!ok)
+        return `${path} must be ${schema.type === 'integer' ? 'an integer' : 'a number'}`;
+    return inRange(value, schema.minimum, schema.maximum) ? null : `${path} is out of range`;
+}
+const inRange = (value, minimum, maximum) => value >= (minimum ?? -Infinity) && value <= (maximum ?? Infinity);
+/** One validator per declared `type`; the schema was checked at parse time, so the lookup always hits. */
+const VALIDATORS = {
+    object: validateObject,
+    array: validateArray,
+    string: validateString,
+    number: validateNumber,
+    integer: validateNumber,
+    boolean: (_schema, value, path) => (typeof value === 'boolean' ? null : `${path} must be a boolean`),
+    null: (_schema, value, path) => (value === null ? null : `${path} must be null`),
+};
+/** One request-size cap for the browser-side host check and the server-side dispatcher (the
+ * authoritative one: string schemas carry no default maxLength). */
+const MAX_PAYLOAD_CHARS = 64 * 1024;
+/** True when `payload` serializes to more than 64 KiB of JSON text, or cannot be serialized. @complexity O(payload size). */
+export function exceedsAdminSurfacePayloadLimit(required, _optional = {}) {
+    try {
+        return (JSON.stringify(required.payload)?.length ?? Infinity) > MAX_PAYLOAD_CHARS;
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=action-schema.js.map

package/dist/admin-surfaces/action-schema.js.map

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

package/dist/admin-surfaces/action-tools.d.ts

@@ -0,0 +1,40 @@
+/** Assistant adapter over the screen's dispatcher and admitted handler host. No module is reloaded here. */
+import type { AdminSurfaceActionOutcome } from './protocol.js';
+import type { AgentPluginAdditionalTool } from '../lifecycle/tools/projection.js';
+import { type AdminSurfaceActionHandler } from './action-dispatcher.js';
+import type { AdminSurfaceDescriptor } from './descriptor.js';
+import type { AdminSurfaceHandlerContext } from './surface-handlers.js';
+/** Admin tools always act for an authenticated principal, supplied by the registry. */
+export interface AdminSurfaceToolContext extends AdminSurfaceHandlerContext {
+    readonly principalId: string;
+}
+/** The host binds this from active, trusted surface contributions and its existing handler host. */
+export interface AdminSurfaceToolSource {
+    readonly pluginId: string;
+    readonly descriptor: AdminSurfaceDescriptor;
+}
+/**
+ * Projects every declared surface action into the existing plugin-tool contract. All actions use a
+ * `payload` envelope (including scalar/array actions), and the SAME dispatcher and handler host as
+ * the screen. The host supplies fresh authorization/admission before each call, including after a
+ * confirmation wait. Browser flows return their result and any host-issued URLs; this seam cannot open a browser.
+ * @param required.authorize - Must enforce the screen action permission and fresh trusted admission.
+ * @param optional.run - Request-local result decoration, e.g. collecting host-issued sign-in URLs.
+ * @returns Contributions for `createAgentPluginToolProjection.sync({ additionalTools })`.
+ * @complexity O(s + a) surfaces and actions, bounded by the descriptor parser; dispatch O(p) + handler.
+ */
+export declare function buildAdminSurfaceActionTools(required: {
+    readonly surfaces: readonly AdminSurfaceToolSource[];
+    readonly handlersFor: (input: {
+        readonly pluginId: string;
+        readonly surfaceId: string;
+    }) => Readonly<Record<string, AdminSurfaceActionHandler<AdminSurfaceToolContext>>>;
+    readonly authorize: (input: {
+        readonly context: AdminSurfaceToolContext;
+    }) => Promise<void>;
+}, optional?: {
+    readonly run?: (input: {
+        readonly dispatch: () => Promise<AdminSurfaceActionOutcome>;
+    }) => Promise<unknown>;
+}): readonly AgentPluginAdditionalTool[];
+//# sourceMappingURL=action-tools.d.ts.map

package/dist/admin-surfaces/action-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-tools.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/action-tools.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE/D,OAAO,KAAK,EAAE,yBAAyB,EAA6B,MAAM,kCAAkC,CAAC;AAC7G,OAAO,EAAsC,KAAK,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAE5G,OAAO,KAAK,EAAsB,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAExE,uFAAuF;AACvF,MAAM,WAAW,uBAAwB,SAAQ,0BAA0B;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,oGAAoG;AACpG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;CAC7C;AAcD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE;IACrD,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC;IACzK,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7F,EAAE,QAAQ,GAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,yBAAyB,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAAO,GAAG,SAAS,yBAAyB,EAAE,CAyBvK"}

package/dist/admin-surfaces/action-tools.js

@@ -0,0 +1,52 @@
+import { ToolInputError, requireInputRecord } from '@jini-ai/core';
+import { createAdminSurfaceActionDispatcher } from './action-dispatcher.js';
+import { exceedsAdminSurfacePayloadLimit, validateAdminSurfaceActionValue } from './action-schema.js';
+/** Checks the tool envelope and delegates payload validation to the screen's schema owner.
+ * @throws ToolInputError without echoing input values. @complexity O(p) payload size. */
+function checkedPayload(required, _optional = {}) {
+    const { input, action } = required;
+    const record = requireInputRecord({ input });
+    if (Object.keys(record).length !== 1 || !Object.hasOwn(record, 'payload') || exceedsAdminSurfacePayloadLimit({ payload: record.payload })
+        || validateAdminSurfaceActionValue({ schema: action.input, value: record.payload }) !== null) {
+        throw new ToolInputError({ message: 'Supply payload matching the declared admin action schema.' });
+    }
+    return record.payload;
+}
+/**
+ * Projects every declared surface action into the existing plugin-tool contract. All actions use a
+ * `payload` envelope (including scalar/array actions), and the SAME dispatcher and handler host as
+ * the screen. The host supplies fresh authorization/admission before each call, including after a
+ * confirmation wait. Browser flows return their result and any host-issued URLs; this seam cannot open a browser.
+ * @param required.authorize - Must enforce the screen action permission and fresh trusted admission.
+ * @param optional.run - Request-local result decoration, e.g. collecting host-issued sign-in URLs.
+ * @returns Contributions for `createAgentPluginToolProjection.sync({ additionalTools })`.
+ * @complexity O(s + a) surfaces and actions, bounded by the descriptor parser; dispatch O(p) + handler.
+ */
+export function buildAdminSurfaceActionTools(required, optional = {}) {
+    return required.surfaces.flatMap(({ pluginId, descriptor }) => descriptor.actions.map((action) => {
+        const name = `${descriptor.id.replace(/-/g, '_')}_${action.name.replace(/-/g, '_')}`;
+        return {
+            pluginId,
+            tool: {
+                name, description: `${descriptor.title}: ${action.name}. Browser sign-in actions return a URL to show the user.`,
+                effect: action.effect ?? 'write',
+                inputSchema: { type: 'object', properties: { payload: action.input }, required: ['payload'], additionalProperties: false },
+                async handler({ auth, input }) {
+                    if (!auth.principalId)
+                        throw new ToolInputError({ message: 'Admin actions require an authenticated principal.' });
+                    const context = { ...auth, principalId: auth.principalId, pluginId, surfaceId: descriptor.id };
+                    await required.authorize({ context });
+                    const payload = checkedPayload({ input, action });
+                    const dispatcher = createAdminSurfaceActionDispatcher({ descriptor, handlers: required.handlersFor({ pluginId, surfaceId: descriptor.id }) });
+                    const dispatch = () => dispatcher.dispatch({ action: action.name, payload, context });
+                    return optional.run ? optional.run({ dispatch }) : dispatch();
+                },
+            },
+            describeAffectedResources({ input }) {
+                checkedPayload({ input, action });
+                return [`${descriptor.title}: ${action.name}`];
+            },
+        };
+    }));
+}
+//# sourceMappingURL=action-tools.js.map

package/dist/admin-surfaces/action-tools.js.map

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

package/dist/admin-surfaces/callback-field-inbox.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file A one-time, bounded holding place for the extra fields a provider returns on a completed
+ * sign-in (for example the id of a resource the person picked during consent), between the host's
+ * callback route and the plugin handler that asked for the sign-in.
+ *
+ * Why it exists: the callback arrives on a host route the plugin never sees, but the plugin's
+ * surface handler is the one that must read and verify those fields. The host deposits them only
+ * after the sign-in completed successfully; the plugin's `connections.takeCallbackFields` takes them
+ * exactly once, and only under the same workspace, plugin, connection and attempt id, so another
+ * plugin or a second read gets `null`. Entries expire and the inbox is capped, so an abandoned
+ * sign-in cannot grow memory. It is in-process: a host that completes sign-ins on another process
+ * implements the same two methods over its own store.
+ */
+export interface AdminSurfaceCallbackFieldKey {
+    readonly workspaceId: string;
+    readonly pluginId: string;
+    readonly connectionId: string;
+    readonly attemptId: string;
+}
+/**
+ * @param required.now - Clock in epoch milliseconds (injected so expiry is testable).
+ * @returns `deposit` (host callback route, after a successful completion) and `take` (consume-once).
+ * @complexity deposit is O(e) to sweep expired entries; take is O(1).
+ */
+export declare function createAdminSurfaceCallbackInbox(required: {
+    readonly now: () => number;
+}, _optional?: Record<string, never>): {
+    /** Holds a completed sign-in's callback fields (call it only after the exchange succeeded). */
+    deposit(input: AdminSurfaceCallbackFieldKey & {
+        readonly fields: Readonly<Record<string, string>>;
+    }, _options?: Record<string, never>): void;
+    /** The fields, removed on the first read; `null` when never deposited, already taken, expired or keyed differently. */
+    take(input: AdminSurfaceCallbackFieldKey, _options?: Record<string, never>): Readonly<Record<string, string>> | null;
+};
+//# sourceMappingURL=callback-field-inbox.d.ts.map

package/dist/admin-surfaces/callback-field-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-field-inbox.d.ts","sourceRoot":"","sources":["../../src/admin-surfaces/callback-field-inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAUD;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,EACxC,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM;IAWnC,+FAA+F;mBAChF,4BAA4B,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;KAAE,aAAY,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAQ,IAAI;IAKhJ,uHAAuH;gBAC3G,4BAA4B,aAAY,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAQ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI;EAQ3H"}