@jini-ai/agent-plugins 0.4.0

package/dist/lifecycle/install.js

@@ -0,0 +1,286 @@
+/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import path from "node:path";
+import { parseAgentPluginManifest as parseAgentPluginManifestValue } from "./manifest.js";
+import { PackagePathViolation } from "./package-paths.js";
+import { createPackagePathsModule } from "./package-paths.js";
+export class AgentPluginInstallError extends Error {
+    code;
+    constructor({ code, message }, options = {}) {
+        super(message, options);
+        this.name = "AgentPluginInstallError";
+        this.code = code;
+    }
+}
+function buildModule(ports) {
+    const chmod = ports.filesystem.chmod.bind(ports.filesystem);
+    const mkdir = ports.filesystem.mkdir.bind(ports.filesystem);
+    const mkdtemp = ports.filesystem.mkdtemp.bind(ports.filesystem);
+    const open = ports.filesystem.open.bind(ports.filesystem);
+    const readdir = ports.filesystem.readdir.bind(ports.filesystem);
+    const readFile = ports.filesystem.readFile.bind(ports.filesystem);
+    const rename = ports.filesystem.rename.bind(ports.filesystem);
+    const rm = ports.filesystem.rm.bind(ports.filesystem);
+    const stat = ports.filesystem.stat.bind(ports.filesystem);
+    const parseAgentPluginManifest = (value) => parseAgentPluginManifestValue({ value });
+    const { assertContainedOnDisk, normalizePackageEntryPath } = createPackagePathsModule(ports);
+    const LIMITS = {
+        maxArchiveBytes: 32 * 1024 * 1024,
+        maxEntries: 4096,
+        maxFileBytes: 16 * 1024 * 1024,
+        maxTotalExtractedBytes: 64 * 1024 * 1024,
+    };
+    function maxAgentPluginInstallArchiveBytes() {
+        return LIMITS.maxArchiveBytes;
+    }
+    const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+    async function installAgentPlugin(required, _optional = {}) {
+        const { archive, expectedSha256, archiveReader, layout, workspaceId } = required;
+        const workspaceLayout = layout.forWorkspace({ workspaceId });
+        if (archive.byteLength > LIMITS.maxArchiveBytes) {
+            throw new AgentPluginInstallError({ code: "ARCHIVE_TOO_LARGE", message: `archive is ${archive.byteLength} bytes, over the ${LIMITS.maxArchiveBytes}-byte cap` });
+        }
+        const digest = sha256(archive);
+        if (!SHA256_HEX_PATTERN.test(expectedSha256) || digest !== expectedSha256.toLowerCase()) {
+            throw new AgentPluginInstallError({ code: "DIGEST_MISMATCH", message: `archive SHA-256 '${digest}' does not match the expected '${expectedSha256}' — refusing to extract unverified bytes` });
+        }
+        await mkdir(workspaceLayout.packages, { recursive: true, mode: 0o700 });
+        const finalRoot = path.join(workspaceLayout.packages, digest);
+        const alreadyPublished = await isRealDirectory(finalRoot);
+        if (alreadyPublished) {
+            return indexInstalledRoot(finalRoot, digest);
+        }
+        await mkdir(workspaceLayout.staging, { recursive: true, mode: 0o700 });
+        await assertEntryCountWithinCap(archiveReader.entries({ archive }));
+        const transactionRoot = await mkdtemp(path.join(workspaceLayout.staging, "install-"));
+        const extractionRoot = path.join(transactionRoot, "root");
+        await mkdir(extractionRoot, { mode: 0o700 });
+        try {
+            const executablePaths = await extractEntries(archiveReader.entries({ archive }), extractionRoot);
+            const indexed = await indexInstalledRoot(extractionRoot, digest);
+            await publish(extractionRoot, finalRoot);
+            await freezeTree(finalRoot, executablePaths);
+            return { ...indexed, packageRoot: finalRoot };
+        }
+        finally {
+            await rm(transactionRoot, { recursive: true, force: true });
+        }
+    }
+    function symlinkRejectionMessage(entry) {
+        const targetSuffix = "linkTarget" in entry && entry.linkTarget ? ` (target '${entry.linkTarget}')` : "";
+        return `archive entry '${entry.entryPath}' has kind '${entry.kind}', which Agent Plugin packages are not permitted to contain${targetSuffix}`;
+    }
+    function normalizeEntryPathOrThrow(entryPath) {
+        try {
+            return normalizePackageEntryPath(entryPath);
+        }
+        catch (error) {
+            throw new AgentPluginInstallError({ code: "UNSAFE_ENTRY_PATH", message: `archive entry path is unsafe: '${entryPath}'` }, { cause: error });
+        }
+    }
+    async function resolveContainedDestinationOrThrow(extractionRoot, normalized) {
+        try {
+            return await assertContainedOnDisk(extractionRoot, normalized);
+        }
+        catch (error) {
+            throw new AgentPluginInstallError({ code: "UNSAFE_ENTRY_PATH", message: `archive entry resolves outside the package root: '${normalized}'` }, {
+                cause: error instanceof PackagePathViolation ? error : undefined,
+            });
+        }
+    }
+    async function extractOneEntry(args) {
+        const { entry, extractionRoot, seen, executablePaths, totalBytesSoFar } = args;
+        if (entry.kind !== "file" && entry.kind !== "directory") {
+            throw new AgentPluginInstallError({ code: "SYMLINK_ENTRY_REJECTED", message: symlinkRejectionMessage(entry) });
+        }
+        const normalized = normalizeEntryPathOrThrow(entry.entryPath);
+        if (seen.has(normalized)) {
+            throw new AgentPluginInstallError({ code: "DUPLICATE_ENTRY", message: `duplicate archive entry '${normalized}' — refusing a second write over an already-vetted first one` });
+        }
+        seen.add(normalized);
+        const destination = await resolveContainedDestinationOrThrow(extractionRoot, normalized);
+        if (entry.kind === "directory") {
+            await mkdir(destination, { recursive: true, mode: 0o700 });
+            return totalBytesSoFar;
+        }
+        if ((entry.declaredSize ?? 0) > LIMITS.maxFileBytes) {
+            throw new AgentPluginInstallError({ code: "FILE_TOO_LARGE", message: `archive file '${normalized}' declares ${entry.declaredSize} bytes, over the ${LIMITS.maxFileBytes}-byte cap` });
+        }
+        await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+        const totalBytes = await writeContainedFile({
+            destination,
+            normalized,
+            stream: entry.openReadStream({}),
+            totalBytesSoFar,
+        });
+        if (entry.executable)
+            executablePaths.add(normalized);
+        return totalBytes;
+    }
+    /**
+     * Refuses a "million small files" archive from entry metadata alone, before a staging
+     * transaction exists. Checking only inside the extraction loop meant an over-cap archive first
+     * had the cap's worth of files contained, written and then deleted again. Every reader derives
+     * its entries from the archive bytes, so a second iteration costs one central-directory walk
+     * and opens no content stream.
+     */
+    async function assertEntryCountWithinCap(entries) {
+        let entryCount = 0;
+        for await (const _entry of entries) {
+            entryCount += 1;
+            if (entryCount > LIMITS.maxEntries)
+                throw tooManyEntriesError();
+        }
+    }
+    function tooManyEntriesError() {
+        return new AgentPluginInstallError({ code: "TOO_MANY_ENTRIES", message: `archive exceeds the ${LIMITS.maxEntries}-entry cap` });
+    }
+    async function extractEntries(entries, extractionRoot) {
+        const seen = new Set();
+        const executablePaths = new Set();
+        let entryCount = 0;
+        let totalBytes = 0;
+        for await (const entry of entries) {
+            entryCount += 1;
+            // Still enforced here: the pre-pass trusts the reader to yield the same entries twice.
+            if (entryCount > LIMITS.maxEntries)
+                throw tooManyEntriesError();
+            totalBytes = await extractOneEntry({ entry, extractionRoot, seen, executablePaths, totalBytesSoFar: totalBytes });
+        }
+        return executablePaths;
+    }
+    async function writeContainedFile(params) {
+        let flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
+        if (ports.process.platform !== "win32")
+            flags |= constants.O_NOFOLLOW;
+        const handle = await open(params.destination, flags, 0o600);
+        let fileBytes = 0;
+        let totalBytes = params.totalBytesSoFar;
+        try {
+            for await (const chunk of params.stream) {
+                fileBytes += chunk.byteLength;
+                totalBytes += chunk.byteLength;
+                if (fileBytes > LIMITS.maxFileBytes) {
+                    throw new AgentPluginInstallError({ code: "DECOMPRESSION_BOMB", message: `archive file '${params.normalized}' exceeded the ${LIMITS.maxFileBytes}-byte cap while decompressing — its declared size was a lie` });
+                }
+                if (totalBytes > LIMITS.maxTotalExtractedBytes) {
+                    throw new AgentPluginInstallError({ code: "TOTAL_SIZE_EXCEEDED", message: `archive exceeds the ${LIMITS.maxTotalExtractedBytes}-byte total extracted-size cap` });
+                }
+                await handle.write(chunk instanceof Buffer ? chunk : Buffer.from(chunk));
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        return totalBytes;
+    }
+    async function indexInstalledRoot(packageRoot, archiveDigest) {
+        let manifestRaw;
+        try {
+            manifestRaw = await readFile(path.join(packageRoot, "plugin.json"), "utf8");
+        }
+        catch (error) {
+            if (isErrnoException(error) && error.code === "ENOENT") {
+                throw new AgentPluginInstallError({ code: "MANIFEST_MISSING", message: "the archive does not contain a plugin.json at its root" });
+            }
+            throw error;
+        }
+        let manifestValue;
+        try {
+            manifestValue = JSON.parse(manifestRaw);
+        }
+        catch (error) {
+            throw new AgentPluginInstallError({ code: "MANIFEST_INVALID", message: "plugin.json is not valid JSON" }, { cause: error });
+        }
+        const parsed = parseAgentPluginManifest(manifestValue);
+        if (!parsed.ok) {
+            throw new AgentPluginInstallError({ code: "MANIFEST_INVALID", message: `plugin.json failed validation: ${parsed.errors.join("; ")}` });
+        }
+        const files = [];
+        const skills = [];
+        async function walk(absolute, prefix) {
+            for (const entry of await readdir(absolute, { withFileTypes: true })) {
+                const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    await walk(path.join(absolute, entry.name), relative);
+                }
+                else if (entry.isFile()) {
+                    files.push(relative);
+                    const match = relative.match(/^skills\/([^/]+)\/SKILL\.md$/);
+                    if (match)
+                        skills.push({ name: match[1], skillPath: relative });
+                }
+            }
+        }
+        await walk(packageRoot, "");
+        return {
+            pluginId: parsed.manifest.name,
+            version: parsed.manifest.version,
+            ...(parsed.manifest.description !== undefined ? { description: parsed.manifest.description } : {}),
+            ...(parsed.manifest.keywords !== undefined ? { keywords: parsed.manifest.keywords } : {}),
+            ...(parsed.manifest.author !== undefined ? { author: parsed.manifest.author } : {}),
+            ...(parsed.manifest.license !== undefined ? { license: parsed.manifest.license } : {}),
+            archiveDigest,
+            packageRoot,
+            files: files.sort(),
+            skills: skills.sort((a, b) => a.name.localeCompare(b.name)),
+        };
+    }
+    async function freezeTree(root, executables, prefix = "") {
+        for (const entry of await readdir(root, { withFileTypes: true })) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const absolute = path.join(root, entry.name);
+            if (entry.isDirectory()) {
+                await freezeTree(absolute, executables, relative);
+                await chmod(absolute, 0o555);
+            }
+            else {
+                await chmod(absolute, executables.has(relative) ? 0o555 : 0o444);
+            }
+        }
+        await chmod(root, 0o555);
+    }
+    async function publish(extractionRoot, finalRoot) {
+        try {
+            await rename(extractionRoot, finalRoot);
+        }
+        catch (error) {
+            if (!isErrnoException(error) || (error.code !== "EEXIST" && error.code !== "ENOTEMPTY" && error.code !== "EACCES")) {
+                throw new AgentPluginInstallError({ code: "PUBLISH_FAILED", message: `failed to publish the extracted package to '${finalRoot}'` }, { cause: error });
+            }
+            if (!(await isRealDirectory(finalRoot))) {
+                throw new AgentPluginInstallError({ code: "PUBLISH_FAILED", message: `'${finalRoot}' exists but is not a real, published package directory` }, { cause: error });
+            }
+        }
+    }
+    async function isRealDirectory(target) {
+        try {
+            const info = await stat(target);
+            return info.isDirectory();
+        }
+        catch (error) {
+            if (isErrnoException(error) && error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }
+    function sha256(value) {
+        return createHash("sha256").update(value).digest("hex");
+    }
+    function isErrnoException(error) {
+        return typeof error === "object" && error !== null && "code" in error;
+    }
+    return { maxAgentPluginInstallArchiveBytes, installAgentPlugin, indexInstalledRoot };
+}
+const instances = new WeakMap();
+/** Internal composition; one state/queue instance per injected host context. */
+export function createInstallModule(ports) {
+    let instance = instances.get(ports);
+    if (!instance) {
+        instance = buildModule(ports);
+        instances.set(ports, instance);
+    }
+    return instance;
+}
+//# sourceMappingURL=install.js.map

package/dist/lifecycle/layout.d.ts

@@ -0,0 +1,20 @@
+export interface AgentPluginWorkspaceLayout {
+    readonly root: string;
+    readonly packages: string;
+    readonly staging: string;
+    pluginDataDir(required: {
+        readonly pluginId: string;
+    }): string;
+}
+export interface AgentPluginLayoutPort {
+    readonly root: string;
+    forWorkspace(required: {
+        readonly workspaceId: string;
+    }): AgentPluginWorkspaceLayout;
+}
+export type AgentPluginLayout = AgentPluginLayoutPort;
+/** Explicit root only; site-root and environment resolution belong to the consumer. */
+export declare function createAgentPluginLayout(required: {
+    readonly root: string;
+}): AgentPluginLayoutPort;
+//# sourceMappingURL=layout.d.ts.map

package/dist/lifecycle/layout.js

@@ -0,0 +1,30 @@
+import path from 'node:path';
+/** Explicit root only; site-root and environment resolution belong to the consumer. */
+export function createAgentPluginLayout(required) {
+    if (!path.isAbsolute(required.root))
+        throw new Error('Agent plugin root must be absolute');
+    const root = path.resolve(required.root);
+    return {
+        root,
+        forWorkspace({ workspaceId }) {
+            const id = workspaceId.toLowerCase();
+            assertSafeSegment(id);
+            const workspaceRoot = path.join(root, 'ws', id);
+            return {
+                root: workspaceRoot,
+                packages: path.join(workspaceRoot, 'packages', 'sha256'),
+                staging: path.join(workspaceRoot, 'staging'),
+                pluginDataDir({ pluginId }) {
+                    assertSafeSegment(pluginId);
+                    return path.join(workspaceRoot, 'data', pluginId);
+                },
+            };
+        },
+    };
+}
+function assertSafeSegment(value) {
+    if (!/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(value) || value.length > 64) {
+        throw new Error(`'${value}' is not a safe plugin/workspace id`);
+    }
+}
+//# sourceMappingURL=layout.js.map

package/dist/lifecycle/manifest.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Historical lifecycle rationale, carried with the implementation during consumer adoption.
+ * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins v1.0.0
+ * `plugin.json` / `mcp.json` grammar (agent-plugins.org/specification), verified against the live
+ * spec rather than inferred from an example manifest.
+ *
+ * Deliberately a SEPARATE, smaller validator from `src/features/plugin-runtime/manifest.ts`'s
+ * `validateManifest()`. That file validates `.host-plugin`'s own tarball format — `integrity`
+ * (per-file SHA-256), `sdkRange`, `tier`, an exactly-three-token capability vocabulary, a single
+ * `content.entry.beforeSave` hook. This file validates the OPEN standard's `plugin.json`, which
+ * shares none of those fields and defines no execution/trust/capability model at all — see this
+ * feature's own header comment in `install.ts` for why the two formats cannot be unified.
+ *
+ * Spec facts this module encodes, quoted/paraphrased from agent-plugins.org/specification (verified
+ * 2026-08-12, not carried forward from an earlier round's inference):
+ * - `plugin.json`'s `name`: 1-64 chars, lowercase alphanumeric/hyphen/period only, must start and
+ *   end alphanumeric, no `--` or `..` consecutive delimiters (§5.5). Valid: `my-plugin`,
+ *   `acme.tools`, `lint3r`, `a`. Invalid: `My-Plugin`, `-start`, `has--double`.
+ * - `plugin.json`'s `$schema` MUST equal `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`
+ *   for this pinned version; `mcp.json`'s MUST equal
+ *   `https://agent-plugins.org/schemas/1.0.0/mcp.schema.json`.
+ * - Unknown top-level `plugin.json` fields produce warnings but do not block loading — this module
+ *   returns them as `warnings`, never as a rejection reason.
+ * - `mcp.json`'s top-level shape is `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }` —
+ *   `mcpServers` MUST be an object whose member names identify servers.
+ * - Each server entry MUST carry a `type` discriminator matching exactly one of three CLOSED
+ *   variants (re-verified live against `agent-plugins.org/schemas/1.0.0/mcp.schema.json` and
+ *   `/specification`, 2026-09-10 — superseding this file's earlier "not validated, no caller needs
+ *   it" note, which is now false: `capability-projection.ts`'s MCP-server descriptors are no longer
+ *   unconditionally `execute: { kind: "unavailable" }`, and launching a server needs its real
+ *   transport config, not just its id):
+ *     - `stdio`: requires `command` (non-empty string); optional `args` (string[]), `env`
+ *       (string-valued object — MUST NOT set `PLUGIN_ROOT`/`PLUGIN_DATA`, which the spec reserves),
+ *       `cwd` (plugin-relative path).
+ *     - `streamable-http` / `sse`: requires `url` (non-empty string); optional `headers`
+ *       (string-valued object).
+ * - **The spec defines NO auth-related field on a server entry at all.** Verbatim from
+ *   `/specification`: "Agent Plugins v1 defines no OAuth configuration or portable
+ *   credential-reference fields. Authorization discovery, user interaction, and credential storage
+ *   are client-managed." A plugin therefore cannot declare "this server needs OAuth" using any
+ *   spec-defined field — the host is the client the spec defers that decision to. This module accepts
+ *   the host-specific metadata in `plugin.json`'s `extensions.<host-namespace>.mcpServers[serverId]`, keeping
+ *   `mcp.json` transport entries closed per §7.2.1. Hosts may translate legacy auth and sign-in defaults in MCP
+ *   entries through readServerMetadata for existing packages, but those cannot supply operator read trust.
+ *   `authMode: "oauth" | "none"` selects client auth; absent defaults to "none".
+ *   `defaultTools: { allow?, write?, read? }` names sign-in grants and reviewed read tools.
+ *   `write` requires `allow` and must be its subset; `read` must be a subset when `allow` is
+ *   present. A read-only declaration without `allow` leaves sign-in grants unchanged.
+ *   Remote hints may veto a read declaration but never supply it. A third,
+ *   `tokenAuth: { helpUrl, probeUrl }`, offers a pasted access token as the sign-in fallback
+ *   (`access-token-tool.ts`). A fourth, `renamedTools: { oldName: newName }`, carries saved tool
+ *   selections across a vendor's tool rename (`apply-tool-renames.ts`). A malformed per-server entry
+ *   (wrong/missing `type`, missing required field) does not fail the whole file — see
+ *   `ParseAgentPluginMcpConfigResult`'s own doc for the fail-open contract this preserves.
+ *
+ * Architectural role:
+ * Pure, no-I/O parsing over an already-`JSON.parse`d value — mirrors `plugin-runtime/manifest.ts`'s
+ * own "receives a JS value, never a file path or raw bytes" contract. `install.ts` is the only
+ * caller that reads the file and hands the parsed value here.
+ */
+export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
+export type { PluginManifest, McpManifest, McpServerEntry } from '../manifest.js';
+import type { PluginManifestAuthor } from '../manifest.js';
+export type { PluginManifestAuthor } from '../manifest.js';
+/** Agent Plugins 1.0.0 parsing, with application metadata confined to an explicit namespace. */
+export type AgentPluginServerMetadataReader = (required: {
+    readonly serverId: string;
+    readonly value: Readonly<Record<string, unknown>>;
+    readonly server: Readonly<Record<string, unknown>>;
+}) => Readonly<Record<string, unknown>>;
+export interface AgentPluginManifest {
+    readonly name: string;
+    readonly version?: (string) | undefined;
+    readonly description?: (string) | undefined;
+    readonly author?: string | PluginManifestAuthor | undefined;
+    readonly license?: (string) | undefined;
+    readonly keywords?: (readonly string[]) | undefined;
+    readonly extensions?: (Readonly<Record<string, unknown>>) | undefined;
+}
+export type ParseAgentPluginManifestResult = {
+    readonly ok: true;
+    readonly manifest: AgentPluginManifest;
+    readonly warnings: readonly string[];
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/**
+ * Validates an already-`JSON.parse`d `plugin.json` value against the v1.0.0 grammar.
+ *
+ * @throws Nothing — every failure is reported via the returned `errors`, matching this codebase's
+ * own convention for expected validation outcomes (`plugin-runtime/manifest.ts`,
+ * `plugin-runtime/discovery.ts`).
+ * @complexity O(k + n) time and space in the input keys and keyword entries.
+ */
+export declare function parseAgentPluginManifest({ value }: {
+    readonly value: unknown;
+}): ParseAgentPluginManifestResult;
+/**
+ * The three closed transport variants `mcp.schema.json` v1.0.0 defines. See this file's header for
+ * the verified field shape of each.
+ */
+export declare const MCP_SERVER_TRANSPORTS: readonly ["stdio", "streamable-http", "sse"];
+export type McpServerTransport = (typeof MCP_SERVER_TRANSPORTS)[number];
+export interface StdioMcpServerConfig {
+    readonly type: "stdio";
+    readonly command: string;
+    readonly args?: (readonly string[]) | undefined;
+    readonly env?: (Readonly<Record<string, string>>) | undefined;
+    readonly cwd?: (string) | undefined;
+}
+export interface AgentPluginServerMetadata {
+    readonly authMode?: ('oauth' | 'none') | undefined;
+    readonly defaultTools?: (AgentPluginDefaultTools) | undefined;
+    readonly tokenAuth?: (AgentPluginTokenAuth) | undefined;
+    readonly renamedTools?: (Readonly<Record<string, string>>) | undefined;
+}
+/**
+ * `streamable-http` and `sse` share an identical field shape (`url` + optional `headers`); only
+ * their `type` differs, and both are handled by the one remote branch below.
+ */
+export interface RemoteMcpServerConfig extends AgentPluginServerMetadata {
+    readonly type: 'streamable-http' | 'sse';
+    readonly url: string;
+    readonly headers?: (Readonly<Record<string, string>>) | undefined;
+}
+/**
+ * the host-specific extension, not part of the spec — see this file's header for why it exists and
+ * what a strictly spec-conformant client does with it (ignores it).
+ *
+ * the host-specific extension, not part of the spec: the tools this server's row is granted on the
+ *  operator's FIRST successful sign-in (`apply-connect-defaults.ts`), so connecting is the only step.
+ *  `write` is a subset of `allow`, the same rule the external-MCP store enforces on a save.
+ *
+ * the host-specific extension, not part of the spec: this server also takes a pasted access token, sent
+ *  as `Authorization: Bearer` — the fallback when its sign-in cannot start (`access-token-tool.ts`).
+ *
+ * the host-specific extension, not part of the spec: `{ oldName: newName }` for tools the vendor
+ *  renamed. A row this plugin provisioned has each old name in its saved lists replaced by the new
+ *  one at boot (`apply-tool-renames.ts`), so a rename never strands an operator's selection.
+ *
+ * Where a human makes the token (`helpUrl`, linked from the form) and the URL a pasted token is
+ *  checked against before it is saved (`probeUrl`: one GET, 401/403 means the token was rejected).
+ *  Both https.
+ *
+ *  `importFromEnv` names an env var whose token is copied onto this server's row at boot when the row
+ *  has no credential yet (`import-access-token.ts`); `retiredEnv` names old env vars that are no
+ *  longer read, so boot can say so once. Both let a plugin take over an old env-configured
+ *  integration without core naming the vendor.
+ */
+export interface AgentPluginTokenAuth {
+    readonly helpUrl: string;
+    readonly probeUrl: string;
+    readonly importFromEnv?: (string) | undefined;
+    readonly retiredEnv?: (readonly string[]) | undefined;
+}
+export interface AgentPluginDefaultTools {
+    readonly allow?: (readonly string[]) | undefined;
+    readonly write: readonly string[];
+    readonly read?: (readonly string[]) | undefined;
+}
+/**
+ * Absent means no first-sign-in defaults, rather than an empty grant.
+ *
+ * Operator-reviewed remote names; absent on older programmatic configs means no read grants.
+ */
+export type McpServerConfig = StdioMcpServerConfig | RemoteMcpServerConfig;
+export interface AgentPluginMcpConfig {
+    readonly serverIds: readonly string[];
+    readonly servers: Readonly<Record<string, McpServerConfig>>;
+}
+/**
+ * `mcpServers`' own member names, in declaration order — the identity a future admission record
+ * pins to (`serverId` in the debate's own admission shape). Includes every declared key
+ * regardless of whether that entry's transport shape validated — see {@link servers} for the
+ * validated subset — so a discovery caller that only ever needed ids (`search_agent_plugin_local`)
+ * sees no behavior change from before this module parsed transports at all.
+ *
+ * Only the entries whose transport shape validated against one of the three closed variants.
+ * A `serverId` present in {@link serverIds} but absent here declared an unrecognized `type` or was
+ * missing a required field for the `type` it declared — fail-open per this file's header, not an
+ * error for the whole `mcp.json`.
+ */
+export type ParseAgentPluginMcpConfigResult = {
+    readonly ok: true;
+    readonly config: AgentPluginMcpConfig;
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/**
+ * Validates an already-`JSON.parse`d `mcp.json` value against the v1.0.0 top-level shape:
+ * `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }`, then validates each declared
+ * server's own transport shape (see this file's header for the three variants).
+ *
+ * @throws Nothing — see {@link parseAgentPluginManifest}.
+ * @complexity O(s) in the number of declared servers.
+ */
+export declare function parseAgentPluginMcpConfig({ value, extensionNamespace }: {
+    readonly value: unknown;
+    readonly extensionNamespace: string;
+}, optional?: {
+    readonly pluginManifest?: unknown;
+    readonly readServerMetadata?: AgentPluginServerMetadataReader | undefined;
+}): ParseAgentPluginMcpConfigResult;
+/** Typed extension reader: unknown namespaces have no semantics until a host supplies a reader. */
+export declare function readAgentPluginExtension<T>(required: {
+    readonly manifest: Pick<AgentPluginManifest, 'extensions'>;
+    readonly namespace: string;
+    readonly read: (required: {
+        readonly value: Readonly<Record<string, unknown>>;
+    }) => T;
+}): T | undefined;
+//# sourceMappingURL=manifest.d.ts.map