@xopcai/xopc 0.0.396 → 0.0.398

package/dist/src/extensions/agent-plugins/user-config.js

@@ -0,0 +1,49 @@
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
+import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
+import { pluginAuthorizations } from "./setup-contract.js";
+import { pluginName } from "./validation.js";
+import { pluginCredentialProviderPrefix } from "./auth.js";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/extensions/agent-plugins/user-config.ts
+init_credentials();
+init_write_file_atomic();
+function readPluginUserConfig(store, id, revision) {
+	const path = join(store.stateDir, "plugin-config", `${pluginName.parse(id)}-${revision}.json`);
+	return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+}
+async function savePluginUserConfig(store, plugin, input) {
+	const fields = plugin.layout?.userConfig ?? {};
+	const values = readPluginUserConfig(store, plugin.id, plugin.receipt.revision);
+	for (const [key, value] of Object.entries(input)) {
+		const field = fields[key];
+		if (!field || typeof value !== field.type || typeof value === "string" && (value.length > 16384 || value.includes("\0"))) throw new Error(`Invalid configuration: ${key}`);
+		if (field.sensitive) {
+			const provider = `${pluginCredentialProviderPrefix(plugin.id)}config-${createHash("sha256").update(`${plugin.receipt.revision}:${key}`).digest("hex")}`;
+			await new CredentialResolver({ stateDir: store.stateDir }).saveApiKey(provider, String(value));
+			values[key] = { xopcSecretRef: {
+				provider,
+				fieldKey: key,
+				prefix: ""
+			} };
+		} else values[key] = value;
+	}
+	writeTextAtomicSync(join(store.stateDir, "plugin-config", `${plugin.id}-${plugin.receipt.revision}.json`), JSON.stringify(values));
+}
+function pluginConfigMissing(store, plugin) {
+	const saved = readPluginUserConfig(store, plugin.id, plugin.receipt.revision);
+	const accountFields = new Set(pluginAuthorizations(plugin.manifest).flatMap((value) => value.methods.flatMap((method) => method.type === "form" || method.type === "cli" ? method.fields : [])));
+	return Object.entries(plugin.layout?.userConfig ?? {}).filter(([key, field]) => !accountFields.has(key) && field.required && (saved[key] === void 0 || saved[key] === "") && field.default === void 0).map(([key]) => key);
+}
+function expandUserConfig(value, values) {
+	const exact = value.match(/^\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}$/);
+	if (exact && typeof values[exact[1]] === "object") return values[exact[1]];
+	return value.replace(/\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g, (_all, key) => {
+		if (values[key] === void 0) throw new Error(`Configure ${key} before starting tools`);
+		if (typeof values[key] === "object") throw new Error("Sensitive configuration must occupy an entire environment/header value");
+		return String(values[key]);
+	});
+}
+//#endregion
+export { expandUserConfig, pluginConfigMissing, readPluginUserConfig, savePluginUserConfig };

package/dist/src/extensions/agent-plugins/validation.d.ts

@@ -1,3 +1,5 @@
+import { pluginResources } from './resources.js';
+import { type PluginLayout } from './formats.js';
 import { z } from 'zod';
 export declare const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export declare const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
@@ -28,6 +30,27 @@ declare const serverSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"streamable-http">;
     url: z.ZodString;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    oauth: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodOptional<z.ZodString>;
+        callbackPort: z.ZodOptional<z.ZodNumber>;
+        callbackUrl: z.ZodOptional<z.ZodString>;
+        clientName: z.ZodOptional<z.ZodString>;
+        clientRegistration: z.ZodOptional<z.ZodEnum<{
+            dcr: "dcr";
+            cimd: "cimd";
+        }>>;
+        authServerMetadataUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    connectionAuth: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            none: "none";
+            oauth: "oauth";
+            "api-key": "api-key";
+        }>;
+        headerName: z.ZodOptional<z.ZodString>;
+        prefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>], "type">;
 export type PluginManifest = z.infer<typeof manifestSchema>;
 export type PluginServer = z.infer<typeof serverSchema>;
@@ -36,6 +59,8 @@ export interface PluginDiagnostic {
     message: string;
 }
 export interface PluginInspection {
+    resources?: ReturnType<typeof pluginResources>;
+    layout?: PluginLayout;
     manifest: PluginManifest;
     rootDir: string;
     skills: Array<{
@@ -50,6 +75,6 @@ export declare function containedPath(root: string, path: string): string;
 export declare function expandPluginVariables(value: string, root: string, data: string): string;
 export declare function resolvePluginCwd(cwd: string | undefined, root: string, data: string): string;
 export declare function validatePluginServer(raw: unknown, root: string, data: string): PluginServer;
-export declare function inspectAgentPlugin(rootDir: string, dataDir?: string): PluginInspection;
+export declare function inspectAgentPlugin(rootDir: string, dataDir?: string, importManifest?: Record<string, unknown>): PluginInspection;
 export declare function pluginServerId(pluginId: string, serverName: string): string;
 export {};

package/dist/src/extensions/agent-plugins/validation.js

@@ -1,10 +1,16 @@
+import { McpOAuthConfigSchema, init_schema } from "../../config/schema.js";
+import { pluginAuthorizations, safeAuthorizationUrl } from "./setup-contract.js";
+import { normalizePluginMcpServer } from "./mcp-format.js";
+import { pluginResources } from "./resources.js";
+import { collectPluginSkillFiles, readPluginLayout } from "./formats.js";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import yaml from "js-yaml";
 import { validateHeaderName, validateHeaderValue } from "node:http";
+import yaml from "js-yaml";
 //#region src/extensions/agent-plugins/validation.ts
+init_schema();
 const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
 const pluginName = z.string().min(1).max(64).regex(/^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/);
@@ -34,7 +40,17 @@ const serverSchema = z.discriminatedUnion("type", [z.strictObject({
 }), z.strictObject({
 	type: z.literal("streamable-http"),
 	url: z.string().min(1),
-	headers: strings.optional()
+	headers: strings.optional(),
+	oauth: McpOAuthConfigSchema.omit({ clientSecret: true }).optional(),
+	connectionAuth: z.strictObject({
+		mode: z.enum([
+			"none",
+			"oauth",
+			"api-key"
+		]),
+		headerName: z.string().optional(),
+		prefix: z.string().optional()
+	}).optional()
 })]);
 function containedPath(root, path) {
 	const base = resolve(root);
@@ -67,7 +83,7 @@ function readPackageFile(root, path) {
 	return readFileSync(safe, "utf8");
 }
 function expandPluginVariables(value, root, data) {
-	return value.replace(/\$\{PLUGIN_(ROOT|DATA)\}/g, (_, key) => key === "ROOT" ? root : data);
+	return value.replace(/\$\{(?:CLAUDE_)?PLUGIN_(ROOT|DATA)\}/g, (_, key) => key === "ROOT" ? root : data);
 }
 function resolvePluginCwd(cwd, root, data) {
 	if (cwd === void 0) return root;
@@ -80,7 +96,7 @@ function validatePluginServer(raw, root, data) {
 	if (server.type === "stdio") {
 		if (server.command.startsWith("./")) {
 			if (!statSync(containedPath(root, resolve(root, server.command))).isFile()) throw new Error("MCP command must be a file");
-		} else if (!/^[^\s/\\:;|&<>`$\x00-\x1f]+$/.test(server.command)) throw new Error("MCP command must be one bare executable or ./package-path");
+		} else if (!/^\$\{PLUGIN_RESOURCES\}\/[a-z][a-z0-9.-]{0,63}$/.test(server.command) && !/^[^\s/\\:;|&<>`$\x00-\x1f]+$/.test(server.command)) throw new Error("MCP command must be one bare executable or ./package-path");
 		for (const key of Object.keys(server.env ?? {})) {
 			if (["PLUGIN_ROOT", "PLUGIN_DATA"].includes(process.platform === "win32" ? key.toUpperCase() : key)) throw new Error("Reserved plugin environment variable");
 			if (!key || /[=\0]/.test(key)) throw new Error("Invalid environment name");
@@ -96,6 +112,16 @@ function validatePluginServer(raw, root, data) {
 		const url = new URL(server.url);
 		const loopback = url.hostname === "localhost" || url.hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(url.hostname);
 		if (!["https:", "http:"].includes(url.protocol) || url.protocol === "http:" && !loopback || url.username || url.password || server.url.includes("#")) throw new Error("Remote MCP requires HTTPS (HTTP is allowed on loopback), without user information or fragments");
+		if (server.connectionAuth?.headerName) {
+			validateHeaderName(server.connectionAuth.headerName);
+			if ([
+				"host",
+				"cookie",
+				"content-length",
+				"connection",
+				"transfer-encoding"
+			].includes(server.connectionAuth.headerName.toLowerCase())) throw new Error("Unsupported authentication header");
+		}
 		const names = /* @__PURE__ */ new Set();
 		for (const [key, value] of Object.entries(server.headers ?? {})) {
 			validateHeaderName(key);
@@ -106,15 +132,19 @@ function validatePluginServer(raw, root, data) {
 	}
 	return server;
 }
-function inspectAgentPlugin(rootDir, dataDir = join(rootDir, ".inspection-data")) {
+function inspectAgentPlugin(rootDir, dataDir = join(rootDir, ".inspection-data"), importManifest) {
 	const root = realpathSync(rootDir);
 	if (existsSync(join(root, "xopc.extension.json"))) throw new Error("This package is a native xopc extension");
 	if (existsSync(join(root, "package.json"))) {
 		if (JSON.parse(readPackageFile(root, join(root, "package.json")))?.xopc?.extension) throw new Error("This package is a native xopc extension");
 	}
-	const raw = JSON.parse(readPackageFile(root, join(root, "plugin.json")));
+	const layout = readPluginLayout(root, (path) => readPackageFile(root, path), (path) => containedPath(root, path), importManifest);
+	const raw = layout.manifest;
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Plugin manifest must be an object");
-	const diagnostics = [];
+	const diagnostics = layout.compatibility.filter((item) => item.support !== "supported").map((item) => ({
+		component: item.component,
+		message: item.message
+	}));
 	const cleaned = { ...raw };
 	for (const key of Object.keys(cleaned)) if (!Object.hasOwn(manifestSchema.shape, key)) {
 		diagnostics.push({
@@ -130,21 +160,34 @@ function inspectAgentPlugin(rootDir, dataDir = join(rootDir, ".inspection-data")
 		});
 		delete cleaned.extensions;
 	}
+	const manifest = manifestSchema.parse(cleaned);
 	const result = {
-		manifest: manifestSchema.parse(cleaned),
+		layout,
+		manifest,
 		rootDir: root,
 		skills: [],
 		servers: Object.create(null),
 		capabilities: [],
 		diagnostics
 	};
+	const report = (item) => {
+		const existing = layout.compatibility.findIndex((value) => value.component === item.component);
+		if (existing >= 0) layout.compatibility[existing] = item;
+		else layout.compatibility.push(item);
+	};
 	const attempt = (component, fn) => {
 		try {
 			fn();
 		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
 			diagnostics.push({
 				component,
-				message: error instanceof Error ? error.message : String(error)
+				message
+			});
+			report({
+				component,
+				support: "invalid",
+				message
 			});
 		}
 	};
@@ -153,47 +196,119 @@ function inspectAgentPlugin(rootDir, dataDir = join(rootDir, ".inspection-data")
 			lstatSync(path);
 			return true;
 		} catch (error) {
-			if (error.code === "ENOENT") return false;
+			if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) return false;
 			throw error;
 		}
 	};
-	const skillsDir = join(root, "skills");
-	if (present(skillsDir)) attempt("skills", () => {
-		const safe = containedPath(root, skillsDir);
-		if (!statSync(safe).isDirectory()) throw new Error("skills must be a directory");
-		for (const name of readdirSync(safe).sort()) attempt(`skill:${name}`, () => {
-			const dir = containedPath(root, join(safe, name));
-			if (!statSync(dir).isDirectory() || !present(join(dir, "SKILL.md"))) return;
-			const filePath = containedPath(root, join(dir, "SKILL.md"));
-			const match = readPackageFile(root, filePath).match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+	const seenSkills = /* @__PURE__ */ new Set();
+	for (const skillsDir of layout.skillRoots) attempt("skills", () => {
+		const files = layout.dialect === "portable" ? readdirSync(skillsDir).sort().map((name) => join(skillsDir, name, "SKILL.md")).filter(present) : collectPluginSkillFiles(skillsDir, (path) => containedPath(root, path));
+		for (const file of files) attempt(`skill:${file.slice(root.length + 1)}`, () => {
+			const filePath = containedPath(root, file);
+			const content = readPackageFile(root, filePath);
+			const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
 			if (!match) throw new Error("Skill requires YAML frontmatter");
-			const metadata = z.object({
+			const parsed = yaml.load(match[1], { schema: yaml.JSON_SCHEMA });
+			const metadata = (layout.dialect === "portable" ? z.object({
 				name: z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
 				description: z.string().min(1).max(1024),
 				license: z.string().optional(),
 				compatibility: z.string().min(1).max(500).optional(),
 				metadata: strings.optional(),
 				"allowed-tools": z.string().optional()
-			}).parse(yaml.load(match[1], { schema: yaml.JSON_SCHEMA }));
-			if (metadata.name !== name || !metadata.description.trim()) throw new Error("Skill name must match its directory and description must not be blank");
+			}) : z.object({
+				name: z.string().min(1).max(64).optional(),
+				description: z.string().min(1).max(1024)
+			})).parse(parsed);
+			const name = metadata.name ?? dirname(filePath).split(/[\\/]/).pop();
+			if (layout.dialect === "portable" && metadata.name !== dirname(filePath).split(/[\\/]/).pop()) throw new Error("Skill name must match its directory");
+			if (!metadata.description.trim() || seenSkills.has(name)) throw new Error("Blank description or duplicate skill name");
+			seenSkills.add(name);
 			result.skills.push({
 				name,
 				filePath
 			});
+			const references = [...new Set(content.match(/\bmcp__[A-Za-z0-9_-]+__[A-Za-z0-9_-]+|\bfunctions\.(?:exec_command|apply_patch|spawn_agent|send_input|wait_agent)|\$\{(?:CLAUDE_)?PLUGIN_(?:ROOT|DATA|RESOURCES)\}/g) ?? [])].slice(0, 20);
+			const message = references.length ? `Host-specific references need execution verification: ${references.join(", ")}` : "Skill format accepted; business execution is not verified.";
+			report({
+				component: `skill:${name}`,
+				support: references.length ? "needs_adapter" : "supported",
+				message
+			});
+			if (references.length) diagnostics.push({
+				component: `skill:${name}`,
+				message
+			});
 		});
 	});
-	const mcpPath = join(root, "mcp.json");
-	if (present(mcpPath)) attempt("mcp", () => {
-		const mcp = z.strictObject({
+	for (const rawConfig of layout.mcpConfigs) attempt("mcp", () => {
+		const mcp = layout.dialect === "portable" && present(join(root, "mcp.json")) ? z.strictObject({
 			$schema: z.literal(MCP_SCHEMA),
 			mcpServers: z.record(z.string(), z.unknown())
-		}).parse(JSON.parse(readPackageFile(root, mcpPath)));
-		for (const [name, rawServer] of Object.entries(mcp.mcpServers)) attempt(`mcp:${name}`, () => {
+		}).parse(rawConfig) : z.object({ mcpServers: z.record(z.string(), z.unknown()) }).parse(rawConfig);
+		for (const [name, value] of Object.entries(mcp.mcpServers)) attempt(`mcp:${name}`, () => {
+			delete result.servers[name];
+			let incomplete = false;
+			const rawServer = normalizePluginMcpServer(value, layout.dialect !== "portable", (message) => {
+				incomplete = true;
+				diagnostics.push({
+					component: `mcp:${name}`,
+					message
+				});
+			});
 			result.servers[name] = validatePluginServer(rawServer, root, dataDir);
+			report({
+				component: `mcp:${name}`,
+				support: incomplete ? "needs_adapter" : "supported",
+				message: incomplete ? "Some MCP declarations require adaptation." : "MCP configuration accepted; connection and tools require setup."
+			});
 		});
 	});
 	for (const skill of result.skills) result.capabilities.push(`content.skills:${skill.name}`);
-	for (const [name, server] of Object.entries(result.servers)) result.capabilities.push(server.type === "stdio" ? `runtime.mcp.stdio:${name}:${JSON.stringify(server)}` : `network.mcp:${name}:${server.type}:${server.url}:${JSON.stringify(server.headers ?? {})}`);
+	for (const [name, server] of Object.entries(result.servers)) result.capabilities.push(server.type === "stdio" ? `runtime.mcp.stdio:${name}:${JSON.stringify(server)}` : `network.mcp:${name}:${server.type}:${server.url}:${JSON.stringify(server.headers ?? {})}:${JSON.stringify(server.oauth ?? {})}:${JSON.stringify(server.connectionAuth ?? {})}`);
+	attempt("resources", () => {
+		result.resources = pluginResources(result);
+		for (const resource of result.resources) {
+			const supported = (!resource.platform || resource.platform === process.platform) && (!resource.arch || resource.arch === process.arch);
+			report({
+				component: `resource:${resource.id}`,
+				support: supported ? "supported" : "unsupported",
+				message: supported ? "Pinned resource declaration accepted." : "Resource does not support this host platform or architecture."
+			});
+			if (!supported) diagnostics.push({
+				component: `resource:${resource.id}`,
+				message: "Resource does not support this host platform or architecture."
+			});
+			result.capabilities.push(`${resource.executable ? "runtime.resource" : "network.resource"}:${resource.id}:${resource.url}:${resource.sha256}:${resource.maxBytes}:${resource.platform ?? "any"}:${resource.arch ?? "any"}`);
+		}
+	});
+	attempt("authorizations", () => {
+		const declarations = pluginAuthorizations(manifest);
+		const ids = /* @__PURE__ */ new Set();
+		for (const authorization of declarations) {
+			if (ids.has(authorization.id) || authorization.servers.some((name) => !result.servers[name])) throw new Error("Invalid or duplicate authorization target");
+			ids.add(authorization.id);
+			const methods = /* @__PURE__ */ new Set();
+			for (const method of authorization.methods) {
+				if (methods.has(method.id)) throw new Error("Duplicate authorization method");
+				methods.add(method.id);
+				if (method.helpUrl) safeAuthorizationUrl(method.helpUrl);
+				if ((method.type === "form" || method.type === "cli") && method.fields.some((key) => !layout.userConfig[key])) throw new Error("Authorization field is not declared in userConfig");
+				if (method.type === "oauth" && (!authorization.servers.includes(method.server) || result.servers[method.server]?.type === "stdio")) throw new Error("OAuth requires a remote MCP server");
+				if (method.type === "cli") {
+					validatePluginServer({
+						type: "stdio",
+						...method.login
+					}, root, dataDir);
+					validatePluginServer({
+						type: "stdio",
+						...method.check
+					}, root, dataDir);
+					result.capabilities.push(`runtime.authorization:${authorization.id}:${JSON.stringify(method)}`);
+				}
+			}
+		}
+	});
 	result.capabilities.sort();
 	return result;
 }

package/dist/src/gateway/agents-admin.js

@@ -1,10 +1,10 @@
 import { normalizeAgentId, validateAgentIdForNewAgent } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope, listAgentEntries, resolveAgentProfileDir, resolveAgentWorkspaceDir, resolveDefaultAgentId, resolveUserPath } from "../agent/agent-scope.js";
-import { AGENT_PROFILE_MARKDOWN_SYSTEM_FILES, REQUIRED_AGENT_PROFILE_MARKDOWN_FILE_SET } from "../agent/context/workspace.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
+import { AGENT_PROFILE_MARKDOWN_SYSTEM_FILES, REQUIRED_AGENT_PROFILE_MARKDOWN_FILE_SET } from "../agent/context/workspace.js";
 import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { GATEWAY_BUILTIN_TOOL_IDS } from "./agent-builtin-tools.js";
 import { resolve } from "node:path";
 import { mkdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";

package/dist/src/gateway/hono/lib/config-payload.js

@@ -1,7 +1,7 @@
+import { ContextPlanningConfigSchema, KnowledgeMemoryConfigSchema, UserModelConfigSchema, init_config } from "../../../user-context/config.js";
 import { normalizeAgentId } from "../../../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../../../agent-catalog/repository.js";
 import { init_agent_scope, listAgentEntries, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
-import { ContextPlanningConfigSchema, KnowledgeMemoryConfigSchema, UserModelConfigSchema, init_config } from "../../../user-context/config.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
 import { init_models_json, loadModelsJson } from "../../../config/models-json.js";
 import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";

package/dist/src/gateway/hono/routes/agent-plugins.js

@@ -1,17 +1,28 @@
+import { getWorkspacePath } from "../../../config/workspace-path-helpers.js";
+import { PluginSelectionRequired } from "../../../extensions/agent-plugins/source-catalog.js";
 import { AgentPluginStore } from "../../../extensions/agent-plugins/store.js";
 import { savePluginAuthBinding } from "../../../extensions/agent-plugins/auth.js";
 import { evictAllEmbeddedSessionRunners } from "../../../agent/embedded/session-runner.js";
-import { withAgentPluginSource } from "../../../extensions/agent-plugins/sources.js";
 import { agentPluginInventoryRow } from "../../../extensions/agent-plugins/inventory.js";
+import { withAgentPluginSource } from "../../../extensions/agent-plugins/sources.js";
+import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { cancelPluginCliAuthorizations } from "../../../extensions/agent-plugins/cli-authorization.js";
+import { PluginSetupService, setupActionSchema } from "../../../extensions/agent-plugins/setup.js";
 import { removePluginCredentials } from "../../../extensions/agent-plugins/credentials.js";
 import { z } from "zod";
 //#region src/gateway/hono/routes/agent-plugins.ts
 const sourceBody = z.strictObject({
 	source: z.string().min(1),
-	reviewHash: z.string().optional()
+	reviewHash: z.string().optional(),
+	setup: z.boolean().optional()
 });
+function setupOwner(c) {
+	const principal = getGatewayPrincipal(c);
+	return principal.kind === "owner" ? "gateway-owner" : principal.principalId;
+}
 function registerAgentPluginRoutes(app, deps) {
 	const store = new AgentPluginStore();
+	const setup = new PluginSetupService(store);
 	const refresh = async () => {
 		evictAllEmbeddedSessionRunners();
 		deps.service.marketplace.reloadSkills();
@@ -21,9 +32,16 @@ function registerAgentPluginRoutes(app, deps) {
 			const body = sourceBody.parse(await c.req.json());
 			return c.json({
 				ok: true,
-				payload: await withAgentPluginSource(body.source, deps.service.currentConfig, (source) => store.inspect(source))
+				payload: await withAgentPluginSource(body.source, deps.service.currentConfig, (source, _provenance, resolvedCommit, importManifest) => ({
+					...store.inspect(source, body.source, importManifest),
+					resolvedCommit
+				}))
 			});
 		} catch (error) {
+			if (error instanceof PluginSelectionRequired) return c.json({
+				ok: true,
+				payload: { candidates: error.candidates }
+			});
 			return c.json({
 				ok: false,
 				error: error instanceof Error ? error.message : String(error)
@@ -33,15 +51,18 @@ function registerAgentPluginRoutes(app, deps) {
 	app.post("/api/extensions/install", deps.strictRateLimitMiddleware, async (c) => {
 		try {
 			const body = sourceBody.parse(await c.req.json());
-			const plugin = await withAgentPluginSource(body.source, deps.service.currentConfig, (source, provenance) => store.install(source, {
+			const plugin = await withAgentPluginSource(body.source, deps.service.currentConfig, (source, provenance, resolvedCommit, importManifest) => store.install(source, {
 				reviewHash: body.reviewHash,
 				sourceLabel: body.source,
-				provenance
+				provenance,
+				resolvedCommit,
+				importManifest
 			}));
+			if (body.setup && plugin.readiness !== "blocked") setup.create(plugin.id, setupOwner(c));
 			await refresh();
 			return c.json({
 				ok: true,
-				payload: agentPluginInventoryRow(plugin)
+				payload: agentPluginInventoryRow(store.get(plugin.id))
 			});
 		} catch (error) {
 			return c.json({
@@ -52,7 +73,7 @@ function registerAgentPluginRoutes(app, deps) {
 	});
 	app.get("/api/extensions/agent-plugins/:id", (c) => {
 		try {
-			const plugin = store.get(c.req.param("id"));
+			const plugin = store.pending(c.req.param("id")) ?? store.get(c.req.param("id"));
 			return plugin ? c.json({
 				ok: true,
 				payload: agentPluginInventoryRow(plugin)
@@ -67,9 +88,91 @@ function registerAgentPluginRoutes(app, deps) {
 			}, 400);
 		}
 	});
+	app.get("/api/extensions/agent-plugins/:id/setup", (c) => {
+		try {
+			const id = c.req.param("id"), job = setup.get(id, setupOwner(c));
+			const plugin = store.pending(id) ?? store.get(id);
+			return c.json({
+				ok: true,
+				payload: job?.packageRevision === plugin?.receipt.revision ? job : null
+			});
+		} catch {
+			return c.json({
+				ok: false,
+				error: "Setup unavailable"
+			}, 403);
+		}
+	});
+	app.get("/api/extensions/agent-plugins/:id/setup/reusable", async (c) => {
+		try {
+			return c.json({
+				ok: true,
+				payload: await setup.reusableConnections(c.req.param("id"), setupOwner(c), deps.service.currentConfig)
+			});
+		} catch {
+			return c.json({
+				ok: false,
+				error: "Reusable connections unavailable"
+			}, 400);
+		}
+	});
+	app.post("/api/extensions/agent-plugins/:id/setup", deps.strictRateLimitMiddleware, async (c) => {
+		try {
+			const id = c.req.param("id"), owner = setupOwner(c);
+			const body = await c.req.json();
+			if (body.action === "start") return c.json({
+				ok: true,
+				payload: setup.create(id, owner)
+			});
+			const action = setupActionSchema.parse(body);
+			if (action.action === "prepare") return c.json({
+				ok: true,
+				payload: setup.startPrepare(id, owner, action.expectedRevision, deps.service.currentConfig, getWorkspacePath(deps.service.currentConfig) || process.cwd(), action.idempotencyKey)
+			});
+			const job = await setup.act(id, owner, action, deps.service.currentConfig, getWorkspacePath(deps.service.currentConfig) || process.cwd());
+			await refresh();
+			return c.json({
+				ok: true,
+				payload: job
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof Error ? error.message : "Setup failed"
+			}, 400);
+		}
+	});
+	app.get("/api/extensions/agent-plugins/:id/setup/auth/:server", async (c) => {
+		try {
+			const result = await setup.authorization(c.req.param("id"), setupOwner(c), c.req.param("server"), deps.service.currentConfig);
+			return c.json({
+				ok: true,
+				payload: result ?? null
+			});
+		} catch {
+			return c.json({
+				ok: false,
+				error: "Authorization unavailable"
+			}, 400);
+		}
+	});
+	app.post("/api/extensions/agent-plugins/:id/setup/auth/:server/redirect", deps.strictRateLimitMiddleware, async (c) => {
+		try {
+			const body = z.strictObject({ url: z.string().max(16384) }).parse(await c.req.json());
+			if (!setup.redirect(c.req.param("id"), setupOwner(c), c.req.param("server"), body.url, deps.service.currentConfig)) throw new Error("Callback does not match this sign-in");
+			return c.json({ ok: true });
+		} catch {
+			return c.json({
+				ok: false,
+				error: "Invalid sign-in callback"
+			}, 400);
+		}
+	});
 	app.post("/api/extensions/agent-plugins/:id/activation", deps.strictRateLimitMiddleware, async (c) => {
 		try {
 			const body = z.strictObject({ enabled: z.boolean() }).parse(await c.req.json());
+			const job = setup.get(c.req.param("id"), setupOwner(c));
+			if (body.enabled && job?.packageRevision === store.receipt(c.req.param("id"))?.revision && job.state !== "completed") throw new Error("Finish plugin setup before enabling");
 			const plugin = store.setEnabled(c.req.param("id"), body.enabled);
 			await refresh();
 			return c.json({
@@ -86,17 +189,21 @@ function registerAgentPluginRoutes(app, deps) {
 	app.post("/api/extensions/agent-plugins/:id/update", deps.strictRateLimitMiddleware, async (c) => {
 		try {
 			const body = sourceBody.parse(await c.req.json());
-			const plugin = await withAgentPluginSource(body.source, deps.service.currentConfig, (source, provenance) => store.install(source, {
+			const plugin = await withAgentPluginSource(body.source, deps.service.currentConfig, (source, provenance, resolvedCommit, importManifest) => store.install(source, {
 				reviewHash: body.reviewHash,
 				replace: true,
 				expectedId: c.req.param("id"),
+				stage: body.setup,
 				sourceLabel: body.source,
-				provenance
+				provenance,
+				resolvedCommit,
+				importManifest
 			}));
+			if (body.setup && plugin.readiness !== "blocked") setup.create(plugin.id, setupOwner(c));
 			await refresh();
 			return c.json({
 				ok: true,
-				payload: agentPluginInventoryRow(plugin)
+				payload: agentPluginInventoryRow(store.pending(plugin.id) ?? store.get(plugin.id))
 			});
 		} catch (error) {
 			return c.json({
@@ -131,7 +238,10 @@ function registerAgentPluginRoutes(app, deps) {
 					prefix: z.string().optional()
 				})).max(20).optional()
 			}).parse(await c.req.json());
+			const owner = setupOwner(c);
+			setup.get(c.req.param("id"), owner);
 			await savePluginAuthBinding(store, c.req.param("id"), c.req.param("server"), body);
+			setup.invalidateConnection(c.req.param("id"), owner, c.req.param("server"));
 			await refresh();
 			return c.json({ ok: true });
 		} catch (error) {
@@ -143,6 +253,7 @@ function registerAgentPluginRoutes(app, deps) {
 	});
 	app.delete("/api/extensions/agent-plugins/:id", deps.strictRateLimitMiddleware, async (c) => {
 		try {
+			cancelPluginCliAuthorizations(c.req.param("id"));
 			const body = z.strictObject({
 				removeData: z.boolean().optional(),
 				removeCredentials: z.boolean().optional()

package/dist/src/gateway/hono/routes/auth-registry-extensions.js

@@ -3,11 +3,11 @@ import { ActivationPlanner } from "../../../extensions/activation-planner.js";
 import { mergeActivationContext } from "../../../extensions/activation-context.js";
 import { validateExtensionConfig } from "../../../extensions/config-validation.js";
 import { fetchRegistry, listExtensions, searchExtensions } from "../../../extensions/marketplace.js";
+import { listAgentPluginInventory } from "../../../extensions/agent-plugins/inventory.js";
 import { createOAuthAsyncHandler } from "../oauth-async.js";
 import { createOAuthHandler } from "../oauth.js";
 import { extensionAssetMimeType } from "../lib/extension-assets.js";
 import { loadExtensionStore, saveExtensionStore } from "../lib/extension-store.js";
-import { listAgentPluginInventory } from "../../../extensions/agent-plugins/inventory.js";
 import { relative, resolve } from "node:path";
 import { existsSync, readFileSync, statSync } from "node:fs";
 //#region src/gateway/hono/routes/auth-registry-extensions.ts