@xopcai/xopc 0.0.395 → 0.0.397

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

@@ -0,0 +1,112 @@
+import { createPluginSourceFetch } from "./source-http-fetch.js";
+import { containedPath } from "./validation.js";
+import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/extensions/agent-plugins/resources.ts
+const resourceVariant = z.strictObject({
+	url: z.string().url(),
+	sha256: z.string().regex(/^[a-f0-9]{64}$/),
+	maxBytes: z.number().int().positive().max(50 * 1024 * 1024).default(50 * 1024 * 1024),
+	executable: z.boolean().default(false),
+	platform: z.enum([
+		"darwin",
+		"linux",
+		"win32"
+	]).optional(),
+	arch: z.enum(["arm64", "x64"]).optional()
+});
+const resourceId = z.string().min(1).max(64).regex(/^[a-z][a-z0-9]*(?:[-.][a-z0-9]+)*$/);
+const resourcesSchema = z.array(z.union([resourceVariant.extend({ id: resourceId }).strict(), z.strictObject({
+	id: resourceId,
+	variants: z.array(resourceVariant).min(1).max(6)
+})])).max(20);
+function pluginResources(plugin) {
+	const extension = plugin.manifest.extensions?.["ai.xopc"];
+	if (extension?.setup?.version !== void 0 && extension.setup.version !== 1) throw new Error("Unsupported plugin setup protocol version");
+	const ids = /* @__PURE__ */ new Set();
+	return resourcesSchema.parse(extension?.setup?.resources ?? []).map((resource) => {
+		if (ids.has(resource.id)) throw new Error("Duplicate plugin resource");
+		ids.add(resource.id);
+		if (!("variants" in resource)) return resource;
+		const matches = resource.variants.filter((value) => (!value.platform || value.platform === process.platform) && (!value.arch || value.arch === process.arch));
+		if (matches.length !== 1) throw new Error(`Expected one resource variant for this platform: ${resource.id}`);
+		return {
+			...matches[0],
+			id: resource.id
+		};
+	});
+}
+function verified(path, sha256, maxBytes) {
+	if (!existsSync(path)) return;
+	const stat = statSync(path);
+	if (!stat.isFile() || stat.size > maxBytes) return;
+	const data = readFileSync(path);
+	return createHash("sha256").update(data).digest("hex") === sha256 ? data : void 0;
+}
+function atomicFile(path, data, mode) {
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	const pending = `${path}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(pending, data, {
+			mode,
+			flag: "wx"
+		});
+		renameSync(pending, path);
+	} finally {
+		rmSync(pending, { force: true });
+	}
+}
+/** Download pinned files; execute them only later through an explicitly reviewed MCP process. */
+async function preparePluginResources(store, plugin, signal) {
+	const dataRoot = store.dataDir(plugin.id), cacheRoot = join(store.stateDir, "plugin-resource-cache");
+	for (const resource of pluginResources(plugin)) {
+		signal.throwIfAborted();
+		if (resource.platform && resource.platform !== process.platform || resource.arch && resource.arch !== process.arch) throw new Error(`Resource is unavailable for this platform: ${resource.id}`);
+		const target = containedPath(dataRoot, join(dataRoot, "resources", plugin.receipt.revision, resource.id));
+		if (verified(target, resource.sha256, resource.maxBytes) && (!resource.executable || (statSync(target).mode & 73) !== 0)) continue;
+		const cached = containedPath(cacheRoot, join(cacheRoot, resource.sha256));
+		let data = verified(cached, resource.sha256, resource.maxBytes);
+		if (!data) {
+			const url = new URL(resource.url);
+			const response = await createPluginSourceFetch(url, {})(url, { signal: AbortSignal.any([signal, AbortSignal.timeout(6e4)]) });
+			if (!response.ok || !response.body) throw new Error(`Resource download failed: ${resource.id}`);
+			const chunks = [];
+			let bytes = 0;
+			const reader = response.body.getReader();
+			try {
+				for (;;) {
+					const part = await reader.read();
+					if (part.done) break;
+					bytes += part.value.length;
+					if (bytes > resource.maxBytes) throw new Error("Resource exceeds size limit");
+					chunks.push(part.value);
+				}
+			} finally {
+				await reader.cancel();
+			}
+			data = Buffer.concat(chunks);
+			if (createHash("sha256").update(data).digest("hex") !== resource.sha256) throw new Error(`Resource integrity failed: ${resource.id}`);
+		}
+		signal.throwIfAborted();
+		const content = data;
+		store.withRevision(plugin.id, plugin.receipt.revision, () => {
+			atomicFile(cached, content, 384);
+			atomicFile(containedPath(dataRoot, target), content, resource.executable ? 448 : 384);
+		});
+	}
+}
+/** Derive ownership from retained revisions, including rollback and staged packages. */
+function prunePluginResourceCache(store) {
+	const cacheRoot = join(store.stateDir, "plugin-resource-cache");
+	if (!existsSync(cacheRoot)) return;
+	const referenced = /* @__PURE__ */ new Set();
+	for (const plugin of store.list()) for (const revision of store.history(plugin.id)) if (existsSync(revision.rootDir)) for (const hash of revision.receipt.resourceHashes ?? []) referenced.add(hash);
+	for (const name of readdirSync(cacheRoot)) if (/^[a-f0-9]{64}$/.test(name) && !referenced.has(name)) rmSync(join(cacheRoot, name), { force: true });
+}
+//#endregion
+export { pluginResources, preparePluginResources, prunePluginResourceCache };

package/dist/src/extensions/agent-plugins/setup-contract.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const setupCommandSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const pluginAuthorizationSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    servers: z.ZodArray<z.ZodString>;
+    methods: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        server: z.ZodString;
+        id: z.ZodString;
+        title: z.ZodString;
+        instructions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        helpUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"form">;
+        fields: z.ZodArray<z.ZodString>;
+        id: z.ZodString;
+        title: z.ZodString;
+        instructions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        helpUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"cli">;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        login: z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        check: z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        id: z.ZodString;
+        title: z.ZodString;
+        instructions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        helpUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>>;
+export type PluginAuthorization = z.infer<typeof pluginAuthorizationSchema>[number];
+export type SetupCommand = z.infer<typeof setupCommandSchema>;
+export declare function pluginAuthorizations(manifest: {
+    extensions?: Record<string, unknown>;
+}): PluginAuthorization[];
+export declare function safeAuthorizationUrl(value: string): string;

package/dist/src/extensions/agent-plugins/setup-contract.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+//#region src/extensions/agent-plugins/setup-contract.ts
+const id = z.string().min(1).max(64).regex(/^[a-z][a-z0-9-]*$/);
+const setupCommandSchema = z.strictObject({
+	command: z.string().min(1),
+	args: z.array(z.string()).max(100).default([]),
+	env: z.record(z.string(), z.string()).default({}),
+	cwd: z.string().optional()
+});
+const guidance = {
+	id,
+	title: z.string().min(1).max(100),
+	instructions: z.array(z.string().min(1).max(1e3)).max(12).default([]),
+	helpUrl: z.string().url().optional()
+};
+const pluginAuthorizationSchema = z.array(z.strictObject({
+	id,
+	title: z.string().min(1).max(100),
+	description: z.string().max(1e3).optional(),
+	servers: z.array(z.string().min(1)).min(1).max(20),
+	methods: z.array(z.discriminatedUnion("type", [
+		z.strictObject({
+			...guidance,
+			type: z.literal("oauth"),
+			server: z.string().min(1)
+		}),
+		z.strictObject({
+			...guidance,
+			type: z.literal("form"),
+			fields: z.array(z.string().min(1)).min(1).max(20)
+		}),
+		z.strictObject({
+			...guidance,
+			type: z.literal("cli"),
+			fields: z.array(z.string().min(1)).max(20).default([]),
+			login: setupCommandSchema,
+			check: setupCommandSchema,
+			timeoutSeconds: z.number().int().min(10).max(900).default(300)
+		})
+	])).min(1).max(6)
+})).max(20);
+function pluginAuthorizations(manifest) {
+	const extension = manifest.extensions?.["ai.xopc"];
+	const declarations = pluginAuthorizationSchema.parse(extension?.setup?.authorizations ?? []);
+	for (const account of declarations) for (const method of account.methods) if (method.helpUrl) safeAuthorizationUrl(method.helpUrl);
+	return declarations;
+}
+function safeAuthorizationUrl(value) {
+	const url = new URL(value);
+	if (url.username || url.password || !(url.protocol === "https:" || url.protocol === "http:" && [
+		"127.0.0.1",
+		"[::1]",
+		"localhost"
+	].includes(url.hostname))) throw new Error("Authorization requires an HTTPS or loopback URL");
+	return url.href;
+}
+//#endregion
+export { pluginAuthorizationSchema, pluginAuthorizations, safeAuthorizationUrl, setupCommandSchema };

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

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import type { Config } from '../../config/schema.js';
+import { AgentPluginStore } from './store.js';
+declare const schema: z.ZodObject<{
+    id: z.ZodString;
+    pluginId: z.ZodString;
+    owner: z.ZodString;
+    packageRevision: z.ZodString;
+    revision: z.ZodNumber;
+    state: z.ZodEnum<{
+        cancelled: "cancelled";
+        failed: "failed";
+        completed: "completed";
+        pending: "pending";
+        running: "running";
+        interrupted: "interrupted";
+        action_required: "action_required";
+    }>;
+    resources: z.ZodEnum<{
+        error: "error";
+        pending: "pending";
+        ready: "ready";
+        running: "running";
+    }>;
+    connections: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        state: z.ZodEnum<{
+            error: "error";
+            pending: "pending";
+            skipped: "skipped";
+            connected: "connected";
+            oauth_required: "oauth_required";
+            token_required: "token_required";
+        }>;
+        toolCount: z.ZodOptional<z.ZodNumber>;
+        authorizationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    installed: z.ZodDefault<z.ZodBoolean>;
+    deferred: z.ZodDefault<z.ZodBoolean>;
+    authorizations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        state: z.ZodEnum<{
+            error: "error";
+            pending: "pending";
+            skipped: "skipped";
+            connected: "connected";
+        }>;
+        method: z.ZodOptional<z.ZodString>;
+        attemptId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    operations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        action: z.ZodString;
+    }, z.core.$strip>>>;
+    missingConfig: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    partial: z.ZodBoolean;
+    updatedAt: z.ZodString;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginSetupJob = z.infer<typeof schema>;
+export declare const setupActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"prepare">;
+}, z.core.$strict>, z.ZodObject<{
+    server: z.ZodString;
+    sourceServerId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"reuse">;
+}, z.core.$strict>, z.ZodObject<{
+    server: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    expectedRevision: z.ZodNumber;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"authorize">;
+}, z.core.$strict>, z.ZodObject<{
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    authorization: z.ZodOptional<z.ZodString>;
+    method: z.ZodOptional<z.ZodString>;
+    expectedRevision: z.ZodNumber;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"configure">;
+}, z.core.$strict>, z.ZodObject<{
+    workspacePaths: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    allowPartial: z.ZodDefault<z.ZodBoolean>;
+    expectedRevision: z.ZodNumber;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"complete">;
+}, z.core.$strict>, z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"defer">;
+}, z.core.$strict>, z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"cancel">;
+}, z.core.$strict>], "action">;
+export declare class PluginSetupService {
+    readonly store: AgentPluginStore;
+    constructor(store?: AgentPluginStore);
+    private path;
+    private key;
+    private write;
+    get(id: string, owner: string): PluginSetupJob | undefined;
+    create(id: string, owner: string): PluginSetupJob;
+    invalidateConnection(id: string, owner: string, name: string): void;
+    reusableConnections(id: string, owner: string, config: Config): Promise<Record<string, Array<{
+        id: string;
+        name: string;
+    }>>>;
+    authorization(id: string, owner: string, server: string, config: Config): Promise<import("../../agent/mcp/connection-setup.js").McpAuthorization | import("./cli-authorization.js").PluginCliAuthorization>;
+    redirect(id: string, owner: string, server: string, url: string, config: Config): boolean;
+    private config;
+    startPrepare(id: string, owner: string, revision: number, config: Config, workspace: string, idempotencyKey?: string): PluginSetupJob;
+    act(id: string, owner: string, input: z.infer<typeof setupActionSchema>, config: Config, workspace: string): Promise<PluginSetupJob>;
+    private perform;
+}
+export {};