myagentmemory 0.4.13 → 0.4.14

package/src/plugin-host.ts

@@ -0,0 +1,255 @@
+export const AGENT_MEMORY_PLUGIN_API_VERSION = 1 as const;
+
+export type PluginPermissionV1 =
+	| "memory:read"
+	| "memory:write"
+	| "memory:correct"
+	| "config:read"
+	| "config:write"
+	| "jobs:run"
+	| "sessions:read"
+	| "state:write";
+
+export type PluginEntitlementStateV1 = "active" | "grace" | "missing" | "expired";
+
+export type PluginPlanV1 = "free" | "trial" | "pro" | "team" | "enterprise";
+
+export interface PluginCapabilityQuotaV1 {
+	limit: number;
+	window: "day";
+	scope: "device";
+}
+
+export interface PluginCapabilityGrantV1 {
+	enabled: boolean;
+	quota?: PluginCapabilityQuotaV1;
+}
+
+export interface PluginEntitlementStatusV1 {
+	plan: PluginPlanV1 | null;
+	state: PluginEntitlementStateV1;
+	features: string[];
+	capabilities: Record<string, PluginCapabilityGrantV1>;
+	expiresAt?: string;
+	offlineUntil?: string;
+	reason?: string;
+}
+
+export interface PluginCommandDescriptorV1 {
+	name: string;
+	description: string;
+	aliases?: string[];
+	requiredCapability: string;
+}
+
+export interface AgentMemoryPluginManifestV1 {
+	schemaVersion: 1;
+	id: string;
+	name: string;
+	version: string;
+	description: string;
+	engine: string;
+	entitlement: "commercial";
+	commands: PluginCommandDescriptorV1[];
+	permissions: PluginPermissionV1[];
+	requires?: string[];
+	capabilities?: string[];
+	optionalCapabilities?: string[];
+}
+
+export interface AgentMemoryBundleManifestV1 {
+	schemaVersion: 1;
+	id: string;
+	version: string;
+	channel: string;
+	core: string;
+	pluginApi: 1;
+	entrypoint: string;
+	plugins: string[];
+}
+
+export interface PluginCommandContextV1 {
+	args: string[];
+	flags: Record<string, string | boolean>;
+	signal: AbortSignal;
+}
+
+export interface PluginCommandResultV1 {
+	ok: boolean;
+	data?: unknown;
+	error?: PluginStructuredErrorV1;
+}
+
+export interface PluginCommandV1 extends PluginCommandDescriptorV1 {
+	run(context: PluginCommandContextV1): Promise<PluginCommandResultV1>;
+}
+
+export interface PluginSessionStartContextV1 {
+	host: string;
+	cwd?: string;
+	signal: AbortSignal;
+}
+
+export interface PluginSessionStartHookV1 {
+	name: string;
+	requiredCapability: string;
+	run(context: PluginSessionStartContextV1): Promise<void>;
+}
+
+export interface PluginMemoryWriteV1 {
+	target: "long_term" | "daily" | "topic";
+	content: string;
+	mode?: "append" | "overwrite";
+	topic?: string;
+	date?: string;
+	sourceUri?: string;
+}
+
+export interface PluginMemoryWriteResultV1 {
+	ok: boolean;
+	path: string;
+	redacted: boolean;
+}
+
+export interface PluginMemoryCorrectionV1 {
+	artifactId: string;
+	scope: "daily" | "durable";
+	content: string;
+	reason?: string;
+	sourceUri?: string;
+}
+
+export interface PluginMemoryCorrectionResultV1 {
+	ok: boolean;
+	path: string;
+	redacted: boolean;
+}
+
+export interface PluginStructuredErrorV1 {
+	code: string;
+	message: string;
+	retryable?: boolean;
+}
+
+export interface AgentMemoryPluginHostV1 {
+	apiVersion: 1;
+	coreVersion: string;
+	registerCommand(command: PluginCommandV1): void;
+	registerSessionStartHook(hook: PluginSessionStartHookV1): void;
+	getStateDirectory(): string;
+	getMemoryDirectory(): string;
+	getEntitlement(): Promise<PluginEntitlementStatusV1>;
+	redactSecrets(value: string): string;
+	writeMemory(request: PluginMemoryWriteV1): Promise<PluginMemoryWriteResultV1>;
+	correctMemory(request: PluginMemoryCorrectionV1): Promise<PluginMemoryCorrectionResultV1>;
+	scheduleSearchRefresh(reason: string): void;
+}
+
+export interface AgentMemoryPluginV1 {
+	manifest: AgentMemoryPluginManifestV1;
+	activate(host: AgentMemoryPluginHostV1): Promise<void>;
+	healthCheck(host: AgentMemoryPluginHostV1): Promise<{ ok: boolean; message?: string }>;
+}
+
+export interface AgentMemoryPluginBundleV1 {
+	apiVersion: 1;
+	manifest: AgentMemoryBundleManifestV1;
+	plugins: readonly AgentMemoryPluginV1[];
+}
+
+const PLUGIN_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const COMMAND_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const PLANS = new Set<PluginPlanV1>(["free", "trial", "pro", "team", "enterprise"]);
+const ENTITLEMENT_STATES = new Set<PluginEntitlementStateV1>(["active", "grace", "missing", "expired"]);
+
+export function validatePluginManifestV1(manifest: AgentMemoryPluginManifestV1): void {
+	if (manifest.schemaVersion !== 1) throw new Error(`Unsupported plugin manifest schema for ${manifest.id}`);
+	if (!PLUGIN_ID.test(manifest.id)) throw new Error(`Invalid plugin id: ${manifest.id}`);
+	if (!manifest.name.trim() || !manifest.description.trim())
+		throw new Error(`Plugin manifest ${manifest.id} is incomplete`);
+	if (!SEMVER.test(manifest.version))
+		throw new Error(`Invalid plugin version for ${manifest.id}: ${manifest.version}`);
+	if (!manifest.engine.trim()) throw new Error(`Plugin manifest ${manifest.id} has no engine range`);
+
+	const commands = new Set<string>();
+	const capabilities = new Set(manifest.capabilities ?? []);
+	if (capabilities.size !== (manifest.capabilities?.length ?? 0))
+		throw new Error(`Plugin manifest ${manifest.id} must declare unique capabilities`);
+	for (const capability of capabilities) {
+		if (!PLUGIN_ID.test(capability)) throw new Error(`Invalid capability '${capability}' in ${manifest.id}`);
+	}
+	for (const command of manifest.commands) {
+		if (!COMMAND_NAME.test(command.name)) throw new Error(`Invalid command '${command.name}' in ${manifest.id}`);
+		if (!command.description.trim())
+			throw new Error(`Command '${command.name}' in ${manifest.id} has no description`);
+		if (commands.has(command.name)) throw new Error(`Duplicate command '${command.name}' in ${manifest.id}`);
+		if (!capabilities.has(command.requiredCapability))
+			throw new Error(
+				`Command '${command.name}' in ${manifest.id} requires undeclared capability '${command.requiredCapability}'`,
+			);
+		commands.add(command.name);
+	}
+
+	for (const dependency of manifest.requires ?? []) {
+		if (!PLUGIN_ID.test(dependency)) throw new Error(`Invalid dependency '${dependency}' in ${manifest.id}`);
+		if (dependency === manifest.id) throw new Error(`Plugin ${manifest.id} cannot require itself`);
+	}
+}
+
+export function validatePluginEntitlementStatusV1(
+	entitlement: unknown,
+): asserts entitlement is PluginEntitlementStatusV1 {
+	if (!entitlement || typeof entitlement !== "object" || Array.isArray(entitlement))
+		throw new Error("Plugin entitlement must be an object");
+	const candidate = entitlement as Partial<PluginEntitlementStatusV1>;
+	if (candidate.plan !== null && !PLANS.has(candidate.plan as PluginPlanV1))
+		throw new Error("Plugin entitlement has an invalid plan");
+	if (!ENTITLEMENT_STATES.has(candidate.state as PluginEntitlementStateV1))
+		throw new Error("Plugin entitlement has an invalid state");
+	if (!Array.isArray(candidate.features) || candidate.features.some((feature) => typeof feature !== "string"))
+		throw new Error("Plugin entitlement features must be strings");
+	if (!candidate.capabilities || typeof candidate.capabilities !== "object" || Array.isArray(candidate.capabilities))
+		throw new Error("Plugin entitlement capabilities must be an object");
+	for (const [capability, grant] of Object.entries(candidate.capabilities)) {
+		if (!PLUGIN_ID.test(capability)) throw new Error(`Invalid entitlement capability: ${capability}`);
+		if (!grant || typeof grant !== "object" || Array.isArray(grant) || typeof grant.enabled !== "boolean")
+			throw new Error(`Capability ${capability} has an invalid grant`);
+		if (grant.quota) {
+			if (!Number.isInteger(grant.quota.limit) || grant.quota.limit <= 0)
+				throw new Error(`Capability ${capability} has an invalid quota limit`);
+			if (grant.quota.window !== "day" || grant.quota.scope !== "device")
+				throw new Error(`Capability ${capability} has an invalid quota policy`);
+		}
+	}
+}
+
+export function isPluginCapabilityEnabled(entitlement: PluginEntitlementStatusV1, capability: string): boolean {
+	return (
+		(entitlement.state === "active" || entitlement.state === "grace") &&
+		entitlement.capabilities?.[capability]?.enabled === true
+	);
+}
+
+export function validateBundleManifestV1(manifest: AgentMemoryBundleManifestV1): void {
+	if (manifest.schemaVersion !== 1) throw new Error(`Unsupported bundle manifest schema for ${manifest.id}`);
+	if (!PLUGIN_ID.test(manifest.id)) throw new Error(`Invalid bundle id: ${manifest.id}`);
+	if (!SEMVER.test(manifest.version))
+		throw new Error(`Invalid bundle version for ${manifest.id}: ${manifest.version}`);
+	if (manifest.pluginApi !== AGENT_MEMORY_PLUGIN_API_VERSION)
+		throw new Error(`Unsupported plugin API ${manifest.pluginApi} for ${manifest.id}`);
+	if (!manifest.channel.trim() || !manifest.core.trim())
+		throw new Error(`Bundle manifest ${manifest.id} is incomplete`);
+	if (!isSafeBundlePath(manifest.entrypoint)) throw new Error(`Invalid bundle entrypoint: ${manifest.entrypoint}`);
+	if (!manifest.plugins.length || new Set(manifest.plugins).size !== manifest.plugins.length)
+		throw new Error(`Bundle manifest ${manifest.id} must list unique plugins`);
+	for (const pluginId of manifest.plugins) {
+		if (!PLUGIN_ID.test(pluginId)) throw new Error(`Invalid plugin id in bundle ${manifest.id}: ${pluginId}`);
+	}
+}
+
+export function isSafeBundlePath(value: string): boolean {
+	if (!value || value.includes("\\") || value.includes("\0") || value.startsWith("/")) return false;
+	const parts = value.split("/");
+	return parts.every((part) => /^[0-9A-Za-z@+._-]+$/.test(part) && part !== "." && part !== "..");
+}

package/src/plugin-runtime.ts

@@ -0,0 +1,296 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { getMemoryDir, memoryWrite, redactSecrets, scheduleQmdUpdate } from "./core.js";
+import {
+	FilePluginInstallStore,
+	OFFICIAL_BUNDLE_ID,
+	type PluginBootstrapBackendV1,
+	PluginBootstrapFailure,
+	type PluginInstallReceiptV1,
+	type PluginInstallStoreV1,
+	type SignedPluginReleaseV1,
+} from "./plugin-bootstrap.js";
+import {
+	AGENT_MEMORY_PLUGIN_API_VERSION,
+	type AgentMemoryPluginBundleV1,
+	type AgentMemoryPluginHostV1,
+	type AgentMemoryPluginManifestV1,
+	isPluginCapabilityEnabled,
+	type PluginCommandContextV1,
+	type PluginCommandResultV1,
+	type PluginCommandV1,
+	type PluginEntitlementStatusV1,
+	type PluginMemoryCorrectionV1,
+	type PluginMemoryWriteV1,
+	type PluginSessionStartHookV1,
+	validateBundleManifestV1,
+	validatePluginEntitlementStatusV1,
+	validatePluginManifestV1,
+} from "./plugin-host.js";
+import { TemporaryPluginBackend } from "./plugin-service.js";
+
+interface RegisteredCommand {
+	command: PluginCommandV1;
+	pluginId: string;
+}
+
+export interface PluginRuntimeOptionsV1 {
+	coreVersion: string;
+	store?: PluginInstallStoreV1;
+	backend?: PluginBootstrapBackendV1;
+}
+
+function assertPermission(manifest: AgentMemoryPluginManifestV1, permission: string): void {
+	if (!manifest.permissions.includes(permission as never))
+		throw new PluginBootstrapFailure(
+			"plugin_permission_denied",
+			`Plugin ${manifest.id} did not declare permission ${permission}`,
+		);
+}
+
+function memoryResult(result: Awaited<ReturnType<typeof memoryWrite>>): {
+	ok: boolean;
+	path: string;
+	redacted: boolean;
+} {
+	if (result.isError)
+		throw new PluginBootstrapFailure("plugin_memory_write_failed", result.text.replace(/^Error:\s*/, ""));
+	return {
+		ok: true,
+		path: typeof result.details.path === "string" ? result.details.path : getMemoryDir(),
+		redacted: result.details.redacted === true,
+	};
+}
+
+async function importBundle(
+	directory: string,
+	receipt: Pick<PluginInstallReceiptV1, "entrypoint" | "bundleId" | "version">,
+): Promise<AgentMemoryPluginBundleV1> {
+	let component = path.resolve(directory);
+	const rootStat = fs.lstatSync(component);
+	if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+		throw new PluginBootstrapFailure("plugin_entrypoint_invalid", "The installed plugin directory is unsafe");
+	for (const part of receipt.entrypoint.split("/")) {
+		component = path.join(component, part);
+		const componentStat = fs.lstatSync(component);
+		if (componentStat.isSymbolicLink())
+			throw new PluginBootstrapFailure(
+				"plugin_entrypoint_invalid",
+				"The installed plugin path contains a symbolic link",
+			);
+	}
+	const entrypoint = path.resolve(directory, ...receipt.entrypoint.split("/"));
+	if (!entrypoint.startsWith(`${path.resolve(directory)}${path.sep}`))
+		throw new PluginBootstrapFailure(
+			"plugin_entrypoint_invalid",
+			"The installed plugin entrypoint escapes its bundle",
+		);
+	const stat = fs.lstatSync(entrypoint);
+	if (!stat.isFile() || stat.isSymbolicLink())
+		throw new PluginBootstrapFailure(
+			"plugin_entrypoint_invalid",
+			"The installed plugin entrypoint is not a regular file",
+		);
+	const imported = (await import(`${pathToFileURL(entrypoint).href}?v=${encodeURIComponent(receipt.version)}`)) as {
+		default?: unknown;
+	};
+	const bundle = imported.default as AgentMemoryPluginBundleV1 | undefined;
+	if (!bundle || bundle.apiVersion !== AGENT_MEMORY_PLUGIN_API_VERSION || !Array.isArray(bundle.plugins))
+		throw new PluginBootstrapFailure(
+			"plugin_bundle_invalid",
+			"The plugin entrypoint did not export a compatible bundle",
+		);
+	validateBundleManifestV1(bundle.manifest);
+	if (bundle.manifest.id !== receipt.bundleId || bundle.manifest.version !== receipt.version)
+		throw new PluginBootstrapFailure(
+			"plugin_bundle_invalid",
+			"The loaded plugin bundle identity does not match its receipt",
+		);
+	const pluginIds = new Set<string>();
+	for (const plugin of bundle.plugins) {
+		validatePluginManifestV1(plugin.manifest);
+		if (pluginIds.has(plugin.manifest.id))
+			throw new PluginBootstrapFailure("plugin_bundle_invalid", "The plugin bundle contains duplicate plugin ids");
+		pluginIds.add(plugin.manifest.id);
+	}
+	if (
+		pluginIds.size !== bundle.manifest.plugins.length ||
+		bundle.manifest.plugins.some((pluginId) => !pluginIds.has(pluginId))
+	)
+		throw new PluginBootstrapFailure("plugin_bundle_invalid", "The plugin bundle contents do not match its manifest");
+	return bundle;
+}
+
+export class InstalledPluginRuntimeV1 {
+	private readonly store: PluginInstallStoreV1;
+	private readonly backend: PluginBootstrapBackendV1;
+	private readonly commands = new Map<string, RegisteredCommand>();
+	private readonly hooks: PluginSessionStartHookV1[] = [];
+	private loaded = false;
+
+	constructor(private readonly options: PluginRuntimeOptionsV1) {
+		this.store = options.store ?? new FilePluginInstallStore();
+		this.backend = options.backend ?? new TemporaryPluginBackend({ root: this.store.root });
+	}
+
+	async load(): Promise<boolean> {
+		if (this.loaded) return true;
+		const receipt = this.store.readReceipt(OFFICIAL_BUNDLE_ID);
+		if (!receipt || !this.store.hasInstalledBundle(receipt)) return false;
+		await this.refreshEntitlement();
+		const directory = path.join(this.store.root, "bundles", receipt.bundleId, receipt.version);
+		const bundle = await importBundle(directory, receipt);
+		for (const plugin of bundle.plugins) {
+			const host = this.createHost(plugin.manifest);
+			await plugin.activate(host);
+			const health = await plugin.healthCheck(host);
+			if (!health.ok)
+				throw new PluginBootstrapFailure(
+					"plugin_health_check_failed",
+					health.message ?? `Plugin ${plugin.manifest.id} failed its health check`,
+				);
+		}
+		this.loaded = true;
+		return true;
+	}
+
+	async run(name: string, context: PluginCommandContextV1): Promise<PluginCommandResultV1 | null> {
+		if (!(await this.load())) return null;
+		const registered = this.commands.get(name);
+		if (!registered) return null;
+		const entitlement = await this.refreshEntitlement();
+		if (!isPluginCapabilityEnabled(entitlement, registered.command.requiredCapability))
+			return {
+				ok: false,
+				error: {
+					code: "plugin_capability_denied",
+					message: `Capability ${registered.command.requiredCapability} is not enabled for ${registered.pluginId}`,
+				},
+			};
+		return registered.command.run(context);
+	}
+
+	private createHost(manifest: AgentMemoryPluginManifestV1): AgentMemoryPluginHostV1 {
+		const descriptors = new Map(manifest.commands.map((command) => [command.name, command]));
+		const stateRoot = path.join(this.store.root, "state");
+		fs.mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+		const stateRootStat = fs.lstatSync(stateRoot);
+		if (!stateRootStat.isDirectory() || stateRootStat.isSymbolicLink())
+			throw new PluginBootstrapFailure("plugin_state_invalid", "The plugin state root is unsafe");
+		const stateDirectory = path.join(stateRoot, OFFICIAL_BUNDLE_ID);
+		if (!fs.existsSync(stateDirectory)) fs.mkdirSync(stateDirectory, { mode: 0o700 });
+		const stateDirectoryStat = fs.lstatSync(stateDirectory);
+		if (!stateDirectoryStat.isDirectory() || stateDirectoryStat.isSymbolicLink())
+			throw new PluginBootstrapFailure("plugin_state_invalid", "The plugin state directory is unsafe");
+		return {
+			apiVersion: AGENT_MEMORY_PLUGIN_API_VERSION,
+			coreVersion: this.options.coreVersion,
+			registerCommand: (command) => {
+				const descriptor = descriptors.get(command.name);
+				if (!descriptor || descriptor.requiredCapability !== command.requiredCapability)
+					throw new PluginBootstrapFailure(
+						"plugin_command_invalid",
+						`Plugin ${manifest.id} registered an undeclared command`,
+					);
+				const names = [command.name, ...(command.aliases ?? [])];
+				for (const name of names) {
+					if (this.commands.has(name))
+						throw new PluginBootstrapFailure(
+							"plugin_command_conflict",
+							`Plugin command ${name} is already registered`,
+						);
+				}
+				for (const name of names) this.commands.set(name, { command, pluginId: manifest.id });
+			},
+			registerSessionStartHook: (hook) => {
+				if (!(manifest.capabilities ?? []).includes(hook.requiredCapability))
+					throw new PluginBootstrapFailure(
+						"plugin_hook_invalid",
+						`Plugin ${manifest.id} registered a hook with an undeclared capability`,
+					);
+				this.hooks.push(hook);
+			},
+			getStateDirectory: () => stateDirectory,
+			getMemoryDirectory: () => {
+				assertPermission(manifest, "memory:read");
+				return getMemoryDir();
+			},
+			getEntitlement: async () => structuredClone(await this.refreshEntitlement()),
+			redactSecrets: (value) => redactSecrets(value).content,
+			writeMemory: async (request: PluginMemoryWriteV1) => {
+				assertPermission(manifest, "memory:write");
+				return memoryResult(await memoryWrite({ ...request, sessionId: `plugin-${manifest.id}` }));
+			},
+			correctMemory: async (request: PluginMemoryCorrectionV1) => {
+				assertPermission(manifest, "memory:correct");
+				const content = `Correction for ${request.artifactId}: ${request.content}${request.reason ? `\nReason: ${request.reason}` : ""}`;
+				return memoryResult(
+					await memoryWrite({
+						target: request.scope === "durable" ? "long_term" : "daily",
+						content,
+						sessionId: `plugin-${manifest.id}`,
+						sourceUri: request.sourceUri,
+					}),
+				);
+			},
+			scheduleSearchRefresh: () => {
+				assertPermission(manifest, "jobs:run");
+				scheduleQmdUpdate();
+			},
+		};
+	}
+
+	private async refreshEntitlement(): Promise<PluginEntitlementStatusV1> {
+		const entitlement = await this.backend.getLocalEntitlement();
+		validatePluginEntitlementStatusV1(entitlement);
+		return entitlement;
+	}
+}
+
+export function createInstalledBundleHealthCheck(
+	coreVersion: string,
+	backend: PluginBootstrapBackendV1,
+	storeRoot: string,
+): (directory: string, release: SignedPluginReleaseV1) => Promise<void> {
+	return async (directory, release) => {
+		const entitlement = await backend.getLocalEntitlement();
+		validatePluginEntitlementStatusV1(entitlement);
+		const receipt = {
+			bundleId: release.manifest.id,
+			version: release.manifest.version,
+			entrypoint: release.manifest.entrypoint,
+		};
+		const bundle = await importBundle(directory, receipt);
+		for (const plugin of bundle.plugins) {
+			const stateDirectory = path.join(storeRoot, "health", OFFICIAL_BUNDLE_ID);
+			const host: AgentMemoryPluginHostV1 = {
+				apiVersion: 1,
+				coreVersion,
+				registerCommand() {},
+				registerSessionStartHook() {},
+				getStateDirectory: () => stateDirectory,
+				getMemoryDirectory: () => {
+					assertPermission(plugin.manifest, "memory:read");
+					return getMemoryDir();
+				},
+				getEntitlement: async () => structuredClone(entitlement),
+				redactSecrets: (value) => redactSecrets(value).content,
+				async writeMemory() {
+					throw new PluginBootstrapFailure("plugin_health_check_invalid", "Health checks cannot write memory");
+				},
+				async correctMemory() {
+					throw new PluginBootstrapFailure("plugin_health_check_invalid", "Health checks cannot correct memory");
+				},
+				scheduleSearchRefresh() {},
+			};
+			const health = await plugin.healthCheck(host);
+			if (!health.ok)
+				throw new PluginBootstrapFailure(
+					"plugin_health_check_failed",
+					health.message ?? `Plugin ${plugin.manifest.id} failed its health check`,
+				);
+		}
+	};
+}